# 新增功能模块 / 模块重构

> 适用场景：新增模块、重大模块重构、核心架构能力演进。
> 不适用场景：小接口或轻量功能变更，请使用“功能变更”模板。

## 基本信息

- 模块 ID：Module-20260915-0001
- 模块名称：StellarX 核心库与自动化测试基础设施
- 状态：非 UI 与人工 UI 已验证，待提交
- 类型：模块重构 / 架构演进
- 所属系统 / 子系统：StellarX Core / Unit Test / UI Regression
- 版本 / 分支：当前工作区
- 环境：Windows + Visual Studio 2022 + MSVC v143 + EasyX
- 负责人：Codex 协作修改

## 背景与目标

- 背景:
  - 原应用工程同时承担框架实现、示例入口和回归验证职责，框架代码与测试代码之间缺少明确边界。
  - 本次全量缺陷修复涉及控件生命周期、重绘、事件循环、MBCS 文本和日志等多个核心模块，需要让应用、单元测试和真实 UI Fixture 复用完全相同的实现。
- 当前痛点:
  - 核心框架源文件分散在应用工程中，难以单独复用和验证。
  - 仅依赖手工启动窗口，无法稳定覆盖回调期间所有权变化、ASan 内存安全和多配置构建。
  - UI 控件基于 EasyX 绘制，不是原生子窗口，UIA/WinAppDriver 无法直接按控件语义定位。
- 目标:
  - 将框架实现集中编译为 `StellarX.Core` 静态库。
  - 建立纯逻辑单元测试、真实 EasyX Fixture 和外部 Win32 UI 驱动三层验证。
  - 让 Debug、Release、Win32、x64 和 x64 ASan 使用统一的核心实现。
- 非目标：[可选]
  - 不在本次工作中将静态库改为 DLL。
  - 不迁移到 Unicode，不改变 GUI 只能在主线程使用的约束。
  - 不将 UI 测试改造成依赖 DPI 或字体的全图 golden image 测试。

## 模块边界

- 职责:
  - `StellarX.Core.vcxproj` 编译 `Window`、`Control`、`Canvas`、各类控件、Dialog、TabControl 和日志实现。
  - 主应用、Native Unit Test 和 UI Fixture 通过 `ProjectReference` 使用同一份核心实现。
  - `scripts/test.ps1` 统一组织 Unit、Render、UI、All 和 CI 测试入口。
  - `scripts/run-ui-tests.ps1` 负责启动 Fixture、注入鼠标输入、等待结果并保存诊断文件。
- 不负责什么:
  - 不负责最终应用资源、业务示例和安装包制作。
  - 不把 `StellarX.Core.lib` 作为普通 GUI 应用用户的运行时 DLL。
  - 不替代 EasyX、Visual C++ Runtime 等外部依赖的发布判断。
- 外部依赖:
  - Visual Studio 2022、MSVC v143、Windows SDK。
  - EasyX 图形库。
  - Visual Studio Native Unit Test Framework。
  - UI 套件需要可交互的 Windows 桌面，并会短暂切换前台窗口和移动鼠标。
- 对外能力 / API:
  - 核心库对外 API 通过 `StellarX.h` 汇总。
  - `StellarX.Core` 本身是构建期静态库，不新增运行时动态加载接口。
  - 测试入口通过 PowerShell 参数和 Fixture 场景提供，不属于框架公共 API。
- 关键数据 / 状态:
  - `StellarX.Core.lib`：框架实现的静态链接产物。
  - `StellarX.Tests.dll`：Native Unit Test 产物。
  - `StellarX.UiFixture.exe`：真实 EasyX UI 场景进程。
  - `TestResults/`：TRX、JSON、PNG 和日志诊断产物。

## 设计说明

- 核心流程:
  1. `StellarX.Core.vcxproj` 编译框架头文件和源文件。
  2. `imGui-easyX.vcxproj` 通过 `ProjectReference` 链接核心静态库，应用入口保留在 `z-testDome.cpp`。
  3. `StellarX.Tests` 和 `StellarX.UiFixture` 同样引用核心工程，避免测试复制另一份框架代码。
  4. Release 构建将核心代码静态链接进目标可执行文件；运行时不要求单独加载 `StellarX.Core.dll`。
- 关键对象 / 类关系:
  - `StellarX.Core.vcxproj`：核心实现的构建边界。
  - `Window / Canvas / Control`：窗口托管、控件所有权、事件和重绘基础。
  - `SxEventLoopInternal.h`：批量事件处理测试辅助。
  - `SxTextInternal.h`：MBCS 字符边界和密码掩码测试辅助。
  - `StellarX.Tests`：不创建窗口的逻辑测试。
  - `StellarX.UiFixture`：创建确定性 EasyX 窗口并导出状态和像素证据。
- 生命周期:
  - 核心库在构建阶段生成，静态链接进应用或测试可执行文件。
  - Unit 测试进程独立运行；涉及 UAF 的回归可在 ASan 配置中隔离执行。
  - UI Fixture 按场景创建和关闭图形上下文，失败时由脚本保存证据并发送 `WM_CLOSE`。
