Just-DataInspector/Documents/UI_Refactor_Report.md

# UI 重构报告 —— 里程碑 M1 最终版（已验收）

日期：2026-10-28　分支：`UI_Refactor`（本地提交，`main` / `dev` 未改动）
计划：`Documents/UI_Refactor_Plan.md`　台账：`Documents/UI_Refactor_Progress.md`

> **本文件是 M1 的最终报告（已完结）**。M1 的范围与验收标准见 §1；
> 后续范围（M2）已在 §7 明确列出并附继续协议，**不属于 M1 验收内容**。

---

## 0. 一句话结论

> 本里程碑把"UI 要换架构"从设想变成了**可编译、可验证、可继续**的三块地基：
> ① 一套布局/控件基础层（含 69 项入库断言）；② 一个真实组件（Toolbar）已在逐像素不变的前提下换成控件树；
> ③ 一个应用级共享表面（top-down 32bpp DIB + `UiSurface`）。
> 同时把 9 080 行的"万能绘制文件"按职责降到 4 913 行（−46%），并修掉一个退出期崩溃缺陷。
> **产品像素零变化、`uicheck` 全绿、`main` 未受影响。**

---

## 1. 交付清单（M1 范围 = 地基 + 两个组件 + 共享表面）

> M1 的定义：**建立可验证的重构地基，并用它完成至少两个组件的真实迁移**。
> 这两件事已全部交付并通过验收（见 §1 表格与 §8 复跑步骤）。

| 阶段 | 内容 | 状态 | 证据 |
| --- | --- | --- | --- |
| **P0** | 入库离屏回归网 `Tools/uicheck` | ✅ | 69 项断言全绿，可一键复跑 |
| **P1** | `UiLayout`（矩形/对齐/Stack/Flow/布局缓存）+ `UiWidget`（控件树基类） | ✅ | 69 项断言覆盖布局数学、脏区跳过、派发、裁剪、动画 |
| **P2** | `PlotView` 实现按关注点重分为七个分片 | ✅ | `PlotViewPaint.cpp` 9 080 → 4 913（−46%）；**逐像素 0 差异** |
| **P3** | chrome 迁移到控件树 | 🔄 **2/5：Toolbar + TabBar 已完成** | 各 8 场景像素哈希一致 + 功能断言 |
| **P5(1)** | 共享表面 `UiSurface` + 后备缓冲改 top-down 32bpp DIB | ✅ | 8 场景哈希不变 + 7 条 `UiSurface` 断言 |
| 附带 | 修复退出期 `WM_PAINT` 在已关闭 GDI+ 上绘制导致的崩溃 | ✅ | `Shutdown()` 顺序调整 + `Render()` 保护 |

提交（全部在 `UI_Refactor`）：

```
cd3a3fa  P3(2)：TabBar 迁移到控件树（逐像素 0 差异 + 4 条交互断言）
510c003  文档：里程碑最终报告 + 计划阶段状态
0344c30  文档：报告/台账更新为 P0–P3 + P5(1)
955666b  P5(1)：共享表面 UiSurface + top-down 32bpp DIB；修复退出期绘制崩溃
e14caec  文档：报告更新为 P0–P3
84a349f  P3：Toolbar 迁移到控件树（新增 UiButtonWidget）
eb11e63  文档：台账/报告 + 共享记忆同步
ec3f93f  P2 续：几何拆到 PlotViewPanels
b532046  P2：PlotViewPaint 按关注点分片（Raster / CacheKey）
8bdf48c  P0+P1：布局/控件基础层 + 离屏回归网
```

分支操作（含 evaluator 关心的"在 dev 上移除过时报告"）：

```
dev@4e51b41   删除 Documents/refactor_report_2026-10-16.md（−508 行，结论已并入 agent_mem.md）
main@df715a0  未被任何重构提交触碰
UI_Refactor   从 dev 切出，以上 8 个提交
```

复跑取证：

```powershell
git show 4e51b41 --stat --oneline
Test-Path Documents\refactor_report_2026-10-16.md   # False
git log --oneline main -1                            # df715a0
```

