XCEngine/docs/plan/xcui_editor_windowing_architecture_plan.md

XCUIEditor Windowing Architecture Plan

更新日期: 2026-04-26

状态: Phase 1 completed, Phase 2 completed, Subplan 3A planned

1. Plan 管理规则

• docs/plan 现在只保留总 plan。
• 已完成 subplan 的结论直接并回总 plan，不再保留阶段性执行文档。
• 新的 subplan 必须保持小切口；一次只收口一条主链，不把 projection、destroy、drag/drop 等多条链路捆在同一阶段。

2. 顶层架构问题

当前 XCUIEditorApp 最严重的架构问题仍然是: 多窗口工作区状态存在双真相源。

这两个真相源目前分别落在:

• editor/app/Windowing/System/EditorWindowSystem.*
• editor/app/Composition/EditorWindowWorkspaceStore.*
• live EditorWindow
• editor/app/Windowing/Content/EditorWorkspaceWindowContentController.*
• editor/app/Platform/Win32/Windowing/EditorWindowWorkspaceCoordinator.*

虽然已经把“同步 diff 规划”和“标题策略”从 Win32 层切回了 app 层，但当前仍然存在以下事实:

• live EditorWindow / EditorWorkspaceWindowContentController 里的 UIEditorWorkspaceController 仍然是可变状态容器。
• EditorWorkspaceWindowContentController::UpdateAndAppend(...) 已经产出显式 workspaceMutation request，但 request 仍然来自 live controller 的本地副本。
• EditorWindowWorkspaceCoordinator::HandleWindowFrameTransferRequests(...) 收到 workspaceMutation 后，仍通过 CommitLiveWindowMutation(sourceWindow) 回读 window.GetWorkspaceController()，而不是直接消费 request payload。
• EditorWindowWorkspaceCoordinator::ApplySynchronizationPlan(...) 仍同时承担 host 执行与 authoritative commit 的时序编排。

这会带来四个直接后果:

1. app 层和 host 层都能改 UIEditorWindowWorkspaceSet，单一真相源名义存在、实际不存在。
2. frame 内部交互修改依赖平台回写兜底，边界方向不稳定。
3. 关闭、拖拽、分离、primary 切换这些跨窗口时序很难纯粹按领域规则推导。
4. editor/app/Platform/Win32 继续承担了不属于 host adapter 的领域编排责任。

3. 已完成收口

当前已完成两阶段收口，结果如下:

• 新增 app 层同步模型:
  • EditorWindowSynchronizationPlan
  • EditorWindowSynchronizationPlanner
  • EditorWindowPresentationPolicy
