Snapshot before max-resize threshold diagnosis

开发记录/功能变更/Feature-20260409-0001-基础资源所有权与生命周期收口.md

@@ -0,0 +1,73 @@
+# 功能变更 ID: Feature-20260409-0001
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260409-0001
+- 标题: 基础资源所有权与生命周期收口
+- 状态：已完成
+- 类型：修改
+- 级别：L2 中等
+- 模块：Control / Window / Button / Table / Label
+- 版本 / 分支：`master`
+- 环境：Windows + EasyX + VS2022
+- 负责人：Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 初始版本中一部分资源持有关系不明确，析构顺序和边界输入处理存在隐患。
+- 目标:
+  - 提高基础稳定性与维护性。
+- 不做什么：[可选]
+  - 不处理字符集体系切换问题。
+
+## 变更内容
+
+- 变更摘要:
+  - 收紧资源所有权，调整析构顺序，补齐基础控件边界防御。
+- 新增项：[可选]
+  - `Control` 提供更明确的快照有效性查询和宿主窗口回溯能力。
+- 修改项：[可选]
+  - `Window` 析构顺序调整
+  - `Table` 行数据规范化、空状态防御、页数保护
+  - `Label` 动态文本变化处理
+- 删除 / 废弃项：[可选]
+  - `MessageBox` 外层强制 `Dialog` 初始化的做法被移除
+- 受影响的文件 / 类 / 函数:
+  - `Control.h / Control.cpp`
+  - `Window.h / Window.cpp`
+  - `Button.h / Button.cpp`
+  - `Table.h / Table.cpp`
+  - `Label.cpp`
+  - `MessageBox.cpp`
+- 对外 API / 属性变化：[可选]
+  - `Button` 回调设置接口语义更正常
+
+## 行为对照
+
+- 变更前:
+  - 生命周期和边界输入更依赖使用者自觉，异常输入容易直接进入绘制或析构链。
+- 变更后:
+  - 基础控件会主动规范化一部分输入，生命周期顺序更安全。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 无强制迁移要求
+
+## 验证与落地
+
+- 验证方式:
+  - 静态审查 + 编译验证 + 现有测试用例回归
+- 验证结果:
+  - 主要基础问题已收敛
+- 关联 BUG / Fix：[可选]
+  - `BUG-20260409-0002`
+  - `Fix-BUG-20260409-0002`
+- Commit:
+  - 早期工作区修改 + `4a6e153` + `7f8431a`
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]
+  - 其中一部分修改早于仓库基线

开发记录/功能变更/Feature-20260409-0002-Dialog与MessageBox行为调整.md

@@ -0,0 +1,71 @@
+# 功能变更 ID: Feature-20260409-0002
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260409-0002
+- 标题: Dialog 与 MessageBox 行为调整
+- 状态：已完成
+- 类型：修改
+- 级别：L2 中等
+- 模块：Dialog / MessageBox / Window
+- 版本 / 分支：`master`
+- 环境：Windows + EasyX + VS2022
+- 负责人：Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 初始版本中 `Dialog` 的初始化、resize、标题绘制和 `MessageBox` 外层调用关系较松散。
+- 目标:
+  - 明确 `Dialog` 行为边界，让其在 resize、显示、关闭、标题更新等场景更稳定。
+- 不做什么：[可选]
+  - 暂不重命名 `setInitialization()` 这类历史接口。
+
+## 变更内容
+
+- 变更摘要:
+  - `Dialog` 在窗口变化时只重新居中；标题直接由 `Dialog` 自身绘制；`MessageBox` 不再外层强制初始化。
+- 新增项：[可选]
+  - `Dialog::recenterInHostWindow()`
+- 修改项：[可选]
+  - `SetTitle / SetMessage / SetType` 触发重新布局
+  - `Dialog` 标题不再使用独立 `Label`
+  - `Dialog` 在模态和非模态场景中的重绘语义被收紧
+- 删除 / 废弃项：[可选]
+  - `MessageBox::showAsync/showModal()` 中对 `setInitialization(true)` 的直接调用已移除
+- 受影响的文件 / 类 / 函数:
+  - `Dialog.h / Dialog.cpp`
+  - `MessageBox.cpp`
+  - `Window.cpp`
+- 对外 API / 属性变化：[可选]
+  - `Dialog` 在窗口变化时的对外可观察行为改为“只居中，不拉伸”
+
+## 行为对照
+
+- 变更前:
+  - `Dialog` resize 时可能重建行为与快照行为混杂，标题区域额外依赖子控件快照。
+- 变更后:
+  - `Dialog` 尺寸由内容决定；窗口变化只重新居中；标题直接绘制，减少一层快照时序问题。
+- 兼容性说明：部分兼容
+- 迁移说明：[可选]
+  - 如果外部逻辑曾假设 `Dialog` 会跟随窗口拉伸，现在需要改按“仅居中”理解
+
+## 验证与落地
+
+- 验证方式:
+  - `KEY == 2 / 3 / 4` 相关场景静态推演与回归
+- 验证结果:
+  - 标题更新、消息框初始化链、resize 后位置语义更稳定
+- 关联 BUG / Fix：[可选]
+  - `BUG-20260409-0001`
+  - `Fix-BUG-20260409-0001`
+- Commit:
+  - `4a6e153`
+  - `7f8431a`
+  - 当前工作区部分未提交整理
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]