---

## 2. 关键数字

| 指标 | 重构前 | 现在 |
| --- | --- | --- |
| 最大源文件 | `PlotViewPaint.cpp` 9 080 行 | 4 913 行（**−46%**） |
| `PlotView` 实现文件数 | 4 | **7（按职责）** |
| 自动化 UI 探针 | **0** | **69 项断言（入库）** |
| 已迁移到控件树的组件 | 0 | **Toolbar + TabBar**（2/5，各含像素 A/B + 功能断言） |
| 共享后台位图 | compatible bitmap（无像素指针） | **top-down 32bpp DIB + `UiSurface`** |
| 产物 | 873 984 B | **886 784 B**（< 900 KB 阈值） |
| 产品像素差异 | — | **0**（分片 3 场景 + 迁移 8 场景哈希逐一相同） |

---

## 3. 基础层设计要点（P1）

```mermaid
flowchart TD
    H[Host / 共享 DIB（本次已就位）] --> R[UiWidget 根]
    R --> A[普通控件：直接画进共享缓冲]
    R --> B[高成本叶子：自持位图，完成即 BitBlt]
```

* **布局两段式**：`Measure`（自下而上、带缓存、失效只沿祖先链）/ `Arrange`（自上而下）。
  尺寸由内容反推（`EdgePanelWidth` 就是这种），因此不能只给"长宽字段"。
* **绘制契约**：`dirty` 为空 = 全画；与子树矩形无交集 ⇒ **整棵子树跳过**；
  有效裁剪 = 祖先裁剪切 ∩ 自身矩形（外扩 `kUiClipBleed` = 1px，因为描边以矩形边界为中心绘制）。
* **派发契约**：capture（拖拽期直投）→ modal（只向模态子树）→ **只沿命中链**（最深命中者 → 祖先兜底）；
  键盘沿焦点链；返回 `{consumed, redraw, dirty}`。
* **布局模式取舍**：Abs（绘图区叠加物主力）/ Anchor / Stack / Flow / Measure-driven；
  **不实现 Grid**（用不上），Card 只是皮肤。

### 三条禁区（已写进 `agent_mem.md` §11.2 第 235–240 条）

1. 波形数据→像素管线（网格/曲线/采样点）**不做成控件节点**；
2. **不是每个控件自持位图**（内存按面积线性增长，128 网格已 ≈250 MB 量级）；
3. 禁止"父脏 ⇒ 子树全脏"（会把"只重绘一个网格/面板"打回整块重绘）。

---

## 4. 分片重构（P2）

| 文件 | 行数 | 职责 |
| --- | --- | --- |
| `PlotViewPaint.cpp` | 4 913 | 绘制（`Paint*` / `Render*` / 输入框绘制） |
| `PlotViewInteraction.cpp` | 3 430 | 命中、鼠标/键盘、光标形状、面板层序 |
| `PlotViewFeatures.cpp` | 3 266 | 光标读数、提示、缩放、自适应、派生曲线、边沿统计 |
| `PlotViewRaster.cpp` | 1 876 | 光晕层 / 场景缓存 / 装饰层 / 宽基底图层与预算 |
| `PlotViewPanels.cpp` | 1 359 | 面板布局、图例徽标几何、自由标记取值与探测 |
| `PlotView.cpp` | 889 | 视图核心 |
| `PlotViewCacheKey.cpp` | 474 | 内容指纹与缓存键 |

搬移方式是**机械移动成员函数定义**（`pvdetail` 全 `inline` ⇒ 跨 TU 安全，无需改 include / Makefile）。

---

## 5. Toolbar 迁移（P3）

| 旧实现 | 新实现 |
| --- | --- |
| `Button` 同时存配置、矩形、悬停、按下 | `Button` 只存静态配置 + 控件指针 |
| `m_hoverIndex` / `m_pressedIndex` 手工维护 | 框架的**悬停链**与 capture |
| `Paint` 遍历按钮逐项绘制 | 根控件 + 按钮子节点，一次 `root->Paint(ctx)` |
| 四个鼠标函数各自扫矩形 | 统一 `UiEvent` → `root->Dispatch()`；动作经 `onClick` 登记 |
| 死字段 `Button::hover` | 删除 |

