完成 StellarX 核心重构、缺陷修复与测试收口

2026-09-30 01:23:18 +08:00
parent 9155a86a8a
commit 568ffc40eb
85 changed files with 5011 additions and 645 deletions
@@ -0,0 +1,53 @@
+# BUG-20251209-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20251209-0001
+- 标题: TabControl 由不可见设置为可见时绘制错乱
+- 状态：已修复
+- 严重性：S3
+- 优先级：P2
+- 模块: TabControl
+- 版本 / 分支: V2.3.1
+- 环境: Visual Studio / Debug / Release
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20251209-0001
+
+## 问题描述
+
+- 现象: 调用 `TabControl::setIsVisible()` 将选项卡由不可见变为可见时，会绘制出未激活的页面。
+- 影响范围: 多页面 TabControl 在隐藏后重新显示时可能出现页面叠加，造成绘制错乱并影响用户体验。
+- 期望结果: TabControl 可见后只绘制当前激活页；如果没有激活页，则不绘制任何页。
+- 实际结果: 所有页面被绘制出来，导致未激活页和激活页重叠。
+
+## 复现信息
+
+- 前置条件：[可选] 存在至少两个页面的 TabControl。
+- 复现步骤:
+
+1. 将 TabControl 设置为不可见。
+2. 通过事件或回调将 TabControl 设置为可见。
+3. 观察页面绘制结果。
+
+- 复现概率：必现
+- 最小复现 Demo：[可选] TabControl 隐藏 / 显示切换场景
+- 证据：PDF 历史记录描述隐藏后恢复显示会绘制所有页；初步定位到 `TabControl::setIsVisible()` 的可见性传播逻辑。
+
+## 初步分析
+
+- 疑似位置: `TabControl::setIsVisible()`
+- 触发条件: TabControl 从不可见切换为可见时，对子页面统一传播可见状态。
+- 相关线索:
+  - `show` 状态恢复为 true 后，非激活页也参与绘制。
+  - TabControl 的页面可见性没有与当前激活状态保持一致。
+- 最近相关改动：[可选]
+
+## 跟踪信息
+
+- 首次发现时间: 2025-12-09
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v2.3.2
+- 验证版本：[可选] v2.3.2
+- 备注：[可选] 来源原始 ID 为 `BUG-20251209`；PDF 未包含 `-XXXX` 后缀，入库时补充序号。
@@ -0,0 +1,60 @@
+# BUG-20251220-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20251220-0001
+- 标题: TabControl::setActiveIndex 绘制前调用崩溃
+- 状态：已修复
+- 严重性：S1
+- 优先级：P0
+- 模块: TabControl
+- 版本 / 分支: v2.3.1
+- 环境: Visual Studio / Debug / Release
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20251220-0001
+
+## 问题描述
+
+- 现象: 在 TabControl 首次绘制前或进入主事件循环前调用 `setActiveIndex()`，会触发空指针访问并导致程序崩溃。
+- 影响范围: 影响默认激活页设置流程，启动阶段即可崩溃，严重影响使用。
+- 期望结果: `setActiveIndex()` 可在绘制前记录默认激活页，并在 TabControl 第一次绘制时完成默认激活。
+- 实际结果: 绘制前调用会直接崩溃，无法设置默认激活页。
+
+## 复现信息
+
+- 前置条件：[可选] TabControl 尚未绘制。
+- 复现步骤:
+
+1. 创建 TabControl 对象。
+2. 在首次绘制前调用 `setActiveIndex(0)`。
+3. 运行程序并观察崩溃。
+
+- 复现概率：必现
+- 最小复现 Demo：
+
+```cpp
+auto ta = std::make_unique<TabControl>(10, 10, 1100, 300);
+ta->setShape(StellarX::ControlShape::B_ROUND_RECTANGLE);
+ta->setActiveIndex(0);
+```
+
+- 证据：PDF 历史记录描述绘制前调用会造成空指针访问。
+
+## 初步分析
+
+- 疑似位置: `TabControl::setActiveIndex()`
+- 触发条件: TabControl / 页签按钮尚未完成绘制和初始化时，提前执行激活页切换逻辑。
+- 相关线索:
+  - 默认激活应属于延迟到首次绘制后的行为。
+  - 绘制前直接触发页签按钮点击回调，会访问尚未初始化的内部状态。
+- 最近相关改动：[可选]
+
+## 跟踪信息
+
+- 首次发现时间: 2025-12-20
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v2.3.2
+- 验证版本：[可选] v2.3.2
+- 备注：[可选] 来源原始 ID 为 `BUG-20251220`；PDF 未包含 `-XXXX` 后缀，入库时补充序号。
@@ -0,0 +1,66 @@
+# BUG-20260109-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260109-0001
+- 标题: TextBox::setText 进入事件循环前调用崩溃
+- 状态：已修复
+- 严重性：S1
+- 优先级：P0
+- 模块: TextBox
+- 版本 / 分支: v2.3.2（基础版 EasyX + Win32）
+- 环境: Windows 10/11 x64 + Visual Studio 2022（MSVC）Debug / Release
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260109-0001
+
+## 问题描述
+
+- 现象: 在 Window 尚未创建或图形上下文尚未初始化时调用 `TextBox::setText()` 设置默认文本，会触发 `TextBox::draw()`，进而进入依赖 EasyX 图形上下文的绘制 / 抓屏逻辑，导致访问冲突或中断。
+- 影响范围: 所有“先创建控件并设置默认文本，再创建 Window / 挂载控件树”的初始化流程。
+- 期望结果: `setText()` 只更新控件状态并标记需要重绘，不应在生命周期未就绪时主动绘制。
+- 实际结果: `setText()` 内部直接调用 `draw()`，绘制链路在图形上下文未就绪时崩溃。
+
+## 复现信息
+
+- 前置条件：[可选] Window / EasyX 图形上下文尚未初始化。
+- 复现步骤:
+
+1. 在创建 Window 或首次 `draw()` 前创建 TextBox。
+2. 调用 `TextBox::setText()` 设置默认文本。
+3. 随后才创建 Window 或将 TextBox 添加到 Canvas / Window。
+4. 观察程序在 `setText()` 阶段崩溃。
+
+- 复现概率：必现
+- 最小复现 Demo：
+
+```cpp
+Window window(1024, 768, NULL, RGB(255, 255, 255), "StellarX Application");
+
+auto initLibPathBox = std::make_unique<TextBox>(230, 230, 700, 30);
+initLibPathBox->setText("textText");
+
+window.addControl(std::move(initLibPathBox));
+window.draw();
+return window.runEventLoop();
+```
+
+- 证据：PDF 历史记录描述 `setText()` 触发 `draw()` 后进入 `saveBackground()` / `getimage()` 等图形上下文相关逻辑。
+
+## 初步分析
+
+- 疑似位置: `TextBox::setText()`
+- 触发条件: 控件属性设置发生在 Window 绘制 / EasyX 图形上下文初始化之前。
+- 相关线索:
+  - setter 不应带有依赖图形上下文的即时绘制副作用。
+  - `draw()` 会进入背景快照与图像抓取链路。
+- 最近相关改动：[可选]
+
+## 跟踪信息
+
+- 首次发现时间: 2026-01-09
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v3.0.0
+- 验证版本：[可选] v3.0.0
+- 备注：[可选] 来源原始 ID 为 `BUG-20260109`；同日另有 Table 重影问题，入库时按顺序拆为 `0001` 与 `0002`。
@@ -0,0 +1,60 @@
+# BUG-20260109-0002
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260109-0002
+- 标题: TabControl 切换后 Table 新旧内容重叠
+- 状态：已修复
+- 严重性：S2
+- 优先级：P1
+- 模块: TabControl / Canvas / Table / 背景快照 / 脏标记重绘链路
+- 版本 / 分支: 基础版（EasyX + Win32）/ v2.3.2
+- 环境: Windows x64 / Visual Studio 2022 / EasyX（Debug / Release 均可能）
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260109-0002
+
+## 问题描述
+
+- 现象: 运行 TabControl 示例后，切换到“按钮1”页签并触发“重置表格数据”，随后打开 / 关闭其他页签再切回“按钮1”，Table 稳定出现旧内容与新内容叠加；偶发情况下重置数据当次即出现重影。
+- 影响范围: 使用背景快照擦除与局部重绘组合的容器 / 控件，尤其是 Table 透明文字背景与 Null 填充模式场景。
+- 期望结果: 切换页签、关闭页签、重置数据后，Table 只显示当前数据，不残留旧像素。
+- 实际结果: Table 区域出现旧行文本像素残留，与新内容叠在同一位置。
+
+## 复现信息
+
+- 前置条件：[可选] TabControl 示例中包含 Table 和“重置表格数据”按钮。
+- 复现步骤:
+
+1. 运行测试程序（TabControl 示例）。
+2. 切换到“按钮1”页签。
+3. 点击“重置表格数据”（清空并重新 `setData()`）。
+4. 随意切换到其他页签，可伴随关闭页签操作。
+5. 再切回“按钮1”。
+6. 观察 Table 区域是否出现旧内容与新内容重叠。
+
+- 复现概率：必现；重置数据当次直接重影为偶现。
+- 最小复现 Demo：`z-testDome.cpp` 中 TabControl + Table + 重置按钮场景；Null FillMode 与透明文字背景更明显。
+- 证据：日志显示 Canvas 快照刚丢弃或未就绪时，Table 可见性恢复立即触发局部重绘，随后 `saveBackground()` 把已绘制像素截入背景快照。
+
+## 初步分析
+
+- 疑似位置:
+  - `Control::setIsVisible(true)`
+  - `Canvas::requestRepaint()`
+  - `TabControl::requestRepaint()`
+- 触发条件: 页签切换 / 关闭期间，父容器快照未就绪或 dirty 未清理时，子控件抢跑执行局部绘制。
+- 相关线索:
+  - `show=true` 时立即向上 `requestRepaint()`。
+  - `Canvas::requestRepaint()` 在 `hasSnap=0` / `dirty=1` 状态下仍允许对子控件局部 `draw()`。
+  - 页签切换期间尺寸变化会触发丢背景快照和标脏。
+- 最近相关改动：[可选] `Control::setIsVisible(true)` 变为立即请求重绘。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-01-09
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v3.0.0
+- 验证版本：[可选] v3.0.0
+- 备注：[可选] 来源原始 ID 为 `BUG-20260109`；同日另有 TextBox 生命周期问题，入库时按顺序拆为 `0001` 与 `0002`。
@@ -0,0 +1,53 @@
+# BUG-20260122-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260122-0001
+- 标题: Window::runEventLoop 普通控件事件分发顺序
+- 状态：已修复
+- 严重性：S3
+- 优先级：P2
+- 模块: Window
+- 版本 / 分支: v3.0.0
+- 环境: Windows 10/11 x64 + Visual Studio 2022（MSVC）Debug / Release
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260122-0001
+
+## 问题描述
+
+- 现象: `Window::runEventLoop()` 对普通控件分发事件时采用正序遍历 `controls`，控件重叠时下层控件可能抢走点击 / 悬停事件，导致行为与绘制顺序不一致。
+- 影响范围: 普通控件存在重叠时，事件命中顺序可能不符合 Z 序直觉。
+- 期望结果: 上层控件优先接收事件，下层控件不应抢走事件。
+- 实际结果: 正序遍历导致下层控件可能先处理事件。
+
+## 复现信息
+
+- 前置条件：[可选] Window 中存在相互重叠的普通控件。
+- 复现步骤:
+
+1. 创建存在重叠区域的普通控件。
+2. 在重叠区域触发点击或悬停事件。
+3. 观察是否由下层控件优先处理事件。
+
+- 复现概率：必现（按 PDF 记录；实际复现未提供）
+- 最小复现 Demo：[可选] 无
+- 证据：PDF 历史记录指出该问题来自之前版本误将逆序分发改为正序分发。
+
+## 初步分析
+
+- 疑似位置: `Window::runEventLoop()`
+- 触发条件: 普通控件重叠，且事件落在重叠区域。
+- 相关线索:
+  - 普通控件绘制顺序与事件分发顺序应保持 Z 序一致。
+  - `Window::controls` 正序遍历会让较早加入的下层控件先处理事件。
+- 最近相关改动：[可选] 某个版本中普通控件遍历顺序被错误修改。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-01-22
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v3.0.1
+- 验证版本：[可选] v3.0.1
+- 备注：[可选] 来源原始 ID 为 `BUG-20260122`；PDF 未包含 `-XXXX` 后缀，入库时补充序号。
@@ -0,0 +1,53 @@
+# BUG-20260203-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260203-0001
+- 标题: 对话框打开时错误下发合成 WM_MOUSEMOVE
+- 状态：已修复
+- 严重性：S3
+- 优先级：P2
+- 模块: Window
+- 版本 / 分支: v3.0.0
+- 环境: Windows 10/11 x64 + Visual Studio 2022（MSVC）Debug / Release
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260203-0001
+
+## 问题描述
+
+- 现象: 对话框打开时会触发本应只在对话框关闭时执行的合成 `WM_MOUSEMOVE`，并下发给所有可见控件以刷新 hover 状态。
+- 影响范围: 对话框打开路径产生额外事件下发，带来性能影响和不必要的 hover 状态刷新。
+- 期望结果: 合成 `WM_MOUSEMOVE` 只在对话框被关闭后下发一次。
+- 实际结果: 对话框打开和关闭时都会下发合成 `WM_MOUSEMOVE`。
+
+## 复现信息
+
+- 前置条件：[可选] 存在可弹出的对话框。
+- 复现步骤:
+
+1. 启动事件循环。
+2. 触发对话框弹出。
+3. 观察日志中是否在对话框打开阶段出现合成 `WM_MOUSEMOVE` 下发记录。
+
+- 复现概率：必现
+- 最小复现 Demo：[可选] 弹出一个对话框即可。
+- 证据：PDF 日志显示对话框弹出后出现“对话框关闭，合成WM_MOUSEMOVE已下发”。
+
+## 初步分析
+
+- 疑似位置: `Window::runEventLoop()`
+- 触发条件: 对话框打开路径触发重绘判断时，也执行了对话框关闭后才需要的鼠标移动合成逻辑。
+- 相关线索:
+  - 相关变量为 `dialogClose`。
+  - 合成 `WM_MOUSEMOVE` 的执行缺少对 `dialogClose` 为真的限定。
+- 最近相关改动：[可选]
+
+## 跟踪信息
+
+- 首次发现时间: 2026-02-03
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v3.0.1
+- 验证版本：[可选] v3.0.1
+- 备注：[可选] 来源原始 ID 为 `BUG-20260203`；PDF 未包含 `-XXXX` 后缀，入库时补充序号。
@@ -0,0 +1,53 @@
+# BUG-20260206-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260206-0001
+- 标题: 对话框打开时持续触发全量重绘
+- 状态：已修复
+- 严重性：S3
+- 优先级：P2
+- 模块: Window
+- 版本 / 分支: v3.0.0 / master
+- 环境: Windows 10/11 x64 + Visual Studio 2022（MSVC）Debug / Release
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260206-0001
+
+## 问题描述
+
+- 现象: 对话框保持打开时持续触发全量重绘，重复重绘所有打开的对话框和可见控件。
+- 影响范围: 对话框打开期间产生不必要的全量绘制，造成性能影响。
+- 期望结果: 只在对话框打开或关闭时触发必要重绘，确保对话框顶层显示并清除关闭残留。
+- 实际结果: 重绘前以“是否有对话框可见或关闭”为依据，导致对话框保持可见时持续触发重绘。
+
+## 复现信息
+
+- 前置条件：[可选] 存在可弹出的对话框。
+- 复现步骤:
+
+1. 触发对话框弹出。
+2. 保持对话框打开。
+3. 观察日志中是否持续输出全量重绘相关记录。
+
+- 复现概率：必现
+- 最小复现 Demo：触发任意对话框即可。
+- 证据：PDF 日志中同一时间片持续出现“对话框打开/关闭，触发全量重绘”。
+
+## 初步分析
+
+- 疑似位置: `Window::runEventLoop()`
+- 触发条件: 对话框处于可见状态且事件循环持续运行。
+- 相关线索:
+  - 相关变量为 `needredraw`。
+  - 重绘判断基于“是否存在可见对话框”，而不是“是否刚刚打开 / 关闭对话框”。
+- 最近相关改动：[可选]
+
+## 跟踪信息
+
+- 首次发现时间: 2026-02-06
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v3.0.1
+- 验证版本：[可选] v3.0.1
+- 备注：[可选] 来源原始 ID 为 `BUG-20260206`；PDF 未包含 `-XXXX` 后缀，入库时补充序号。
@@ -0,0 +1,54 @@
+# BUG-20260217-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260217-0001
+- 标题: TabControl::getActiveIndex 无激活页返回最后索引
+- 状态：已修复
+- 严重性：S2
+- 优先级：P1
+- 模块: TabControl
+- 版本 / 分支: v3.0.0 / master
+- 环境: Windows 10/11 x64 + Visual Studio 2022（MSVC）Debug / Release
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260217-0001
+
+## 问题描述
+
+- 现象: 当 TabControl 的页签对列表不为空，但所有页签均未激活 / 未打开时，调用 `getActiveIndex()` 会返回最后一个页签的索引。
+- 影响范围: 用户通过 `getActiveIndex()` 判断当前激活页时，可能拿到错误索引。
+- 期望结果: 无页签激活时返回 `-1`；有页签激活时返回对应索引。
+- 实际结果: 无页签激活时返回最后一个页签索引。
+
+## 复现信息
+
+- 前置条件：[可选] TabControl 页签列表不为空，但所有页签都未激活。
+- 复现步骤:
+
+1. 创建含有页签的 TabControl。
+2. 保持所有页签未激活 / 未打开。
+3. 调用 `TabControl::getActiveIndex()`。
+4. 观察返回值。
+
+- 复现概率：必现
+- 最小复现 Demo：[可选]
+- 证据：PDF 历史记录标记为代码分析发现。
+
+## 初步分析
+
+- 疑似位置: `TabControl::getActiveIndex()`
+- 触发条件: 页签列表非空且无任何页签处于激活状态。
+- 相关线索:
+  - 旧逻辑未处理“列表非空但全部未激活”的兜底分支。
+  - 返回值应能区分无激活页与最后一页激活。
+- 最近相关改动：[可选]
+
+## 跟踪信息
+
+- 首次发现时间: 2026-02-17
+- 最后更新时间: 2026-09-19（从 PDF 整理入库）
+- 修复版本: v3.0.1
+- 验证版本：[可选] v3.0.1
+- 备注：[可选] 来源原始 ID 为 `BUG-20260217`；PDF 未包含 `-XXXX` 后缀，入库时补充序号。
@@ -48,7 +48,7 @@
 ## 初步分析

 - 疑似位置：
