StellarX-kaifa/开发记录/BUG/BUG-20260415-0005-局部重绘未补画上层兄弟导致遮挡错误.md

BUG-20260415-0005

适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。

基本信息

• ID: BUG-20260415-0005
• 标题: 局部重绘未补画上层兄弟导致遮挡错误
• 状态：已修复
• 严重性：S2
• 优先级：P1
• 模块: Window / Canvas / TabControl 局部重绘与合成
• 版本 / 分支: 当前工作区
• 环境: Windows + EasyX
• 发现人: 用户回归测试
• 关联 Fix ID：[可选]
  • Fix-BUG-20260415-0005

问题描述

• 现象:
  • 下层控件发生局部重绘后，位于其上方且与 coverage 相交的兄弟控件没有被补画回来。
  • 表现为上层 Canvas / Dialog / 页 / 页签按钮 被“切掉”或被下层重新盖住。
• 影响范围:
  • 顶层普通控件之间
  • Canvas 直接子控件之间
  • TabControl 页签按钮与页面之间
• 期望结果:
  • 任意局部重绘提交后，父容器应按实际绘制顺序把 coverage 上方相交的兄弟重新合成回来。
• 实际结果:
  • 仅 dirty root 或 dirty child 被重画，上层兄弟未恢复。

复现信息

• 前置条件：[可选]
  • 使用 KEY5 测试场景
• 复现步骤:

1. 进入 KEY5
2. 触发下层控件局部重绘，例如 Table 翻页或相交子控件 hover / click
3. 观察上层相交兄弟区域

• 复现概率：高概率
• 最小复现 Demo：[可选]
  • KEY5 中 Table 与顶层粉色浮层重叠场景
  • 同父 Canvas 兄弟相交场景
• 证据：截图 / 日志 / 调用栈 / 录屏 / 断点观察
  • 断点观察显示 dirty root 已提交，但上层 sibling 未重新执行 draw

初步分析

• 疑似位置:
  • Window.cpp
  • Canvas.cpp
  • TabControl.cpp
• 触发条件:
  • 局部重绘提交写入了下层像素，但没有做 overlay 兄弟补画
• 相关线索:
  • 该问题不依赖“是否回贴背景快照”，直接重绘同样会破坏上层合成结果
  • Dialog 之前之所以需要补画，本质上是同一类问题
• 最近相关改动：[可选]
  • 第二阶段开始引入更严格的局部重绘与 overlay 收口后，问题被系统性暴露

跟踪信息

• 首次发现时间: 2026-04-15
• 最后更新时间: 2026-04-15
• 修复版本：[可选]
  • 当前工作区
• 验证版本：[可选]
  • 当前工作区
• 备注：[可选]
  • 后续仍需继续关注 Dialog 旧 synthetic move 机制与新模型的统一。