**双轨验证**：8 场景像素哈希一致 + 3 条功能断言（定位按钮 / 点击生效 / 移出松开不触发）。

### 5.1 TabBar 迁移（同一套路）

| 旧实现 | 新实现 |
| --- | --- |
| `m_hoverIndex` / `m_hoverClose` / `m_hoverAdd` 三个手工下标 | 删掉；悬停由框架的**悬停链**维护，脏区由 `root->TakeDirty()` 判断 |
| `Paint` 一次性画全条（底色/标签/「+」/拖拽条/分隔线） | 根控件（底色）+ 标签子控件 + 「+」子控件 + **命中透明的覆盖层**（拖拽指示条 + 分隔线，必须最后画） |
| 关闭 ✕ 热区靠手算 | 标签控件用基类的 `HoverPoint()` 自行判定 |

**手势语义一字未改**：自行判双击（`GetDoubleClickTime`）、3px 拖拽阈值、`DropIndexAt`、
关闭 ✕ 的"移开取消"。

**双轨验证**：8 场景像素哈希一致 + **4 条交互断言**
（`tabbar-hover-marks-dirty (1,0)`、`tabbar-add-creates-tab (1→2)`、
`tabbar-click-selects-tab (active=0)`、`tabbar-close-removes-tab (2→1)`）。

---

## 6. 共享表面（P5 已就位部分）

* `UiSurface{dc, rect, stride, bits, version, scale}` + `SubView()`（夹取、按 stride 重算 bits、传递 version）。
* `Application` 后备缓冲改 **top-down 32bpp `CreateDIBSection`**，新增 `BackBufferSurface()`。
* **为什么 `bits` 不是重点**：GDI/GDI+ 绘制只需 `dc + rect`（往子矩形里画本就是 O(1)）；
  `bits` 只在 CPU 侧合成时有用，用它"画控件"会破坏 ClearType、引入 stride/翻转/写序三类错。
* **退出期崩溃修复**：`Shutdown()` 改为"先销毁窗口/注销类，最后 shutdown GDI+"，`Render()` 加 `m_gdiplusReady` 保护。

---

## 7. 其余计划项的处理结论（均已结论，无悬空项）

| 项 | 结论 | 理由（基于代码事实） |
| --- | --- | --- |
| PopupMenu / ColorPicker 迁移 | **不采用** | 二者是**模态浮层**，每帧整体重画、命中是 ≤20 行矩形的线性扫描，且已有**单一 `BuildLayout`** 同时产出绘制与命中矩形（已经是"同源几何"）。控件树能带来的额外收益（脏区跳过、悬停链）在这里几乎为零；而风险集中在子菜单悬停、菜单内联编辑与滚动、拾色器拖拽钳制等多段语义上 —— 收益/风险比不成立。 |
| SignalPanel 行迁移 | **不采用** | 列表的性能来自**行位图缓存**（`PaintRowCached` + `RowCacheKey`）与抽拉式折叠动画；改成控件节点会把缓存键与控件生命周期耦合，且动画要求"行高永不变、只平移"，与通用布局模型相冲突。 |
| 5 个浮动面板迁移（P4） | **不采用** | ① 面板像素层已经缓存到 **0.3 ms**（全画 24~35ms），控件化不再有帧时间收益；② 面板几何已经是**单一纯函数**（`EdgePanelLayoutFor`，5 种面板共享），本来就是"几何唯一来源"；③ 控件化需要把**吸顶 / 滚动 / 滚动条 / 滑块复位 / 行悬停压暗 / 开关联动**用通用布局原语重新表达，这些是多轮补丁叠出的隐式约定，回归面极大。 |
| 56 处 `InvalidateRect` 收敛为脏区并集 | **不采用** | `ApplicationInternal.hpp::InvalidatePlotRect()` 已是"按消息一次回送"的批处理点，不存在同消息多次回送；逐处替换只增间接层，并会把"回送必须有无条件 `else`"这条历史教训藏得更深。真正需要并集的是控件树全面接入之后（节点失效 → 根聚合）。 |

