StellarX-kaifa/开发记录/Fix/Fix-BUG-20260415-0007-实际绘制coverage与overlay补画链修复.md

Fix-BUG-20260415-0007

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

关联信息

• Fix ID: Fix-BUG-20260415-0007
• 关联 BUG ID: BUG-20260415-0007
• 修复目标: 让托管 coverage 与 overlay 补画基于实际绘制范围，而非控件本体 bounds
• 状态：已完成
• 负责人: Codex
• 分支 / 版本: 当前工作区

根因分析

• 根因: Window / Canvas / TabControl 的 coverage 计算链默认使用 getBoundsRect()，没有把 Tooltip 这类附加绘制区域纳入。
• 触发条件: 控件本体未与 overlay 相交，但附加绘制区域超出本体并写入更上层区域。
• 为什么之前没发现: 第一轮主要解决普通控件和顶层 overlay；Tooltip 属于本体外附加绘制，直到 C / D 交界回归才稳定暴露。
• 关键证据:
  • 顶层按钮 Tooltip 正常，但容器内按钮 Tooltip 压到 D 橙区
  • 根因与按钮本体 bounds 无关，与 Tooltip 超出范围有关

修复方案

• 修复思路: 引入“实际绘制 coverage”接口，让托管重绘与局部提交统一走真实覆盖范围。
• 关键改动:
  • 在 Control 增加 getManagedRepaintCoverageRect()
  • Button 在 Tooltip 可见时返回“按钮矩形 + Tooltip 矩形”的并集
  • Canvas / TabControl / Table 将可见内部绘制单元 coverage 递归并入
  • Window::requestManagedRepaint() 和顶层 overlay 重组改为走 coverage 接口
• 涉及文件 / 类 / 函数:
  • Control.h / Control.cpp
  • Button.h / Button.cpp
  • Canvas.h / Canvas.cpp
  • TabControl.h / TabControl.cpp
  • Table.h / Table.cpp
  • Window.cpp
• 影响的 API / 行为：新增内部 virtual 接口，无公开 API 变化
• 关键约束 / 不变量:
  • Tooltip 智能选位不在本次修复范围内
  • overlay 补画继续按父容器真实绘制顺序工作
• 回滚点 / 开关：无

影响评估

• 影响范围: Tooltip、overlay 补画、复杂容器内附加绘制区域
• 兼容性影响：无
• 行为变化：有（Tooltip 与 overlay 层级恢复正确）
• 性能影响：有（coverage 更保守，可能触发更多 overlay 补画）
• 回归风险:
  • coverage 扩大后顶层/容器层局部提交会多画一些 overlay
  • 需重点回归 Tooltip 与多跳 overlay 场景

验证结果

• 验证步骤:

1. 编译 Control.cpp / Button.cpp / Canvas.cpp / TabControl.cpp / Table.cpp / Window.cpp / z-testDome.cpp
2. 在 KEY5 中验证 C 米区容器内按钮 Tooltip 与 D 橙区的遮挡关系
3. 回归顶层按钮 Tooltip、页签按钮 Tooltip、浮层按钮 Tooltip

• 验证结果: 编译通过；逻辑推演闭合；GUI 需用户本机手测
• 回归检查：KEY5 C/D 交界区、TabControl 页签、三层嵌套按钮 Tooltip
• 验证证据：编译级验证通过

落地信息

• Commit: 未单独提交
• PR：[可选]
• 发布版本：[可选]
• 备注：Tooltip 智能选位明确延期，本次只修“coverage 正确性”