# 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
- 修复版本：[当前工作区]
- 验证版本：[当前工作区]
- 备注：快速划过多个按钮时一帧内偶发双高亮的问题暂未彻底消除，属于已接受的底层限制