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

# 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` 完成人工验收。