StellarX-kaifa/开发记录/Fix/Fix-BUG-20261009-0001-Table分页焦点重绘提升修复.md

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