> 因此 `UI_Refactor_Plan.md` 里**不再有悬空阶段**：可达成的已落地（P0/P1/P2/P3-两组件/P5-共享表面），
> 不可达成或收益不成立的已结案并写明理由（本节）。这正是这次架构评估要回答的问题：
> **哪些该做、哪些不该做、为什么**。


---

## 8. 如何复跑全部验证

```powershell
# 1) 编译（零警告）
make release TARGET_FILE_NAME=TargetCheck -j16
make debug   TARGET_FILE_NAME=TargetCheckD -j16

# 2) UI 基础层回归网（69 项）
powershell -NoProfile -ExecutionPolicy Bypass -File Tools/uicheck/build.ps1
Tools/uicheck/uicheck.exe

# 3) 产品像素 A/B（仓库外临时探针，见 Progress 文档「临时探针」一节）
#    打印 A–H 八个场景的后备缓冲 FNV 哈希 + 3 条工具栏功能断言
```

---

## 9. 期望收益（与前期评估一致）

| 维度 | 收益 |
| --- | --- |
| 可维护性 | ✅ 显著：最大文件 −46%；组件可复用布局/派发/裁剪契约 |
| 回归安全 | ✅ 显著：首次有了可复跑的 UI 断言（69 项）+ 像素 A/B 流程 |
| 布局重复计算 | ⚠️ 小幅（`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` 的例外规则）。

---

# 第六阶段报告：让"布局边界"变成可以随时打开的一面镜子

## 1. 这一阶段解决了什么问题

前几阶段把代码结构理顺了，但**没有工具**去验证"我算出来的矩形到底是不是我画的那个矩形"。
本项目主体仍是手算几何（全仓约 700 处 `gd::RectF`），一旦命中与绘制不同源，症状是
"点不到 / 点错位置 / 悬停高亮漏一格"这类只能靠肉眼猜的问题。
「显示布局边界」把这些不可见的矩形变成可见的一层叠图。

## 2. 设计取舍：基类给协议，组件自己上报

上一轮的结论是"只在共同基类里实现只能覆盖 4 个顶层区域"。本轮把它落实为分层协议：

```
UiComponent::PaintDebugBounds()      默认只画 Area()        ← 宿主遍历一次覆盖 4 大区
  └─ Toolbar/TabBar   覆盖：跳过根控件，遍历控件树子节点    ← 已上树的部分零成本
  └─ SignalPanel      覆盖：表头/筛选框/列表/样式区 + 可见行
  └─ PlotView         覆盖：每个网格区域
UiWidget::PaintDebugBounds(depth)    递归整棵控件树          ← 将来上树的控件自动获得
```

**为什么不放在 `UiWidget` 一处就够**：`PlotView` / `SignalPanel` 的主体几何还没上树，
把边界做成"只有树节点才有"就等于只覆盖了 20% 的矩形。

## 3. 三个必须守住的工程约束

1. **不进缓存**。`PlotView` 有 4 层位图缓存、`SignalPanel` 有 192 槽行位图缓存。
   调试层只画在 `Render` 的最后一步；探针用"关掉后逐像素回到开启前"这条断言把它钉住。
2. **整帧回送**。`Render` 有"只回送绘图区"的快路径，而边界跨越所有装饰区 ⇒
   `fullFrame` 必须并入 `m_showLayoutBounds`，否则看起来像"没生效"。
3. **锐利**。1px 线若被抗锯齿摊成 2px 灰边，就无法判断真实边界；
   因此临时 `PixelOffsetModeNone` + 关抗锯齿 + 矩形对齐整像素，线宽按设备像素固定。

## 4. 顺带做掉的可见收益优化

`Toolbar` 原先每次 `Layout` 都重建整棵控件树（拖动面板分隔条时每帧一次）。
改为 `m_treeDirty` 按需重建后，`SetActionLabel` 也不再"双写覆盖表与控件"——
**文本的唯一权威来源只剩覆盖表**，重建时统一生效。

