geopro/docs/superpowers/plans/2026-06-09-elawidgettools-migration.md

# geopro_desktop → ElaWidgetTools (Fluent) 迁移计划

**分支**：`feat/elawidgettools`　**日期**：2026-06-09　**决策**：全面 Ela 化（最彻底），支持明/暗主题。
**前置评估已完成**：spike(`spike/ela/`) 证明 ElaWidgetTools(RainbowCandyX fork) 可用官方 Qt 6.11.1 + MSVC 经 FetchContent 构建，ElaWindow + ADS 内嵌 + QVTK 渲染均可行；ElaTheme 明暗切换可用，但**只自动覆盖 Ela\* 控件与 ElaWindow 外壳**，标准 QWidget/ADS/VTK 需手工主题联动。

---

## 0. 硬前提（动手前必须满足）

- **P0-a　清理 C: 盘**：当前 C: 0 GB 可用，链接器写 `%TEMP%` 失败（`LNK1108`）。迁移需大量构建验证。需用户清理 C:；我同时把 `TEMP/TMP→D:` 兜底固化进 `build.bat`，避免反复手动重定向。
- **P0-b　验证靠用户**：每阶段我构建通过后，用户运行 + 截图，我据反馈迭代（登录门槛 + GUI，我无法目视）。
- **P0-c　回退保障**：全程保留 `GEOPRO_UI_SHELL=classic|ela` 环境变量开关，可在「现 QMainWindow 壳」与「ElaWindow 壳」间切换，便于 A/B 与回退；迁移稳定后再移除。

## 1. 依赖固化（P0 工程）

- ElaWidgetTools 从 spike 提升为**正式依赖**：`FetchContent` 的 `GIT_TAG` 由 `main` **钉到具体 commit**（可复现）。
- **静/动态**：先静态（MIT，省 DLL）；若遇静态资源（字体/SVG 图标 .qrc）被剥离导致图标缺失，改动态（`ELAWIDGETTOOLS_BUILD_STATIC_LIB OFF` + DLL 随 `TARGET_RUNTIME_DLLS` 拷贝）。
- **插件部署**：把 `platforms / styles / imageformats / iconengines`（含 SVG 图标用的 `qsvg`/`qsvgicon`）部署接进 `geopro_desktop` 的 post-build（今天 spike 是手动拷的，要正式化；windeployqt 会被 ADS 的 DLL 依赖卡住，改为显式 copy Qt plugins）。

## 2. P1 — 换壳（带开关）

- 新建 `ElaShellWindow`（继承 `ElaWindow`）或在 `main()` 分支构造。把现有 `buildWorkbench()` 产出的中心内容（ADS `CDockManager` + 工具条）作为 ElaWindow 的一个 page/central content 挂入（`addPageNode` / `setCentralCustomWidget`）。
- `eApp->init()` 在 `QApplication` 后调用；保留高 DPI 与 QVTK surface format 设置顺序。
- **dock 持久化注意**：ElaWindow 接管后，`restoreState` 后重隐藏 ADS 标题栏的时序修复（已在主分支）需在新壳下复核。
- **验收**：`GEOPRO_UI_SHELL=ela` 启动 → 登录 → 工作台；ADS 停靠可拖动；中央/详情 VTK 正常；导航/标题栏 Fluent 外观。截图确认。

## 3. P2 — 主题桥（明/暗覆盖所有非 Ela 面）

- 新建 `ThemeBridge`：监听 `ElaTheme::themeModeChanged`，把明/暗同步到：
  1. **全局 QSS**：把 `Theme.cpp` 的 `kStyleSheet` 拆成「明」与「暗」两版（用已有 `type/space/radius/semantic` 令牌派生暗色盘），按主题切换。
  2. **ADS 停靠区**：`CDockManager::setStyleSheet` 明/暗两套。
  3. **VTK 背景**：中央 + 详情 renderer 背景随主题切深/浅底并 `Render()`。
  4. **内联样式面板**：PanelHeader / TopBar / LoginWindow / main 浮层 的内联 QSS 改为「跟随主题」（去硬编码色，引用桥提供的明/暗令牌）。
