gaozheng
/
geopro
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geopro/docs/superpowers/HANDOFF-vtk-category-view-r...

19 KiB
Raw Blame History

交接：VTK 三维分析视图重构（按数据类型分组 + 对象树联动）

给下一个会话无缝接手。日期 2026-06-24。分支 feat/vtk-3d-view。 本会话产出 spec + 实施 plan + openapi 修订，未改业务代码——下一步是按 plan 执行实现。

速览：把 VTK 左侧三 tab 重构为「按数据类型大类分组」两 tab；经真实接口实测定分类/字段、opus 子代理评审、客户两轮交互确认后定稿。产出 spec（specs/2026-06-24-vtk-category-view-refactor-design.md）+ 实施 plan（plans/2026-06-24-vtk-category-view-refactor.md，8 phase/12 task）+ openapi v0.6（docs/api/vtk-3d-openapi.json）。

⏩ 实施进度（2026-06-24 续会话，Task 1-10 完成）

已完成 Task 1-10（10/12），全部已提交、可编译、逻辑层单测全绿（425 测试，5 个失败均为 PROJ_DATA 环境性、非回归）。剩 Task 11-12（main 接线总成）。

提交链（在 a7d558b docs 之后）：

a06d9e8 feat(data): createVolume(VoxelGenerateRequest) 重载+fromRequest 派生+请求体打印(mock)   # Task10
3af7e44 feat(ui): VtkViewToolbar 画布工具条 + AxesSettingsDialog 坐标轴设置                      # Task9
98114a3 feat(ui): CategoryAnalysisTab(QScrollArea 5段)+ColumnDrawer 两tab(旧栏隐藏过渡)         # Task8
30e990d feat(ui): CategorySection 类型段组件 + DatasetFieldDictionary 缓存类                    # Task7
40646f7 refactor(tree): 评审修复-抽 recomputeAllGsStates 去 nullptr 信号 hack                   # Task4-6 review 修复
c5b3907 feat(data): DatasetFieldDictionary 解析 arrayType/collectTime 映射+装置字典             # Task6
1978a31 feat(tree): GS 三态状态机(停 AutoTristate)+右键 ds/tm + checkedSourcesChanged          # Task4+5(合并)
6b39901 test(data): 补 properties[1] 日期项断言
f00a214 feat(data): VoxelGenerateRequest/SliceGenerateRequest DTO + toJson                      # Task3
07cf75d feat(app): CategoryConfig 映射表 + splitByCategory                                      # Task2
5a719ca feat(data): DsRow 加 dsTypeCode/properties + parseDsRows 解析                            # Task1

已就绪的新构件（均编译通过）：

  • 逻辑层：DsRow 扩字段、splitByCategory(CategoryConfig 5 段)、Vtk3dRequests(Voxel/Slice DTO + toJson + fromRequest)、DatasetFieldDictionary(parseFieldMapping + 缓存类)、ObjectTreeSelection(aggregateGsState/dedupeSources)。
  • 对象树：ObjectTreePanel GS 三态状态机(停 AutoTristate)+ 右键「选择▸ds/tm」+ checkedSourcesChanged(QList<DataSource>) 信号（与旧 checkedTmsChanged 并存，Task 12 删旧）。
  • UI 组件：CategorySection(段头装置/日期筛选+段体可勾选树+「+新增三维体」+双击详情)、CategoryAnalysisTab(QScrollArea 5 段，setBuckets/section/勾选并集)、ColumnDrawer 已改两 tab(三维分析=analysisTab / 二维分析=col2D；旧 col3D_/colAnalysis_ 仍实例化但 hide()、不入 tab，保留访问器供 main 过渡)、VtkViewToolbar、AxesSettingsDialog。
  • data：Api3dRepository::createVolume(VoxelGenerateRequest) 重载(组装真实请求体+打印+lastVoxelRequest)，旧 createVolume(VolumeBuildParams,name) 保留。

⚠️ 当前过渡态：app 可编译运行，但「三维分析」tab 是空的 CategoryAnalysisTab（数据接线在 Task 12）；旧三维数据集/三维分析功能已隐藏。对象树 GS 三态+右键 ds/tm 已在现 app 生效（旧 checkedTmsChanged 仍兼容），可立即真实验证（plan Task 4 Step 7 清单）。

