chore(docs): 删除过时的 UI 重构阶段文档
Documents/UI_Refactor_Plan.md、UI_Refactor_Progress.md、UI_Refactor_Report.md 描述的是 2026-10-28 那一阶段的计划与结论，已被后续多轮实现推翻/覆盖， 且内容与当前代码不一致，继续保留会误导接手者。 删除后由 Documents/Code_Review_Plan.md / Code_Review_Progress.md / Code_Review_Report.md 承接（下一分支 Code_Review）。
This commit is contained in:
DeepSeek-V4.1-Flash committed
1 parent
266ab657be
commit
764e5bee71
3 files changed
-512
No files matched your search
@@ -1,202 +0,0 @@
|
||||
# Just DataInspector UI 重构 —— 当前进度
|
||||
|
||||
> 计划见 `UI_Refactor_Plan.md`，结论与遗留见 `UI_Refactor_Report.md`。
|
||||
> 最后更新：2026-10-29（本轮：体积 L3 落地 + L1 几何产物层 + 审计）
|
||||
|
||||
---
|
||||
|
||||
## 1. 总览
|
||||
|
||||
| 层 | 内容 | 状态 |
|
||||
| --- | --- | --- |
|
||||
| L0 | `UiComponent` 协议 + 有序组件表 + `UiWidget` 控件树 | ✅ 已完成（前几轮） |
|
||||
| L1 | `UiBox` / `UiBoxTable` / `UiComponent::BuildBoxes` | ✅ **本轮完成** |
|
||||
| L2 | `UiDamage` 脏矩形 + S4 独立叠加层 | ⏸ **评估后缓做**（理由见 Plan §5） |
|
||||
| L3 | `-fno-exceptions` + `MemProbe` + `-ffunction-sections` + `--gc-sections` + LTO | ✅ **本轮完成** |
|
||||
|
||||
---
|
||||
|
||||
## 2. L3 体积与异常策略
|
||||
|
||||
### 2.1 Makefile 开关
|
||||
|
||||
| 开关 | 默认 | 作用 | 备注 |
|
||||
| --- | --- | --- | --- |
|
||||
| `LAYOUT_BOUNDS` | `1` | 是否编入「显示布局边界」调试叠加层 | `make release LAYOUT_BOUNDS=0` 可剔除 |
|
||||
| `NO_EXCEPTIONS` | `1` | 追加 `-fno-exceptions` | 必须配合 `MemProbe` 的预检验 |
|
||||
| `LTO` | `1` | 追加 `-flto`（编译 + 链接） | **切换需 `make clean`** |
|
||||
|
||||
派生变量：
|
||||
|
||||
| 变量 | `LTO=1` | `LTO=0` |
|
||||
| --- | --- | --- |
|
||||
| `FUNC_SECTIONS` | 空 | `-ffunction-sections -fdata-sections` |
|
||||
| `ASM_LISTING` / `ASM_LISTING_C` | 空 | `-Wa,-a,-ad,-ahlms=$(@:%.o=%.lst)` |
|
||||
| `GC_SECTIONS` | `-Wl,--gc-sections` | 同左 |
|
||||
|
||||
> `GC_SECTIONS` / `FUNC_SECTIONS` / `ASM_LISTING*` 都定义在 `LDFLAGS` 之后。
|
||||
> 它们是递归变量（`=` / `+=`），make 在展开 recipe 时才求值，所以顺序不影响生效；
|
||||
> 之所以还是放在后面，是为了让"三个开关"集中在同一处，不散落在两个位置。
|
||||
|
||||
### 2.2 两个已复现的坑
|
||||
|
||||
**坑 1：切换 LTO 必须 `make clean`。**
|
||||
LTO 与非 LTO 目标文件混链会让 GCC 15.2.0 在 `binds_to_current_def_p (symtab.cc:2598)` 处 ICE。
|
||||
|
||||
**坑 2：`-flto` 与 `-ffunction-sections -fdata-sections` 同时打开也会触发同一个 ICE。**
|
||||
即使全部干净重编也必崩（`Utilities/Inc/DataModel.hpp:393` 的 `struct SignalData` 被指为出错点，
|
||||
但那只是 COMDAT 解析的落点，不是原因）。
|
||||
**解决办法**：LTO 下 `FUNC_SECTIONS` 置空（LTO 自己就做跨单元分区与去重），
|
||||
并追加 **`-flto-partition=one`**：
|
||||
默认多分区 LTRANS（本项目 11 个分区）稳定复现，单分区从未复现。
|
||||
代价是 LTRANS 串行，全量构建慢约一倍。
|
||||
|
||||
> 结论：**`-flto-partition=one` 不是性能选项，是稳定性选项**，不要删。
|
||||
|
||||
### 2.3 实测体积
|
||||
|
||||
| 阶段 | 产物 | 体积 | 相对基线 |
|
||||
| --- | --- | --- | --- |
|
||||
| 基线 | `BaseCheck.exe` | 909,824 B | — |
|
||||
| `-fno-exceptions` + `--gc-sections` + `MemProbe` | `Step1.exe` | 882,688 B | **−27,136 B** |
|
||||
| 再叠加 LTO | `JustDataInspector.exe` | **788,992 B** | **−120,832 B（−13.3%）** |
|
||||
|
||||
段构成（`objdump -h`，最终构建）：
|
||||
|
||||
| 段 | 基线 | `-fno-exc` + `gc-sections` | 最终（LTO） |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| `.text` | 735,600 | 720,528 | **657,168** |
|
||||
| `.rdata` | 49,184 | 45,072 | **35,016** |
|
||||
| `.xdata` | 48,132 | 34,152 | **27,512** |
|
||||
| `.pdata` | 35,424 | 34,524 | **28,524** |
|
||||
| `.rsrc` | 20,656 | 20,656 | 20,656 |
|
||||
| `.data` | 2,272 | 9,312 | 1,952 |
|
||||
| `.bss` | 10,224 | 3,088 | 10,000 |
|
||||
| `.idata` | 12,440 | 12,440 | 12,440 |
|
||||
| `.tls` | 16 | 16 | 16 |
|
||||
| `.reloc` | — | — | 1,700 |
|
||||
|
||||
**体积溯源（超阈值时必须能回答这个问题）**：
|
||||
|
||||
* `.text` 减少最多（−78 KB / −10.7%）—— 主要来自 LTO 的跨单元内联与重复代码合并。
|
||||
* `.xdata`+`.pdata`（异常展开表 + 函数表）减少 27.5 KB —— 来自 `-fno-exceptions`
|
||||
与 `--gc-sections` 丢弃未引用的函数。
|
||||
* `.rdata` 减少 14 KB —— 来自"未引用字符串/常量被 gc 掉"。
|
||||
* `.rsrc` 完全不变（图标/清单）。
|
||||
|
||||
> 预警阈值 1MB（1,048,576 B）：当前 788,992 B，**余量 259,584 B（约 253 KiB）**。
|
||||
|
||||
### 2.4 `MemProbe`（预检验 + 兜底）
|
||||
|
||||
| 函数 | 作用 |
|
||||
| --- | --- |
|
||||
| `MemAvailablePhysical()` | `GlobalMemoryStatusEx` + **200ms 缓存**（绘制路径每帧可能问多次） |
|
||||
| `MemCanAllocate(bytes)` | 留出 1/8 可用内存作 headroom 后判断是否安全 |
|
||||
| `MemReserveIfRoom(container, n)` | 仅供"按数据规模预留"：含 `capacity()` 早退与乘法溢出保护 |
|
||||
| `MemInstallTerminateHandler()` | `std::set_terminate` 装一次性模态提示后 `_Exit` |
|
||||
|
||||
改动点：
|
||||
|
||||
* `Utilities/Src/DataModel.cpp`：原先**唯一**的 `try/catch`（`extremes.reserve(count / 8)`
|
||||
捕 `std::bad_alloc`）→ `MemReserveIfRoom(extremes, count / 8)`。
|
||||
* `Components/PlotView/Src/PlotView.cpp`：`PlotView::AvailablePhysicalBytes()` 原有**一份完整的
|
||||
`GlobalMemoryStatusEx` + 200ms 缓存实现**（与 `MemProbe` 重复）→ 改为转发 `MemAvailablePhysical()`。
|
||||
* `Components/Application/Src/Application.cpp`：`Initialize()` 开头 `MemInstallTerminateHandler();`。
|
||||
|
||||
> 全仓已确认**无 `try/catch` 残留**（除 `MemProbe` 注释中对它的说明）。
|
||||
|
||||
---
|
||||
|
||||
## 3. L1 几何产物层
|
||||
|
||||
### 3.1 结构
|
||||
|
||||
```
|
||||
UiBox.hpp struct UiBox { rect, clip, depth, layer }; ← 纯值，无行为
|
||||
class UiBoxTable : UiTextRectSink ← 只累积几何 + 裁剪/层/遮挡
|
||||
UiDebugBounds.hpp UiDebugBoundsColor / UiDebugPaintBoundsClipped / UiDebugPaintBoxList
|
||||
↑ 唯一的消费者（调试描边），与几何解耦
|
||||
```
|
||||
|
||||
`UiComponent::BuildBoxes(UiBoxTable&)` 默认实现：
|
||||
|
||||
```cpp
|
||||
void UiComponent::BuildBoxes(UiBoxTable& boxes) { boxes.Add(Area(), 0); }
|
||||
```
|
||||
|
||||
各组件覆盖情况：
|
||||
|
||||
| 组件 | 上报内容 |
|
||||
| --- | --- |
|
||||
| `SignalPanel` | 表头 / 筛选框 / 列表 / 样式区 / 每个可见行 / 行内元素（复选框、色块、名称、GX 徽标、✕、折起三角、组计数）/ 滚动轨道与滑块 / 编辑框 |
|
||||
| `PlotView` | 网格、GX 徽标、图例条目、**5 类浮动面板**（含逐字段）+ 面板遮挡与裁剪 |
|
||||
| `Toolbar` | 区域、每个按钮、按钮内容（文本/图标） |
|
||||
| `TabBar` | 区域、每个标签条、新建按钮、标签 ✕、控件树 |
|
||||
| `PopupMenu` | 条目（裁到 `m_scrollEnabled ? m_scrollViewport : m_rect`）、可视区、轨道、滑块、二级子菜单 |
|
||||
| `ColorPickerPopup` | 各控件 |
|
||||
|
||||
### 3.2 与 `UiDebugBounds` 的边界
|
||||
|
||||
* 几何（矩形 / 层级 / 层号 / 裁剪 / 遮挡）→ `UiBox.hpp`
|
||||
* 观感（配色 / 包角粗细 / 图元数量 / 抗锯齿开关）→ `UiDebugBounds.hpp`
|
||||
|
||||
这样 `SignalPanel.cpp` / `PlotViewPaint.cpp` / `PopupMenu.cpp` 等**只包含 `UiBox.hpp`**，
|
||||
不再把"调试描边"这个依赖拉进自己的编译单元；只有宿主 `ApplicationCommands.cpp` 同时包含两者。
|
||||
|
||||
### 3.3 零像素回归的证明
|
||||
|
||||
L1 落地前后 `JustDataInspector.exe` **字节数完全相同（788,992 B）**，
|
||||
`rendercheck` 8 个场景哈希逐一相同 —— 因为这只是"把几何从调试绘制里搬出来"，
|
||||
没有动任何绘制顺序或图元。
|
||||
|
||||
---
|
||||
|
||||
## 4. 回归结果（最终构建上跑）
|
||||
|
||||
| 探针 | 结果 |
|
||||
| --- | --- |
|
||||
| `Tools/uicheck` | **69 passed, 0 failed** |
|
||||
| `.preflight/lbcheck` | **21 passed, 0 failed** |
|
||||
| `.preflight/lbresid` | **5 passed, 0 failed** |
|
||||
| `.preflight/lbzorder` | **4 passed, 0 failed** |
|
||||
| `.preflight/lbcovr` | **7 passed, 0 failed** |
|
||||
| `.preflight/lbpanel` | **10 passed, 0 failed** |
|
||||
|
||||
`Tools/rendercheck`（逐像素哈希，必须与基线逐一相同）：
|
||||
|
||||
```
|
||||
A FAED59DF284153DB B E6443BFE4E3955F8 C 96A0AA8C402F1729 D E3D5DBD998E43720
|
||||
E DA0583CB13C26A6F F FFB822159F604D1D G 19F8DE8FE3A8DF18 H DBBDDE4CB2C97C92
|
||||
FUNC 7/7 PASS, exit=0
|
||||
```
|
||||
|
||||
构建：`make release` 零 error / 零 warning；`make debug` 零 warning。
|
||||
|
||||
> ⚠️ 探针 `build.ps1` 链接的是 `Build/Release/*.o`。**LTO 下这些是 LTO 字节码**，
|
||||
> 因此 7 个探针脚本的链接参数里都补了 `-flto -flto-partition=one`。
|
||||
> 若把 `LTO` 关掉，这两个参数无害（可与普通目标文件混链）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 本轮审计清单
|
||||
|
||||
| 项 | 处理 |
|
||||
| --- | --- |
|
||||
| `MemProbe.hpp` / `.cpp` 里"省 40~60KB"的估算 | 改为实测值 27,136 B（909,824 → 882,688） |
|
||||
| `MemProbe.hpp` 的 `#include <new>` | 未使用，删除 |
|
||||
| `MemProbe.cpp` 的 `#include <cstdio>` | 未使用，删除 |
|
||||
| `UiDebugPaintBounds(g, rect, depth)` | **零调用者**（唯一调用者是它自己），删除；只保留带 `clip` 的版本 |
|
||||
| `TabBar::BuildBoxes` / `Toolbar::BuildBoxes` / `PlotView::BuildBoxes` / `SignalPanel::BuildBoxes` 的"（调试用）" | 改为"几何 box"（层级已变，它们不再关心调试） |
|
||||
| `PlotView::SetForceFullRepaint` 文档 | 补写"为什么保留而不优化"（L2 缓做的理由） |
|
||||
| 全仓旧名 `UiDebugBoxList` / `UiDebugBox` / `CollectDebugBoxes` | 源码零残留（仅 `Documents/agent_mem.md` 历史记录保留原样） |
|
||||
|
||||
---
|
||||
|
||||
## 6. 已知问题 / 未做
|
||||
|
||||
1. **L2 未做**（见 Plan §5）。`SetForceFullRepaint` 仍在，布局边界打开时 `PlotView` 走整幅重绘。
|
||||
2. `Tools/` 与 `.preflight/` 下的探针脚本未被 git 跟踪（本地验证工具），
|
||||
本轮给它们补的 `-flto` 参数**不会进版本库**。若 LTO 长期默认开启，
|
||||
建议把探针脚本纳入版本管理，否则下次 `make clean` 后重建探针需要手工补参数。
|
||||
3. `.lst` 汇编清单在 `LTO=1` 时不再生成（`lto-wrapper` 会丢弃 `-Wa` 参数）。
|
||||
需要看汇编时用 `make release LTO=0`。
|
||||
Reference in new issue
Block a user