开发记录/功能变更/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：[可选]
+- 发布版本：[可选]
+- 备注：[可选]

开发记录/功能变更/Feature-20260409-0004-测试用例与可观测性调整.md

@@ -0,0 +1,69 @@
+# 功能变更 ID: Feature-20260409-0004
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260409-0004
+- 标题: 测试用例与可观测性调整
+- 状态：已完成
+- 类型：修改
+- 级别：L1 轻量
+- 模块：z-testDome / 日志
+- 版本 / 分支：`master`
+- 环境：Windows + EasyX + VS2022
+- 负责人：Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 对话框、遮挡、hover、分页和页签的组合问题需要更有针对性的回归入口。
+- 目标:
+  - 增加一组综合用例，并降低 DEBUG 日志噪音。
+- 不做什么：[可选]
+  - 不改变原有 `KEY == 1 / 2 / 3` 的默认运行逻辑
+
+## 变更内容
+
+- 变更摘要:
+  - 新增 `KEY == 4` 的综合回归用例，覆盖对话框遮挡、Tab、Table、模态 resize 等场景。
+- 新增项：[可选]
+  - `KEY == 4` 测试分支
+- 修改项：[可选]
+  - hover 相关日志降噪
+  - 事件日志补充更清晰的事件名
+- 删除 / 废弃项：[可选]
+  - 无
+- 受影响的文件 / 类 / 函数:
+  - `z-testDome.cpp`
+  - `Window.cpp`
+  - `Canvas.cpp`
+  - `Button.cpp`
+- 对外 API / 属性变化：[可选]
+  - 无
+
+## 行为对照
+
+- 变更前:
+  - 回归更多依赖手工拼场景，hover 日志容易刷屏。
+- 变更后:
+  - 有固定综合回归入口，日志更适合看关键路径。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 测试 `KEY == 4` 需手动切换宏值
+
+## 验证与落地
+
+- 验证方式:
+  - 编译 `z-testDome.cpp`
+  - 静态推演 `KEY == 4` 控件创建、显示、对话框触发和关闭链
+- 验证结果:
+  - 当前默认 `KEY == 2` 未被带坏，`KEY == 4` 逻辑链自洽
+- 关联 BUG / Fix：[可选]
+  - 可作为 `BUG-20260409-0001` 相关问题的回归入口
+- Commit:
+  - 当前工作区未提交阶段
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]

开发记录/功能变更/Feature-20260409-0005-开发记录与模板体系整理.md

@@ -0,0 +1,69 @@
+# 功能变更 ID: Feature-20260409-0005
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260409-0005
+- 标题: 开发记录与模板体系整理
+- 状态：已完成
+- 类型：修改
+- 级别：L1 轻量
+- 模块：文档模板 / 开发记录
+- 版本 / 分支：`master`
+- 环境：本地工作区
+- 负责人：Codex 协作修改
+
+## 变更背景
+
+- 背景:
+  - 需要对本轮协作中的大量修改建立可持续维护的记录体系。
+- 目标:
+  - 将“问题、修复、功能变化、模块设计”这四类信息分层记录，避免后续继续靠聊天上下文回忆。
+- 不做什么：[可选]
+  - 不把模板设计成覆盖所有场景的一份大而全文档
+
+## 变更内容
+
+- 变更摘要:
+  - 重写四个文档模板，修正编码内容，并建立统一的开发记录目录。
+- 新增项：[可选]
+  - `开发记录/BUG`
+  - `开发记录/Fix`
+  - `开发记录/功能变更`
+  - `开发记录/模块`
+- 修改项：[可选]
+  - `文档模板` 目录下四个模板重写并重新划分职责
+- 删除 / 废弃项：[可选]
+  - 原模板中“功能变更”和“模块说明”职责重叠的写法已废弃
+- 受影响的文件 / 类 / 函数:
+  - `文档模板/*.md`
+  - `开发记录/*.md`
+- 对外 API / 属性变化：[可选]
+  - 无
+
+## 行为对照
+
+- 变更前:
+  - 模板存在乱码，功能变更和模块说明边界不清，小改动记录成本过高。
+- 变更后:
+  - 模板职责明确，记录粒度更合理，可以持续沉淀协作历史。
+- 兼容性说明：兼容
+- 迁移说明：[可选]
+  - 后续新增记录优先按新模板写，不再沿用旧模板内容
+
+## 验证与落地
+
+- 验证方式:
+  - 读取模板文件确认编码与内容正常
+  - 创建第一批记录文件验证模板可用
+- 验证结果:
+  - 模板可正常使用，第一批记录已按新体系落地
+- 关联 BUG / Fix：[可选]
+  - 无
+- Commit:
+  - 当前工作区未提交阶段
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：[可选]