# 功能变更 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：[可选]
- 发布版本：[可选]
- 备注：[可选]