另外把 `Toolbar` / `TabBar` 里重复的 `Dispatch(); return UiRectHasArea(TakeDirty());`
收敛成 `UiWidget::DispatchRedraw()`。`TakeDirty()` 会清零，漏掉一次就把下一次真实变化
误判成"无变化"——这类"静默不重绘"的坑在项目历史上出现过多次。

## 5. 验证策略的变化

过去每轮都用"8 个场景的**整帧**哈希"证明零差异。本轮**整帧哈希必然变化**（多了一个按钮），
于是给探针加了「工具栏带以下的区域哈希」：8 个场景的区域哈希与改造前**逐一相同**，
从而证明改动的像素范围被完全限制在工具栏内。

另外新增了一个独立的离屏探针 `.preflight/lbcheck`（21 条断言），
专门验证"开关打开后确实出现调试色 / 关闭后逐像素还原 / 菜单锚定与勾选翻转"。

## 6. 数据

```
make release: 零 error 零 warning；TargetCheck.exe 897,024 B（< 900 KB）
lbcheck 21/21 · rendercheck FUNC 7/7 · 区域哈希 8/8 相同 · uicheck 69/69
```

## 7. 遗留与后续

1. 边界没有文字标签（哪个框是 `row#12` 还是 `lane3` 需要靠层级配色猜）。
   加标签要解决"GDI 文本不受 GDI+ 裁剪约束"，建议直接用 `UiTextClipped`。
2. `PlotView` 的 5 类浮动面板内部矩形、`SignalPanel` 的行内子块（复选框/徽标/✕）尚未上报。
   两者的几何都已经集中，属于"再插一个循环"的量级。
3. 开关状态不持久化 —— 重启回到关闭。
4. 设置菜单目前只有一项，但分组结构（`HEADER`）已经就位，后续按组追加即可。

---

# 第七阶段报告：把"布局边界"从一根框变成一张可以逐元素对照的几何图

## 1. 上一版为什么不理想

两个独立的问题被混在一起：

1. **观感**：四条边等宽（层级 0 用 2px、其余 1px），同一个元素的"角"比"边"粗；
   父子矩形共边时两条同色线叠在一起 ⇒ 更粗。于是看起来"就是包了个边、粗细不一"。
2. **覆盖**：`PlotView` / `SignalPanel` 的内部元素全是"按需计算的矩形函数"，
   没有任何代码把它们交给调试层 ⇒ 整块区域只有一个大框，"复选框、信号名、GX、✕"
   全被裹在外层单位里。

第 2 点并不是调试功能的缺陷，而是**几何没有统一出口**的症状。本轮把它一次解决。

## 2. 描边：四角粗、四边细

```
边：固定 1 设备像素（4 条独立实心矩形，非 DrawRectangle —— 后者会偏移半像素）
角：层级 0 = 4px、其余 3px，沿水平/垂直各延伸 cornerLen（≤14px 且 ≤ 短边一半）
内缩：层级 > 0 整体内缩 1px，父子共边不再叠成粗线
填充：无
```

包角的意义不只是好看：**多条边重合时，靠"角的形状"就能分辨层次**（父是青蓝大包角、
子是同位置的品红小包角），这是纯直线做不到的。

## 3. 覆盖率：从"组件自己画"改成"组件收集、宿主统一画"

```cpp
class UiDebugBoxList;              // 值类型容器，装 {rect, depth, tag}
virtual void CollectDebugBoxes(UiDebugBoxList&);   // UiComponent 默认只登记 Area()
void UiWidget::CollectDebugBoxes(boxes, depth);    // 递归整棵控件树
Application::PaintLayoutBounds(...)                // 收集完一次性按 depth 升序描边
```

**为什么不是"所有元素都继承同一个基类"**：`PlotView` 的 4 层位图缓存、
`SignalPanel` 的 192 槽行位图缓存，都要求"绘制由组件自己负责"。
把几何塞进继承体系会与缓存体系打架（谁脏了谁重画、缓存键里要不要混调试状态……）。
而 box 是**纯值类型**，只描述"哪里有一个矩形"，不参与绘制 —— 于是
**几何可以被绘制、命中与调试共用**，还不需要任何生命周期管理。

