Documents/UI_Refactor_Report.md

@@ -1,4 +1,4 @@
-# UI 重构报告（第一阶段：P0 / P1 / P2）
+# UI 重构报告（P0 / P1 / P2 / P3-Toolbar）
 
 日期：2026-10-28　分支：`UI_Refactor`（从 `dev` 切出；`dev` 又由 `main@df715a0` 切出）
 所有提交**只在本地仓库**，`main` / `dev` 未受影响。计划见 `UI_Refactor_Plan.md`，台账见 `UI_Refactor_Progress.md`。
@@ -12,10 +12,13 @@
 | **P0** | 入库离屏回归网 `Tools/uicheck`（62 项断言，`build.ps1` + `main.cpp`） | ✅ |
 | **P1** | UI 基础层 `Components/Shared/{Inc,Src}/UiLayout.*` + `UiWidget.*`（约 1 440 行含注释） | ✅ |
 | **P2** | `PlotView` 实现按关注点重分为**七个分片**；`PlotViewPaint.cpp` 9 080 → **4 913** 行（**−46%**） | ✅ |
+| **P3** | **Toolbar 已迁移到控件树**（新增 `UiButtonWidget`，公开 API 未变、逐像素 0 差异） | ✅（1/5 组件） |
 
-三个提交：
+五个提交：
 
 ```
+84a349f  UI 重构 P3：Toolbar 迁移到控件树（新增 UiButtonWidget，逐像素 0 差异 + 功能断言）
+eb11e63  UI 重构：补充进度台账、阶段报告与共享记忆同步
 ec3f93f  UI 重构 P2 续：把布局与命中几何从绘制分片拆出（PlotViewPanels.cpp，逐像素 0 差异）
 b532046  UI 重构 P2：PlotViewPaint.cpp 按关注点分片（机械搬移，逐像素 0 差异）
 8bdf48c  UI 重构 P0+P1：新增布局/控件基础层与离屏回归网（对产品像素零影响）
@@ -31,8 +34,9 @@ b532046  UI 重构 P2：PlotViewPaint.cpp 按关注点分片（机械搬移，
 | 最大源文件 | 9 080（`PlotViewPaint.cpp`） | 4 913（`PlotViewPaint.cpp`） |
 | `PlotView` 实现文件数 | 4 | **7**（职责单一） |
 | 自动化 UI 探针 | **0** | **62 项断言**（入库、可复跑） |
-| 产物 | 873 984 B | **877 568 B**（+3.6 KB，< 900 KB 阈值） |
-| 产品像素差异 | — | **0**（三场景渲染哈希逐一相同） |
+| 已迁移到控件树的组件 | 0 | **Toolbar**（1 个，含 8 场景像素 A/B + 3 条功能断言） |
+| 产物 | 873 984 B | **881 664 B**（+7.7 KB，< 900 KB 阈值） |
+| 产品像素差异 | — | **0**（分片三场景 + 迁移八场景哈希逐一相同） |
 
 ---
 
@@ -141,11 +145,40 @@ flowchart TD
 
 ---
 
-## 6. 明确未做的事（避免误解）
+## 6. P3：Toolbar 迁移到控件树（真实组件落地）
+
+这是第一个**真正换成控件树**的现有组件（不是新增代码，而是替换旧实现），公开 API 一字未改。
+
+| 旧实现 | 新实现 |
+| --- | --- |
+| `Toolbar::Button` 同时存配置、矩形、悬停、按下 | `Button` 只存**静态配置 + 控件指针**；几何与外观状态归控件 |
+| `m_hoverIndex` / `m_pressedIndex` 手工维护 | 由 `UiWidget` 的**悬停链**与 capture 维护 |
+| `Paint` 自己遍历按钮逐项绘制 | 根控件（底色 + 底部分隔线）+ 按钮子节点，一次 `root->Paint(ctx)` |
+| 四个鼠标函数各自扫按钮矩形 | 统一翻译 `UiEvent` → `root->Dispatch()`；动作经 `onClick` 登记、抬起后执行 |
+| 死字段 `Button::hover`（从未赋值） | 删除，改用基类 `Hovered()` |
+
+新增 `UiButtonWidget`（`Components/Shared`）：主按钮/普通按钮/可切换/禁用四套配色与旧实现逐像素一致；
+按下即 `CaptureMouse()`，"在自身范围内松开才算点击"，指针离开时 `CancelPress()`。
+
+**框架约定调整**：`UiWidget::Paint` 的裁剪由"严格等于自身矩形"改为**"自身矩形外扩 `kUiClipBleed`(1px)"**
+—— 边框以矩形边界为中心绘制，严格裁剪会切掉外半侧、控件变细（与旧代码不再像素一致）。
+
+**验证（两类，缺一不可）**
+
+1. **像素**：8 个场景（全览 / 深放大+自由标记+滤波+弱峰+光标 / 平移 / 悬停按钮 / 按下 / 松开 /
+   悬停主按钮 / 移出工具栏）哈希迁移前后**逐一相同**。
+2. **功能**（证明"点击真的翻译成动作"，而不是"看起来没坏"）：
+   * `locate-cursor-button PASS (1291,73)` —— 用控件自身矩形定位「光标」按钮；
+   * `click-cursor-changes-mode PASS (1 -> 2)` —— 点击后光标模式 单→双；
+   * `release-outside-does-not-fire PASS (2 -> 2)` —— 按下后移出再松开，不触发动作。
+
+---
+
+## 7. 明确未做的事（避免误解）
 
 | 未做 | 原因 |
 | --- | --- |
-| 迁移 Toolbar / TabBar / SignalPanel / PlotView 到 `UiWidget` | 属 P3/P4；需逐组件迁移、每个组件单独 A/B，本轮只打地基 |
+| 迁移 TabBar / PopupMenu / ColorPicker / SignalPanel 行 | 其余 chrome 组件：需逐个迁移 + 逐组件 A/B（Toolbar 已示范套路） |
 | `UiHost` + 共享 32bpp DIB + `SurfaceView` | 属 P5；需同时把 56 处 `InvalidateRect` 收敛成脏区并集，必须与迁移同批验证 |
 | 引入多线程光栅 | 本项目实测 **1.03x**（GDI+ 内部串行），且有"后台改写视界覆盖用户平移"的历史事故 |
 | 每控件独立位图 | 内存按面积线性增长（128 网格 ≈250 MB） |
@@ -153,9 +186,10 @@ flowchart TD
 
 ---
 
-## 7. 下一步建议（按收益/风险排序）
+## 8. 下一步建议（按收益/风险排序）
 
-1. **P3：Toolbar 迁移**（最小、最易验证）→ 用 `uicheck` + 新旧像素对比收口。
+1. **P3 继：TabBar**（标签 + 「+」+ 重命名内联输入框）→ 再 `PopupMenu` / `ColorPickerPopup` 条目行。
+   判据同 Toolbar：**8+ 场景像素哈希一致 + 功能断言**（点击/悬停/取消、重命名提交与取消）。
 2. **P4：浮动面板迁移**：`EdgePanelLayoutFor`（651 行）→ 真控件（Stack + Abs + Measure-driven），
    同时消掉面板里 10 多个平行数组（`rowRefs/rowChecks/rowPoints/rowOrder/rowLevelTracks/...`）。
    ⚠️ 每个面板单独一轮：吸顶/滚动/滚动条/滑块复位/行悬停压暗/开关联动是 6 轮补丁叠出的隐式约定。
@@ -165,9 +199,9 @@ flowchart TD
 
 ---
 
-## 8. 一句话结论
+## 9. 一句话结论
 
-> 本阶段没有改动任何产品行为：**新增了一套可复用、可测试的布局/控件基础层**，
-> 并把 9 080 行的"万能绘制文件"按关注点降到 4 913 行（−46%），
-> 两者都用**逐像素 0 差异**与 **62 项离屏断言**证明。后续每个组件迁移都可以复用这套回归网，
+> 本阶段**首次把一个现有组件（Toolbar）真的换成了控件树**，并且同时以**像素哈希一致**与**功能断言**证明
+> 行为未变；同时新增了布局/控件基础层、入库回归网，并把 9 080 行的"万能绘制文件"降到 4 913 行（−46%）。
+> 后续每个组件迁移都能复用同一套路（`uicheck` + 像素 A/B + 功能断言），
 > 从而把"AI 写得快"转换成"你敢合多少"。