Expose layout API and refresh regression docs

开发记录/Fix/Fix-BUG-20260415-0008-TabControl页签层级与重复激活链路修复.md

@@ -0,0 +1,75 @@
+# Fix-BUG-20260415-0008
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260415-0008
+- 关联 BUG ID: BUG-20260415-0008
+- 修复目标: 修正 TabControl 页签层级和重复激活已激活页签的回调链
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因:
+  - `TabControl::draw()` 与局部重绘顺序为“先页签按钮，后页面”，导致页签 Tooltip 被页面盖掉。
+  - `Button::setButtonClick()` 对 `TOGGLE` 没有做“同状态短路”，外部重复激活同一页签会重复触发 `onToggleOnCallback`。
+  - `TabControl::setActiveIndex()` 也没有对“目标已是当前激活页”做保护，导致当前可见页的 `onWindowResize()` / `setIsVisible(true)` 链被重复执行。
+- 触发条件:
+  - 任意页打开时触发页签 Tooltip
+  - 外部对已激活页签再次 `setActiveIndex()`
+- 为什么之前没发现: KEY1 外部按钮重复激活场景和 KEY5 页签 Tooltip 场景是后续专项回归才补出来的。
+- 关键证据:
+  - 所有页关闭时页签 Tooltip 正常，说明问题在页面层级覆盖
+  - 只点一次外部激活正常，重复激活后残影出现，说明问题在重复回调链
+
+## 修复方案
+
+- 修复思路:
+  - 把 TabControl 绘制/局部重绘顺序改为“先页面、后页签按钮”
+  - 给 `TOGGLE` 状态设置和 `setActiveIndex()` 增加同状态短路
+- 关键改动:
+  - `TabControl::draw()` 改成先画页面、后画页签按钮
+  - `TabControl::requestRepaint(this)` 的局部提交顺序同步调整
+  - `Button::setButtonClick()` 在 `TOGGLE` 同状态时直接返回
+  - `TabControl::setActiveIndex()` 若目标已是当前激活页则直接返回
+- 涉及文件 / 类 / 函数:
+  - `TabControl.cpp`
+  - `Button.cpp`
+- 影响的 API / 行为:
+  - 重复设置相同 `TOGGLE` 状态不再重复触发回调
+- 关键约束 / 不变量:
+  - 页签按钮视觉层级应始终高于页面
+  - 外部重复激活同一页签不应重新走页面显示链
+- 回滚点 / 开关：无
+
+## 影响评估
+
+- 影响范围: TabControl 页签 Tooltip、外部页签激活、页内超出页面边界的复合控件
+- 兼容性影响：有（收紧了 TOGGLE 同状态重复 set 的回调语义）
+- 行为变化：有（页签 Tooltip 层级恢复正确；重复激活同一页签不再重复触发回调）
+- 性能影响：无
+- 回归风险:
+  - 如有外部代码依赖“同状态重复 set 也要重复触发回调”，该行为将被收掉
+  - 需重点回归 KEY1 和 KEY5 的 TabControl 场景
+
+## 验证结果
+
+- 验证步骤:
+
+1. 编译 `Button.cpp / TabControl.cpp`
+2. 编译 `z-testDome.cpp` 的 `KEY=1`
+3. 回归 `KEY5` 页签 Tooltip 与 `KEY1` 外部按钮重复激活页签场景
+
+- 验证结果: 编译通过；逻辑推演闭合；GUI 需用户本机手测
+- 回归检查：KEY1 页签 1 表格超出区、KEY5 页签 Tooltip
+- 验证证据：编译级验证通过
+
+## 落地信息
+
+- Commit: 未单独提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注：此修复不包含 TabControl 其它内部布局专题