StellarX-kaifa/开发记录/Fix/Fix-BUG-20260415-0005-局部重绘补画上层兄弟修复.md

Fix-BUG-20260415-0005

适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。

关联信息

• Fix ID: Fix-BUG-20260415-0005
• 关联 BUG ID: BUG-20260415-0005
• 修复目标: 收口局部重绘提交后的 overlay 兄弟补画机制
• 状态：已完成
• 负责人: Codex 协作修改
• 分支 / 版本: 当前工作区

根因分析

• 根因:
  • 局部重绘提交只重画了 dirty root 或 dirty child，没有按父容器真实绘制顺序把 coverage 上方相交的兄弟补画回来。
• 触发条件:
  • 下层区域写入像素后，上层 sibling 与本次 coverage 相交。
• 为什么之前没发现：[可选]
  • 旧场景多集中在对话框覆盖链，普通 sibling overlay 问题没有被系统化回归。
• 关键证据：[可选]
  • KEY5 中 Table 翻页覆盖顶层粉色浮层可稳定复现。
  • 同父 Canvas 相交子控件在局部重绘后会出现相同症状。

修复方案

• 修复思路:
  • 不做控件之间的长期联动标记。
  • 改为由父容器在局部重绘提交后，按真实绘制顺序动态补画 coverage 上方相交的直接绘制单元。
• 关键改动:
  • Window：补画普通顶层控件 overlay，而不再只补 Dialog
  • Canvas：补画 coverage 上方相交的直接子控件
  • TabControl：按自己的真实绘制顺序补画页签按钮与页面
  • overlay 补画前统一 invalidateBackgroundSnapshot()，避免旧快照反贴旧背景
• 涉及文件 / 类 / 函数:
  • Window.cpp
  • Canvas.cpp
  • TabControl.cpp
• 影响的 API / 行为：[可选]
  • 无对外 API 变化
  • 局部重绘行为更严格遵守视觉合成顺序
• 关键约束 / 不变量：[可选]
  • 父容器只处理自己的直接绘制单元
  • overlay 补画顺序必须与实际 draw() 顺序一致
  • 不升级为整窗 / 整容器重绘，除非父容器自身快照或 dirty 条件不满足
• 回滚点 / 开关：[可选]
  • 无单独开关，回滚需回退相关局部重绘提交逻辑

影响评估

• 影响范围:
  • Window / Canvas / TabControl 的局部重绘提交路径
• 兼容性影响：无
• 行为变化：有（局部重绘后会补画上层 overlay）
• 性能影响：有（增加必要的 overlay 补画），但仍显著小于整窗 / 整容器重绘
• 回归风险:
  • 若 coverage 计算不准，仍可能遗漏或多画
  • TabControl 局部重绘顺序必须和真实 draw() 顺序保持一致

验证结果

• 验证步骤:

1. 编译 Window.cpp、Canvas.cpp、TabControl.cpp
2. 编译 z-testDome.cpp KEY=5
3. 回归 Table 翻页、相交 Canvas、TabControl 页签/页面遮挡场景

• 验证结果:
  • 编译级验证通过
  • GUI 手动回归需继续在本机确认
• 回归检查：[可选]
  • Table 分页按钮与页码链已同步收口
• 验证证据：[可选]
  • KEY5 已新增更明确的 overlay 专项场景

落地信息

• Commit: 未提交（当前工作区）
• PR：[可选]
• 发布版本：[可选]
• 备注：[可选]
  • Dialog 旧 synthetic move 逻辑本轮保留，后续可再评估是否纳入通用清理模型。