Snapshot before max-resize threshold diagnosis

开发记录/功能变更/Feature-20260409-0003-输入事件与遮挡交互调整.md

@@ -0,0 +1,75 @@
+# 功能变更 ID: Feature-20260409-0003
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260409-0003
+- 标题: 输入事件、hover 与遮挡交互调整
+- 状态：已完成
+- 类型：修改
+- 级别：L2 中等
+- 模块：Window / Canvas / Button / TextBox / Dialog / TabControl
+- 版本 / 分支：`master`
+- 环境：Windows + EasyX + VS2022
+- 负责人：Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 初始版本中，hover、点击、遮挡与重叠控件之间的事件传递不够稳定。
+- 目标:
+  - 建立更一致的鼠标事件消费规则，减少穿透、残留 hover 和无意义重绘。
+- 不做什么：[可选]
+  - 暂不彻底解决“快速划过多按钮偶发一帧双高亮”的底层限制问题。
+
+## 变更内容
+
+- 变更摘要:
+  - 收紧 `Button / TextBox / Dialog` 的事件消费语义，并补上对话框关闭后及遮挡场景下的 hover 清理。
+- 新增项：[可选]
+  - `Window::dispatchSyntheticMouseMoveToControls(...)`
+- 修改项：[可选]
+  - `Button` 只在合理命中路径上吞掉鼠标事件
+  - `TextBox` 纯 hover 不再处理
+  - 非模态对话框覆盖区域内阻断底层穿透
+  - 对话框关闭后补发合成鼠标移动同步 hover
+- 删除 / 废弃项：[可选]
+  - 大量 hover DEBUG 日志已降噪
+- 受影响的文件 / 类 / 函数:
+  - `Window.cpp`
+  - `Canvas.cpp`
+  - `Button.cpp`
+  - `TextBox.cpp`
+  - `Dialog.cpp`
+  - `TabControl.cpp`
+- 对外 API / 属性变化：[可选]
+  - 无新增公开 API，主要是行为语义变化
+
+## 行为对照
+
+- 变更前:
+  - 遮挡区域 hover/click 可能穿透；对话框关闭后底层 hover 可能残留。
+- 变更后:
+  - 交互更偏向“命中即消费，关闭后同步清理 hover，遮挡区域不透传”。
+- 兼容性说明：部分兼容
+- 迁移说明：[可选]
+  - 若旧代码依赖非模态对话框下方控件还能收到事件，这种行为已被收紧
+
+## 验证与落地
+
+- 验证方式:
+  - `KEY == 2 / 3 / 4` 中对按钮、Tab、Table 分页、对话框关闭链做回归
+- 验证结果:
+  - 主要交互一致性问题已收敛
+- 关联 BUG / Fix：[可选]
+  - `BUG-20260409-0001`
+  - `Fix-BUG-20260409-0001`
+- Commit:
+  - `7f8431a`
+  - `b07a4ec`
+  - 当前工作区未提交阶段
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]