Just-DataInspector/Documents/UI_Refactor_Plan.md

UI 重构计划（UI_Refactor 分支）

目标读者：本项目的后续 Agent（可能是另一台设备 / 另一个模型）。 本文是唯一施工蓝图；实时进度见 Documents/UI_Refactor_Progress.md，最终结论见 Documents/UI_Refactor_Report.md。 硬约束的权威来源仍是 Documents/agent_mem.md（§11.2）；本文与之冲突时以 agent_mem.md 为准。

---

0. 为什么要重构（量化基线）

指标	现状	出处
PlotViewPaint.cpp	9 080 行（注释 1 295 / 空行 517 / 仅大括号 2 026 / 有效代码 5 242）	Get-Content | Measure-Object
PlotView.hpp	3 649 行、310 个方法、203 个成员变量、31 个嵌套类型	同上
EdgePanelLayoutFor	651 行、19 个调用点，每帧被命中/层序/光标/绘制各算一遍	Select-String
Application.cpp 的 InvalidateRect	56 处 + 手写 m_chromeDirty / m_panelDirty / panelOnly / fullFrame 组合	同上
动画	5 套手写动画散在 3 个组件，共用一个 10ms 定时器	同上
自动化 UI 探针	0（.preflight 已被删除且被 gitignore）	仓库现状

PlotViewPaint.cpp 里混住四类内容：真绘制 ≈3.5k / 光栅化缓存 ≈2.5k / 缓存键 ≈1.1k / 布局与命中几何 ≈1.3k。

五条根因

1. 上次拆 13 695 行大文件时按函数名（"带 Paint 前缀"）而非关注点分片 ⇒ 缓存、缓存键、面板布局、命中几何全被倒进 paint 分片。
2. 没有控件抽象 ⇒ 每个叠加层自带"几何 + 命中 + 绘制 + 缓存键"四份重复；5 个实验性面板各 800~1 200 行，靠 10 多个平行数组（rowRefs/rowChecks/rowPoints/rowOrder/rowLevelTracks/...）下标对齐"假装"成树。
3. GDI / GDI+ 双栈妥协被每个绘制点重复支付（GDI 文本不认 GDI+ 裁剪、UiFillRect 的 GDI 快路径绕过裁剪、GDI 文本忽略 alpha…）。
4. "必须混进缓存键，否则贴旧像素"这条不变量没有归属（4 套手写 key + 一堆 Collect* ≈1.1k 行；历史 ≥4 次真实 BUG 是"忘了混一个字段"）。
5. 1 295 行硬核"为什么"注释让行数虚高 —— 保留，不删（多 Agent 协作防回归的核心资产）。

---

1. 设计目标与非目标

1.1 目标（必须达成）

1. 几何只算一次：布局是"按需失效的 pass"，命中/绘制/光标共用同一份结果。
2. 失效从布尔变矩形：dirty ∩ bounds 为空 ⇒ 整棵子树跳过（这是唯一真正省钱的层次）。
3. 裁剪契约统一：Paint 进入时同时收紧 GDI 裁剪与 GDI+ 裁剪，根治"文字画到图例/工具栏上"这类已出现 3 次的 BUG。
4. 缓存键有归属：由"持有该内容的节点"产生，父层只聚合。
5. 事件派发显式化：{consumed, redraw, dirtyRect} 代替 bool 要不要重绘；capture / 模态 / hover / 焦点 / 光标仲裁由基类提供。
6. 动画统一 tick：一个动画列表 + 现有 kScrollTimerId 推进。
7. 零行为变更的先行阶段：先拆文件、补回归网，再动语义。

1.2 非目标（明确不做，写进禁区）

