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

开发记录/MIGRATION.md

@@ -0,0 +1,74 @@
+# StellarX API 迁移说明
+
+本次变更包含不兼容的所有权与文本样式 API 调整。GUI 仍限定在主线程，字符集仍为 MBCS。
+
+## Window 与 Canvas 所有权
+
+不再公开可变的 `std::vector<std::unique_ptr<Control>>`。调用方必须保存稳定句柄，而不是保存容器迭代器或假设控件地址永久有效。
+
+```cpp
+auto button = std::make_unique<Button>(10, 10, 100, 32, "run");
+const StellarX::ControlHandle handle = window.addControl(std::move(button));
+
+Control* control = window.findControl(handle);
+const bool removed = window.removeControl(handle);
+```
+
+新接口：
+
+- `ControlHandle addControl(std::unique_ptr<Control>)`
+- `bool removeControl(ControlHandle)`
+- `void clearControls()`
+- `Control* findControl(ControlHandle)`
+- `std::vector<ControlHandle> getControlHandles() const`
+
+已删除：
+
+- `Window::getControls()`
+- `Canvas::getControls()`
+- `Canvas::clearAllControls()`
+
+事件、绘制、tick 和按钮回调遍历期间的新增、删除与清空会延迟到最外层事务结束后提交。回调结束后不要继续使用已请求删除的裸指针。
+
+## 字体名称
+
+`ControlText::lpszFace` 已替换为拥有型字符串 `ControlText::faceName`。
+
+```cpp
+StellarX::ControlText style;
+style.faceName = "微软雅黑";
+```
+
+不再传入临时 `c_str()` 指针。字体样式比较按字符串内容进行，复制赋值使用默认值语义。
+
+## TabControl
+
+页签身份改为索引，重复标题合法。
+
+```cpp
+const size_t index = tabs.addTab(std::move(button), std::move(page));
+auto rejected = tabs.tryAddToPage(index, std::move(control));
+if (rejected) {
+    // 添加失败，调用方仍拥有控件。
+}
+```
+
+替换关系：
+
+- `add(pair<Button, Canvas>)` 改为 `addTab(button, page)`，返回页签索引。
+- `add(tabText, control)` 改为 `tryAddToPage(index, control)`；文本重载只匹配第一个同名页签。
+- `setActiveIndex(int)` 现在返回 `bool`，运行期非法索引返回 `false`。
+
+空 TabControl 可预设首次激活索引；首次绘制不会访问空容器。索引超过首批页签范围时首次激活最后一个可用页签。
+
+## 日志配置
+
+`SxLogger::setConfig` 现在返回 `bool`：
+
+```cpp
+if (!StellarX::SxLogger::Get().setConfig(config)) {
+    // 候选文件 sink 打开失败，旧配置和旧 sink 保持有效。
+}
+```
+
+文件输出禁用、路径、追加模式或滚动阈值变化会同步更新 sink。滚动重命名失败时继续追加原文件，不再截断。