偏离 plan 的决策（已记录理由）：① Task 4+5 合并一个 commit（plan Task4 右键已引用 Task5 的 emitCheckedSources，循环依赖）；② DatasetFieldDictionary 异步拉取下放 main（data 层无网络，类只内存缓存）；③ CategorySection 段体先平铺（populateDatasetList），「项目根/GS/TM 容器节点分层」推迟 Task 12 接真实 StructNode；④ createSlice 虚接口未改签名，SliceGenerateRequest 组装并入 Task 12 main 层。

🔧 Task 11+12 待做（main.cpp 接线总成，最高风险，须真实 app 验证）

main.cpp 1943 行，接线密集。关键现状符号位置：

  • :361 new ColumnDrawer(centerWidget) —— 需改传 dict（构造已支持第2参 DatasetFieldDictionary* dict=nullptr）。
  • :397 refreshAnomalies / :448 refreshAnalysis 闭包用 drawer->colAnalysis()。
  • :442 c3 = drawer->col3D()；:641 c3 checkedDatasetsChanged→sceneCtrl；:653 c3 generateVolumeRequested→createVolume；:898/902 c3 verticalExaggeration。
  • :579/745 createSlice 调用（补 projectId + 组装 SliceGenerateRequest）。
  • :584/623 colAnalysis()->setItemChecked；:666 ca=colAnalysis()。
  • :1117/1267 对象树 checkedTmsChanged 接线（→改 checkedSourcesChanged + confType 分流 loadRowsAsync(projId, src.id, src.confType, 3, ...)）。
  • :1134 splitByDimension→splitByCategory + analysisTab()->setBuckets；:1135 col3D/col2D setDatasets。
  • :1215 clearCentral。:1328 drawer->expand()。

Task 11 缺口：CategoryAnalysisTab/CategorySection 尚无 colAnalysis 的 setItemChecked、异常子区 API；三维体段需迁入 Column3DAnalysis 异常控件（参 src/app/panels/columns/Column3DAnalysis.{hpp,cpp} + main :397 refreshAnomalies）。

Task 12 要点（plan §Task12 Step1-8 已详列）：① 对象树勾选→confType 分流拉取→splitByCategory→analysisTab setBuckets；② analysisTab checkedDatasetsChanged→并入 checkedProfiles/checkedAnalysis→pushChecked；③ generateVolumeRequested→VolumeParamsDialog 扩展（左侧勾选源树·可二次增删 + 右侧「生成位置」下拉=项目内 GS/TM）→组装 VoxelGenerateRequest→createVolume(req)；④ 工具条 VtkViewToolbar 叠加中央 QVTK + AxesSettingsDialog 接坐标轴；⑤ createSlice 补 nav.currentProjectId()；⑥ 删旧 checkedTmsChanged/col3D()/colAnalysis()/splitByDimension/Column3D* 引用 + setStructure 传对象树同源 StructNode（容器分层）。

✅ Task 12 阶段 A 已完成（commit 901c84e）—— 核心数据流接通

  • refreshAnalysis 重构为统一入口：lastSourceRows + volumeRows + sliceRows → splitByCategory → analysisTab->setBuckets（5 段出数据）+ splitByDimension(...).dim2D → col2D。
  • 对象树 checkedTmsChanged 接线：finish 改 *lastSourceRows=*acc; refreshAnalysis()（仍用 checkedTmsChanged，confType 分流见剩余①）。
  • analysisTab 三接线：checkedDatasetsChanged→按 isSlice/isVolume 分流(切片→checkedSliceIds+syncSlices / 体素→checkedAnalysis / 反演剖面→checkedProfiles)→pushChecked；generateVolumeRequested→VolumeParamsDialog→组装 VoxelGenerateRequest→createVolume(req)；detailRequested→Slice/Volume 属性对话框。
  • clearCentral 改走 lastSourceRows/refreshAnalysis。
  • 现可验：勾对象树 TM → 电阻率/视/瞬变段出数据 → 勾选段内 ds → 帘面渲染；生成三维体 → voxel 段出现 → 勾选渲体；切片段同理。