- 事件 / 渲染 / 数据流:
  - 逻辑测试使用 FakeControl、假时钟、假消息源和临时目录验证状态转移。
  - UI 驱动程序通过 `SendInput` 注入鼠标事件，通过 `SetWindowPos` 驱动窗口变化。
  - Fixture 导出 JSON 状态和 EasyX 后备缓冲像素，脚本按关键像素不变量判断结果。
- 关键不变量:
  - 应用、逻辑测试和 UI Fixture 必须链接同一份核心实现。
  - ASan 产物与普通 Debug 产物使用独立目录。
  - UI 场景串行执行，避免多个 EasyX 图形上下文争用桌面。
  - UI 断言不依赖 DPI、字体抗锯齿和完整截图的像素一致性。
- 降级 / 回退策略：[可选]
  - 没有交互桌面时，CI 只运行逻辑测试；设置 `STELLARX_UI_TESTS=1` 且环境满足条件时才执行 UI。
  - 全局 resize、Dialog 开关等场景保留整场景重绘兜底。

## 实现与影响

- 关键实现点:
  - 新增 `StellarX.Core` 静态库工程和解决方案项目引用。
  - 新增 `StellarX.Tests`、`StellarX.UiFixture`、PowerShell 测试脚本和诊断输出约定。
  - 新增 `SxEventLoopInternal.h`、`SxTextInternal.h` 两个仅供内部实现和测试使用的头文件。
  - 核心控件采用稳定句柄、延迟变更事务和统一 geometry/coverage 处理。
- 涉及文件 / 类 / 函数:
  - 工程：`StellarX.Core.vcxproj`、`imGui-easyX.vcxproj`、`imGui-easyX.sln`。
  - 核心：`Control`、`Window`、`Canvas`、`Button`、`Label`、`TextBox`、`Table`、`Dialog`、`TabControl`、`SxLogger`。
  - 测试：`tests/StellarXTests.cpp`、`tests/UiFixture.cpp`、`scripts/test.ps1`、`scripts/run-ui-tests.ps1`。
- 兼容性影响:
  - 工程内部从直接编译框架源文件调整为引用 `StellarX.Core`。
  - 本阶段同时包含破坏性公共 API 调整，迁移方式见 [`MIGRATION.md`](D:/programming/imGUI-easyX/imGui-easyX/开发记录/MIGRATION.md)。
- 性能影响:
  - 事件循环单轮最多处理 128 条消息，活动轮不固定休眠，空闲轮短暂休眠。
  - 静态库不引入运行时动态分发开销；托管重绘仍按覆盖范围选择性提交并保留全局兜底。
- 风险点:
  - EasyX UI 测试依赖前台交互桌面，不能作为无桌面 CI 的默认测试。
  - 当前 `Render` 入口复用 UI Fixture，尚未形成完全独立的进程内 Native Render 测试类别。
  - 编译仍存在 EasyX `C4201`、未使用变量和名称遮蔽等非阻断警告。

## 测试与验证

- 测试范围:
  - 所有权事务、空 TabControl、Tab 索引、字体拥有权、MBCS 掩码、Tooltip tick、事件批处理和日志配置。
  - Button、Label、TextBox、Canvas、Table、Dialog、TabControl 的真实 EasyX 重绘和 coverage 不变量。
  - Debug x64、Debug x64 ASan、Release x64、Debug Win32，以及 KEY1 至 KEY6 编译。
- 验证步骤:

1. 使用 `scripts/test.ps1 -Suite NonUI` 验证四套逻辑配置、ASan 和 KEY1 至 KEY6 编译。
2. 按 `TESTING.md` 的人工 UI 清单验证 KEY1、KEY2、KEY4、KEY5、KEY6。
3. 检查 TRX 和人工验收记录；只有明确允许自动 UI 时才使用 `scripts/test.ps1 -Suite All`。

- 验证结果:
  - 2026-09-29 的 Debug x64、Debug x64 ASan、Release x64、Debug Win32 均为 15/15 通过。
  - x64 ASan 未报告内存错误；KEY1 至 KEY6 均编译、链接通过。
  - 2026-09-30 为 `scripts/test.ps1` 补充 UTF-8 BOM 后，Windows PowerShell 5.1 下的 `NonUI` 全矩阵复验通过。
  - 本轮未启动自动 UI Fixture；用户于 2026-09-30 手工完成 KEY1 至 KEY6，暂未发现明显问题。
  - 2026-07-22 的 UI 六类场景三轮通过记录保留为历史证据；当前快照以 2026-09-30 的人工验收结果为准。
- 已知限制 / 遗留问题：[可选]
  - `Render` 当前复用单轮真实 UI Fixture；后续可单独建立进程内渲染测试类别。
  - UI 自动化仍需要已解锁的交互式桌面。
  - 本次未清理已有非阻断编译警告。

## 落地信息

- 关联功能变更 ID：[可选]
  - `Feature-20260915-0001`
- 关联 BUG / Fix：[可选]
  - 本次以全量缺陷修复矩阵统一记录，未为每个历史问题重新创建重复 BUG/Fix 文档。
- Commit:
  - 当前工作区未提交
- PR：[可选]
- 发布版本：[可选]
- 相关文档：[可选]
  - [`TESTING.md`](D:/programming/imGUI-easyX/imGui-easyX/开发记录/TESTING.md)
  - [`MIGRATION.md`](D:/programming/imGUI-easyX/imGui-easyX/开发记录/MIGRATION.md)