Expose layout API and refresh regression docs

开发记录/BUG/BUG-20260415-0008-TabControl页签层级与重复激活链路导致Tooltip和残影异常.md

@@ -0,0 +1,68 @@
+# BUG-20260415-0008
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260415-0008
+- 标题: TabControl 页签层级与重复激活链路导致 Tooltip 和残影异常
+- 状态：已修复
+- 严重性：S2
+- 优先级：P1
+- 模块: TabControl / 页签绘制 / 外部激活页签
+- 版本 / 分支: 当前工作区
+- 环境: Windows / EasyX / KEY1 / KEY5
+- 发现人: 用户
+- 关联 Fix ID：Fix-BUG-20260415-0008
+
+## 问题描述
+
+- 现象:
+  - 有任意页签打开时，页签按钮 Tooltip 无法正常显示，只有全部页签关闭时正常。
+  - KEY1 中页签 1 的表格超出 TabControl 区域，外部按钮重复激活同一页签后，再切页或关闭页签会留下超出部分残影。
+- 影响范围: TabControl 页签按钮 Tooltip、外部 `setActiveIndex()` 重复调用、页内超出页面边界绘制的控件。
+- 期望结果:
+  - 页签按钮应始终位于页面之上，Tooltip 正常显示。
+  - 外部重复激活已激活页签不应破坏当前可见页面的快照链。
+- 实际结果:
+  - 页签按钮 Tooltip 会被页面盖掉。
+  - 外部重复激活同一页签后，页内超出页面区域的 Table 在切页/关页时会残留。
+
+## 复现信息
+
+- 前置条件:
+  - KEY5：存在可见页面和页签按钮 Tooltip
+  - KEY1：页签 1 内的 Table 长于 TabControl 页面区域，存在外部按钮 `test`
+- 复现步骤:
+
+1. 在 KEY5 中打开任意页签，将鼠标移到页签按钮上触发 Tooltip。
+2. 观察 Tooltip 是否被页面盖掉。
+3. 在 KEY1 中点击一次 `test` 激活页签 1。
+4. 再点击一次 `test`，然后切页或关闭页签 1。
+
+- 复现概率：必现
+- 最小复现 Demo：KEY5 TabControl 区、KEY1 页签 1 + 外部 `test` 按钮
+- 证据：Tooltip 被页面覆盖；重复激活后切页/关页出现残影
+
+## 初步分析
+
+- 疑似位置:
+  - `TabControl::draw()`
+  - `TabControl::requestRepaint()`
+  - `TabControl::setActiveIndex()`
+  - `Button::setButtonClick()`
+- 触发条件:
+  - 页签按钮先画、页面后画
+  - `TOGGLE` 同状态重复 set 仍触发 onToggleOn
+- 相关线索:
+  - 页面绘制层级高于页签按钮时，页签 Tooltip 会被后画的页面盖掉
+  - 重复激活已激活页签会重复执行页面 `onWindowResize()` / `setIsVisible(true)` 链
+- 最近相关改动：TabControl overlay / Tooltip 回归专项修复
+
+## 跟踪信息
+
+- 首次发现时间: 2026-04-15
+- 最后更新时间: 2026-04-15
+- 修复版本：当前工作区
+- 验证版本：KEY1 / KEY5 编译级验证通过，待用户手测
+- 备注：本次只修页签层级和重复激活链路，不扩到 TabControl 其它内部布局语义