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。每步构建通过后由用户运行+截图确认再进下一步。