重构(UI): 统一组件协议 + 去手写链路 + 大文件按职责拆分 + 代码审查 + 剥离 Tools
## 1. 新增 UiComponent 顶层组件协议（不是负优化）
Components/Shared/Inc/UiComponent.hpp：纯接口、无状态，8 个方法
SetScale / Layout / Area / Paint / HitTest / OnMouseLeave / IsEditing / QueryCursor。
Toolbar / TabBar / SignalPanel / PlotView 本来就各自拥有完全同名同签名的成员，
因此改造 = 加 override + 补 Area()（PlotView 另加一个非 const 的 QueryCursor 转发，
因为它自己的查询会惰性建立行缓存），实现代码零改动、静态派发、体积无增长。
刻意不把 UiWidget 当作它的基类：UiWidget 是"树节点"（父给尺寸、父下探脏区、
命中沿树链派发），而 PlotView（4 层位图缓存）/ SignalPanel（行位图缓存）是
"地盘宿主"。强行上树会推翻"父脏则子全脏"的前提，历史上正是这类耦合导致过
"后台渲染覆盖平移结果""命中矩形错位"的事故。头文件里已写明这条理由。
Toolbar/TabBar 是两者的交集：对外实现 UiComponent，对内持有一棵 UiWidget 树。
## 2. 宿主侧：四条手写链 -> 组件表
Application 新增 ComponentEntry{ component, target, chrome } 与 m_components
（底->顶：plot -> panel -> toolbar -> tabBar），BuildComponentTable() 装配一次。
- ApplyDpi 6 行逐个 SetScale -> 1 个循环
- Relayout 手算三列 x 坐标 -> UiStackRects(内容区, HORIZONTAL, {panelW, splitW, AUTO})
- WM_MOUSELEAVE 逐个 OnMouseLeave -> 循环累积 chromeChanged / plotChanged
- WM_SETCURSOR if/else if 链 -> 从表尾向前找首个命中者，取其 QueryCursor
顺带兑现历史缺口：UiLayout::UiStackRects 自引入以来第一次有了生产调用点。
有意保留显式的三条链（WM_LBUTTONDOWN / WM_LBUTTONUP / WM_MOUSEMOVE）：它们各自带
组件专属后置动作（提交重命名、构建派生信号、面板联动滚动、更新拖拽光标、
plotOnlyMove 决定局部失效还是整帧失效）。塞进表里只能靠 lambda 字段，
可读性反而下降 —— 属于用户明确禁止的"过度抽象"，因此不做。
## 3. 大文件按职责拆分（纯整函数搬移，逐像素 0 差异）
SignalPanelInteraction.cpp 2329 -> 831 行，拆出：
SignalPanelEdit.cpp 616 内联编辑（筛选框、组名/信号名、数值、颜色与透明度）
SignalPanelScroll.cpp 205 动画与滚动（折起、联动滚动、滚动到目标信号）
SignalPanelMenu.cpp 527 弹出菜单（系数/偏移、镜像、右键菜单与命令回执）
Shared/PopupMenu.cpp 1901 -> 706 行，拆出：
PopupMenuLayout.cpp 753 尺寸测量、项矩形排版、滚动可见性
PopupMenuPaint.cpp 397 背景/阴影/项绘制
Inc/PopupMenuInternal.hpp 103 pmdetail 常量 + inline 辅助（跨 TU 安全）
拆分判据是"职责"而非行数；共享常量一律收敛到 *Internal.hpp。
## 4. 代码审查（修 5 处）
- SignalPanelInteraction.cpp 头注释仍写"4 片"，实际 6 片 -> 改为完整清单
- PopupMenuLayout.cpp 机械搬移时把构造函数一起搬走 -> 重复定义，只保留在交互分片
- PopupMenu.cpp 的 #include "PopupMenuInternal.hpp" 落进 namespace jdi 内 -> 移到文件头
- PopupMenuPaint.cpp 缺 UiControls.hpp（UiDrawEditFieldContent 未声明）-> 补 include
- 全仓复查历史删除符号残留引用（m_paintPlot / ClampCursorsAfterPan /
PaintFreeMarkerTooltip / CaptureDecorCache / FitSinglePointSignal / CsvTable /
DataFile / .preflight / structcheck）-> 零命中
## 5. Tools/ 剥离
git rm -r --cached Tools + .gitignore 新增 Tools/（本地文件保留，可随时复跑）。
ui_refactor 分支为全本地分支，另做 filter-branch 清除历史中的该目录。
## 6. 验证
- make release / make debug：零 error 零 warning
- rendercheck：A-H 八个场景哈希与改造前逐一相同
(A 2166933039626F66 B C444ECFEB18FD73D C 7984446D8E7A4418 D BF855879CA12F289
E 1C663E4118616016 F 0535292D8E07AE18 G 7A58172C46577729 H 23F390DD76141113)
FUNC 7/7 PASS
- uicheck：69 passed, 0 failed
- TargetCheck.exe 891,392 B（< 900 KB 阈值）
## 7. 文档
Documents/UI_Refactor_Plan.md / UI_Refactor_Progress.md / UI_Refactor_Report.md
新增第五阶段章节；Documents/agent_mem.md 同步变更日志与「第七轮」硬约束。
This commit is contained in:
DeepSeek V4.1 Flash committed
1 parent
675c2a5f54
commit
0ec8055e95
20 files changed
+3287
-2678
No files matched your search
@@ -202,3 +202,81 @@ Tools/uicheck/uicheck.exe
|
||||
| 布局重复计算 | ⚠️ 小幅（`EdgePanelLayoutFor` 19 个调用点，待 P4 落地后才吃到 1~3ms/帧） |
|
||||
| 拖拽/缩放帧耗时（45~80ms 那部分） | ❌ 不改善：瓶颈是 GDI+ 光栅化的像素量，架构不改变"要画多少像素" |
|
||||
| 派发开销 | ❌ 不改善：µs 级，占预算 <0.1%；控件树改善的是**正确性**不是帧时间 |
|
||||
|
||||
---
|
||||
|
||||
# 第五阶段（2026-10-28）：统一组件协议、去手写链路、按职责拆分
|
||||
|
||||
## 1. 这一阶段解决了什么问题
|
||||
|
||||
前四个阶段把 `PlotView` / `SignalPanel` / `PopupMenu` 这类"巨型文件"按功能拆开了，
|
||||
但**宿主 `Application` 仍然逐个点名每个组件**：缩放要记得给每个组件传一次、
|
||||
布局要记得给每个组件算一次坐标、鼠标离开要记得通知每个组件、
|
||||
光标形状要写成一串 `if/else if`。每加一个顶层组件，就有四处必须同步修改——
|
||||
漏掉任何一处都是"改了但没反应"的静默 bug。
|
||||
|
||||
本阶段把这个"人肉登记表"换成**真正的登记表**。
|
||||
|
||||
## 2. 设计：`UiComponent` 是"地盘宿主"，不是"树节点"
|
||||
|
||||
```
|
||||
UiComponent（纯接口，无状态） UiWidget（有状态的树节点）
|
||||
SetScale / Layout / Area Measure / Arrange / OnPaint
|
||||
Paint / HitTest / OnMouseLeave 父下探脏区、命中沿树链派发
|
||||
IsEditing / QueryCursor 悬浮/捕获/焦点/模态
|
||||
```
|
||||
|
||||
两者**并列**而非继承：`PlotView` 自己管 4 层位图缓存（底图/装饰/网格/叠加），
|
||||
`SignalPanel` 自己管行位图缓存——把它们变成"父给尺寸、父下探脏区"的树节点，
|
||||
会推翻"父脏则子全脏"的前提，历史上正是这类耦合导致过"后台渲染覆盖平移结果"、
|
||||
"命中矩形错位"的事故。
|
||||
|
||||
`Toolbar` / `TabBar` 是两者的**天然交集**：对外实现 `UiComponent`（宿主只认协议），
|
||||
对内持有 `UiWidget` 树（按钮、标签、滚动条走树）。这条分层让"小型控件复用树的派发能力"
|
||||
与"大型组件保留自己的渲染策略"可以并存。
|
||||
|
||||
**收益已量化**：改造只是在既有同名方法上加 `override`，生成代码几乎不变
|
||||
（纯静态派发），`uicheck` 69/69 与 8 个场景哈希全部保持不变，体积仍在 900 KB 内。
|
||||
|
||||
## 3. 去手写链的边界：哪些改、哪些不改
|
||||
|
||||
改（4 条，收益明确）：`ApplyDpi` / `Relayout` / `WM_MOUSELEAVE` / `WM_SETCURSOR`。
|
||||
|
||||
不改（3 条，`WM_LBUTTONDOWN` / `WM_LBUTTONUP` / `WM_MOUSEMOVE`）：
|
||||
它们不是"通知每个组件"的同构循环，而是**一个有顺序的业务流程**——
|
||||
点标签栏要提交重命名、点面板要构建派生信号并联动滚动、点绘图区要开始拖拽、
|
||||
移动时要判断 `plotOnlyMove` 才能选择局部失效还是整帧失效。
|
||||
把这些塞进表里只能靠 lambda 字段，阅读成本反超收益。**刻意保留显式代码。**
|
||||
|
||||
## 4. 拆分的度量
|
||||
|
||||
拆分判据换成"职责"之后，每个文件的定位能用一句话说清：
|
||||
|
||||
| 文件 | 一句话职责 |
|
||||
| --- | --- |
|
||||
| `SignalPanel.cpp` | 状态、行集合、布局与几何 |
|
||||
| `SignalPanelPaint.cpp` | 把状态画成像素（含行位图缓存） |
|
||||
| `SignalPanelInteraction.cpp` | 坐标 → 语义（命中、派发、光标） |
|
||||
| `SignalPanelEdit.cpp` | 内联编辑的生命周期 |
|
||||
| `SignalPanelScroll.cpp` | 动画与滚动联动 |
|
||||
| `SignalPanelMenu.cpp` | 弹出菜单与其命令回执 |
|
||||
|
||||
`PopupMenu` 同理：`Layout`（几何）/ `Paint`（像素）/ `PopupMenu.cpp`（交互）。
|
||||
纯搬移 + 逐像素哈希校验，保证"重构不改行为"。
|
||||
|
||||
## 5. 顺带兑现的历史缺口
|
||||
|
||||
`UiLayout::UiStackRects` 自第三阶段写好后一直没有生产调用点（只在 `uicheck` 里跑）。
|
||||
本轮 `Relayout` 的内容区三列切分改用它，**布局库终于有了真实使用场景**，
|
||||
也顺手删掉了一段手算坐标。
|
||||
|
||||
## 6. 遗留与建议
|
||||
|
||||
1. `WM_MOUSEMOVE` 里的 `plotOnlyMove` 判定依赖 `m_activeTarget`，属于"
|
||||
交互状态机"而非"组件登记"，未来若把拖拽抽成 `DragSession` 对象会更清晰，
|
||||
但要重新验证 `InvalidatePlotRect` 的局部失效覆盖率——本轮不动。
|
||||
2. `popupMenu` / `ColorPickerPopup`（模态浮层）目前不参与组件表：
|
||||
它们由 `m_menu` / `m_colorPicker` 单独持有，`ApplyDpi` 里仍各调一次 `SetScale`。
|
||||
若以后浮层数量增加，可给它们一个"浮层表"，但两个成员值不值得抽象——存疑。
|
||||
3. `Tools/` 已剥离；若将来要把它作为**对外可复现的验证资产**，建议单独开一个
|
||||
`qa/` 目录并显式加入版本控制（同时更新 `.gitignore` 的例外规则）。
|
||||
Reference in new issue
Block a user