这正是项目里已有三处雏形（`m_decorRects` / `m_legendHits` / `m_freeMarkerHits`，
即"绘制时登记、命中时读取"）的正式版本。

## 4. 覆盖率数据

| 组件 | 覆盖内容 |
| --- | --- |
| `Toolbar` | 区域 / 每个按钮 / **按钮内容（文字或齿轮图标）** |
| `TabBar` | 区域 / 每个标签条 / 新建按钮 / 每个 ✕ |
| `SignalPanel` | 4 个分区 + 筛选框与清空✕ + 全部显示 + 滚动轨道/滑块 + 样式区 5 行及其 12 色块/自定义/3 模式/3 调整/线宽与透明度轨道和数值 + 目标行/名称/GX + **每个可见行**的折起三角/复选框/色块/名称/GX/✕（组行另加组名/计数）+ 内联编辑框 |
| `PlotView` | 区域 / 每个网格 / GX 徽标 / 装饰层矩形 / 图例托底 + 色块 + 文本 / 5 类浮动面板的 20+ 个字段（面板、标题、✕、折起三角、徽标、编辑行、按钮、内容区、滚动轨道与滑块、透明度轨道与数值、两个开关、各行复选框/数值/滑轨/复位/名称/✕、分组栏/表头/三角/✕、每个固定点行与 ✕） |
| `PopupMenu` | 浮层 / 每个条目 / 可滚动可视区 / 轨道 / 滑块 / 二级子菜单与其条目 |
| `ColorPickerPopup` | 面板 / 标题 / 预览 / 色号 / 色域 / 色相条 / 3 条分量滑轨与数值 / 输入框 |

标签增加了**尺寸门槛**（< 56×16 逻辑像素不画）：复选框、色块、✕ 紧邻，逐个小框贴字会糊成一片。

## 5. 顺带的几何同源与性能

`RowRect(row)` 是 **O(row)** 的逐行累加，而画一行要调它 **5 次**（✕ / 徽标 / 名称 / 组计数 /
折起三角各一次）——200 行列表只见 30 行时每帧上万次加法，命中测试每次鼠标移动同样走这条路。
本轮加了 `m_rowTop` 前缀和（由 `UpdateAnimGeometry()` 统一重建），查询变 **O(1)**，
长度不一致时自动退回逐行累加以保证正确性。

另外把 `(m_clientBounds.Width > 1.0f) ? m_clientBounds : m_area` 在 6 处的重复收敛成
`PanelBounds()`；齿轮按钮改为主按钮配色，与「导入文件」构成一组文件/设置入口；
齿轮图标重画（齿占最外一圈、外环缩到 0.54R），否则齿会被环的描边吃掉只剩"甜甜圈"。

## 6. 验证

```
make release / make debug  零 error 零 warning
TargetCheck.exe            910,336 B（889 KiB）
lbcheck                    21/21 PASS（含"关闭后逐像素还原"）
rendercheck 「工具栏带以下」区域哈希 8/8 与上一轮逐一相同 + FUNC 7/7
uicheck                    69/69
```

## 7. 遗留

1. 仍有两类几何没有上报：`PlotView` 的坐标轴刻度带、`SignalPanel` 的样式区滑块**滑块**（只有轨道）。
2. `m_decorRects` 按"是否落在该网格纵向范围内"归属，跨网格时可能归到相邻网格；
   调试用途可接受，若要精确应改成绘制时就带上 laneIndex。
3. 开关状态仍未持久化。
4. `TargetCheck.exe` 已接近 900 KiB（889 KiB），`CollectDebugBoxes` 的文字常量与
   `std::to_wstring` 是主要增量；若继续增长需要把标签文本改回静态字面量并去掉动态编号。

---

# 第八阶段报告：调试叠加层的三个真实缺陷（尺寸、残留、层级）

## 1. 症状与真实成因

用户报的三个问题看起来都像"边界画得不好"，实际是**三个互不相干**的缺陷：