-  - [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Window.cpp) 的 `runEventLoop()` resize 收口逻辑
+  - [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/src/StellarX/Window.cpp) 的 `runEventLoop()` resize 收口逻辑
 - 可疑代码特征：
  - 使用 `abs(finalW - width) > 1000 || abs(finalH - height) > 1000` 作为跳过条件
  - 命中后直接：
@@ -46,7 +46,7 @@
 ## 初步分析

 - 疑似位置:
-  - [`Button.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Button.cpp)
+  - [`Button.cpp`](D:/programming/imGUI-easyX/imGui-easyX/src/StellarX/Button.cpp)
  - `Button::hideTooltip()`
 - 触发条件:
  - Tooltip 已经显示
@@ -50,9 +50,9 @@
 ## 初步分析

 - 疑似位置:
-  - [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Window.cpp)
-  - [`Canvas.cpp`](D:/programming/imGUI-easyX/imGui-easyX/Canvas.cpp)
-  - [`TabControl.cpp`](D:/programming/imGUI-easyX/imGui-easyX/TabControl.cpp)
+  - [`Window.cpp`](D:/programming/imGUI-easyX/imGui-easyX/src/StellarX/Window.cpp)
+  - [`Canvas.cpp`](D:/programming/imGUI-easyX/imGui-easyX/src/StellarX/Canvas.cpp)
+  - [`TabControl.cpp`](D:/programming/imGUI-easyX/imGui-easyX/src/StellarX/TabControl.cpp)
 - 触发条件:
  - 局部重绘提交写入了下层像素，但没有做 overlay 兄弟补画
 - 相关线索:
@@ -0,0 +1,54 @@
+# BUG-20260929-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20260929-0001
+- 标题: Table 运行期重置后页码标签被旧分页按钮快照覆盖
+- 状态：已修复
+- 严重性：S2
+- 优先级：P1
+- 模块: Table / Label / Button / 背景快照
+- 版本 / 分支: 当前工作区
+- 环境: Windows / EasyX / KEY1
+- 发现人: 用户
+- 关联 Fix ID: Fix-BUG-20260929-0001
+
+## 问题描述
+
+- 现象: KEY1 页签 1 中点击页内按钮重置表头和数据后，分页区中间的页码标签只显示一部分；触发表格重绘或与其他页签按钮进行 hover 交互后恢复完整。
+- 影响范围: Table 运行期数据变化导致表格宽度及分页控件位置同时变化的场景。
+- 期望结果: 重置后的首帧立即完整显示新页码，不依赖后续 hover、翻页或页签重绘修复。
+- 实际结果: 页码已经绘制，但随后移动的分页按钮回贴旧位置背景快照，覆盖了新页码的一部分。
+
+## 复现信息
+
+- 前置条件: 启动 KEY1 并进入页签 1。
+- 复现步骤:
+
+1. 点击页签 1 内用于重置表格的“按钮”。
+2. 不移动鼠标，立即观察“上一页”和“下一页”之间的页码标签。
+3. 对表格或页签 2 按钮进行 hover 交互，触发后续重绘。
+
+- 复现概率：稳定复现
+- 最小复现 Demo：KEY1 页签 1
+- 证据：用户截图中重置后的页码标签首帧显示不全，后续重绘恢复。
+
+## 初步分析
+
+- 疑似位置: `Table::drawPageNum()`、`Table::drawButton()` 和内部控件 `Control::setX()` 的调用顺序。
+- 触发条件: 新旧表格宽度不同，分页 Label 和分页按钮需要同时横向移动。
+- 相关线索:
+  - 旧顺序先绘制页码，再在 `drawButton()` 中移动分页按钮。
+  - 分页按钮移动时会通过 `discardBackground()` 回贴旧背景。
+  - 旧按钮区域与新页码区域相交，导致新页码被局部擦除。
+- 最近相关改动：[可选] Table 页码强制设脏和分页按钮整表重绘链已经存在，但未覆盖内部控件同帧搬移后的旧快照覆盖。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-09-29
+- 最后更新时间: 2026-09-30
+- 修复版本: 当前工作区
+- 验证版本: 2026-09-29 非 UI 全矩阵通过；2026-09-30 用户完成 KEY1 至 KEY6 手工回归，暂未发现明显问题
+- 备注：[可选]