Expose layout API and refresh regression docs

开发记录/模块/Module-20260416-0005-布局策略公开API落地.md

@@ -0,0 +1,146 @@
+# 新增功能模块 / 模块重构
+
+> 适用场景：新增模块、重大模块重构、核心架构能力演进。
+> 不适用场景：小接口或轻量功能变更，请使用“功能变更”模板。
+
+## 基本信息
+
+- 模块 ID：Module-20260416-0005
+- 模块名称: 布局策略公开 API 落地
+- 状态：开发中
+- 类型：架构演进
+- 所属系统 / 子系统: GUI 框架 / Layout API
+- 版本 / 分支: 当前工作区 / 下一开发阶段
+- 环境: Windows + EasyX
+- 负责人: Codex 协作修改
+
+## 背景与目标
+
+- 背景:
+  - 第一阶段与第二阶段已经把内部布局模型收口到 `LayoutSpec / LayoutCapability / AxisSizePolicy / AxisAlignPolicy`。
+  - 外部调用层仍主要依赖 `setLayoutMode(...)` 与 `setAnchor(...)`，无法直接表达“固定尺寸 + 比例位移”“固定尺寸 + 居中”这类语义。
+  - `KEY2` 顶部位选择区就是典型例子：旧双锚点语义不足，导致按钮与标签 resize 后错位，且难以继续扩展。
+- 当前痛点:
+  - 外部用户无法直接设置 `AxisSizePolicy / AxisAlignPolicy`。
+  - 旧 demo 继续依赖旧锚点入口，验证成本高，迁移路径不清晰。
+  - 新旧 API 混用规则若不写清，后续容易再次回到“旧 anchor 硬凑新布局”的状态。
+- 目标:
+  - 将当前内部布局策略正式开放为公开 API。
+  - 明确新旧 API 混用规则与对外可见语义。
+  - 用 `KEY2` 作为新布局 API 的首个迁移样例。
+- 非目标：[可选]
+  - 不统一 `Dialog` 旧 synthetic `WM_MOUSEMOVE` 机制。
+  - 不实现 `Table` 内部局部重绘体系。
+  - 不实现 Tooltip 智能选位。
+  - 不扩展 `Table` 纵向拉伸和字体缩放。
+
+## 模块边界
+
+- 职责:
+  - 对外开放按轴设置布局规格的最小 API。
+  - 固化新旧 API 的混用规则与默认行为。
+  - 提供首个迁移样例，验证新 API 可表达旧场景中“旧 anchor 无法清晰表达”的布局。
+- 不负责什么:
+  - 不开放 `LayoutCapability` 的通用外部修改接口。
+  - 不改变控件内部硬能力边界。
+  - 不把所有旧 demo 一次性全部迁完。
+- 外部依赖:
+  - `Control / Canvas / TabControl / Table / Label / TextBox`
+  - `z-testDome.cpp`
+- 对外能力 / API:
+  - `setHorizontalLayoutSpec(...)`
+  - `setVerticalLayoutSpec(...)`
+  - `setHorizontalAnchors(...)`
+  - `setVerticalAnchors(...)`
+  - `setHorizontalSizePolicy(...)`
+  - `setVerticalSizePolicy(...)`
+  - `setHorizontalAlignPolicy(...)`
+  - `setVerticalAlignPolicy(...)`
+  - `getHorizontalLayoutSpec()`
+  - `getVerticalLayoutSpec()`
+- 关键数据 / 状态:
+  - `layoutSpec`
+  - `layoutMode`
+  - `layoutCapability`
+  - `localx / localy / localWidth / localHeight`
+  - `x / y / width / height`
+
+## 设计说明
+
+- 核心流程:
+  - 外部通过新 API 直接写入水平轴 / 垂直轴布局规格。
+  - 新 API 被调用后，控件自动切到 `AnchorToEdges` 布局模式。
+  - 运行时统一解算继续以 `layoutSpec` 为唯一依据。
+- 关键对象 / 类关系:
+  - [`Control.h`](D:/programming/imGUI-easyX/imGui-easyX/Control.h)：公开布局策略 API 的对外入口。
+  - [`Control.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Control.cpp)：新 API 的实现、新旧 API 映射共存规则。
+  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)：`KEY2` 迁移示例与验证入口。
+- 生命周期:
+  - 新 API 只影响运行态布局策略，不自动提交设计基线。
+  - 设计基线仍由显式提交路径或控件内部受控路径维护。
+- 事件 / 渲染 / 数据流：[按模块类型填写]
+  - 新 API 不改变事件分发与局部重绘主链。
+  - 只是改变布局规格输入层与解算参数来源。
+- 关键不变量:
+  - 新旧 API 混用时，后调用者生效。
+  - 旧 API 仍保留兼容，但只覆盖新模型的有限子集。
+  - 公开布局 API 不得自动回写 `local*`。
+- 降级 / 回退策略：[可选]
+  - 非法组合继续沿用现有降级规则，并输出最小必要日志。
+  - 若后续回退，只需回退 `Control` 中新增 API 与 `KEY2` 迁移代码，不影响第二阶段主线。
+
+## 实现与影响
+
+- 关键实现点:
+  - 在 `Control` 层开放最小够用的布局策略 API。
+  - 新 API 调用后自动切换到 `AnchorToEdges`。
+  - 保留 `setAnchor(...)` 与旧 getter，不破坏兼容路径。
+  - 以 `KEY2` 位选择区、功能区、显示区和配置区作为迁移样例，验证新 API 的可用性。
+- 涉及文件 / 类 / 函数:
+  - [`Control.h`](D:/programming/imGUI-easyX/imGui-easyX/Control.h)
+  - [`Control.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Control.cpp)
+  - [`z-testDome.cpp`](D:/programming/imGUI-easyX/imGui-easyX/z-testDome.cpp)
+- 兼容性影响:
+  - 兼容旧 `setAnchor(...)` 调用。
+  - 新 API 为新增能力，不影响现有二进制接口使用方式。
+  - 混用时以最后一次设置为准。
+- 性能影响:
+  - 布局解算主逻辑不变，性能影响可忽略。
+  - `KEY2` 迁移后控件层次变多，但仍处于测试用例范围。
+- 风险点:
+  - `KEY2` 迁移后可能暴露旧 demo 中原本被旧锚点语义掩盖的布局问题。
+  - 若后续没有补使用说明，外部调用仍可能继续滥用旧锚点入口。
+
+## 测试与验证
+
+- 测试范围:
+  - `Control` 新公开布局 API 编译级验证
+  - `KEY2` 迁移后的布局与显示联动
+  - `KEY5` 回归，确认新 API 未破坏第二阶段主线
+- 验证步骤:
+
+1. 编译 `Control.cpp`
+2. 编译 `z-testDome.cpp /DKEY=2`
+3. 编译 `z-testDome.cpp /DKEY=5`
+4. 手动回归 `KEY2` 位选择区、功能区、显示区与配置区的 resize 和联动行为
+
+- 验证结果:
+  - 编译级验证通过。
+  - GUI 手动回归待本机继续确认。
+- 已知限制 / 遗留问题：[可选]
+  - `Dialog` 旧 synthetic `WM_MOUSEMOVE` 机制暂未统一。
+  - `Table` 内部局部重绘体系暂未实现。
+  - resize 过程中若开启高频 console 日志，可能出现一帧视觉延迟；当前判断属于调试态 I/O 现象，不作为 bug 处理，后续可在官网或 API 文档中注明。
+
+## 落地信息
+
+- 关联功能变更 ID：[可选]
+  - `Feature-20260416-0009`
+- 关联 BUG / Fix：[可选]
+  - [Module-20260415-0004-布局系统第二阶段验收与封口.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260415-0004-布局系统第二阶段验收与封口.md)
+- Commit:
+- PR：[可选]
+- 发布版本：[可选]
+- 相关文档：[可选]
+  - [Module-20260410-0002-锚点与布局系统第一阶段重构.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260410-0002-锚点与布局系统第一阶段重构.md)
+  - [Module-20260415-0004-布局系统第二阶段验收与封口.md](D:/programming/imGUI-easyX/imGui-easyX/开发记录/模块/Module-20260415-0004-布局系统第二阶段验收与封口.md)