🔧 Task 12 剩余精修（6 项，新会话做，每步 build + 真实验证）

  1. confType 分流：对象树接线从 checkedTmsChanged(QStringList tmIds) 换 checkedSourcesChanged(QList<DataSource>)，loadRowsAsync(projId, src.id, src.confType, 3,1,100000) 第3参传 src.confType（支持 GS 直挂 ds，现仅 TM）。改 main :~1171 对象树接线 + :~1330 第二个 checkedTmsChanged→nav 接线。
  2. dict 填充：main 创建 DatasetFieldDictionary 并传 new ColumnDrawer(centerWidget, &dict)；对每个反演 dsType 调 loadDatasetFormAsync→parseFieldMapping→dict.setFields（装置/日期筛选才生效，现 dict=nullptr 退化不筛）。
  3. 工具条接入：实例化 VtkViewToolbar 叠加中央 QVTK，信号接 sceneCtrl（viewRequested/zoom/fit 接现有 c3 对应槽 :647 区；axesSettingsRequested→弹 AxesSettingsDialog→应用坐标轴）；VE 控件迁工具条。
  4. VolumeParamsDialog 扩展：左侧勾选源 ds 树(按 GS 分组·可二次增删) + 右侧「生成位置」下拉(项目内 GS/TM，默认 源单GS→该GS/跨GS→项目根)→ 填 req.structParentId/structParentConfType。
  5. 异常迁三维体段（Task 11 本体）：给 CategorySection(voxel 段)/CategoryAnalysisTab 加异常子区 + setItemChecked/sliceRequested/sliceDelete/sliceSave 等 API（迁 Column3DAnalysis :395 refreshAnomalies 控件）；main refreshAnomalies(:~397) 改用 analysisTab。
  6. 退役旧栏：删 main 中 c3/ca 旧接线(:641/669-760 区)、col3D()/colAnalysis() 调用、Column3D* 实例；删 ColumnDrawer 的 col3D_/colAnalysis_ 成员+访问器；评估删 splitByDimension（dim2D 改轻量过滤）。
  • 切片保存/关闭(:584/623 setItemChecked)、createSlice projectId(:579/745) 随 #5/#1 一并处理。

下方为初版交接（spec/plan 设计定论，仍有效）。

1. 背景

  • 代码库 = 原版 web 系统（D:\Git\lanbingtech\commercial-admin，复刻权威）移植的 Qt6 桌面客户端。
  • 现状 VTK 视图左侧 ColumnDrawer 是三 tab（三维数据集/二维数据集/三维分析），splitByDimension 按 ddCode 分 3 维度。
  • 需求（用户截图设计）：把「三维数据集」并入「三维分析」，改成按数据类型大类分组（电阻率/视电阻率/瞬变电磁/三维体/切片），每类各自筛选+操作；对象树勾选联动、支持 GS/项目直挂数据；全局视图控制移 VTK 画布工具条。

2. 本会话已完成

  1. 摸透现状源码（ColumnDrawer/Column3D*/DatasetDimension/DatasetListPanel/ObjectTreePanel/RepoTypes/NavDto/Api3dRepository/main.cpp 接线等）。
  2. 真实接口实测定关键事实（用用户给的 token 直连后端，见 §6）——纠正了多个二手猜测。
  3. brainstorming 澄清全部设计决策（容器布局、分类策略、对象树三态交互、装置类型、生成入口等）。
  4. 产出 spec 并经 opus 子代理评审 + 据评审修订（GS 三态停 AutoTristate、properties 两接口形态澄清、帘面勾选链承接等）。
  5. 产出实施 plan（8 phase/12 task，TDD bite-sized，逻辑层完整测试代码、UI 层 build+手动验证）。
  6. 客户两轮交互确认收敛生成三维体交互（见 §3 第 5 条），同步更新 spec/openapi(v0.6)/plan。
  7. openapi 修订：三维体归属层级 TM → GS/项目根 → 再放开 GS/项目根/TM。