- **暗色盘设计**：在 `Theme.hpp` 增加暗色语义（surface/ink/border/accent 的暗版），保持品牌蓝在暗底的可读性与对比度（≥4.5:1）。
- **验收**：明/暗一键切换，全界面（外壳+停靠+面板+VTK）协调一致、无残留亮/暗块；对比度达标。截图明、暗各一。

## 4. P3 — 全面控件 Ela 化（工作量主体）

逐面替换标准控件为 `Ela*` 等价物，"白嫖"明暗与 Fluent 观感。映射（精确 Ela 类名在实施时按头文件确认）：

| 现状 | → Ela 等价 | 所在 |
|---|---|---|
| QPushButton | ElaPushButton | LoginWindow / 各处 |
| QLineEdit | ElaLineEdit | LoginWindow / ProjectListDialog 过滤 |
| QCheckBox | ElaCheckBox | LoginWindow / 图层浮层 / 异常列表 |
| QComboBox | ElaComboBox | ProjectListDialog / 全局 |
| QLabel(文本) | ElaText | 各处文本/标题 |
| QToolButton(Tab/操作) | ElaToolButton / ElaIconButton | PanelHeader / TopBar |
| QMenuBar / QMenu | ElaMenuBar / ElaMenu | TopBar |
| QTreeWidget | ElaTreeView(+model) 或保留+主题联动 | ObjectTreePanel |
| QListWidget | ElaListView(+model) 或保留+联动 | Dataset/Anomaly 面板 |
| QTableWidget | ElaTableView 或保留+联动 | ProjectListDialog |
| QProgressBar | ElaProgressBar | 全局 |
| QStatusBar | ElaStatusBar 或保留+联动 | main |
| QTabWidget/分段 | ElaTabWidget / ElaToggleSwitch | PanelHeader 数据/文件 |
| QDialog(登录) | ElaWidget/ElaWindow 风格弹窗 | LoginWindow |
| **保留(无替代)** | QVTKOpenGLStereoWidget、ADS CDockManager | 中央/详情/停靠 |

- 树/列表/表若用 Ela 的 View 需改 model（成本高），可分两步：先保留 widget 版做主题联动，后续再评估换 View。
- 登录窗重做为 Fluent 风格（沿用现有令牌与文案）。

## 5. P4 — 收尾

- 插件部署正式化、ElaWidgetTools 版本锁定、静态资源核验。
- 去掉 `GEOPRO_UI_SHELL` 过渡开关（确认稳定后）。
- 开源声明：ElaWidgetTools(MIT)、ADS(LGPLv2.1)、Qt(LGPL) NOTICE 归集。
- 回归：登录、项目切换、对象树、数据集/文件分页、异常、VTK 各视图、dock 持久化。

## 风险登记

| 风险 | 缓解 |
|---|---|
| Qt 6.11 Windows Popup 渲染（作者红旗） | spike 已初验；P1 重点复核菜单/下拉/提示；必要时打 fork 的条件补丁 |
| ADS 在 ElaWindow 内主题/交互异常 | spike 已验内嵌；P2 专门做 ADS 明暗 QSS |
| Ela View 需 model 重写（树/列表/表） | 分步：先 widget 版主题联动，再评估换 View |
| 静态库资源剥离（图标/字体缺失） | 改动态库 |
| 我无法目视 | 每阶段用户运行+截图验收 |
| C: 满导致构建反复失败 | 清理 C: + TEMP→D: 固化进 build.bat |
| 大重构回归 | 全程 env 开关可回退；主分支零影响 |

## 执行顺序

P0 → P1（验收）→ P2（验收）→ P3（按面板分批，每批验收）→ P4。每步构建通过后由用户运行+截图确认再进下一步。