体积 L3（-fno-exceptions + MemProbe + LTO）与 L1 几何产物层；产物 909,824 -> 788,992 B
## 为什么
用户 2026-10-29 要求：按既定计划完整实现改进，但
① **不得把编译产物拆成 DLL**（项目定位是单文件轻量工具，最终只能有一个 .exe）；
② 异常处理改用**预检验**而不是 try/catch（-fno-exceptions 省体积，且 try/catch 本身开销大）；
③ 先删除 Documents 内三份 UI 重构文档再按"计划 / 当前进度 / 最终报告"重建；
④ 顺便审计代码，删除无用/过时注释，修复名实不符；
⑤ 提交到本地仓库，期间不要占用用户的鼠标/键盘/屏幕。
## 改了什么
### 1. 体积（909,824 B -> 788,992 B，-120,832 B，-13.3%）
Makefile 新增三个可覆盖开关（默认全为 1）：
- `LAYOUT_BOUNDS` 编入/剔除「显示布局边界」叠加层
- `NO_EXCEPTIONS` 追加 `-fno-exceptions`
- `LTO` 追加 `-flto`（编译 + 链接）
派生：`FUNC_SECTIONS`（LTO 下为空）、`GC_SECTIONS`（`-Wl,--gc-sections`）、
`ASM_LISTING`/`ASM_LISTING_C`（LTO 下为空，因为 lto-wrapper 会丢弃 `-Wa` 清单）。
两个实测复现的坑（已写进 Makefile 注释）：
- **切换 LTO 必须 `make clean`**：LTO 与非 LTO 目标文件混链会让 GCC 15.2.0 在
`binds_to_current_def_p (symtab.cc:2598)` 处 ICE。
- **`-flto` 与 `-ffunction-sections -fdata-sections` 同时打开也 ICE**（干净重编也必崩，
报错落点是 `DataModel.hpp:393`，但那是 COMDAT 解析落点、不是原因）⇒
LTO 下 `FUNC_SECTIONS` 置空，并加 `-flto-partition=one`：默认 11 个分区的 LTRANS
稳定复现，单分区从未复现。**这是稳定性选项，不是性能选项。**
### 2. 关异常必须成对交付：预检验 + 兜底
新增 `Utilities/Inc/MemProbe.hpp` + `Utilities/Src/MemProbe.cpp`：
- `MemAvailablePhysical()`：`GlobalMemoryStatusEx` + 200ms 缓存
- `MemCanAllocate(bytes)`：预留后仍须保有 1/8 可用内存
- `MemReserveIfRoom(container, n)`：含 `capacity()` 早退与乘法溢出保护
- `MemInstallTerminateHandler()`：OOM 时弹一次带建议的模态提示后 `_Exit`（而不是静默消失）
接入：
- `Utilities/Src/DataModel.cpp`：全仓**唯一**的 `try/catch`（`extremes.reserve` 捕
`std::bad_alloc`）改为 `MemReserveIfRoom(extremes, count / 8)`
- `Components/PlotView/Src/PlotView.cpp`：`AvailablePhysicalBytes()` 原有一份**完整重复**
的 `GlobalMemoryStatusEx` + 缓存实现 → 转发 `MemAvailablePhysical()`
- `Components/Application/Src/Application.cpp`：`Initialize()` 开头安装 terminate handler
### 3. L1 几何产物层
新增 `Components/Shared/Inc/UiBox.hpp` + `Src/UiBox.cpp`：
- `struct UiBox { rect, clip, depth, layer }` —— 纯值类型，不继承任何东西
（继承会和 PlotView 4 层位图缓存 / SignalPanel 行位图缓存的失效体系打架）
- `class UiBoxTable : public UiTextRectSink` —— 只累计几何 + 裁剪/层/遮挡，**不含绘制代码**
`UiComponent::CollectDebugBoxes` → **`virtual void BuildBoxes(UiBoxTable&)`**：
组件从"收集布局边界（调试用）"改为"上报几何产物"，不再需要知道"调试"这个概念存在。
`UiDebugBounds.hpp/.cpp` 退化为唯一的消费者（配色 + 包角描边 + 遮挡挖洞）。
除宿主 `ApplicationCommands.cpp` 外，所有组件源码现在只包含 `UiBox.hpp`。
### 4. 审计
- `MemProbe` 里"省 40~60KB"的估算 → 改为实测 27,136 B
- `MemProbe.hpp` 的 `<new>`、`MemProbe.cpp` 的 `<cstdio>`：未使用，删除
- `UiDebugPaintBounds(g, rect, depth)`：零调用者，删除（只保留带 clip 的版本）
- `TabBar`/`Toolbar`/`PlotView`/`SignalPanel` 的 `BuildBoxes` 文档"（调试用）"→"几何 box"
- `PlotView::SetForceFullRepaint` 补写"为什么保留而不优化"
### 5. 文档
`Documents/UI_Refactor_Plan.md` / `_Progress.md` / `_Report.md` 先 `git rm` 再按
「计划 / 当前进度 / 最终报告」重建；`Documents/agent_mem.md` 追加第十三轮记录。
## 怎么验证
```
make clean
make release TARGET_FILE_NAME=JustDataInspector -j16 # 零 error / 零 warning，788,992 B
make debug TARGET_FILE_NAME=JustDataInspectorD -j16 # 零 warning
uicheck 69/69 lbcheck 21/21 lbresid 5/5 lbzorder 4/4 lbcovr 7/7 lbpanel 10/10
rendercheck: 8 个场景哈希与改造前逐一相同 + FUNC 7/7 PASS, exit=0
A FAED59DF284153DB B E6443BFE4E3955F8 C 96A0AA8C402F1729 D E3D5DBD998E43720
E DA0583CB13C26A6F F FFB822159F604D1D G 19F8DE8FE3A8DF18 H DBBDDE4CB2C97C92
```
体积溯源（`objdump -h`，基线 → 最终）：
`.text` 735,600 → 657,168；`.rdata` 49,184 → 35,016；
`.xdata` 48,132 → 27,512；`.pdata` 35,424 → 28,524；`.rsrc` 20,656 不变。
## 没做什么（有意为之）
- **没有拆 DLL**（用户明确要求单文件）
- **没有改优化等级**（`-Oz` 保持）
- **L2（`UiDamage` 脏矩形 + 独立叠加层）评估后缓做**：受益方只有"调试开关打开时的帧率"，
而正确实现必须把叠加层旧矩形注入底层组件重绘范围，穿透 PlotView 四条快路径 + 两层缓存；
在用户反复报过"拖拽错位 / 贴图残留"的背景下，风险与收益不成比例。理由写在
`Documents/UI_Refactor_Plan.md` §5 与 `PlotView::SetForceFullRepaint` 的文档里。
This commit is contained in:
DeepSeek V4.1 Flash committed
1 parent
739a523af5
commit
044b87383b
34 files changed
+1117
-2200
No files matched your search
+116
-557
@@ -1,594 +1,153 @@
|
||||
# UI 重构计划（UI_Refactor 分支）
|
||||
# Just DataInspector UI 重构 —— 计划
|
||||
|
||||
> 目标读者：本项目的后续 Agent（可能是另一台设备 / 另一个模型）。
|
||||
> 本文是**唯一施工蓝图**；实时进度见 `Documents/UI_Refactor_Progress.md`，最终结论见 `Documents/UI_Refactor_Report.md`。
|
||||
> 硬约束的权威来源仍是 `Documents/agent_mem.md`（§11.2）；本文与之冲突时**以 agent_mem.md 为准**。
|
||||
> 本文档只描述**要做什么、为什么这么做、怎么验收**。
|
||||
> 已完成情况见 `UI_Refactor_Progress.md`，结论与遗留见 `UI_Refactor_Report.md`。
|
||||
> 最后更新：2026-10-29
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么要重构（量化基线）
|
||||
## 1. 目标与非目标
|
||||
|
||||
| 指标 | 现状 | 出处 |
|
||||
### 1.1 目标
|
||||
|
||||
| # | 目标 | 判据 |
|
||||
| --- | --- | --- |
|
||||
| `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） | 仓库现状 |
|
||||
| G1 | 收敛"宿主点名每个组件"的散乱结构 | 宿主只遍历一张组件表，不再 `if (component == plot)` 式分支 |
|
||||
| G2 | 几何只有**一处**来源 | "画出来的形状"与"能点到的区域"由同一批函数给出，不再各算一遍 |
|
||||
| G3 | 源码按**职责**分片，单片可读 | 单个 `.cpp` 不超过约 1200 行；文件名与内容一致 |
|
||||
| G4 | 减小产物体积，且**仍然只有一个 `.exe`** | 体积比基线小，无新增依赖 DLL |
|
||||
| G5 | 关闭 C++ 异常后**不牺牲健壮性** | 所有大块分配前有预检验；OOM 有可见提示 |
|
||||
| G6 | 重构**不得改变任何绘制像素** | 8 个场景的逐像素哈希与基线逐一相同 |
|
||||
|
||||
`PlotViewPaint.cpp` 里混住四类内容：真绘制 ≈3.5k / 光栅化缓存 ≈2.5k / 缓存键 ≈1.1k / **布局与命中几何 ≈1.3k**。
|
||||
### 1.2 非目标（明确不做）
|
||||
|
||||
**五条根因**
|
||||
|
||||
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 协作防回归的核心资产）。
|
||||
* **不把编译产物拆成 DLL**：本项目的定位是"单文件、拷过去就能跑的轻量工具"。
|
||||
任何以拆 DLL 换体积的方案一律否决。
|
||||
* **不改优化等级**（`-Oz` 保持不变）。
|
||||
* **不把"波形"与"网格线"拆成两层位图**：像素级平移不变量会被破坏。
|
||||
* **不为体积牺牲可维护性**（例如放弃分片、放弃几何同源）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计目标与非目标
|
||||
## 2. 硬约束
|
||||
|
||||
### 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` 会覆盖用户平移（第一代已因此回退） |
|
||||
| ❌ 逐控件细粒度像素缓存 | 画一个按钮 20~80µs vs 贴图 5~10µ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，必须走失效 |
|
||||
1. **单一可执行文件**：不得引入额外的 `.dll` / 运行时依赖。
|
||||
2. **体积预警阈值 = 1MB（1,048,576 B）**。这不是硬上限：超过仍可发布，
|
||||
但必须主动提醒用户，并说明"超在哪一段（`.text` / `.rdata` / `.xdata`+`.pdata` / `.rsrc`）、
|
||||
由哪个改动贡献"。旧的 900KB / 800KB 红线**已作废**。
|
||||
3. **异常处理用预检验，不用 try/catch**：`-fno-exceptions` 下 `try/catch` 不会被编译，
|
||||
因此所有"按数据规模预留大块内存"的地方必须先问 `MemReserveIfRoom()`。
|
||||
4. **像素级零回归**：验收以 `Tools/rendercheck` 的 8 个场景哈希为准。
|
||||
5. **中文注释按 UTF-8 无 BOM 保存**；构建参数用 `-finput-charset=UTF-8 -fexec-charset=GBK`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标架构
|
||||
## 3. 分层架构（L0–L3）
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
L3 体积与异常策略 -fno-exceptions / MemProbe / LTO / gc-sections
|
||||
▲
|
||||
L2 重绘范围控制 UiDamage（脏矩形） ← 本轮评估后**缓做**，见 §5
|
||||
▲
|
||||
L1 几何产物层 UiBox / UiBoxTable / UiComponent::BuildBoxes
|
||||
▲
|
||||
L0 组件协议 UiComponent + 组件表 + UiWidget 控件树
|
||||
```
|
||||
|
||||
**分层原则**
|
||||
### L0 组件协议（前几轮已完成）
|
||||
|
||||
- **共享一张缓冲**：省内存、免分配抖动、合成顺序天然确定。
|
||||
- **只有高成本叶子自持缓冲**：这是"把重画换成贴图"的唯一手段。
|
||||
- **脏区向下取交集**（不是并集）。
|
||||
- **布局由下往上、每帧最多一轮 Measure**；尺寸由内容反推（`EdgePanelWidth` 就是这种）。
|
||||
* `UiComponent`：`SetScale / Layout / Area / Paint / HitTest / OnMouseLeave / IsEditing / QueryCursor`。
|
||||
* 宿主持有一张**有序组件表**，逐个遍历；新增组件不必改宿主的 5 处消息分支。
|
||||
* `UiWidget` 与 `UiComponent` 是**兄弟**而非父子：前者管"一块区域内部的布局/命中/绘制"，
|
||||
后者管"自己这一整块地盘：区域、缓存、局部重绘策略"。
|
||||
`Toolbar` / `TabBar` 同时是两者。
|
||||
|
||||
### 2.1 新增文件
|
||||
### L1 几何产物层（本轮完成）
|
||||
|
||||
| 文件 | 职责 | 依赖 |
|
||||
| --- | --- | --- |
|
||||
| `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/Inc/UiBox.hpp` + `Src/UiBox.cpp`。
|
||||
* `struct UiBox { rect, clip, depth, layer }`：**纯值类型**，不继承任何东西。
|
||||
* `class UiBoxTable`：几何收集器，只维护"矩形 / 层级 / 绘制层 / 裁剪 / 遮挡"这些**几何事实**，
|
||||
**不含任何绘制代码**。
|
||||
* `UiComponent::BuildBoxes(UiBoxTable&)`：组件上报自己的几何产物（默认只登记 `Area()`）。
|
||||
* `UiDebugBounds` 退化为**消费者**：`UiDebugPaintBoxList(g, table)` 把几何画成彩色包角线。
|
||||
⇒ 组件不再需要知道"调试"这个概念存在。
|
||||
|
||||
> ⚠️ `Components/Shared` 已在 `Makefile` 的 `CXX_INCLUDES_PATHS` / `CXX_SOURCES_PATHS` 中 ⇒ 新增 `.cpp` **无需改 Makefile**（按 basename 自动收集）。
|
||||
### L2 重绘范围控制（缓做 —— 见 §5）
|
||||
|
||||
* 设计意图：`UiDamage`（最多 12 个矩形的脏区集合，超限退化为包围盒）替代
|
||||
"全窗重绘 / 绘图区重绘"的二值分支；`PlotView::Paint(g, UiDamage&)` 逐路径累加脏区。
|
||||
* 收益：去掉 `SetForceFullRepaint`（布局边界开关打开时的整幅重绘）。
|
||||
|
||||
### L3 体积与异常策略（本轮完成）
|
||||
|
||||
见 `UI_Refactor_Progress.md` 的实测表。
|
||||
|
||||
---
|
||||
|
||||
## 3. 布局层设计（`UiLayout`）
|
||||
## 4. 阶段与验收标准
|
||||
|
||||
### 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` 绘制样式，不是布局 |
|
||||
| P1–P6 | 文件按职责拆分、`UiComponent` 协议、组件表、布局边界功能 | 编译 + `uicheck` |
|
||||
| P7 | 布局边界"几何同源"（`RowRect` 前缀和、文本墨迹矩形、浮层层级/遮挡/裁剪） | `lbcovr` / `lbzorder` / `lbresid` / `lbpanel` |
|
||||
| P8 | 体积：`-fno-exceptions` + `MemProbe` + `-ffunction-sections` + `--gc-sections` | 体积下降且 8 哈希不变 |
|
||||
| P9 | 体积：LTO（含 `-flto-partition=one` 稳定性约束） | 同上，且可重复构建 |
|
||||
| P10 | L1 几何产物层（`UiBox` / `UiBoxTable` / `BuildBoxes`） | 同上，且源码零残留旧名 |
|
||||
| P11 | 代码审计（过时注释 / 名实不符 / 死代码） | 零 warning + 全量回归 |
|
||||
| P12 | 文档重建 + 本地提交 | `git status` 干净 |
|
||||
|
||||
### 3.3 `UiLayoutCache`（本次最关键的性能点）
|
||||
**统一验收命令**
|
||||
|
||||
`EdgePanelLayoutFor` 的 19 个调用点全部来自"同一份几何被反复问"。做法：
|
||||
```powershell
|
||||
make clean
|
||||
make release TARGET_FILE_NAME=JustDataInspector -j16 # 期望零 error / 零 warning
|
||||
make debug TARGET_FILE_NAME=JustDataInspectorD -j16 # 期望零 warning
|
||||
|
||||
```cpp
|
||||
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();
|
||||
};
|
||||
objdump -h Build\Release\JustDataInspector.exe # 段构成，用于体积溯源
|
||||
|
||||
Tools\uicheck\uicheck.exe # 69/69
|
||||
.preflight\lbcheck\lbcheck.exe # 21/21
|
||||
.preflight\lbresid\lbresid.exe # 5/5
|
||||
.preflight\lbzorder\lbzorder.exe # 4/4
|
||||
.preflight\lbcovr\lbcovr.exe # 7/7
|
||||
.preflight\lbpanel\lbpanel.exe # 10/10
|
||||
Tools\rendercheck\rendercheck.exe # 8 哈希不变 + FUNC 7/7
|
||||
```
|
||||
|
||||
**硬约束**：`Invalidate` 必须由"改变几何的那条路径"**显式**调用（与 `m_edgeScans` 的定向失效同一纪律），**禁止**为了让缓存命中率好看而整体 `Clear()`。
|
||||
---
|
||||
|
||||
## 5. 明确缓做的部分及理由
|
||||
|
||||
### L2 `UiDamage` + 独立叠加层（S4）
|
||||
|
||||
**为什么缓做**
|
||||
|
||||
1. 受益方只有"**调试开关打开时**的帧率"。`SetForceFullRepaint` 只在
|
||||
「显示布局边界」开启时被置位（`Application::Render` 里 `m_plot.SetForceFullRepaint(m_showLayoutBounds)`），
|
||||
普通用户路径上**本来就是快路径**。
|
||||
2. 正确实现无法只改 `PlotView` 内部：宿主用的是**持久后备缓冲区**，
|
||||
上一帧叠加层画上去的边框像素必须在下一帧被"底层内容重画"覆盖掉。
|
||||
若改成"独立叠加位图 + 只混合脏区"，就必须把叠加层的旧矩形**注入**到底层组件的重绘范围里 ——
|
||||
这要穿透 `PlotView` 的全部四条快路径（静态场景贴图 / 宽基底贴图 / 样式补丁 / 网格层重建）
|
||||
与两层缓存。
|
||||
3. 风险与收益不成比例：用户已在 2026-10-28 反复报告过"拖拽错位 / 贴图残留"一类事故，
|
||||
而这类事故正是从"某条快路径漏了某块像素"开始的。
|
||||
|
||||
**保留了什么**：`SetForceFullRepaint` 及其四处守卫、`UiBoxTable` 的几何产物。
|
||||
将来若真要做，只需把 `UiBoxTable` 的 `rect` 直接喂给 `UiDamage`，不需要重新收集几何。
|
||||
|
||||
---
|
||||
|
||||
## 4. 控件基类设计（`UiWidget`）
|
||||
## 6. 交付物清单
|
||||
|
||||
### 4.1 接口骨架
|
||||
|
||||
```cpp
|
||||
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`）：
|
||||
```cpp
|
||||
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` 未被触碰。
|
||||
|
||||
---
|
||||
|
||||
# 第六阶段（2026-10-28）：「显示布局边界」调试开关 + 三处可见收益优化
|
||||
|
||||
> 用户要求：先做可见收益的优化，然后在「导入文件」左侧加一个齿轮按钮，点击展开二级菜单，
|
||||
> 菜单里放「显示布局边界」勾选项，风格参考 Android 调试功能；先落地，后续再改进。
|
||||
|
||||
## 1. 可见收益的优化（3 项，均为纯收益、行为不变）
|
||||
|
||||
| # | 位置 | 改前 | 改后 | 收益 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| O1 | `Toolbar::Layout` | **每次**都 `RebuildWidgets()`（销毁 + 重建整棵树） | 新增 `m_treeDirty`，只在规格/字体/主题/缩放/动态文本变化时重建 | 拖动面板分隔条时 `Relayout` 每帧调用一次 ⇒ 每帧省 10 次堆分配 + 8 次测量缓存失效 |
|
||||
| O2 | `Toolbar::SetActionLabel` | 同时写「覆盖表」和「控件文本」两处 | 只写覆盖表 + 置树脏 | 消除双写可能不同步（旧实现下次重建会把文本退回默认值） |
|
||||
| O3 | `Toolbar` / `TabBar` 的 `OnMouseMove` | 各自手写 `Dispatch(); return UiRectHasArea(TakeDirty());` | 新增 `UiWidget::DispatchRedraw(event)` | 两处重复收敛成一处；`TakeDirty()` 会清零，漏掉一次就把下一次真实变化误判为"无变化" |
|
||||
|
||||
## 2. 新功能：齿轮按钮 → 应用设置菜单 → 显示布局边界
|
||||
|
||||
### 2.1 入口
|
||||
|
||||
* `ToolbarAction::SETTINGS` + `kButtonSpecs[0]`（`UiButtonIcon::GEAR`）。
|
||||
* 工具栏布局从"首按钮靠左 + 其余靠右"改为**左侧固定簇**（`kLeftClusterCount = 2`：齿轮 + 导入文件）+ 右侧按钮组。
|
||||
* 齿轮是**矢量绘制**（`PaintGearIcon`：8 齿 + 外环 + 轴孔，全部按 `half` 的比例推导），
|
||||
不用字体里的 `⚙` —— 该字符在不同回退字体里的大小与基线不一致，会"忽大忽小、垂直不居中"。
|
||||
* `UiButtonWidget` 新增 `UiButtonIcon`（`NONE`/`GEAR`）与 `SetIcon`；图标按钮宽度固定 40 逻辑像素。
|
||||
* `Application::OpenSettingsMenu()` 用 `Toolbar::ButtonRect(SETTINGS, …)` 取**控件实测矩形**做锚点
|
||||
（宿主不自己推算按钮几何），菜单在按钮下沿 +4 逻辑像素处右下展开。
|
||||
|
||||
### 2.2 菜单
|
||||
|
||||
`MenuScope::APP_SETTINGS`（新增）→ 宿主自己处理，不下发到组件。
|
||||
条目：`HEADER "调试"` + `NORMAL "显示布局边界"`（`keepOpen = true`，点击后菜单保持打开，
|
||||
勾选态由 `PopupMenu::UpdateItemLabel` 回写）。
|
||||
|
||||
### 2.3 布局边界：为什么放在共同基类
|
||||
|
||||
`UiComponent` 新增 **`virtual void PaintDebugBounds(gd::Graphics&, float scale)`**，默认只画 `Area()`。
|
||||
四个组件各自覆盖：先调基类（自己的区域），再补画**层级更深的**矩形。
|
||||
|
||||
这正是上一轮回答里"是不是只需要在共同基类内实现"的答案：
|
||||
**能覆盖顶层 4 块区域，覆盖不了组件内部的手绘结构**。所以采用"基类给出协议 + 组件自己上报"：
|
||||
|
||||
| 组件 | 上报内容 |
|
||||
| --- | --- |
|
||||
| 全部 | `Area()`（层级 0） |
|
||||
| `Toolbar` / `TabBar` | 跳过与区域重合的根控件，直接遍历 `m_root->Children()`（层级 1）；TabBar 另加每个 ✕（层级 2） |
|
||||
| `SignalPanel` | 表头 / 筛选框 / 列表 / 样式区（1）＋ 滚动条、样式行、**当前可见**的列表行（2） |
|
||||
| `PlotView` | 每个 `LaneVisual::rect`（1）；**不**上报曲线/胶囊/提示这类随数据变化的瞬态几何 |
|
||||
| 宿主 | 客户区外框、分隔条、打开的菜单 / 拾色器（层级 0） |
|
||||
|
||||
`UiWidget::PaintDebugBounds(g, scale, depth)` 递归整棵控件树 —— 凡已上树的控件**零成本**获得边界。
|
||||
|
||||
### 2.4 视觉与实现约束
|
||||
|
||||
* **只描边、不填充**（与 Android 一致）：填充会在几十个嵌套矩形上层层叠加把内容糊住。
|
||||
* 层级配色：0 青蓝 `#29B6F6`（2px）/ 1 品红 `#E040FB` / 2 琥珀 `#FFB300` / ≥3 绿 `#66BB6A`（1px）。
|
||||
* 线宽按**设备像素**固定（不乘 `scale`），并临时 `PixelOffsetModeNone` + 关抗锯齿 + 矩形对齐整像素，
|
||||
保证 1px 就是 1px。
|
||||
* 绘制位置：`Render` 的**最后一步**（加载遮罩之后）。⚠️ **绝不进入任何位图缓存**
|
||||
（`PlotView` 4 层缓存、`SignalPanel` 行位图缓存）—— 否则关掉开关后线条会残留。
|
||||
* `fullFrame` 追加 `m_showLayoutBounds`：开启时必须整帧回送，否则"只回送绘图区"的快路径会让
|
||||
装饰区的边界停在旧帧上。
|
||||
|
||||
## 3. 验证
|
||||
|
||||
| 项 | 结果 |
|
||||
| --- | --- |
|
||||
| `make release` / `make debug` | 零 error / 零 warning |
|
||||
| **新增离屏探针 `.preflight/lbcheck`** | **21 / 21 PASS** |
|
||||
| `Tools/rendercheck` 8 场景**工具栏以下区域**哈希 | 与改造前**逐一相同**（改动只落在工具栏带内） |
|
||||
| `Tools/rendercheck` 7 条功能断言 | 7 / 7 PASS |
|
||||
| `Tools/uicheck` | 69 / 69 |
|
||||
| `TargetCheck.exe` | 897 024 B（< 900 KB） |
|
||||
|
||||
新增断言覆盖：齿轮存在 / 在「导入文件」左侧 / 同高 / 更窄；开机后无调试色；
|
||||
开启后青蓝 24 930 px、品红 19 734 px；**关闭后逐像素回到开启前**；菜单 scope、锚定贴合按钮、
|
||||
宽度未被撑大、条目初始未勾选、点击翻转开关、菜单保持打开。
|
||||
|
||||
## 4. 后续可改进（用户："先落地实现然后再进一步改进"）
|
||||
|
||||
1. 边界左上角标短 tag（`row#12` / `lane3`）—— 需要处理 GDI 文本不受 GDI+ 裁剪约束的问题。
|
||||
2. `PlotView` 的浮动面板（`EdgePanelLayout` 里的 `panel/title/close/…`）目前未上报；
|
||||
它们已经是集中结构，插入一个循环即可。
|
||||
3. `SignalPanel` 的复选框 / 徽标 / ✕ 等行内子块（现在只到"行"这一层）。
|
||||
4. 开关状态目前**不持久化**（重启恢复为关闭）；若要持久化需要引入配置存储。
|
||||
5. 菜单只有一项；后续设置项按 `HEADER` 分组追加即可。
|
||||
|
||||
---
|
||||
|
||||
# 第七阶段计划（2026-10-28 第九轮）：边界观感重做 + 覆盖补全 + 几何同源
|
||||
|
||||
> 用户反馈：① 设置齿轮按钮的颜色应与「导入文件」一致；
|
||||
> ② 边界绘制"就是实心矩形、粗细不一"，希望是**四角粗、其他边细**；
|
||||
> ③ 按上一轮总结的覆盖率问题着手改进（很多元素没有边界）。
|
||||
|
||||
## 任务清单
|
||||
|
||||
| # | 任务 | 验证手段 |
|
||||
| --- | --- | --- |
|
||||
| P7-1 | 齿轮按钮改为主按钮（`primary = true`），与「导入文件」同色 | 探针断言两按钮底色一致 |
|
||||
| P7-2 | 边界的描边改为**四角粗（3–4px）+ 四边细（1px）**的包角样式；只描边不填充 | 逐像素探针 + 人工核对 |
|
||||
| P7-3 | 层级 > 0 的 box 内缩 1px，避免与父矩形共边时叠成粗线 | 同上 |
|
||||
| P7-4 | 协议从「组件自己画」改为「组件**收集 box**、宿主统一画」（`CollectDebugBoxes`） | 编译 + 探针 |
|
||||
| P7-5 | `SignalPanel`：行内元素全部上报（复选框/色块/名称/GX 徽标/✕/折起三角/组名/计数）+ 筛选框/清空✕/滚动条/滑块/样式区 5 行与行内控件/目标行/编辑框 | 探针断言 box 数量 |
|
||||
| P7-6 | `PlotView`：GX 徽标、装饰层矩形、图例条目（托底/色块/文本）、5 类浮动面板全部字段 | 同上 |
|
||||
| P7-7 | `Toolbar`：按钮内部**文本/图标**矩形（新增 `UiButtonWidget::ContentRect()`） | 同上 |
|
||||
| P7-8 | `PopupMenu` / `ColorPickerPopup`：条目、滚动区/轨道/滑块、子菜单；拾色器各控件 | 同上 |
|
||||
| P7-9 | `RowRect` 从 **O(row) → O(1)**（行顶前缀和 `m_rowTop`） | 行为不变（像素哈希） |
|
||||
| P7-10 | `PanelBounds()` 收敛 6 处重复三元表达式 | 编译 |
|
||||
| P7-11 | 三份文档 + `agent_mem.md` 同步；`TargetCheck.exe` < 900 KiB | 构建 |
|
||||
|
||||
## 风险与对策
|
||||
|
||||
| 风险 | 对策 |
|
||||
| --- | --- |
|
||||
| 前缀和与行集合短暂不一致 | `RowRect` / `ContentOffsetBeforeRow` 检测长度后**退回逐行累加**（正确性优先） |
|
||||
| box 数量暴涨导致调试帧变慢 | 只在开关打开时执行；标签设**尺寸门槛**（< 56×16 逻辑像素不画标签） |
|
||||
| 调试层污染位图缓存 | 仍只在 `Render` 最后一步叠加，探针 `bounds-off-restores-pixels` 钉住 |
|
||||
| 浮层 box 需要读取私有几何 | 给两个浮层加 `CollectDebugBoxes`，几何仍由它们自己给出（不外泄成员） |
|
||||
|
||||
## 完成判据
|
||||
|
||||
* `make release` / `make debug` 零 error 零 warning；
|
||||
* 「工具栏带以下」区域哈希与上一轮**逐一相同**（证明改动只落在工具栏带内）；
|
||||
* `lbcheck` 21/21、`rendercheck` FUNC 7/7、`uicheck` 69/69；
|
||||
* 打开开关后：每行的复选框/色块/名称/GX 徽标/✕、每个网格的 GX 徽标与图例、每个浮层控件都有独立包角框。
|
||||
|
||||
---
|
||||
|
||||
# 第八阶段计划（2026-10-28 第十轮）：边界观感自适应 + 残留与层级缺陷修复
|
||||
|
||||
> 用户反馈：① 包角对小元素来说太粗（小方框直接变成粗描边）；② 不需要黑色底衬的文字标签；
|
||||
> ③ 加载 MF4-Record.MF4 全部信号独立网格后，按住左键拖动网格滚动条快速滚动会出现大量
|
||||
> 绘制残留（工具栏与网格区域都有），松开并移动鼠标才消失；④ 右键二级菜单上被下层元素的
|
||||
> 边界线覆盖，干扰观察菜单布局。
|
||||
|
||||
## 任务清单
|
||||
|
||||
| # | 任务 | 验证手段 |
|
||||
| --- | --- | --- |
|
||||
| P8-1 | 包角粗细／长度按矩形短边自适应；小方框只画角不画边；过小则不画 | 截图放大 3 倍核对 |
|
||||
| P8-2 | 删除文字标签（连同 `UiDebugPaintStyle`），降低体积与视觉噪声 | 编译 + 体积 |
|
||||
| P8-3 | 定位并修复「拖网格滚动条时的绘制残留」 | 新增离屏探针 `.preflight/lbresid` |
|
||||
| P8-4 | 修复 `PlotView` 误用 `m_decorRects`（位图坐标系）产生的跨工具栏幽灵框 | 同上（box 清单打印） |
|
||||
| P8-5 | 调试叠加层开启时强制绘图区整幅重绘（禁用三条快路径） | 同上（同状态两帧必须逐像素相同） |
|
||||
| P8-6 | box 增加 `clip`（组件地盘），组件内越界元素不再画到邻居上 | 同上（差异 bbox 不得越过绘图区上沿） |
|
||||
| P8-7 | 层级：`(layer, depth)` 双排序键 + 浮层 `occluder` 挖洞 | 新增探针 `.preflight/lbzorder`（4 条断言） |
|
||||
| P8-8 | 文档与共享记忆同步；`TargetCheck.exe` < 900 KiB | 构建 |
|
||||
|
||||
## 风险与对策
|
||||
|
||||
| 风险 | 对策 |
|
||||
| --- | --- |
|
||||
| 强制整幅重绘让调试模式变慢 | 只在开关打开时生效；关闭立即恢复快路径 |
|
||||
| `Region::Exclude` 影响其他绘制 | 只在 `Save/Restore` 内临时 `SetClip`，且仅在存在遮挡时才走该分支 |
|
||||
| 裁剪把紧贴边界的包角裁掉 | 裁剪用 `floor/ceil` 向外取整（宁可多一像素） |
|
||||
| 移除标签后难以辨认 box 归属 | 层级配色（青蓝/品红/琥珀/绿）+ 包角形状 |
|
||||
|
||||
## 完成判据
|
||||
|
||||
* 零 warning；`lbresid` 5/5、`lbzorder` 4/4、`lbcheck` 21/21、`uicheck` 69/69；
|
||||
* `rendercheck` 的「工具栏带以下」区域哈希与上一轮**逐一相同**、FUNC 7/7；
|
||||
* 拖动滚动条期间工具栏区域像素**完全不变**，且同状态两帧**逐像素相同**；
|
||||
* 菜单/二级子菜单区域内不出现下层组件的边界色。
|
||||
|
||||
---
|
||||
|
||||
# 第九阶段计划（2026-10-28 第十一轮）：把"边界"这件事从补丁改成机制
|
||||
|
||||
> 背景：第十轮结论是"三个性质不同的问题"——① `inset` 破坏 '框 = 可见形状外接矩形'；
|
||||
> ② 元素清单不完整（几何没有枚举出口）；③ 描边图元太多。本轮把三者一起解决。
|
||||
|
||||
## 任务清单
|
||||
|
||||
| # | 任务 | 验证手段 |
|
||||
| --- | --- | --- |
|
||||
| P9-1 | **取消内缩**：框必须与可见形状外接矩形重合（修 GX 胶囊圆弧落在框外） | 探针断言 box 与 `LaneBadgeRect` 重合（容差 0.5px） |
|
||||
| P9-2 | **文本获得几何身份**：`PaintUtil` 增加 `UiTextRectSink`，在绘制的**唯一出口**回报墨迹矩形 | 覆盖 60+ 调用点，无需逐处修改 |
|
||||
| P9-3 | 离屏位图（面板行缓存）中的文本按**位图原点**回放，缓存命中也能显示文本框 | 探针 `row-text-boxes-from-cached-rows` |
|
||||
| P9-4 | 补齐 `PlotView` 漏项：时间轴 / 网格滚动条 / 回到最上方 / 光标标签 / 差值标签 / 内联输入框 | 探针 4 条 box 断言 |
|
||||
| P9-5 | 描边图元 12 → 8（4 边 + 4 角块），耗时 5.9ms → 4.0ms | 微基准 + 帧耗时分解 |
|
||||
| P9-6 | 关闭开关时清空容器（释放内存，避免误读） | 探针 `boxes-cleared-when-off` |
|
||||
| P9-7 | 文档 + 共享记忆；`TargetCheck.exe` < 900 KiB | 构建 |
|
||||
|
||||
## 关键设计决定
|
||||
|
||||
* **文本不做"逐处登记"**：全仓 65 处文本绘制点手写登记必漏。改为在 `UiText`/
|
||||
`UiTextClipped`/`UiTextAtClipped` 的公共出口 `ReportTextRect()` 里回报一次，
|
||||
代价是开关关闭时一次判空。
|
||||
* **缓存命中也要有文本框**：行位图渲染时用一个本地收集器把矩形存进 `RowBitmapCache`，
|
||||
贴图时按原点偏移回放；否则第二帧起文本框全部消失。
|
||||
* **不内缩**：重叠时"后画的覆盖"就是正确语义，内缩是错误取舍。
|
||||
|
||||
## 完成判据
|
||||
|
||||
* 零 warning；四个探针全绿（21 + 5 + 4 + 7）、`uicheck` 69/69；
|
||||
* `rendercheck` 8 个场景的整帧与区域哈希与上一轮**逐一相同**（调试功能不能影响正常绘制）；
|
||||
* 打开开关后：文本有橙色墨迹框、GX 胶囊被框住、时间轴/滚动条/回到最上方均有框。
|
||||
|
||||
---
|
||||
|
||||
# 第十阶段计划（2026-10-29 第十二轮）：同步远端 + 既有性能问题 + 浮层层级修复
|
||||
|
||||
> 用户报告（附截图）：① 远端 gitea 已把 `UI_Refactor` 合入 `main`（分支保留），需 fetch 并同步各分支，
|
||||
> `dev` 为意外产物，本地删除；② 排查"顺带发现的既有性能问题"并解决；③ 浮动面板被网格边界穿透；
|
||||
> ④ 滚动网格滚动条时浮动面板上的边界闪烁；⑤ 信号面板 GX 徽标的「所属网格」二级菜单边界溢出菜单、
|
||||
> 滚动后条目仍像在绘制。
|
||||
|
||||
## 任务清单
|
||||
|
||||
| # | 任务 | 验证手段 |
|
||||
| --- | --- | --- |
|
||||
| P10-1 | `git fetch` 同步；`main` 快进到 `gitea/main`；本地删除 `dev`；`UI_Refactor` 快进到合并提交 | `git branch -vv` |
|
||||
| P10-2 | 定位"空闲帧比强制整帧更慢"的真因 | 离屏计时探针 |
|
||||
| P10-3 | 修复：离屏网格不再逐帧算内容指纹/入队 | 排空后稳态与排空过程分别计时 |
|
||||
| P10-4 | 浮动面板另起绘制层 + 登记遮挡矩形 + 内容裁剪到面板 | 新增探针 `.preflight/lbpanel` |
|
||||
| P10-5 | 弹出菜单条目裁到可视区（滚动条目不再登记盒子） | 同上（10 条断言） |
|
||||
| P10-6 | `EdgePanelLayoutFor` 只在"该网格有面板展开"时才调用 | 收集耗时对比 |
|
||||
| P10-7 | 文档 + 共享记忆；零警告；< 900 KiB | 构建 |
|
||||
|
||||
## 关键结论（P10-2）
|
||||
|
||||
用两级计时探针（先整体、再拆到 `WarmLaneLayersStep` 内部）测得：
|
||||
|
||||
* "空闲帧 2.4ms" **不是稳态**，而是**图层预热队列排空**的瞬时开销
|
||||
（16 个网格 × 每帧补 1 个 ≈ 1~3ms/帧，约 16 帧后结束）；
|
||||
* 排空后稳态为 **0.53ms**，与"强制整帧"的 0.46ms 基本相同 —— 所以**不存在**每帧白烧的固定开销；
|
||||
* 但 `RollWideBuffer` 里"先算每网格内容指纹、再判断是否可视"的顺序确实有问题：
|
||||
283 个网格每帧全算一遍 `LaneLayerKey()`（约 0.7ms），并会把离屏网格塞进待重画队列。
|
||||
**把可视性判断提到最前面**后，离屏网格既不哈希也不入队。
|
||||
|
||||
## 完成判据
|
||||
|
||||
* 零 warning；`lbpanel` 10/10 + 既有四个探针全绿；`uicheck` 69/69；
|
||||
* `rendercheck` 8 场景哈希与上一轮**逐一相同**（本轮不应改变任何正常绘制像素）；
|
||||
* 面板区域内不出现网格层颜色；菜单/面板的盒子不得完全落在自身矩形之外。
|
||||
Components/Shared/Inc/UiBox.hpp 新增（几何产物层）
|
||||
Components/Shared/Src/UiBox.cpp 新增
|
||||
Components/Shared/Inc/UiDebugBounds.hpp 精简为"只画"（消费者）
|
||||
Components/Shared/Src/UiDebugBounds.cpp 精简为"只画"
|
||||
Components/Shared/Inc/UiComponent.hpp CollectDebugBoxes → BuildBoxes
|
||||
Utilities/Inc/MemProbe.hpp 新增（分配预检验 + terminate 兜底）
|
||||
Utilities/Src/MemProbe.cpp 新增
|
||||
Makefile LAYOUT_BOUNDS / NO_EXCEPTIONS / LTO 三个开关
|
||||
Documents/UI_Refactor_{Plan,Progress,Report}.md 重建
|
||||
```
|
||||
Reference in new issue
Block a user