From aa559c2bb7105ff2e0d62b95db4ab05ec2d4e22e Mon Sep 17 00:00:00 2001 From: gaozheng Date: Wed, 24 Jun 2026 08:55:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8E=E7=AB=AF=20API=20=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E4=BC=9A=E8=AF=9D=E4=BA=A4=E6=8E=A5=E6=96=87=E6=A1=A3?= =?UTF-8?q?(=E4=B8=89=E7=BB=B4=E4=BD=93/=E5=88=87=E7=89=87/=E5=BC=82?= =?UTF-8?q?=E5=B8=B8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录本会话设计定论、剩余工作、待确认问题与代码地图， 配套 docs/api/vtk-3d-openapi.json 与实现交接 HANDOFF-vtk-3d.md。 --- .../superpowers/HANDOFF-vtk-3d-backend-api.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/superpowers/HANDOFF-vtk-3d-backend-api.md diff --git a/docs/superpowers/HANDOFF-vtk-3d-backend-api.md b/docs/superpowers/HANDOFF-vtk-3d-backend-api.md new file mode 100644 index 0000000..8c29621 --- /dev/null +++ b/docs/superpowers/HANDOFF-vtk-3d-backend-api.md @@ -0,0 +1,84 @@ +# 交接：VTK 三维视图 后端 API 设计（三维体 / 切片 / 异常） + +> 给下一个会话无缝接手用。更新日期 2026-06-24。分支 `feat/vtk-3d-view`。本会话**纯设计 + 产出对接文档，未改业务代码**。配套实现交接见 [`HANDOFF-vtk-3d.md`](./HANDOFF-vtk-3d.md)。 +> +> **进度速览**：澄清了"三维体/切片/异常存为 ds、能否复用存量 ds 接口"的全部疑问，产出后端对接 Swagger `docs/api/vtk-3d-openapi.json`（OpenAPI 3.0.3，15 路径/26 schema），已提交 `9d3b103`（未推送）。记忆 [[vtk-3d-persistence-structure]] 已同步定论。**无半成品**。下一会话方向：① 把这份契约交付后端排期；② 后端就绪后做客户端切真实（接口不动，换 `Api3dRepository` 实现）。 + +## 1. 背景 +- 代码库 `D:\Git\lanbingtech\geopro` = 原版 web 系统移植的 Qt 桌面客户端；原版 web 源码 `D:\Git\lanbingtech\commercial-admin` 是复刻权威。 +- 三维体/切片/异常的渲染/交互**已实现**（见另一份 handoff），但持久化全是 **mock**（`I3dSceneRepository` 留缝、`Api3dRepository` 内存 map）。 +- 本会话起点问题：三维体/切片要存为 ds、异常要挂三维体，**现有 ds 接口能否复用？** 由此推导出后端要补哪些端点，并产出 Swagger。 + +## 2. 本会话已完成 +- **摸清存量两套仓储 + 真实端点**（见 §6 代码地图）。 +- **澄清一系列关键设计点**（§3）。 +- **产出 `docs/api/vtk-3d-openapi.json`**：三件套后端对接设计稿，JSON 校验通过、无悬空/未用 schema。 +- **提交** `9d3b103`（仅该文件，未推送；按全局设置未加署名）。曾有中间产物 `docs/api/voxel-slice-openapi.json`，迭代后已删并合入 vtk-3d-openapi.json。 +- **更新记忆** [[vtk-3d-persistence-structure]]，加全部定论 + 文档路径 + commit 号。 + +## 3. 设计定论（多轮被用户纠正后收敛，**这是核心交付**） + +1. **三维体/切片对后端 = 纯元数据 dsObject** + - 增删改查/属性**复用存量 dsObject 面**：`projectStruct`树 / `dsObject/data/page`列表 / `getDetail`详情 / `dynamicForm`属性 / `updateDsObject`更新 / `dsObject/{id}`删除。 + - 各只加 **1 个登记端点**（`/dsObject/voxel/generate`、`/dsObject/slice/generate`）——存量"建 ds = 文件 import"对生成类不适用；登记只建记录、**不触发后端计算**。 + +2. **体素字节/切面数据全在客户端，后端零数据端点** + - 连 GPR 大体（13.6G）体素也**不上传**、即使落盘也在客户端本地（`ChunkedVolumeStore`）；后端只持有 dsObject 记录。 + - 故**无** meta/brick/上传/切片位姿端点（设计途中曾加过，全删）。params/voxel 是否本地落盘是纯客户端策略，后端不感知。 + +3. **小块结构化数据搭车 `attachedParameters`** + - 三维体构建参数（`voxelParams`）、切片三点位姿（`slicePose`）存这里，读走 `getDetail`、写走 `updateDsObject`（与描述 `deltaContent` 同机制）。`dynamicForm` 只放给人看的键值属性。 + +4. **归属结构：TM → 三维体(dd_voxel) → 切片(dd_slice)**，异常挂三维体 + - **三维体挂在 TM 下**（本会话纠正，之前记忆误写"对象/GS"）。`structParentConfType=2`(TM)。 + +5. **异常复用整套 `/business/exception` 端点**（实体无关，三维体 id 直接塞 `remarkSourceId`） + - **异常体(consortium)分组是存量已有**（`parseExceptions` 已解析 `consortiumId/Name/Type`，`queryExceptionByTmObjectId` 按其分组）——**非 3D 新增**（此前误判已纠正）。 + - 3D 仅扩展两处、都在 body/返回字段（**不新增端点**）：① `location` 加 `worldPts`（三维多边形点）+`plane`（所在平面），存量是 2D `coordinate[{x,y}]`+经纬/投影坐标；② 截图（R88）。 + +## 4. 剩余工作（按依赖顺序） + +**后端**（阻塞一切，把 `vtk-3d-openapi.json` 交付排期）： +1. 注册 `dd_voxel`/`dd_slice` 两个 dd 类型 + 各自 `classifyType` code。 +2. 实现两个登记端点（`voxel/generate`、`slice/generate`），返回真 `dsObjectId`。 +3. 为这两类型注册 `dynamicForm`（属性表单）。 +4. 扩展异常 `location` schema 容纳 3D `worldPts`+`plane` 并保证往返不丢。 +5. 加异常 `screenshot` 字段 + 定传输方式。 + +**客户端**（后端就绪后；接口 `I3dSceneRepository` 不动，留缝就是为此）： +6. `Api3dRepository` 内存 map 换成调真实端点。 +7. `main.cpp:450-451` 手动 append 三维体/切片行改成走后端树。 +8. 3D 异常路径从 `I3dSceneRepository`(mock) 切到 `IDatasetCommandRepository`(真)，`remarkSourceId`=三维体真 id。 + +## 5. 待确认问题 +- `classifyTypeList` 里 dd_voxel/dd_slice 的具体 code（后端定）。 +- `location` 3D 字段精确结构（后端定）。 +- 截图传输：base64 内联 vs 单独上传（后端定）。 +- **未验证风险**：原系统 `remarkSourceId` 只挂过 2D dsObject，没挂过三维体 id；`listExceptionTypes`/`getExceptionName` 挂三维体时是否如预期，需后端整链就绪后实测。 + +## 6. 代码地图（本会话查证过的关键文件） +| 文件 | 作用 | +|---|---| +| `src/data/repo/I3dSceneRepository.hpp` | mock 留缝接口（三维体/切片/异常/任务 CRUD）| +| `src/data/api/Api3dRepository.{hpp,cpp}` | mock 实现（`volumes_`/`slices_`/`anomalies_` 内存 map）| +| `src/data/repo/LocalSample3dRepository.cpp` | 本地样本 stub | +| `src/data/repo/IDatasetCommandRepository.hpp` | **真实**异常端点 + ds 详情写操作 | +| `src/data/api/ApiProjectRepository.cpp` | **真实** dsObject 面（getDetail/dynamicForm/data/page/delete/update/import/projectStruct）| +| `src/core/model/Anomaly.hpp` | 异常模型（2D: localPts/lonLat/eastNorth；3D: worldPts/plane）| +| `src/data/repo/VolumeBuildParams.hpp` | 三维体构建参数 | +| `src/data/store/ChunkedVolumeStore.hpp` | GPR 分块体存储（客户端本地落盘）| +| `src/app/main.cpp` | 接线（450-451 合并注入、577/661/745 createSlice/createVolume）| +| `src/data/dto/NavDto.cpp:374` | `parseExceptions`（含 consortium 字段，证实异常体存量已有）| +| `src/data/dto/DatasetChartDto.cpp` | 异常 location/坐标系解析 | +| `docs/api/vtk-3d-openapi.json` | **本会话产出** | + +**后端响应信封**：`{code:int, msg:string, data:object|array}`，`code==200` 成功，列表/集合放 `data.value`。 + +## 7. 铁律 / 注意 +- **贴源码/日志，别凭印象**：本会话多次因臆测（"装不下"、"异常体是 3D 新增"、自造端点不贴存量）被用户纠正——任何接口字段/语义都先去代码里核实。 +- **复用优先于新建**：实体无关的契约一律复用存量；只有"生成动作"和"3D 几何/截图"这种存量真装不下的才扩展。 +- 全部回复中文。 + +## 8. 相关 +- 记忆：[[vtk-3d-persistence-structure]]（已含本会话定论）、[[gpr-volume-design-trio]]、[[dataset-list-is-tree]]、[[vtk96-hdfwriter-no-imagedata]]。 +- 实现交接：[`HANDOFF-vtk-3d.md`](./HANDOFF-vtk-3d.md)。