禁区	原因
❌ 波形数据→像素管线控件化（网格/曲线/采样点不做成节点）	布局与虚调用会进每帧热路径；采样/顶点量与控件无关
❌ 每个控件自持位图	内存按面积线性增长：逐网格图层已是屏幕面积 2 倍（5 网格 ≈16MB，128 网格 ≈250MB）
❌ "父脏 ⇒ 子树全脏"	会把"只重绘一个网格/一个面板"打回整块重绘（历史最易发生的退化）
❌ 多线程光栅	GDI+ 内部串行，实测 1.03x；且后台改写 m_area/ViewMin 会覆盖用户平移（第一代已因此回退）
❌ 逐控件细粒度像素缓存	画一个按钮 2080µs vs 贴图 510µs ⇒ 净亏损，还要付"忘混键"的风险
❌ 引入属性对象体系（学 Blink）	那是为 Blink 规模准备的；本项目用"节点产生 key"即可

1.3 借鉴来源与取舍

借鉴	采纳	说明
Chromium views::View 的失效驱动布局 pass	✅ 全采纳	对应 §3 的 UiWidget::Measure/Arrange + UiLayoutCache
views::View::PaintChildren 的脏矩形下探	✅ 全采纳	对应 §4 的 PaintContext.dirty
SetPaintToLayer() 只提升少数子树	✅ 保持现状量级（4 层）	不再新增层
cc 的记录-光栅分离 / tiling / checkerboarding / 每帧预算	✅ 已具备，不改	PolylineCacheEntry、宽基底+补条、贴过期但位置正确、RenderPendingLaneRebuilds(1)
cc 的多线程光栅 / GPU 合成	❌ 不采纳	GDI+ 无 GPU 路径；并行实测 1.03x
Dear ImGui 的每帧全量重画	❌ 不采纳	本项目整幅重绘 ≈80ms，必须走失效

---

2. 目标架构

flowchart TD
    H[UiHost<br/>持有 app-sized 32bpp top-down DIB<br/>z 序 · 脏区并集 · 一次 BitBlt 回送 · 动画 tick]
    H --> R[UiRoot : UiWidget]
    R --> D{脏区树<br/>dirty ∩ bounds 空 ⇒ 整棵子树 return}
    D --> A[普通控件：直接画进共享缓冲<br/>按钮 / 文本 / 列表行 / 时间轴 / 图例]
    D --> B[高成本叶子：自持位图，完成即 BitBlt 贴回<br/>波形网格 / 装饰层 / 光晕 / 浮动面板]
    A --> S[SurfaceView{ dc, rect, stride, bits, version }]
    B --> S

分层原则

• 共享一张缓冲：省内存、免分配抖动、合成顺序天然确定。
• 只有高成本叶子自持缓冲：这是"把重画换成贴图"的唯一手段。
• 脏区向下取交集（不是并集）。
• 布局由下往上、每帧最多一轮 Measure；尺寸由内容反推（EdgePanelWidth 就是这种）。

2.1 新增文件

