diff --git a/docs/plan/xcui_editor_windowing_architecture_plan.md b/docs/plan/xcui_editor_windowing_architecture_plan.md deleted file mode 100644 index d8e80102..00000000 --- a/docs/plan/xcui_editor_windowing_architecture_plan.md +++ /dev/null @@ -1,114 +0,0 @@ -# XCUI Editor Windowing Plan - -## 阶段门禁 - -- 每完成一个阶段，必须先编译 `XCUIEditorApp`。 -- 编译通过后，必须实际运行 editor，并执行一次 12 秒冒烟测试。 -- 只有在编译与 12 秒冒烟测试都通过后，才能提交并推送该阶段改动。 - -更新日期: `2026-04-26` - -状态: `In Progress, live projection payload、常规 sync/presentation 去副本化已收口，下一阶段聚焦交互 / 过渡路径去 controller 读依赖` - -## 1. 长期目标 - -这个计划只关注 `editor/app/Windowing` 到 `editor/app/Platform/Win32/Windowing` 的多窗口工作区主线。目标不是继续把行为堆进 `EditorWindowWorkspaceCoordinator`，而是把 editor 窗口系统收口为下面的单向数据流: - -```text -EditorWindowSystem authoritative window set - -> semantic mutation / lifecycle policy - -> synchronization plan - -> Win32 host execution - -> native observation / frame requests - -> app-layer reconciliation -``` - -长期完成态应满足: - -- `EditorWindowSystem` 是窗口工作区 authority、validation、planner、destroy reconciliation 的唯一 app 层入口。 -- `EditorWorkspaceWindowContentController` 只负责 projection、交互和 mutation request 生产，不再充当 host 可写的 authority 副本。 -- `EditorWindow` 不再把 `TryGetWorkspaceController()` / `ReplaceWorkspaceController()` 作为跨层同步主接口；host 侧消费的是受控 projection 或 presentation data。 -- `EditorWindowWorkspaceCoordinator` 收缩为 host executor + native event bridge，不再同时承担领域编排、live projection 回滚和跨窗口语义决策。 -- detach、dock、close、destroy、primary switch 都先形成 app 层 mutation / transition，再生成 sync plan，再由 host 执行。 - -验证基线统一收口到 `tests/UI/Editor`: - -- `editor_windowing_phase1_tests` 负责 planner / reconcile / transition 规则。 -- 若当前 checkout 提供对应 target，则由 `editor_app_feature_tests` 负责 host 集成行为。 -- `xcui_editor_app_smoke` 负责启动烟测。 -- `tests/UI/Editor/manual_validation` 保留复杂交互人工验证。 - -## 2. 当前进展 - -已完成并已经并回总 plan 的收口项: - -- `EditorWindowSystem` 已拥有 `BuildPlanForWorkspaceMutationRequest(...)`、`BuildPlanForDestroyedWindow(...)`、`CommitSynchronizationPlan(...)`。 -- `EditorWindowWorkspaceCoordinator` 已不再直接写 authority store。 -- live frame 内工作区变化已经通过显式 `workspaceMutation` request 回到 app 层。 -- `editor_windowing_phase1_tests` 已覆盖显式 mutation request commit、unknown `windowId` rejection、detached window create/close、destroyed primary closeout 等基础规则。 -- workspace window 已引入显式 `EditorWorkspaceWindowProjection`，标题、minimum size、detached title bar/tab strip 文案改由 projection / authoritative state 导出。 -- `EditorWindowWorkspaceCoordinator` 的常规同步路径已改为 `RefreshWorkspaceProjection(...)`，不再依赖 `ReplaceWorkspaceController(...)` 整体替换 live controller。 -- `xcui_editor_app_smoke` 对应 runner 已支持 12 秒 smoke auto-exit 门禁，能作为阶段收口验证入口。 - -这意味着前一轮 subplan 里围绕“authority 回写收口”“显式 request 成为主输入”“destroy reconciliation 回到 app 层”的工作已经完成，后续不再继续保留为独立 subplan。 - -当前离长期目标仍有两个核心缺口: - -- live content 仍持有可变 `UIEditorWorkspaceController`，且 drag bootstrap、少量 runtime/过渡路径仍会直接读 controller。 -- `EditorWindowWorkspaceCoordinator` 仍然过厚，把 host 执行、drag/detach 流程、标题刷新和失败回滚串在同一层。 - -## 3. 下一个阶段执行计划 - -### 3.1 阶段目标 - -下一阶段只做一个切口: 把“live workspace controller 是 host 可写副本”收口为“content 只持有受控 projection，并通过显式 request 回传语义变化”。 - -做完这一阶段后，`EditorWindowWorkspaceCoordinator` 可以暂时保留现有 drag/detach 能力，但它不应再依赖 `EditorWindow::GetWorkspaceController()` / `ReplaceWorkspaceController()` 作为常规同步手段。 - -### 3.2 范围 - -主要涉及: - -- `editor/app/Windowing/Content/**` -- `editor/app/Windowing/System/**` -- `editor/app/Platform/Win32/Windowing/**` -- `tests/UI/Editor/unit` -- 必要时补 `tests/UI/Editor/smoke` - -本阶段不扩到 shell、viewport、panel feature 业务重构。 - -### 3.3 执行步骤 - -1. 定义 projection 边界 -- 为 workspace window 引入明确的 projection / presentation payload，至少覆盖 content compose、title、minimum size、detached title bar 所需数据。 -- `EditorWorkspaceWindowContentController` 改为消费 projection 并产出 request，不再把内部 `UIEditorWorkspaceController` 暴露为 host 通用读写接口。 - -2. 改造窗口更新路径 -- 拆分 `EditorWindowWorkspaceCoordinator::ApplySynchronizationPlan(...)`，把“host 执行”和“projection 刷新/commit”从同一段流程里拆开。 -- `UpdateWorkspaceWindow` 动作不再通过 `ReplaceWorkspaceController(...)` 整体替换 live controller，而是通过受控 projection refresh API 更新窗口内容。 - -3. 收口 presentation 读取路径 -- `RefreshWindowTitle(...)`、`ResolveMinimumOuterSize()`、`ResolveDetachedWindowTitleText(...)` 等 presentation 决策统一基于 authoritative state 或 projection payload。 -- 清理 `EditorWindow::TryGetWorkspaceController()` 在 Win32 协调器里的常规读路径，只保留确实无法在本阶段消除的过渡性接口。 - -4. 建立回归验证 -- 保持现有 `workspaceMutation` request / destroyed window reconciliation 测试基线不回退。 -- 为 projection refresh、title refresh 增补 focused unit coverage。 -- 为 detach、dock、primary switch 至少补一组 focused integration 或 app feature tests，确保改造后 host 行为不回退。 -- 继续保留 `xcui_editor_app_smoke` 作为 editor 启动基线。 - -### 3.4 本阶段验收标准 - -- `EditorWorkspaceWindowContentController` 不再被当成 authority 副本使用。 -- `EditorWindowWorkspaceCoordinator` 的常规同步路径不再依赖 `ReplaceWorkspaceController(...)`。 -- 标题、最小尺寸、detached tab strip 文案等 presentation 行为能从 projection / authoritative state 稳定导出。 -- `workspaceMutation` 仍是 frame 内工作区变化的显式入口，没有恢复任何平台隐式写回。 -- `editor_windowing_phase1_tests` 与可用的 host 集成测试入口能覆盖本阶段新增规则。 -- `xcui_editor_app_smoke` 继续通过。 - -### 3.5 本阶段非目标 - -- 不重写 `XCUIEditorApp` 启动流程。 -- 不在本阶段改造 `EditorShellRuntime`、viewport render loop 或各 feature panel 业务。 -- 不追求一次性删除所有 `UIEditorWorkspaceController` 使用点，先消除 host 常规同步路径上的 authority 副本语义。 -- 不把 Win32 host adapter 直接扩写成跨平台窗口系统。 diff --git a/editor/AGENT.md b/editor/AGENT.md index fd3e6ee8..ef300c25 100644 --- a/editor/AGENT.md +++ b/editor/AGENT.md @@ -137,7 +137,6 @@ EditorContext::BuildWorkspaceController() 因此： - 不要把当前架构写成“projection-only content controller 已完成”。 -- 涉及这一段的改动，应同时参考 `docs/plan/xcui_editor_windowing_architecture_plan.md`。 ## 5. 窗口类别与内容控制器 @@ -236,7 +235,6 @@ Application::Run - 新增 utility window 先补 `EditorUtilityWindowKind`、`EditorUtilityWindowDescriptor`、`CreateEditorUtilityWindowPanel(...)`，不要直接在 Win32 coordinator 里硬编码窗口类型。 - 新增跨窗口语义时，优先增加显式 frame request 或 app/windowing plan builder，不要回退到 Win32 host 直接读写 authority。 - 修改窗口同步逻辑时，区分“当前代码事实”和“长期目标”。当前还存在 live mutable projection，不要按尚未落地的终态直接删接口。 -- 若改动触及窗口 authority / projection / coordinator 职责边界，记得同步检查 `docs/plan/xcui_editor_windowing_architecture_plan.md`。 - 不要让 `editor/include/XCEditor/**` 暴露 `App::*` 类型。 - draw append 只负责绘制，不顺手修改 scene / project / authority 状态。 @@ -281,7 +279,6 @@ Application::Run 开始 editor 相关任务时，优先阅读： -- `docs/plan/xcui_editor_windowing_architecture_plan.md` - `editor/CMakeLists.txt` - `editor/app/Bootstrap/Application.*` - `editor/app/Composition/EditorContext.*`