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

开发记录/Fix/Fix-BUG-20260929-0001-Table分页控件绘制前统一布局修复.md

@@ -0,0 +1,66 @@
+# Fix-BUG-20260929-0001
+
+> 适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。
+
+## 关联信息
+
+- Fix ID: Fix-BUG-20260929-0001
+- 关联 BUG ID: BUG-20260929-0001
+- 修复目标: 避免 Table 运行期重置后的分页按钮旧快照覆盖新页码
+- 状态：已完成
+- 负责人: Codex
+- 分支 / 版本: 当前工作区
+
+## 根因分析
+
+- 根因: `Table::draw()` 先通过 `drawPageNum()` 绘制新页码，随后 `drawButton()` 才重新定位上一页和下一页按钮。按钮的 `setX()/setY()` 会回贴旧位置背景快照；当旧按钮区域与新页码位置相交时，新页码被局部擦除。
+- 触发条件: 运行期替换表头或数据后，表格宽度和分页控件位置发生变化。
+- 为什么之前没发现: 既有检查覆盖普通翻页重绘，但没有覆盖“表格结构尺寸变化 + 三个分页控件同帧搬移”的首帧顺序。
+- 关键证据: 后续 hover 只触发重绘、不再改变分页控件位置，此时页码立即恢复完整，说明页码内容和设脏逻辑本身有效。
+
+## 修复方案
+
+- 修复思路: 将分页内部控件的布局刷新前移到 Table 新一帧绘制之前。先更新页码文本，再统一移动页码 Label 和两个分页按钮并清理旧快照，最后绘制表体、页码和按钮。
+- 关键改动:
+  - 集中生成当前页码文本，避免布局阶段和绘制阶段使用不同字符串。
+  - 当分页布局失效时，在 Table 回贴并重绘自身之前完成页码 Label 的尺寸、位置和文本更新。
+  - 在同一预布局阶段完成上一页、下一页按钮的位置更新，确保旧快照不会覆盖本帧已经绘制的分页元素。
+  - 保留最终“表体 -> 页码 -> 分页按钮”的绘制顺序。
+- 涉及文件 / 类 / 函数:
+  - `src/StellarX/Table.cpp`
+  - `Table::draw()`
+  - `Table::drawPageNum()`
+- 影响的 API / 行为: 无公共 API 变化；仅修正运行期重置后的首帧绘制结果。
+- 关键约束 / 不变量: Table 内部控件因布局变化产生的旧快照回贴必须发生在父 Table 绘制新内容之前。
+- 回滚点 / 开关: 回退 `Table::draw()` 中的分页预布局块及统一页码文本生成函数。
+
+## 影响评估
+
+- 影响范围: Table 数据、表头、每页行数变化后的分页区重绘。
+- 兼容性影响：无
+- 行为变化：有（重置后的首帧直接显示完整页码）
+- 性能影响：可忽略，仅在分页布局失效时提前执行原有位置刷新。
+- 回归风险:
+  - 透明 Table 背景下的分页区快照恢复顺序变化。
+  - 页码位数变化造成 Label 宽度变化时，需要确认左右按钮仍与页码保持正确间距。
+  - 隐藏分页按钮后再恢复显示时，需要确认按钮仍能初始化并正确定位。
+
+## 验证结果
+
+- 验证步骤:
+
+1. 执行 `scripts/test.ps1 -Suite NonUI`。
+2. KEY1 页签 1 点击页内按钮后，不移动鼠标立即检查完整页码。
+3. 连续重置三次，并执行上一页、下一页切换。
+4. hover 页签 2、页签 3 并切换后返回，确认分页区无残影。
+
+- 验证结果: 2026-09-29 执行 `scripts/test.ps1 -Suite NonUI`，Debug x64、Debug x64 ASan、Release x64、Debug Win32 均为 15/15 通过；ASan 未报告内存错误；KEY1 至 KEY6 均编译、链接通过。用户于 2026-09-30 完成 KEY1 至 KEY6 手工回归，暂未发现明显问题。
+- 回归检查: KEY1 表格重置与翻页；KEY5 Table 分页、页码和上层浮层。
+- 验证证据：[可选]
+
+## 落地信息
+
+- Commit: 未提交
+- PR：[可选]
+- 发布版本：[可选]
+- 备注: UI 像素结果已由用户按 `TESTING.md` 完成人工验收。