StellarX-kaifa/开发记录/BUG/BUG-20260409-0001-对话框重绘快照与遮挡交互异常.md

BUG-20260409-0001

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

基本信息

• ID: BUG-20260409-0001
• 标题: 对话框重绘、快照残留与遮挡交互异常
• 状态：已修复 / 待持续回归
• 严重性：S2
• 优先级：P0
• 模块：Window / Dialog / Canvas / Button / TextBox
• 版本 / 分支：master
• 环境：Windows + EasyX + VS2022
• 发现人：协作过程静态审查与测试用例回归
• 关联 Fix ID：Fix-BUG-20260409-0001

问题描述

• 现象:
  • 非模态对话框打开后，底层被遮挡控件仍可能收到鼠标事件。
  • 模态或非模态对话框在窗口尺寸变化后，可能出现背景快照残留。
  • 模态对话框标题区域曾出现抓到底层背景的问题。
  • 对话框关闭后，底层按钮 hover 状态可能不能立即恢复。
  • 多个按钮快速 hover 切换时，对话框补画链容易闪烁。
• 影响范围:
  • 对话框交互正确性
  • 重绘层级稳定性
  • hover 与点击行为一致性
• 期望结果:
  • 对话框始终位于正确层级。
  • 被对话框覆盖的底层控件不会误交互。
  • resize / 打开 / 关闭过程中无残影、无错位。
• 实际结果:
  • 曾出现穿透、残影、错误快照、关闭后 hover 残留、频繁补画闪烁等问题。

复现信息

• 前置条件：存在非模态或模态对话框，且下层有可交互控件
• 复现步骤:

1. 打开包含按钮、Canvas、TabControl 的测试窗口。
2. 弹出非模态或模态对话框。
3. 在对话框遮挡区域附近快速移动鼠标，或拖动窗口大小。

• 复现概率：高概率 / 偶现（不同问题不同）
• 最小复现 Demo：z-testDome.cpp 中 KEY == 2 / 3 / 4
• 证据：日志、静态推演、用户回归观察

初步分析

• 疑似位置:
  • Dialog::handleEvent
  • Dialog::draw / recenterInHostWindow / clearControls
  • Window::runEventLoop / pumpResizeIfNeeded / flushManagedRepaint
  • Button::handleEvent
• 触发条件:
  • 对话框覆盖底层控件
  • 窗口 resize
  • hover 高频切换
  • 对话框打开/关闭后的层级切换
• 相关线索:
  • “快照作废”和“回贴旧背景”语义混用
  • 事件阶段与绘制阶段原先分离不彻底
  • 非模态对话框区域内鼠标事件吞掉后，底层控件拿不到离开消息

跟踪信息

• 首次发现时间：本轮协作初期
• 最后更新时间：2026-04-09
• 修复版本：[当前工作区]
• 验证版本：[当前工作区]
• 备注：快速划过多个按钮时一帧内偶发双高亮的问题暂未彻底消除，属于已接受的底层限制