功能变更 ID: Feature-20260317-0002

适用场景：记录小到中等规模的功能、接口、行为、默认值或配置变化。不适用场景：新增核心模块、重大模块重构、架构级设计，请使用“新增功能模块”模板。

基本信息

背景:
- 早期 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
- v3.0.0 修复：Fix-BUG-20260109-0001-TextBox-setText进入事件循环前调用崩溃.md
Commit:
- 实现提交：c66cad3423a46ec4ef902965baa4c1816d10148a
- 发布记录提交：b765e54eff28ebcd0bd99a81dec80b3ac0769337
PR：[可选]
发布版本：[可选] v3.0.1
备注：[可选]
- 资料来源：StellarX功能_模块变更.pdf 第 10-12 页，并以对应提交和历史 CHANGELOG.md 交叉核对。