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,54 @@
+# BUG-20261009-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20261009-0001
+- 标题: Table 内部分页按钮焦点视觉延迟刷新
+- 状态：已修复，自动回归通过，KEY1 人工复验待执行
+- 严重性：S2
+- 优先级：P1
+- 模块: Focus / Table / Managed Repaint
+- 版本 / 分支: `master`，阶段 3 实现提交 `29df994`
+- 环境: Windows + EasyX + Routed 键盘生产路径
+- 发现人: 用户 KEY1 人工回归
+- 关联 Fix ID: Fix-BUG-20261009-0001
+
+## 问题描述
+
+- 现象: Tab 把逻辑焦点移入 Table 的分页 Button 后，焦点框不会立即出现；焦点离开后，旧焦点框也不会立即消失。只有 hover、翻页或其它原因再次触发表格重绘时，屏幕才与逻辑焦点状态一致。
+- 影响范围: Table 内部上一页/下一页 Button 的全部逻辑焦点视觉；逻辑焦点身份和 Tab 顺序本身正确。
+- 期望结果: 分页 Button 获焦和失焦都必须在当前输入批次的托管重绘收口中刷新整张 Table，不依赖下一次无关事件。
+
+## 复现信息
+
+- 前置条件: Table 已首次绘制并 materialize 分页 Button，当前页存在可用分页方向。
+- 复现步骤:
+
+1. 启动 KEY1。
+2. 使用 Tab 把焦点移动到 Table 分页 Button。
+3. 不移动鼠标、不触发其它控件，观察分页区。
+4. 再按 Tab 离开分页 Button，继续观察分页区。
+
+- 复现概率：人工回归稳定观察到
+- 人工证据: 用户于 2026-10-09 的 KEY1 回归描述。
+
+## 根因分析
+
+- Table 分页 Button 是真实 `Button`，但它属于 Table 内部绘制单元，不能作为独立顶层重绘 root 提交。
+- `Button::applyFocusState()` 只把内部 Button 自身标脏并请求重绘；Table 没有因此进入 dirty，外层 Canvas 的脏子树判断看不到需要重画的 Table。
+- 逻辑焦点状态已更新，但屏幕继续保留上一帧，直到后续事件把 Table 自身标脏。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-10-09
+- 最后更新时间: 2026-10-09
+- 修复版本: `29df994`
+- 验证版本: Debug x64 定向 focus UI 3/3、完整 UI 1/1、四配置 67/67 与 KEY1–KEY6 编译通过
+- 关联记录: `Module-20261009-0007`
+
+## 关闭边界
+
+- 自动像素测试已证明分页 Button 焦点框在 Tab 进入时即时出现、离开时即时清除。
+- BUG 最终人工关闭仍需用户复验 KEY1；自动通过不替代该人工门槛。