docs: 收口阶段3键盘路由与焦点回归结论

2026-10-10 00:06:41 +08:00
parent 29df994f09
commit dd88a80b8c
8 changed files with 649 additions and 34 deletions
@@ -0,0 +1,60 @@
+# Fix-BUG-20261009-0001
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20261009-0001
+- 关联 BUG ID: BUG-20261009-0001
+- 修复目标: 让 Table 内部分页 Button 的焦点变化在当前批次即时重绘
+- 状态：已完成，自动与 KEY1 人工复验通过
+- 负责人: Codex
+- 分支 / 版本: `master`，实现提交 `29df994`
+
+## 根因分析
+
+- 根因: 分页 Button 的焦点状态只把 Button 自身标脏，没有把变化提升到负责实际合成的 Table。
+- 触发条件: 通过 Tab 或程序化焦点切换让分页 Button 获焦/失焦，且之后没有 hover、翻页等额外 Table 重绘事件。
+- 为什么之前没发现: 阶段 2 的 UI 只验证分页 Button 进入焦点树，没有验证内部焦点框的同帧出现与消失。
+- 关键证据: 逻辑 Tab 顺序正确，人工观察到后续任意重绘会补出或清掉焦点框。
+
+## 修复方案
+
+- 修复思路: `Table::applyFocusState()` 成功命中内部分页 Button 后，把 Table 本体设为 dirty，并向父容器请求重绘。
+- 关键改动:
+  - 上一页和下一页 Button 采用同一提升规则。
+  - 保留真实 Button 的 `FocusTargetId`，不创建合成 Table 子节点。
+  - 新增像素回归：TextBox 后一次 Tab 进入 Table next Button，下一次 Tab 离开；分别断言 Table 区域立即变化并恢复。
+- 涉及文件 / 类 / 函数:
+  - `src/StellarX/Table.cpp`
+  - `tests/UiFixture.cpp`
+  - `scripts/run-ui-tests.ps1`
+- 影响的 API / 行为: 无公开 API 变化；只修正焦点视觉提交时机。
+- 关键约束 / 不变量: Table 分页 Button 仍是 `subNode == 0` 的真实 ControlHandle。
+- 回滚点 / 开关: 回退 `Table::applyFocusState()` 的 Table dirty/repaint 提升与对应测试。
+
+## 影响评估
+
+- 影响范围: Table 分页区焦点框、Table 整体托管重绘。
+- 兼容性影响：无
+- 行为变化：有，焦点视觉从延迟刷新改为当前批次刷新。
+- 性能影响：焦点进入/离开分页 Button 时多一次整 Table 重绘；只发生在焦点切换边界。
+- 回归风险: Table 重绘可能影响与其相交的上层控件，因此与 overlay 回归共同验证。
+
+## 验证结果
+
+- Debug x64 新增 `CanvasBackgroundPointerDownClearsFocusAndConsumes` 后为 67/67。
+- Debug x64、x64 ASan、Release x64、Debug Win32 均为 67/67；KEY1–KEY6 全部编译/链接成功。
+- 扩展 `focus` UI 连续 3/3 通过；Table 焦点出现和消失均有独立截图与像素区域断言。
+- 完整 UI 1/1 通过，包含 Tooltip、Table、Dialog、input-shadow 和 keyboard-routing。
+- 最终 fixture 自动 UI 证据：`TestResults/ui/20261009-223506-755-18932`，九场景 9/9，通过 fixture SHA-256 `F439C0636CD6B979A47C4594BC5AB3728F6342F49602FE43078435011A877793`。
+- 人工复验: 用户重新执行 KEY1，Table 分页焦点框即时出现/消失，暂未发现问题。
+
+## 落地信息
+
+- Commit: `29df994`
+- PR: 无
+- 发布版本: 未发布
+- 证据:
+  - `TestResults/ui/20261009-220625-941-15096`
+  - `TestResults/ui/20261009-220940-941-31488`
@@ -0,0 +1,62 @@
+# Fix-BUG-20261009-0002
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20261009-0002
+- 关联 BUG ID: BUG-20261009-0002
+- 修复目标: 下层持久重绘命中上层兄弟时，优先完整恢复上层而不是只提交其脏子树
+- 状态：已完成，自动与 KEY5 人工复验通过
+- 负责人: Codex
+- 分支 / 版本: `master`，实现提交 `29df994`
+
+## 根因分析
+
+- 根因: `Canvas::requestRepaint()` 把“上层自身有脏子树”放在“下层持久 coverage 命中上层”之前，导致完整 overlay 恢复被局部提交短路。
+- 触发条件: 下层与上层相交，且一次焦点事务同时让下层失焦、上层获焦。
+- 为什么之前没发现: 既有 overlay 测试主要覆盖只有下层变脏的情况，没有覆盖上下层同批变脏。
+- 关键证据: 额外事件触发完整重绘后画面恢复，说明 z-order 和内容本身正确，错误集中在局部提交优先级。
+
+## 修复方案
+
+- 修复思路: 每个上层兄弟在选择提交方式前，先判断本轮累计的下层持久 coverage 是否与其持久/完整 coverage 相交。
+- 关键改动:
+  - `persistentHit` 为真时，无条件作废上层旧快照并完整重画。
+  - 只有不命中下层持久内容时，才允许继续提交上层自己的局部脏子树。
+  - Tooltip 等临时 coverage 不进入持久相交条件，继续保持既有临时浮层契约。
+  - 扩展 focus UI，构造同父上下层 Canvas，并在下层失焦、上层获焦后精确断言交叠点颜色。
+- 涉及文件 / 类 / 函数:
+  - `src/StellarX/Canvas.cpp`
+  - `tests/UiFixture.cpp`
+  - `scripts/run-ui-tests.ps1`
+- 影响的 API / 行为: 无公开 API 变化；调整托管局部重绘内部优先级。
+- 关键约束 / 不变量: 完整 coverage 负责“是否被写到”，持久 coverage 负责“是否需要刷新背景快照”；两者不能重新合并。
+- 回滚点 / 开关: 回退 Canvas 分支优先级与同批双脏像素回归。
+
+## 影响评估
+
+- 影响范围: Canvas 内相交兄弟、嵌套 Canvas、焦点框与持久内容的同批重绘。
+- 兼容性影响：无
+- 行为变化：有，错误覆盖改为按 z-order 完整恢复。
+- 性能影响：仅在下层持久写屏区域命中上层时，把上层局部提交升级为完整控件重画。
+- 回归风险:
+  - 若把 Tooltip 临时 coverage 错当持久内容，可能重新引入 Tooltip 被擦除；本修复继续使用独立 persistent coverage，并执行完整 tooltip UI。
+  - 完整上层重画会刷新其背景快照，因此必须先让下层本轮像素稳定落屏。
+
+## 验证结果
+
+- 扩展 `focus` UI 连续 3/3 通过；同父下层/上层焦点切换后，交叠点精确保持上层背景色 `RGB(200,160,120)`。
+- 完整 UI 1/1 通过，`tooltip` 到期显示与移出清除均未回归。
+- Debug x64、x64 ASan、Release x64、Debug Win32 均为 67/67；KEY1–KEY6 全部编译/链接成功。
+- 最终 fixture 自动 UI 证据：`TestResults/ui/20261009-223506-755-18932`，九场景 9/9，通过 fixture SHA-256 `F439C0636CD6B979A47C4594BC5AB3728F6342F49602FE43078435011A877793`。
+- 人工复验: 用户重新执行 KEY5 D 区，D-1 → D-2 未再发生下层重绘覆盖，暂未发现问题。
+
+## 落地信息
+
+- Commit: `29df994`
+- PR: 无
+- 发布版本: 未发布
+- 证据:
+  - `TestResults/ui/20261009-220625-941-15096`
+  - `TestResults/ui/20261009-220940-941-31488`