完成 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,77 @@
+# 功能变更 ID: Feature-20260317-0002
+
+> 适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。
+> 不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。
+
+## 基本信息
+
+- ID: Feature-20260317-0002
+- 标题: TextBox::setText 运行期刷新语义调整
+- 状态：已完成（历史记录；本次仅归档，未重新验证）
+- 类型：修改
+- 级别：L2 中等
+- 模块: TextBox / Repaint
+- 版本 / 分支: v3.0.1 / master
+- 环境: Windows 11 / Visual Studio 2022 / Debug、Release / EasyX
+- 负责人: Ysm-04（历史实现）
+
+## 变更背景
+
+- 背景:
+  - 早期 `setText()` 直接调用 `draw()`，在图形上下文尚未初始化时可能崩溃。
+  - v3.0.0 将 Setter 收敛为更新状态并标脏，解决初始化阶段的生命周期问题，但运行期程序化设置文本可能要等后续事件或重绘周期才能显示。
+- 目标: 在不破坏初始化阶段安全性的前提下，让已经绘制过的 TextBox 在运行期更新文本后请求或执行刷新。
+- 不做什么：[可选]
+  - 不改变 `setText(std::string)` 的函数签名。
+  - 不在没有有效背景快照时强制进入绘制链路。
+
+## 变更内容
+
+- 变更摘要: `setText()` 根据文本是否变化、最大长度、父控件和有效快照状态决定仅标脏、向父控件请求重绘或直接绘制。
+- 新增项：[可选]
+  - 文本未变化时立即返回，避免无效更新。
+- 修改项：[可选]
+  - 文本变化后始终更新内部值并标记为脏。
+  - 有父控件且 `hasSnap` 为真时，调用 `requestRepaint(parent)`。
+  - 无父控件且 `hasSnap` 为真时，直接调用 `draw()`。
+  - `hasSnap` 为假时只保留脏标记，等待首次绘制或统一重绘流程。
+- 删除 / 废弃项：[可选]
+  - 无。
+- 受影响的文件 / 类 / 函数:
+  - 历史路径：`src/textBox.cpp`
+  - `TextBox::setText(std::string)`
+- 对外 API / 属性变化：[可选]
+  - 函数签名不变；运行期可见刷新时机发生变化。
+
+## 行为对照
+
+- 变更前（v3.0.0）: `setText()` 更新内部文本并标脏，不保证调用后立即触发可见重绘。
+- 变更后（v3.0.1）:
+  - 初始化/首次绘制前没有有效快照，仅更新文本并标脏，不触发依赖图形上下文的绘制。
+  - 已绘制且存在有效快照时，通过父容器请求重绘；没有父控件时直接绘制。
+  - 文本未变化时不执行重复重绘。
+- 兼容性说明：部分兼容
+- 迁移说明：[可选]
+  - 若旧代码在 `setText()` 后手动调用 `draw()`，升级到 v3.0.1 后应移除重复绘制，避免闪烁或重复刷新。
+  - 初始化阶段仍可先设置默认文本，由首次统一绘制完成显示。
+
+## 验证与落地
+
+- 验证方式:
+  - 创建 TextBox，在窗口和图形上下文建立前调用 `setText()`，确认不会进入绘制链路或中断。
+  - 窗口运行后，在按钮回调中调用 `setText()`，确认无需额外鼠标事件即可刷新。
+  - 重复设置相同文本，确认不会产生无效刷新。
+- 验证结果:
+  - PDF 历史记录将“初始化前设置默认文本”和“按钮回调中运行期更新”记为正常。
+  - 本次归档通过历史提交确认了 `hasSnap` 分支逻辑，但未构建 v3.0.1，也未重新运行 GUI 用例。
+  - `hasSnap` 是历史实现用于判断是否已具备绘制条件的代理状态；本记录不把它扩展解释为所有图形上下文状态的通用保证。
+- 关联 BUG / Fix：[可选]
+  - 前序问题：[`BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md`](../BUG/BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md)
+  - v3.0.0 修复：[`Fix-BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md`](../Fix/Fix-BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md)
+- Commit:
+  - 实现提交：`c66cad3423a46ec4ef902965baa4c1816d10148a`
+  - 发布记录提交：`b765e54eff28ebcd0bd99a81dec80b3ac0769337`
+- PR：[可选]
+- 发布版本：[可选] v3.0.1
+- 备注：[可选]
+  - 资料来源：`StellarX功能_模块变更.pdf` 第 10-12 页，并以对应提交和历史 `CHANGELOG.md` 交叉核对。