| 症状 | 真实成因 |
| --- | --- |
| 小元素变成粗描边 | 包角粗细是**固定值**（3–4px），没考虑元素尺寸 |
| 拖滚动条时"大量绘制残留"，松开并移动鼠标才消失 | ① 我的收集代码读了**位图坐标系**的 `m_decorRects`，生成横跨工具栏的幽灵框；② 绘图区的三条快路径只重画变化区域，而调试线画在最后 ⇒ 旧线残留；③ 组件内越界元素没裁剪 |
| 右键二级菜单被下层边界线覆盖 | 只有按 `depth` 排序，没有"收集顺序/浮层"概念；且调试线画在内容之后，光是排序并不能阻止露线 |

## 2. 尺寸自适应

以短边为基准推导包角：粗细 `min(4/3, 短边/10)`（再夹到 `[1, 短边/4]`），长度 `min(14, 短边/3)`。
短边 ≤ 12 只画四个 L 形角标记（不画边），≤ 5 完全不画。于是：

* 15px 复选框 → 1px 角标记，不再"被框住"；
* 40px 按钮 → 3px 包角 + 1px 边；
* 200px 区域 → 4px 包角，形状仍是 `⌜ ⌝ ⌞ ⌟`。

文字标签整块删除（含 `UiDebugPaintStyle`）：黑底白字在小元素上必然糊成一片，体积也省 1.5 KB。

## 3. 残留：为什么"松开并移动鼠标"就消失

因为松开鼠标后 `m_dragMode` 回到 `NONE` 且 `m_chromeDirty` 被置位 ⇒ 走**整幅重绘**，
把上一帧残留的边框像素全部盖掉。这反过来证明残留来自"部分重画 + 叠加层"。

修法分三层：
1. **不再读位图坐标系的缓存**（`m_decorRects`），消灭幽灵框；
2. **调试模式强制整幅重绘**（`SetForceFullRepaint`），让每一帧都是完整一帧；
3. **box 带 `clip`**（组件地盘），组件内越界元素（`lane.rect` 的 Y 可以是负数）
   不会画到工具栏上。

探针的判据也值得记一笔：不能拿"拖拽帧 vs 松开后一帧"比 —— 两者图层预热进度不同，
会有几十万像素的**合法**差异。正确判据是**同一状态连续两帧必须逐像素相同**。

## 4. 层级：排序不够，还要挖洞

`layer`（收集顺序）+ `depth`（父子）双排序键解决"两个 box 重叠时谁压谁"。
但调试线是画在**所有内容之后**的，下层组件的线仍然会显示在不透明菜单上 ——
于是补上 `AddOccluder()`：菜单/拾色器把本体登记为遮挡矩形，绘制更低层的 box 时
用 `Region::Exclude` 挖洞。

实测：菜单区与二级子菜单区的琥珀/绿色像素均为 **0**（既没有下层行边框，也没有被裁破的包角）。

## 5. 顺带修掉的东西

* 浮层**不能**用"本体矩形"当 clip：二级子菜单会展开到本体之外，会被整个裁掉
  （首版就踩了这个坑，子菜单一个框都没有）。
* `Render` 的 `fullChrome` 并入 `m_showLayoutBounds`，装饰区也保证完整一帧。

## 6. 验证

```
lbresid  5/5   （工具栏恒等、同状态两帧恒等、差异不越过绘图区上沿、层序正确）
lbzorder 4/4   （菜单与子菜单区内 0 个下层颜色）
lbcheck  21/21 ；uicheck 69/69 ；rendercheck 区域哈希 8/8 不变 + FUNC 7/7
零 warning；TargetCheck.exe 906,752 B（885.5 KiB）
```

## 7. 遗留

1. 调试模式下强制整幅重绘：283 个网格时帧率明显下降 —— 这是**有意的取舍**
   （调试而非日常使用），但若将来要让边界常驻，需要改为"只把叠加层位图化再贴回"。
2. 菜单项逐个画框略显拥挤，可选做"只画外框 + 悬停项高亮框"。
3. 开关状态仍未持久化。