Snapshot before max-resize threshold diagnosis

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

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