docs: VTK 重构实施 plan + 生成三维体入口/归属调整

- 新增实施计划(8 phase/12 task, TDD bite-sized) - 客户确认变动: 新增三维体入口回段头(数据类型层面)+对话框「生成位置」选归属; 归属放开 GS/项目根/TM(structParentConfType 1或2, 默认单GS挂该GS/跨GS挂项目根) - spec 同步该变动; openapi 升 v0.6-draft
2026-06-24 17:17:32 +08:00 · 2026-06-24 17:17:32 +08:00 · ef10c354c9
parent eceb964aa1
commit ef10c354c9
3 changed files with 1131 additions and 15 deletions
--- a/docs/api/vtk-3d-openapi.json
+++ b/docs/api/vtk-3d-openapi.json
@ -2,8 +2,8 @@
  "openapi": "3.0.3",
  "info": {
    "title": "Geopro3 三维视图 API（三维体 / 切片 / 异常 三件套）",
-    "version": "0.5.0-draft",
-    "description": "VTK 三维视图后端接口。归属结构(2026-06-24 修订)：**GS/项目根 → 三维体(dd_voxel) → 切片(dd_slice)**(三维体由空间容器节点生成，非 TM；TM 单线不成体)，异常挂在三维体上(remarkSourceId=三维体 dsObjectId)。\n\n**总原则：实体无关的契约一律复用存量；只为各自特有、存量装不下的部分扩展。**\n- 三维体/切片对后端 = 纯元数据 dsObject：增删改查/属性复用存量 dsObject 面，各加 1 个登记端点；体素字节/切面数据全在客户端(算+存+取+渲染)，后端零数据端点。\n- 异常复用整套存量 /business/exception 端点(端点不限实体类型，三维体 id 直接塞 remarkSourceId)；**异常体(consortium)分组也是存量已有**(consortiumId/Name/Type)。3D 仅扩展两处：location 加 worldPts+plane(三维几何)、加截图(R88)。\n\n响应统一信封 `{ code:int, msg:string, data:object|array }`，code==200 成功；列表/集合放 data.value。\n\n依赖前提：异常 remarkSourceId 指向三维体，须等三维体登记出真 dsObjectId 后，3D 异常才能接真端点。"
+    "version": "0.6.0-draft",
+    "description": "VTK 三维视图后端接口。归属结构(2026-06-24 修订)：**GS/项目根/TM → 三维体(dd_voxel) → 切片(dd_slice)**(三维体生成位置由用户在生成对话框选择,默认单GS挂该GS/跨GS挂项目根,可改为项目内任意 GS/TM；源数据集与归属解耦)，异常挂在三维体上(remarkSourceId=三维体 dsObjectId)。\n\n**总原则：实体无关的契约一律复用存量；只为各自特有、存量装不下的部分扩展。**\n- 三维体/切片对后端 = 纯元数据 dsObject：增删改查/属性复用存量 dsObject 面，各加 1 个登记端点；体素字节/切面数据全在客户端(算+存+取+渲染)，后端零数据端点。\n- 异常复用整套存量 /business/exception 端点(端点不限实体类型，三维体 id 直接塞 remarkSourceId)；**异常体(consortium)分组也是存量已有**(consortiumId/Name/Type)。3D 仅扩展两处：location 加 worldPts+plane(三维几何)、加截图(R88)。\n\n响应统一信封 `{ code:int, msg:string, data:object|array }`，code==200 成功；列表/集合放 data.value。\n\n依赖前提：异常 remarkSourceId 指向三维体，须等三维体登记出真 dsObjectId 后，3D 异常才能接真端点。"
  },
  "servers": [
    { "url": "/", "description": "业务网关根(各路径已含 /business 前缀)" }
@ -34,7 +34,7 @@
      "post": {
        "tags": ["dsObject-reuse"],
        "summary": "[复用] 分页查询某父节点下的数据集行",
-        "description": "存量端点(loadRowsAsync)。查三维体：structParentId=容器节点 id(GS/项目根)、structParentConfType=1；查某三维体下切片：structParentId=该三维体 dsObjectId。返回行 ddCode=dd_voxel / dd_slice。",
+        "description": "存量端点(loadRowsAsync)。查三维体：structParentId=生成位置节点 id(GS/项目根/TM)、structParentConfType=1或2；查某三维体下切片：structParentId=该三维体 dsObjectId。返回行 ddCode=dd_voxel / dd_slice。",
        "operationId": "dsObjectDataPage",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DsPageRequest" } } } },
        "responses": {
@ -99,7 +99,7 @@
      "post": {
        "tags": ["voxel-new"],
        "summary": "[新增] 登记三维体记录",
-        "description": "在容器节点(GS/项目根)下登记一条 dd_voxel dsObject(名称 + 构建参数写入 attachedParameters.voxelParams)，返回新 dsObjectId。只建记录、不触发后端计算——体素插值/落盘/渲染全在客户端。",
+        "description": "在生成位置节点(GS/项目根/TM)下登记一条 dd_voxel dsObject(名称 + 构建参数写入 attachedParameters.voxelParams)，返回新 dsObjectId。只建记录、不触发后端计算——体素插值/落盘/渲染全在客户端。",
        "operationId": "registerVoxel",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoxelGenerateRequest" } } } },
        "responses": {
@ -303,8 +303,8 @@
        "required": ["projectId", "structParentId", "structParentConfType", "classifyTypeList", "pageNo", "pageSize"],
        "properties": {
          "projectId": { "type": "string" },
-          "structParentId": { "type": "string", "description": "查三维体填容器节点 id(GS/项目根)；查切片填所属三维体 dsObjectId" },
-          "structParentConfType": { "type": "integer", "description": "父节点配置类型：GS/项目根=1(三维体场景)；查切片时=三维体所在层级" },
+          "structParentId": { "type": "string", "description": "查三维体填生成位置节点 id(GS/项目根/TM)；查切片填所属三维体 dsObjectId" },
+          "structParentConfType": { "type": "integer", "description": "父节点配置类型：1=GS/项目根 2=TM(三维体生成位置)；查切片时=三维体所在层级" },
          "classifyTypeList": { "type": "array", "items": { "type": "integer" }, "description": "数据类别过滤(dd_voxel/dd_slice 的 classify code 由后端定义)" },
          "pageNo": { "type": "integer", "default": 1 },
          "pageSize": { "type": "integer", "default": 20 }
@ -321,7 +321,7 @@
          "id": { "type": "string" }, "dsName": { "type": "string" },
          "ddCode": { "type": "string", "enum": ["dd_voxel", "dd_slice"] },
          "typeName": { "type": "string", "example": "三维体" },
-          "parentId": { "type": "string", "nullable": true, "description": "三维体=容器节点 id(GS/项目根)；切片=所属三维体 dsObjectId" }
+          "parentId": { "type": "string", "nullable": true, "description": "三维体=生成位置节点 id(GS/项目根/TM)；切片=所属三维体 dsObjectId" }
        }
      },
      "DsObjectDetail": {
@ -385,8 +385,8 @@
        "type": "object", "required": ["projectId", "structParentId", "structParentConfType", "name", "sourceDatasetIds"],
        "properties": {
          "projectId": { "type": "string" },
-          "structParentId": { "type": "string", "description": "归属容器节点 id —— 三维体挂在 GS/项目根下" },
-          "structParentConfType": { "type": "integer", "default": 1, "description": "父节点配置类型：GS/项目根=1(项目根本质亦为 GS)" },
+          "structParentId": { "type": "string", "description": "生成位置节点 id —— 三维体挂在所选 GS/项目根/TM 下" },
+          "structParentConfType": { "type": "integer", "default": 1, "description": "1=GS/项目根 2=TM；默认单GS挂该GS、跨GS挂项目根，用户可在生成对话框改为任意 GS/TM" },
          "name": { "type": "string" },
          "sourceDatasetIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
          "interpModel": { "$ref": "#/components/schemas/InterpModel" },
--- a/docs/superpowers/plans/2026-06-24-vtk-category-view-refactor.md
+++ b/docs/superpowers/plans/2026-06-24-vtk-category-view-refactor.md
--- a/docs/superpowers/specs/2026-06-24-vtk-category-view-refactor-design.md
+++ b/docs/superpowers/specs/2026-06-24-vtk-category-view-refactor-design.md
@ -93,8 +93,8 @@

 | 节点 | 复选框 | 右键新增项 |
 |---|---|---|
-| 项目根 | 无（不可勾，直挂 ds 固定显示） | 生成三维体 |
-| 非根 GS | 三态 | 选择 ▸ ds / tm（带对号）、生成三维体 |
+| 项目根 | 无（不可勾，直挂 ds 固定显示） | —（生成三维体改在段头，见 §7） |
+| 非根 GS | 三态 | 选择 ▸ ds / tm（带对号） |
 | TM 叶子 | 普通二态 | — |

 **GS 三态语义**（标准 tristate 聚合）：GS 复选框 = `[GS 自身 ds]` + `[所有子 TM 勾选]` 的聚合；都有=Checked，都无=Unchecked，部分=PartiallyChecked。
@ -121,7 +121,7 @@ checkedSourcesChanged
 - **段头**：标题 + 折叠开关 + 日期范围筛选 + 装置类型下拉（仅 `装置类型筛选=✓` 的段显示）。
 - **段体**：项目根 / GS / TM 树 + 数据行，复用 `DatasetListPanel::populateDatasetList`（按 parentId 建树）与卡片委托；数据行可勾选 = 渲染。
 - **渲染勾选链承接（必须）**：CategorySection 暴露 `checkedDatasetsChanged`，**接管退役的 `Column3DDataset` 原有「剖面勾选→帘面渲染」主链**——main.cpp 把 5 段（电阻率/视电阻率/瞬变=帘面，三维体/切片=体素/切片）的勾选并集后下发 `pushChecked`（沿用现有 `checkedProfiles`/`checkedAnalysis` 并集模型），否则帘面渲染整体失联。
- **生成三维体入口**：仅 `可生成三维体=✓` 的段（电阻率/视电阻率/瞬变电磁），在段内**项目根 / GS 节点**右键提供「生成三维体」——用该容器下本段类型的剖面生成体，类型由段决定、空间范围由容器节点决定。TM 节点不提供（单线不成体）。生成的 `sourceDatasetIds` 须按「**本段 dsTypeCode ∩ 本容器归属**」双重过滤，杜绝跨物理量插值（现 `Column3DDataset::showListContextMenu` 仅按 ddCode 白名单收集、不分 dsTypeCode，会把电阻率+瞬变混入同体；重构后入口移入段内天然隔离，但仍须按段类型+容器双重圈定源）。
+- **生成三维体入口**：仅 `可生成三维体=✓` 的段（电阻率/视电阻率/瞬变电磁）**段头**有「+新增三维体」按钮。**源数据集 = 三维分析中当前勾选的同类型 ds**（本段类型，天然按段隔离、可跨 GS）。点击 → `VolumeParamsDialog`（页面中心弹窗）：**左侧·数据列表** 树状（按 GS 分组）展示这些已勾选源，每项可勾选/取消供**确认或二次修改**；**右侧·插值参数**：名称、**生成位置**（下拉）、插值模型、水平/竖向间距、IDW 幂次、最大影响距离。**生成位置（归属）规则**：默认 = 源同属单 GS→该 GS、源跨 GS→项目根；用户可改为**项目内任意 GS / TM**（故归属 `structParentConfType` 可为 1 或 2，与源数据解耦）。提交 → 组装 `VoxelGenerateRequest` → `createVolume`。
 - **筛选**：复用并扩展 `applyDatasetFilter`，日期比较字段由 `createTime` 改为 `collectTime`（§10）。

 「三维分析」tab 容器（替代原 Column3DDataset/Column3DAnalysis 在 tab 中的位置）：`QScrollArea` + 垂直布局，按配置表实例化 5 个 `CategorySection`。
@ -130,13 +130,13 @@ checkedSourcesChanged

 复用现有 `Api3dRepository`（mock）与 `refreshAnalysis` 合并注入机制，仅重新组织到段：

-> 三维体归属 **GS / 项目根**（非 TM）。后端契约 `docs/api/vtk-3d-openapi.json` 已同步至 v0.5-draft（`structParentConfType=1`）；客户端 `createVolume` 接真实端点时需补 `structParentId/structParentConfType`，并新增按三维体 id 查异常的 `queryException/{remarkSourceId}` 调用。
- **三维体段**：列已生成的体（客户端 mock + 后端 `dd_voxel`），按归属（项目/GS）分组。（**「正在生成…」状态**：现 `createVolume` 同步登记、首次 `loadVolume` 惰性插值，本期**不引入异步生成态机**、体即时出行；如需占位仅作纯展示文案、不做进度。）异常挂三维体（记忆 `vtk-3d-persistence-structure`）：现 `Column3DAnalysis` 的 3D 异常列表 / 显示过滤档位 / 单条显隐，迁入三维体段内（随当前活动体展示）。
+> 三维体归属由「生成位置」选择决定：默认单 GS→该 GS、跨 GS→项目根，用户可改为项目内任意 **GS / TM**（`structParentConfType` 可 1 或 2）。后端契约 `docs/api/vtk-3d-openapi.json` 已同步至 v0.6-draft（`structParentConfType` 放开 1/2 + 默认规则）；客户端 `createVolume` 接真实端点时需补 `structParentId/structParentConfType`，并新增按三维体 id 查异常的 `queryException/{remarkSourceId}` 调用。
+- **三维体段**：列已生成的体（客户端 mock + 后端 `dd_voxel`），按归属（项目/GS/TM）分组。（**「正在生成…」状态**：现 `createVolume` 同步登记、首次 `loadVolume` 惰性插值，本期**不引入异步生成态机**、体即时出行；如需占位仅作纯展示文案、不做进度。）异常挂三维体（记忆 `vtk-3d-persistence-structure`）：现 `Column3DAnalysis` 的 3D 异常列表 / 显示过滤档位 / 单条显隐，迁入三维体段内（随当前活动体展示）。
 - **切片段**：列已保存切片（`dd_slice`），按父体分组（`parentId` = 所属体）。

 体素 / 切片 / 异常的渲染、生成、保存路径不变（`VtkSceneController` / `InteractionManager` / `Api3dRepository`），只改列表的承载位置。

-**请求体组装（本次新增）**：`createVolume` 扩参为 `(projectId, structParentId, structParentConfType, params, name)`——归属来自生成入口的 GS/项目根节点；`createSlice` 补 `projectId`。两者内部按新增客户端 DTO `VoxelGenerateRequest`/`SliceGenerateRequest`（对齐 `docs/api/vtk-3d-openapi.json` schema）组装出**完整请求体**并提供 `toJson` 序列化；mock 路径存内存 +（debug）打印请求体，将来切真实端点只把「存」改「发」、组装逻辑原样复用。如此重构一落地即可从 UI 真实产出请求体（值为 mock、结构与字段为真）。`createSlice` 补 `projectId` 会波及 main.cpp 切片保存调用点（切片右键/列表保存路径），须一并传 `nav.currentProjectId()`。
+**请求体组装（本次新增）**：`createVolume` 扩参为 `(projectId, structParentId, structParentConfType, params, name)`——归属来自对话框「生成位置」选择（GS/项目根/TM，默认单GS→该GS、跨GS→项目根）；`createSlice` 补 `projectId`。两者内部按新增客户端 DTO `VoxelGenerateRequest`/`SliceGenerateRequest`（对齐 `docs/api/vtk-3d-openapi.json` schema）组装出**完整请求体**并提供 `toJson` 序列化；mock 路径存内存 +（debug）打印请求体，将来切真实端点只把「存」改「发」、组装逻辑原样复用。如此重构一落地即可从 UI 真实产出请求体（值为 mock、结构与字段为真）。`createSlice` 补 `projectId` 会波及 main.cpp 切片保存调用点（切片右键/列表保存路径），须一并传 `nav.currentProjectId()`。

 ## 9. VTK 画布工具条 `VtkViewToolbar`