• EditorWindowSystem 新增 BuildSynchronizationPlan(...)，开始由 app 层产出 authoritative sync plan。
• EditorWindowWorkspaceCoordinator 不再持有窗口集 diff 算法和标题策略定义，只保留 host snapshot 采集与 plan 执行。
• EditorWindowTransferRequests 新增显式 workspace mutation request，frame 内工作区变化不再依赖平台隐式回写 authority。
• EditorWindowSystem 收口 live window mutation / native destroy observation / authoritative commit 语义入口。
• EditorWindowLifecycleCoordinator::HandleNativeWindowDestroyed(...) 不再直接删除 authority store entry，而是回到 app 层做 destroy reconciliation。
• editor/app/Platform/Win32/** 已移除对 authority raw write 接口的直接依赖。
• 新增聚焦验证:
  • tests/UI/Editor/unit/test_editor_window_synchronization_planner.cpp
  • editor_windowing_phase1_tests
• editor 本体已完成构建与 12s 启动冒烟验证。
• editor 测试入口回到 tests/UI/Editor，legacy tests/editor 已从当前活动构建图移除。

这两阶段的目标分别是:

• Phase 1: 先把“领域决策”和“Win32 执行”切开。
• Phase 2: 删除“平台回写 authority”链路，把 authority mutation 收口回 editor/app/Windowing。

这两个目标都已经达成。

4. 当前剩余缺口

原计划中针对 authority writeback 的核心缺口已经完成收口，但还有一段“半收口”链路仍然存在:

• EditorWindowTransferRequests 已有 EditorWindowWorkspaceMutationRequest，但 EditorWorkspaceWindowContentController::UpdateAndAppend(...) 目前只填 workspace/session，没有把稳定的 windowId 一并带出。
• EditorWindowWorkspaceCoordinator::HandleWindowFrameTransferRequests(...) 目前拿到 request 后并不直接消费它，而是再次回读 sourceWindow 上的 live projection。
• 这意味着 frame 内交互虽然已经显式化为 request，但 request 还没有真正成为这条链路的唯一语义输入。

这一段正好适合作为下一个小 subplan；在它完成之前，不适合继续展开更大的 live projection 去状态化。

5. 目标架构

目标状态下，窗口系统的数据流应当是单向的:

authoritative window set (app/windowing)
  -> mutation validation
  -> synchronization plan
  -> Win32 execution
  -> host observation / lifecycle event
  -> app-layer semantic callback

这里的关键约束是:

• authority 只在 editor/app/Windowing 侧维护。
• Win32 层只能消费 plan、上报 observation/event，不能直接写 authority store。
• live content controller 只能是 projection 或受控 mutation producer，不能再充当隐式 authority 副本。

6. 后续路线

后续按“小 subplan”推进，每个 subplan 只解决一条主链。下一个 subplan 只收口 frame 内显式 workspaceMutation request，不同时处理 live projection 去状态化、native destroy reconciliation 或 global tab drag。

6.1 Subplan 3A: 显式 workspace mutation request 收口

6.1.1 阶段目标

• 让 frame 内 workspace 变更通过 EditorWindowWorkspaceMutationRequest 进入 app 层，而不是由 coordinator 再回读 live UIEditorWorkspaceController。
• 把“显式 request 已存在但未真正成为主输入”的半收口状态补完整。
• 保持本阶段足够小，只处理 live workspace mutation commit 这条链。

6.1.2 建议改动范围

• editor/app/Windowing/Frame/EditorWindowTransferRequests.h
• editor/app/Windowing/Content/EditorWorkspaceWindowContentController.*
• editor/app/Windowing/System/EditorWindowSystem.*
• editor/app/Platform/Win32/Windowing/EditorWindowWorkspaceCoordinator.*
• tests/UI/Editor/unit/test_editor_window_synchronization_planner.cpp
• 必要时补 tests/UI/Editor/unit 下新的 focused test；若必须经过 host 协调器，再补 editor_app_feature_tests

6.1.3 详细执行步骤

1. 先把 workspaceMutation request payload 补完整。
   • EditorWorkspaceWindowContentController::UpdateAndAppend(...) 在生成 EditorWindowWorkspaceMutationRequest 时补齐 windowState.windowId。
   • request 的有效性以“windowId 非空且 workspace state 可用”为准，避免继续依赖 source window 隐式补信息。
2. 再把 app 层计划入口改成显式 request 驱动。
   • 在 EditorWindowSystem 中新增或收口一个直接消费 EditorWindowWorkspaceMutationRequest 的 plan builder。
   • 该入口只做三件事: 校验 windowId、把 request 中的 workspace/session 合并进当前 authoritative window set、复用 BuildPlanForWindowSet(...)。
   • BuildPlanForLiveWindowMutation(...) 如果还有旧调用方，可暂时降级成薄封装；本阶段不再新增新的调用点依赖它。
3. 最后切换 EditorWindowWorkspaceCoordinator 的 live commit 路径。
   • HandleWindowFrameTransferRequests(...) 直接把 transferRequests.workspace.workspaceMutation 传给 commit 路径。
   • CommitLiveWindowMutation(...) 改成基于 request 的实现，或者删除旧的 EditorWindow& 回读版本。
   • 本阶段完成后，live workspace mutation commit 不再依赖 window.GetWorkspaceController()；该接口只允许继续服务 projection / title / UI 查询。
4. 补 focused 验证，保证这是小收口而不是行为漂移。
   • planner/system 侧至少覆盖“显式 request 改 active panel 后可生成并提交有效 plan”。
   • 增加“unknown windowId request 被拒绝”的负向验证。
   • 如果 unit 无法覆盖 coordinator 消费 request 的行为，再补一条最小 host-side focused test，而不是直接上重型运行时验证。

6.1.4 本阶段验收标准

• workspaceMutation request 自身携带稳定 windowId，不再需要 source window 兜底补齐。
• EditorWindowWorkspaceCoordinator::HandleWindowFrameTransferRequests(...) 不再忽略 request payload。
• live frame mutation 的 authoritative commit 路径不再回读 sourceWindow.GetWorkspaceController()。
• 现有 detach / dock / close / primary switch 行为不因本阶段发生语义漂移。
• editor_windowing_phase1_tests 继续通过；若新增 host-side focused test，对应测试目标也应通过。

6.1.5 本阶段非目标

• 不在本阶段删除 EditorWindow / content controller 上的 TryGetWorkspaceController() 或 ReplaceWorkspaceController()。
• 不在本阶段处理 native destroy reconciliation。
• 不在本阶段重做 global tab drag / detach 相关编排。
• 不在本阶段把 live content controller 改成完全只读 projection。

7. 验收标准

整个计划完成后，应至少满足:

1. editor/app/Platform/Win32/** 不再直接调用 authority store 原始写接口。
2. EditorWindowSystem 成为窗口工作区 authoritative mutation 的唯一 app 层入口。
3. 任意多窗口变化都先形成 app 层语义上的 mutation / transition，再形成 sync plan，再由 host 执行。
4. native close / destroy 不再通过平台层“直接删 store entry”完成状态收口。
5. EditorWorkspaceWindowContentController 不再被当作 authority 副本，而只是 projection 或受控 mutation source。
6. detach / dock / close / primary switch 至少具备稳定 unit coverage，并对关键 host 时序具备 focused integration coverage。

8. 验证策略

验证入口仍然以 tests/UI/Editor 为主，不重新启用旧 tests/editor。

优先级如下:

• tests/UI/Editor/unit
• 必要时补 tests/UI/Editor/smoke
• 只有在 unit / focused integration 无法覆盖的 host 时序下，才考虑更重的运行时验证

当前已建立的验证基线:

• cmake --build build --config Debug --target editor_windowing_phase1_tests
• build/tests/UI/Editor/unit/Debug/editor_windowing_phase1_tests.exe

9. 非目标

本计划当前不直接解决以下事项:

• 把 XCUIEditorApp 立即改造成跨平台窗口系统
• 全量重写 shell / viewport / message dispatcher
• 顺手重构所有 inspector、panel、runtime 业务逻辑
• 在 authority 收口前提前合并全部 Win32 coordinator

这些都必须排在“窗口领域 authority 真正收口”之后。