3. 最终设计定论（核心，已写入 spec）

  1. 两 tab：「三维分析」（5 段）+「二维分析」（现 Column2DDataset 不动）。
  2. 大类分类按 dsTypeCode（不是 ddCode）——电阻率/视电阻率/瞬变电磁三者 ddCode 同为 dd_inversion_data，只 dsTypeCode 不同。映射表 CategoryConfig 驱动；三维体/切片按 ddCode（dd_voxel/dd_slice）识别。
  3. 对象树联动：
    • 非根 GS = 三态复选框（聚合「GS 自身 ds 开关」+「子 TM 勾选」）+ 右键「选择▸ds/tm」；必须停用 Qt::ItemIsAutoTristate、手动维护三态（UserRole 存 ds 开关）。
    • 项目根 = 无复选框、直挂 ds 固定显示、其下 TM 各自二态勾选。
    • 信号 checkedTmsChanged → checkedSourcesChanged(QList<DataSource{id,confType}>)，按 structParentConfType(1=GS/项目, 2=TM) 分流 loadRowsAsync。
  4. 装置类型/采集时间筛选：是 ds 结构化属性（arrayType/collectTime），值在 ds 行 properties[]（confFieldId），经 DatasetFieldDictionary（按 dsType 拉一次 dynamicForm 取 confFieldId↔fieldCode 映射 + 装置 value→中文字典）解析。装置类型只电阻率/视电阻率段有。日期筛选按 collectTime（三维体/切片回退 createTime）。
  5. 新增三维体（客户两轮确认定稿）：
    • 入口：数据类型段头「+新增三维体」按钮（电阻率/视电阻率/瞬变段），不在对象树/容器节点右键。
    • 源数据集 = 三维分析中当前勾选的同类型 ds（本段类型、可跨 GS）。
    • 点击 → VolumeParamsDialog：左侧树状（按 GS 分组）展示勾选源、可勾选/取消供确认或二次修改；右侧参数：名称、生成位置下拉、插值模型、水平/竖向间距、IDW 幂次、最大影响距离。
    • 生成位置（归属）：默认 = 源同属单 GS→该 GS、源跨 GS→项目根；用户可改为项目内任意 GS/TM（structParentConfType 1 或 2）。源与归属解耦。
  6. VTK 画布工具条：全局视图控制（坐标轴/比例/快捷视图/缩放）移到中央 VTK 竖排工具条；设置→AxesSettingsDialog(X/Y/深度 显示+min/max)；快捷视图按钮文字「前/后/上/下/左/右」；复位=现「适配」。
  7. 请求体 DTO：createVolume/createSlice 扩参，内部按 VoxelGenerateRequest/SliceGenerateRequest 组装真实请求体结构（仍 mock 存储、假 id），toJson 序列化；重构落地即可从 UI 产出给后端联调的真实请求体。
  8. 三维体/切片/异常仍 Api3dRepository mock；异常迁入三维体段。

4. 剩余工作 = 执行 plan

plans/2026-06-24-vtk-category-view-refactor.md，8 phase/12 task，依赖顺序：

  • Phase 1-2（Task 1-3）：DsRow 扩展+parseDsRows / CategoryConfig+splitByCategory / 请求体 DTO —— 纯逻辑完整 TDD。
  • Phase 3-4（Task 4-6）：GS 三态状态机+checkedSourcesChanged / DatasetFieldDictionary —— 逻辑可单测。
  • Phase 5-6（Task 7-9）：CategorySection / CategoryAnalysisTab+ColumnDrawer / VtkViewToolbar+AxesSettingsDialog —— build+手动验证。
  • Phase 7-8（Task 10-12）：Api3d 扩参组装请求体 / 段重组(异常迁三维体段) / main.cpp 接线总成 + 退役 Column3DDataset/Column3DAnalysis。

建议：subagent-driven（每 task 新 subagent + task 间两阶段 review）+ 独立 git worktree 隔离。每 task 自带测试/验证+commit；Phase 间「新旧信号并存→Task 12 统一切换删旧」保证每次可编译。

plan 中 Task 7 段头按钮 + Task 12 VolumeParamsDialog 扩展（左侧源列表二次增删 + 生成位置下拉）已按 §3.5 定稿写好。

5. 待确认 / 风险

  • 装置类型 value→中文 字典源（唯一待坐实，不阻塞实现）：实测 arrayType 原始值（如 1429468249448449）不在该字段 optionsObject（另一套 id 1456095451258368…）里；parseDynamicForm:208 也不翻译；但用户说客户端属性面板显中文。Task 6 先用 optionsObject 建表 + 缺失回退原值。需用户提供客户端数据集属性面板截图以定位现有翻译路径（候选：fieldConfigJsonObject.fieldDataRadius 指向的全局字典 / script/arrayTypeList）。
  • 段体容器树建法（Task 7 核心）：段体要呈现「项目根/GS/TM 容器节点→ds」层级，需 main 传 setStructure（对象树同源 StructNode）+ ds 的 structParentId/structParentConfType（Task 1 已解析）建容器节点。
  • 三维体/切片/异常仍 mock；后端就绪后切真实（I3dSceneRepository 留缝，见 HANDOFF-vtk-3d-backend-api.md）。