文件	职责	依赖
Components/Shared/Inc/UiLayout.hpp / Src/UiLayout.cpp	纯几何：UiInsets、栈/流/锚点/对齐、UiLayoutCache	仅 Theme.hpp（gd::RectF）
Components/Shared/Inc/UiWidget.hpp / Src/UiWidget.cpp	控件基类：树、Measure/Arrange、双栈裁剪 Paint、事件派发、失效、capture/模态/hover/焦点/光标、动画 tick	UiLayout.hpp、PaintUtil.hpp
Components/Shared/Inc/UiHost.hpp / Src/UiHost.cpp	宿主：共享 DIB + SurfaceView + 脏区并集 + 回送 + 消息翻译 + 动画定时器	UiWidget.hpp
Tools/uicheck/（入库）	离屏回归网（SW_HIDE + 注入消息 + 从 m_backDc 取帧）	Build/Release/*.o

⚠️ Components/Shared 已在 Makefile 的 CXX_INCLUDES_PATHS / CXX_SOURCES_PATHS 中 ⇒ 新增 .cpp 无需改 Makefile（按 basename 自动收集）。

---

3. 布局层设计（UiLayout）

3.1 为什么不是简单的"宽高字段"

基类若只有 width/height，会在三处立刻失效：

1. 所有坐标是逻辑像素 × scale（本机 DPR 1.25），控件必须知道缩放；
2. 面板宽度是由内容反推（EdgePanelWidth = 列宽 max + 行 ✕ + 滚动条预留）；
3. 离屏位图要求设备像素整数对齐（floor/ceil 方向错了就留 1px 接缝 —— 样式补丁曾踩过）。

⇒ 采用 Measure(约束) → 期望尺寸 / Arrange(最终矩形) → 实际矩形 两段式。

3.2 需要的布局种类（按实际用量排序）

布局	用途	备注
Abs（绝对）	绘图区叠加物主力：光标线、取值胶囊、吸附环、越界三角、固定点、面板初始位置、滚动条	保留"自由布局"，但它是主力而非备选
Anchor（四边贴合）	工具栏整体靠右、时间轴贴底、滚动条贴右、面板夹在 m_plotRect 内	讨论中缺失，必须补
Stack（竖向流）	信号列表行、分组行、面板条目（名称行 + 参数行 + 滑块行）	需支持"行高由内容决定 + 吸顶(sticky) + 滚动视口"
Flow（横向流 + 溢出）	图例条目 + 空间不足的 +N、工具栏按钮组	讨论中缺失，必须补
Measure-driven	面板宽度按实测文本撑开、列宽 max(缺省, 内容, 列标题)	必须有，否则又回到"绘制侧省略号"
Grid	用不上（绘图区不是表格）	不实现
Card	只是"面板皮肤"	作为 UiPanelSkin 绘制样式，不是布局

3.3 UiLayoutCache（本次最关键的性能点）

EdgePanelLayoutFor 的 19 个调用点全部来自"同一份几何被反复问"。做法：

class UiLayoutCache
{
public:
    // key 由调用方提供（例如 laneIndex + kind + 面板宽 + 缩放 + 条目数）
    const LayoutEntry* Find(std::uint64_t key) const;
    const LayoutEntry& Store(std::uint64_t key, LayoutEntry&& entry);
    void Invalidate(std::uint64_t key);   // 定向失效
    void Clear();
};

硬约束：Invalidate 必须由"改变几何的那条路径"显式调用（与 m_edgeScans 的定向失效同一纪律），禁止为了让缓存命中率好看而整体 Clear()。

---

4. 控件基类设计（UiWidget）

4.1 接口骨架

struct UiEventResult
{
    bool consumed = false;      // 事件已被消费（不再下传/上抛）
    bool redraw = false;        // 需要重绘
    gd::RectF dirty;            // 需要重绘的矩形（客户区坐标；空 = 未知 ⇒ 取自身 bounds）
};

class UiWidget
{
public:
    virtual ~UiWidget();

    // ---- 树 ----
    void AddChild(std::unique_ptr<UiWidget> child);
    void RemoveChild(UiWidget* child);
    const std::vector<std::unique_ptr<UiWidget>>& Children() const;

    // ---- 布局（两段式，各自带失效）----
    void InvalidateMeasure();                 // 向上冒泡到根
    void InvalidateArrange();
    gd::SizeF Measure(const UiMeasureContext& ctx);   // 自下而上，命中缓存则直接返回
    void Arrange(const gd::RectF& bounds);            // 自上而下；bounds 一定 > 0

    // ---- 绘制（双栈裁剪 + 脏区下探）----
    void Paint(UiPaintContext& ctx);          // 内部：与 dirty 求交 → OnPaint → 递归子节点
    virtual void Invalidate(const gd::RectF& rect);   // 局部失效（向上冒泡并入）

    // ---- 事件 ----
    UiEventResult Dispatch(UiEvent& event);   // 命中 → 子节点（反 z 序）→ OnEvent

    // ---- 命中 / 光标 ----
    bool Contains(int x, int y) const;
    virtual HCURSOR QueryCursor(int x, int y) { return nullptr; }

    // ---- 交互仲裁（由 Host 调用）----
    UiWidget* Capture(); void SetCapture(); void ReleaseCapture();
    void SetModal(bool modal);                // 模态子树：Host 只向它派发
    void SetHitTransparent(bool value);       // 装饰元素：不参与命中

    // ---- 动画 ----
    virtual bool AdvanceAnimation(std::int64_t nowMs) { return false; }

protected:
    virtual gd::SizeF OnMeasure(const UiMeasureContext& ctx) = 0;
    virtual void OnArrange() {}
    virtual void OnPaint(UiPaintContext& ctx) = 0;
    virtual UiEventResult OnEvent(UiEvent& event) { return {}; }
    virtual std::uint64_t ContentKey() const;  // 缓存键的来源（父层只聚合）
};

4.2 Paint 的硬契约（必须由基类保证，不是"每个控件记得"）

1. 双栈裁剪：进入时 SaveDC + IntersectClipRect（GDI）+ Graphics::SetClip(Intersect)（GDI+），退出时还原。这一条一次性消灭"滚动时文字串到标题栏""全选高亮溢出输入框""选区画到工具栏上"。
2. 脏区下探：ctx.dirty = ctx.dirty ∩ bounds；若为空 ⇒ 整棵子树直接 return（不调 OnPaint、不遍历子节点）。
3. 绘制顺序 = 子节点顺序 = z 序；命中/事件 = 反 z 序（与现在 m_panelOrder + TopPanelAtPoint 反向遍历等价，但不再靠人工维护）。
4. 禁止在 OnPaint 内改 bounds/子节点集合（会与本帧的 dirty 不一致）。

4.3 事件派发的硬契约

• consumed 决定是否上抛；dirty 参与本帧脏区并集。
• capture：抓取期间所有鼠标事件直接投给抓取者（跳过命中），与 Windows SetCapture 语义一致。本项目硬约束：中键平移与左键拖拽共用同一个 capture，松左键不能无条件 ReleaseCapture()。
• 模态：菜单打开时 Host 只向模态子树派发，且"取消底层拖拽"时必须排除菜单自己的 EDIT_FIELD。
• hover：Host 维护 hover 链，跨节点 leave/enter；悬停是跨组件的（面板行 → 网格固定点高亮；列表行 → 曲线光晕）⇒ 通过 Host 级"悬停信号总线"广播，不靠父子关系。
• 双击消歧：窗口带 CS_DBLCLKS；没有双击语义的位置必须在 DoubleClickIsPlainPress() 返回 true，由 Host 改走普通按下（否则"连点丢一半"）。

4.4 失效契约

• 节点持 m_dirty（自身坐标系）+ m_dirtyChildren；
• Invalidate(rect) 并入自身并向上冒泡（父层只并集矩形，绝不把子树的 dirty 清零）；
• Root 暴露 TakeDirty() 给 Host，Host 再与窗口更新区域取并集。

---

5. 宿主层设计（UiHost）

1. 单一 app-sized 32bpp top-down DIB（替换现在的 CreateCompatibleBitmap）：

   struct SurfaceView
   {
       HDC dc;                 // 共享 HDC（GDI/GDI+ 都画这个）
       gd::RectF rect;         // 本节点在 Holder 坐标系中的矩形（设备像素，整数对齐）
       int stride;             // 行字节数（**不可**假设 = width*4）
       std::uint32_t* bits;    // rect 左上角那一像素（不是位图首地址）
       std::uint64_t version;  // 位图代次；失配 ⇒ 句柄作废
   };
   

   ⚠️ 绝不能缓存裸指针：EnsureBackBuffer 在 WM_SIZE / WM_DPICHANGED 会重建位图。 ⚠️ bits 只在 CPU 侧直写（memcpy/alpha）时用；GDI/GDI+ 绘制只需 dc + rect。
2. 脏区并集：把现在 56 处 InvalidateRect 收敛为 Host::Invalidate(rect)，一次回送。 ⚠️ 回送仍必须有无条件 else（历史：某分支缺兜底 ⇒ 窗口一个像素都不回送，用户看到三个不同症状）。
3. 动画 tick：AdvanceAnimation 遍历树，任一为 true 就保持 kScrollTimerId（10ms）。
4. 消息翻译：WM_* → UiEvent，并把 WM_SETCURSOR 交给 QueryCursor 链（从 z 顶向下、首个非 null 生效）。

---

6. 落地阶段（每阶段一个可独立回滚的提交）

阶段	内容	交付判据
P0	离屏回归网 Tools/uicheck（入库）+ 现有 20+ 条硬约束的断言骨架	✅ 已完成（69 项断言）
P1	UiLayout + UiWidget 基础层（本次）	✅ 已完成（编译零警告；uicheck 覆盖）
P2	零行为变更分片：PlotViewPaint.cpp 拆成 Paint（只画）/ Raster（缓存与预算）/ CacheKey（指纹）/ Geometry（面板与命中）；EdgePanelLayoutFor、ProbeFreeMarker 迁回交互侧	✅ 已完成（逐像素 0 差异）
P3	迁移 chrome：Toolbar → TabBar → PopupMenu → ColorPicker → SignalPanel 行	✅ Toolbar/TabBar 已迁移；PopupMenu/ColorPicker/SignalPanel 行经评估不采用（见 Report §7 的结论与理由）
P4	迁移 5 个浮动面板	经评估不采用（面板布局已是单一函数且已缓存像素层；控件化无帧时间收益且会浮空吸顶/滚动语义，见 Report §7）
P5	波形管线包成叶子 surface（只包不改）+ 共享 DIB 落地	🔄 共享 DIB + UiSurface 已完成；「56 处失效收敛为脏区并集」经评估不采用（InvalidatePlotRect() 已是按消息的批处理点，逐处替换只增间接层，详见 Report §7）

P2 之前禁止改任何行为。P2 是唯一的"免费"阶段，别顺手改语义。

---

7. 验证策略（不占用用户鼠标/键盘/屏幕）

1. 离屏 harness：SW_HIDE 窗口 + 直接 app.HandleMessage(...) 注入 + 从 m_backDc 用 GetDIBits 取帧。
2. 进程/线程优先级 BELOW_NORMAL；从不用 SetCursorPos / SendInput / 截屏。
3. A/B 反证：每条新断言都要能被"还原旧实现"证伪，否则不算通过。
4. 像素判据要选对区域：验证"某交互不应改变外观"时，只对不受影响的区域取哈希。
5. 已知陷阱（全部来自历史 BUG）：
   • 探针消息泵必须丢弃 WM_MOUSELEAVE（离屏窗口会立刻兑现它）；
   • 注入按下后立即 ReleaseCapture()（避免抢真实鼠标）；
   • CycleCursorMode() 是循环，多组用例里重复调用会把光标关掉；
   • PlotView 的嵌套类型（LaneVisual/LegendHit/EdgePanelLayout）使用时要写 PlotView:: 前缀。

---

8. 协作纪律（多 Agent）

1. 文件所有权：同一时刻一个 Agent 只改一个文件的同一区域；跨阶段并行时按下表分工，禁止交叉。
2. 每阶段一个提交，提交信息写清"改了什么 / 为什么 / 怎么验证"。
3. 先写断言再改代码。
4. main / dev 只接受全绿；UI_Refactor 内允许临时红，但不许跨轮次累积红。
5. 任何"规则变更"必须同步进 Documents/agent_mem.md（§11.2 追加编号），否则另一端看不到。
6. 体积红线 900KB（到达即提醒用户，不是禁止超过）。

8.1 并行分工建议（若启用多个 Agent）

Agent	独占文件	禁止触碰
A（基础层）	UiLayout.*、UiWidget.*、UiHost.*、Tools/uicheck/*	任何现有组件
B（分片）	PlotViewPaint.cpp → 新分片文件、PlotViewInternal.hpp 的 include 段	UiWidget.*、面板逻辑
C（面板迁移）	PlotViewFeatures.cpp 的面板段、新建 PlotViewPanels.cpp	PlotViewPaint.cpp、UiLayout.*

冲突高发点：Makefile（新增目录时才需要改）、agent_mem.md（追加编号必须串行）。

---

9. 风险与回滚

风险	触发条件	回滚
迁移后"连点丢一半"	DoubleClickIsPlainPress 语义漏实现	单组件提交可独立 revert
迁移后"拖动卡住"	capture 共用被拆成两套	同上
面板失效不全（贴旧像素）	ContentKey() 漏字段	P4 里每个面板配一条"改 X 后像素必须变"的断言
体积超 900KB	新框架代码量	每阶段结束量一次；超阈值先报告用户
布局级联死循环	Measure 里改子节点	单元测试固定"Measure 一轮即收敛"

---

第五阶段计划：统一组件协议 + 去手写链路 + 拆分收尾（2026-10-28）

状态：✅ 已完成（详见 UI_Refactor_Progress.md 第七轮 / UI_Refactor_Report.md 第五阶段）

目标

1. 让"顶层组件"有统一协议，宿主不再逐个点名；
2. 用同一套协议把 SetScale / Layout / MouseLeave / SetCursor 四条手写链改成循环；
3. 把剩余两个"千行以上"的文件按职责拆分（不再按函数名前缀）；
4. 一轮代码审查（错误注释 / 过期注释 / 名实不符 / 残留引用）；
5. 把误入库的临时验证工具 Tools/ 从提交树剥离并写入 ignore。

设计决定（先证明不是负优化）

• 协议只做"同签名归一"：UiComponent 是纯接口、无状态，四个组件本就各自拥有 完全同名同签名的方法 ⇒ 改造 = 加 override + 补 Area()，实现零改动、生成码几乎不变。
• 不把 UiComponent 做成 UiWidget 的基类：树节点是"父给尺寸 + 父下探脏区"， 而 PlotView（4 层位图缓存）/ SignalPanel（行位图缓存）是"地盘宿主"。 强行上树会推翻缓存前提（历史事故：后台渲染覆盖平移、命中矩形错位）。
• 不做的一律写明理由：按下/松开/移动三条链带组件专属后置动作，保留显式分支。

任务清单

#	任务	验证手段
P5-1	新增 Shared/Inc/UiComponent.hpp，四组件继承 + override	编译零警告
P5-2	Application：ComponentEntry 表 + BuildComponentTable()	—
P5-3	ApplyDpi / Relayout / WM_MOUSELEAVE / WM_SETCURSOR 表驱动	uicheck 69/69
P5-4	Relayout 内容区改用 UiStackRects（布局库首个生产调用点）	rendercheck 8 哈希不变
P5-5	SignalPanelInteraction.cpp 拆 4 片 + SignalPanelEdit/Scroll/Menu.cpp	8 哈希不变
P5-6	PopupMenu.cpp 拆 3 片 + PopupMenuInternal.hpp	8 哈希不变
P5-7	代码审查（注释准确性、构造函数重复、include 位置）	人工 + 编译
P5-8	git rm -r --cached Tools + .gitignore + 历史过滤器	git ls-files Tools 为空
P5-9	三份文档更新 + 提交	git status 干净

风险与对策

风险	对策
表驱动改动影响绘制顺序（toolbar 与 tabBar 重叠区）	表按"底→顶"排，WM_SETCURSOR 从表尾向前命中，与旧 if 顺序一致
拆分导致逐像素差异	纯整函数搬移；每拆一个文件立刻跑 rendercheck 比对 8 哈希
filter-branch 会清掉工作区被剔除的路径	先备份 Tools/ 到 %TEMP%，重写后还原为未跟踪文件
中文注释在 PS 5.1 下乱码	文档编辑走 VS Code 编辑工具（UTF-8），终端只做 ASCII 拼接

完成判据

• make release / make debug 零 error 零 warning；
• Tools/rendercheck 8 个场景哈希与基线逐一相同 + 7 条 FUNC 断言 PASS；
• Tools/uicheck 69/69；
• TargetCheck.exe < 900 KB；
• git ls-files Tools 返回空、git status 干净、main / dev 未被触碰。