Archive XCUI subplan 04

docs/plan/used/XCUI_Subplan-01_Core_Tree_State_完成归档_2026-04-04.md

@@ -0,0 +1,93 @@
+# XCUI Subplan 01：Core Tree / State / Invalidation
+
+归档日期：
+
+- `2026-04-04`
+
+状态：
+
+- 已完成
+
+本次实际完成内容：
+
+- 新增 XCUI core 基础契约：`UIElementId`、`UIDirtyFlags`、`IUIViewModel`、`RevisionedViewModelBase`
+- 新增 retained-mode build 层：`UIBuildElementDesc`、`UIBuildList`、`UIBuildContext`
+- 新增 retained-mode tree 层：`UIElementTree`、`UIElementNode`、`UIElementTreeRebuildResult`
+- 新增统一入口：`UIContext`
+- 实现最小闭环：tree rebuild、dirty flag 标记、layout dirty 向祖先传播、dirty root 收集
+- 新增并验证 UI core 测试：tree 创建、unchanged rebuild、local state invalidation、view model invalidation、structure change、未闭合 build scope 失败
+
+本次涉及文件：
+
+- `engine/include/XCEngine/UI/Types.h`
+- `engine/include/XCEngine/UI/Core/UIInvalidation.h`
+- `engine/include/XCEngine/UI/Core/UIViewModel.h`
+- `engine/include/XCEngine/UI/Core/UIBuildContext.h`
+- `engine/include/XCEngine/UI/Core/UIElementTree.h`
+- `engine/include/XCEngine/UI/Core/UIContext.h`
+- `engine/src/UI/Core/UIBuildContext.cpp`
+- `engine/src/UI/Core/UIElementTree.cpp`
+- `tests/core/UI/CMakeLists.txt`
+- `tests/core/UI/test_ui_core.cpp`
+
+验证结果：
+
+- `cmake --build . --config Debug --target core_ui_tests`
+- `ctest -C Debug --output-on-failure -R UICoreTest --test-dir .`
+- 结果：`6/6` 通过
+
+当前结论：
+
+- `Subplan 01` 的最小 retained-mode core 已经可用
+- 后续 `Subplan 03/05/06/07/08/09` 可以基于这套 core 继续推进
+
+原始 subplan 内容归档如下：
+
+# Subplan 01：XCUI Core Tree / State / Invalidation
+
+目标：
+
+- 搭出 XCUI 的 retained-mode 核心骨架。
+- 明确 `ElementTree`、`NodeId`、`View`、`ViewModel`、`dirty flag`、`rebuild`、`lifecycle` 的最小闭环。
+
+负责人边界：
+
+- 负责 `engine/include/XCEngine/UI/` 与 `engine/src/UI/Core/` 的核心树模型。
+- 不负责具体布局算法。
+- 不负责 ImGui 适配绘制。
+
+建议目录：
+
+- `engine/include/XCEngine/UI/Core/`
+- `engine/src/UI/Core/`
+- `tests` 中对应 XCUI core 测试文件
+
+前置依赖：
+
+- 依赖主线完成 `Phase 0` 的基础类型和 UI 生命周期边界清理。
+
+现在就可以先做的内容：
+
+- 设计 `UIElementId` / `UIElement` / `UIContext` / `UIBuildContext`
+- 设计 dirty 标记与增量重建规则
+- 设计 ViewModel 读写边界和 command 回调入口
+- 写最小 tree rebuild 测试
+
+明确不做：
+
+- 不接入 `.xcui` 文件
+- 不接入 editor 面板
+- 不写具体 widget 大库
+
+交付物：
+
+- XCUI core 基础类与生命周期定义
+- tree rebuild / invalidation / state propagation 单元测试
+- 一个最小 demo：代码构建 UI tree 并触发一次增量更新
+
+验收标准：
+
+- 可以构建一棵稳定的 UI tree
+- 局部状态变化时只标脏必要节点
+- 重建逻辑与布局/渲染解耦
+- 其他 subplan 可以基于该模块定义控件树和状态更新