6. 关键实测事实 + 接口（直连后端核实）

  • 后端基址 http://tenant.geomative.cn/pop-api；header geomativeauthorization: Geomative <token>（token 本会话由用户提供，下会话需重新索取）。
  • 样本项目「演示项目（高密度+瞬变）」1438889436225536：项目根 GS 1438889436291072 下直挂 TM（ERT1-8 confCode=ERT、TEM1-15 confCode=TEM01），无中间 GS 层（印证「项目根本质是 GS」「TM 可直挂项目根」）。
  • 大类 dsTypeCode：电阻率=ERT platform inversion data、视电阻率=visual resistivity data、瞬变电磁反演剖面=DD TRANSIENT ELECTROMAGNETIC INVERSION（三者 ddCode 同 dd_inversion_data）。
  • ds 行 properties（dsObject/data/page）= [{confFieldId,value}] 数组；dynamicForm 的 properties = {fieldCode:value} map（两接口形态不同，勿混）。
  • 装置类型字段 arrayType、采集时间 collectTime（fieldCode）；装置枚举 GET /business/script/arrayTypeList → [{itemValue,name}]（15 项）。
  • 层级 structParentConfType：1=GS/项目根，2=TM；loadRowsAsync 第 3 参即透传它（现状 main.cpp:1142 写死 2）。
  • 详情接口 dsObject/getDetail/{id}、动态表单 dsObject/dynamicForm/{id}（客户端 loadDatasetFormAsync→parseDynamicForm）。

7. 代码地图

现状关键文件（重构基础）：

文件 作用
src/app/panels/columns/ColumnDrawer.{hpp,cpp} 现三 tab 容器（→两 tab）
src/app/panels/columns/Column3DDataset/Column3DAnalysis/Column2DDataset 三栏现状（前两退役、二维不动）
src/app/DatasetDimension.{hpp,cpp} splitByDimension（→splitByCategory 替代）
src/app/panels/DatasetListPanel.cpp populateDatasetList/卡片委托/applyDatasetFilter（复用）
src/app/panels/ObjectTreePanel.{hpp,cpp} 对象树（GS:123 AutoTristate、:174 itemChanged、:207 右键）
src/data/repo/RepoTypes.hpp DsRow（扩 dsTypeCode/properties/structParent*）
src/data/dto/NavDto.cpp parseDsRows:116 / parseDynamicForm:179
src/data/api/Api3dRepository.{hpp,cpp} 三维体/切片/异常 mock（createVolume/createSlice 扩参）
src/data/repo/VolumeBuildParams.hpp / src/core/model/Anomaly.hpp 三维体参数 / 异常模型
src/app/main.cpp 接线（:388-460 异常/勾选、:1113-1225 对象树→分类分发）
src/data/api/ApiProjectRepository.cpp loadRowsAsync parentConfType 透传

新建（plan §文件结构）： CategoryConfig.hpp、DatasetCategory.{hpp,cpp}、Vtk3dRequests.{hpp,cpp}、DatasetFieldDictionary.{hpp,cpp}、CategorySection.{hpp,cpp}、CategoryAnalysisTab.{hpp,cpp}、VtkViewToolbar.{hpp,cpp}、AxesSettingsDialog.{hpp,cpp} + 对应 tests。

契约文档： docs/api/vtk-3d-openapi.json（v0.6-draft）、真实 schema docs/apis/business_OpenAPI.json（DsObjectDataVO/DsTypeVO/ArrayTypeVO）。

8. 铁律 / 注意

  • 贴源码/实测，别凭印象：本会话多次因二手猜测（"装置类型要后端补字段"、"properties 形态矛盾"、归属层级）被用户/实测纠正——任何字段/语义先去代码或真实接口核实。
  • 复用优先：DatasetListPanel/Api3dRepository/Column2DDataset 复用，不重写。
  • 每 task TDD + 可编译 + commit；不留 TODO 占位。
  • 全部回复中文。

9. 相关

  • spec：docs/superpowers/specs/2026-06-24-vtk-category-view-refactor-design.md
  • plan：docs/superpowers/plans/2026-06-24-vtk-category-view-refactor.md
  • 后端契约交接：docs/superpowers/HANDOFF-vtk-3d-backend-api.md（三维体/切片/异常端点）
  • 记忆：vtk-3d-persistence-structure、dataset-detail-types-catalog、web-3d-view-threetile、gpr-volume-design-trio
  • 提交：eceb964（spec+openapi v0.5）、ef10c35（plan + 客户变动 + openapi v0.6）