Tighten new editor shell chrome and add dock convergence plan

docs/plan/XCEditor_Dock统一与Tab拖拽停靠收口计划_2026-04-10.md

@@ -0,0 +1,364 @@
+# XCEditor Dock统一与Tab拖拽停靠收口计划
+
+日期：`2026-04-10`
+
+## 1. 文档定位
+
+这份计划只解决 `XCEditor` 当前 dock 基础层的两个核心问题：
+
+1. `Hierarchy / Inspector` 与 `Scene / Game / Console / Project` 顶部 chrome 不是同一套。
+2. tab 不能像旧 `editor/` 的 ImGui docking 那样拖拽重排与调整停靠位置。
+
+这两个问题本质上是同一个根问题：当前 `DockHost` 的叶子语义和渲染路径没有统一，导致视觉、命中、交互、布局变更都被拆成两套，后续再堆业务面板只会继续在错误基础上加复杂度。
+
+本计划属于 `Editor` 基础层收口，不属于业务面板重建计划。
+在这份计划完成前，不继续推进 `new_editor` 的 `Project / Hierarchy / Inspector / Console` 业务重建。
+
+## 2. 当前问题与根因
+
+## 2.1 当前现象
+
+- `Hierarchy / Inspector` 的 header 仍然走 standalone panel 外壳。
+- `Scene / Game / Console / Project` 走 tab stack 外壳。
+- 用户看到的直接结果是：tab 高度、内边距、标题区结构、可交互区域都不一致。
+- 用户尝试拖 tab 时，没有任何重排、合并、分裂停靠反馈。
+
+## 2.2 当前真实根因
+
+当前实现里同时存在两种叶子形态：
+
+- `Panel`
+- `TabStack`
+
+这使得 `DockHost` 的整条链路都被拆成两套：
+
+- 布局输出分叉
+- 绘制分叉
+- hit test 分叉
+- 交互分叉
+- 未来的 docking mutation 也无从统一落点
+
+当前代码里的直接证据：
+
+- `new_editor/app/Shell/ProductShellAsset.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorDockHost.h`
+- `new_editor/src/Shell/UIEditorDockHost.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorDockHostInteraction.h`
+- `new_editor/src/Shell/UIEditorDockHostInteraction.cpp`
+- `new_editor/include/XCEditor/Collections/UIEditorTabStripInteraction.h`
+- `new_editor/src/Collections/UIEditorTabStripInteraction.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorWorkspaceController.h`
+- `new_editor/src/Shell/UIEditorWorkspaceController.cpp`
+- `new_editor/src/Shell/UIEditorWorkspaceLayoutPersistence.cpp`
+
+当前控制器层只具备：
+
+- `OpenPanel`
+- `ClosePanel`
+- `ShowPanel`
+- `HidePanel`
+- `ActivatePanel`
+- `ResetWorkspace`
+- `SetSplitRatio`
+
+还没有真正支撑 docking 的命令与树变更能力：
+
+- `ReorderTab`
+- `MoveTabToStack`
+- `DockTabRelative`
+- `ExtractTab`
+- `MergeTabStack`
+
+## 3. 改造目标
+
+本轮收口后的目标状态如下：
+
+1. 运行态叶子节点只保留一种语义：`TabStack`。
+2. 单面板也被视为“只有一个 tab 的 tab stack”。
+3. `DockHost` 只保留一套统一的 `DockHeader / TabWell / ContentBody` 视觉结构。
+4. `Hierarchy / Inspector` 与 `Scene / Game / Console / Project` 必须走同一套 header/tab primitive。
+5. tab 至少支持：
+   - 同 stack 重排
+   - 跨 stack 合并
+   - 向目标 leaf 的 `left/right/top/bottom/center` 停靠
+6. 拖拽过程中必须有明确 preview，不允许“拖了但没有反馈”。
+7. workspace 布局持久化必须覆盖新结构，并兼容旧布局升级。
+8. 在 `tests/UI/Editor` 中补齐单元测试与集成测试后，才允许继续推进业务面板。
+
+## 4. 范围边界
+
+## 4.1 本轮必须做
+
+- `XCEditor` 的 dock 叶子语义统一
+- dock chrome 统一
+- tab 拖拽状态机
+- docking drop target 与 preview overlay
+- workspace tree surgery
+- layout persistence 升级
+- `tests/UI/Editor` 的回归补齐
+
+## 4.2 本轮明确不做
+
+- 多原生窗口 detached docking
+- 浮动窗口系统
+- 业务面板内部复杂逻辑重建
+- `Runtime UI` 相关能力
+- 为 `Editor` 再做一套资源化主题体系
+
+`Editor` 当前继续采用固定代码样式，不走 UI 资源那套。
+
+## 5. 目标结构
+
+## 5.1 统一后的 workspace 叶子模型
+
+运行态只保留：
+
+- `SplitNode`
+- `TabStackNode`
+
+其中 `TabStackNode` 内部包含：
+
+- `tabs`
+- `selectedTabId`
+- `activePanelId`
+
+不再保留“裸 `Panel` 叶子节点”这种视觉语义。
+
+## 5.2 统一后的 dock 布局输出
+
+`DockHost` 最终应面向统一 leaf 输出：
+
+- `tabWellRect`
+- `contentBodyRect`
+- `selectedPanelId`
+- `tabItems`
+- `dropPreview`
+
+不再分成：
+
+- `panelLayouts`
+- `tabStackLayouts`
+
+两套平行分支。
+
+## 5.3 统一后的交互分层
+
+交互链路收口为：
+
+1. `UIEditorTabStripInteraction`
+   - 负责 tab press / armed / drag / release / cancel
+2. `UIEditorDockHostInteraction`
+   - 负责把 tab 拖拽映射为 docking preview 与 docking command
+3. `UIEditorWorkspaceController`
+   - 负责真正修改 workspace tree
+4. `UIEditorWorkspaceLayoutPersistence`
+   - 负责新旧布局读写与升级
+
+## 6. 分阶段执行计划
+
+## Phase A：统一叶子语义
+
+### 目标
+
+把 workspace 运行态的叶子语义统一到 `TabStackNode`，彻底消除 standalone panel 叶子。
+
+### 任务
+
+- 调整 `UIEditorWorkspaceModel`，明确叶子节点只允许 `TabStackNode`。
+- 调整 `ProductShellAsset` 与默认 workspace 构建逻辑，让单面板默认也生成单-tab stack。
+- 调整 `UIEditorWorkspaceSession`，保证 active/selected 状态都围绕 tab stack 工作。
+- 调整 `UIEditorWorkspaceLayoutPersistence`，读旧格式时自动升级为统一 leaf 结构。
+- 增加 degenerate tree cleanup：
+  - 空 stack 删除
+  - 单子 split 折叠
+  - 非法 selectedTab 修正
+
+### 完成标准
+
+- 运行态 workspace 中不再出现 standalone panel 叶子。
+- 旧布局能被自动升级并正常显示。
+
+## Phase B：统一 dock chrome 与布局输出
+
+### 目标
+
+让所有 panel 顶部都走同一套 dock header / tab well primitive。
+
+### 任务
+
+- 重构 `UIEditorDockHost` 的 layout 输出结构，改为统一 leaf 布局。
+- 删除 standalone panel 与 tab stack 的渲染分叉。
+- `UIEditorPanelFrame` 缩回“边框与 body 外壳”职责，不再自带独立 header 风格。
+- `UIEditorTabStrip` 成为唯一 tab/header 渲染入口。
+- `UIEditorPanelContentHost` 只根据统一 leaf layout 定位 panel body。
+- 统一 hit target 语义，保证 header/tab/body 命中都来自同一套结构。
+
+### 完成标准
+
+- `Hierarchy / Inspector / Scene / Game / Console / Project` 顶部结构完全统一。
+- tab 高度、padding、命中区域、激活态样式只由一套 metric/palette 控制。
+
+## Phase C：同 stack tab 拖拽重排
+
+### 目标
+
+先把最小闭环做稳：同一个 stack 内 tab 可拖拽重排。
+
+### 任务
+
+- 在 `UIEditorTabStripInteraction` 增加拖拽状态机：
+  - `pressed`
+  - `armed`
+  - `dragging`
+  - `cancelled`
+  - `committed`
+- 增加 drag threshold、pointer capture、Esc cancel、release commit。
+- 在同 stack 内计算插入位置与 preview insertion marker。
+- 在 `UIEditorWorkspaceController` 增加 `ReorderTab(...)`。
+- 保证 selected/active/focus 状态在重排后仍然正确。
+
+### 完成标准
+
+- 同一 tab strip 内可拖拽重排。
+- 有明确插入线 preview。
+- 无闪烁、无丢焦、无错误激活。
+
+## Phase D：跨 stack 合并与 split docking
+
+### 目标
+
+把 tab 从“只能在本组重排”扩展到“可跨组移动并形成新停靠布局”。
+
+### 任务
+
+- 在 `DockHostInteraction` 中引入 drop target 解析：
+  - `center`
+  - `left`
+  - `right`
+  - `top`
+  - `bottom`
+  - `root empty area`
+- 增加 preview overlay：
+  - center merge 预览
+  - edge split 高亮预览
+  - 同 stack reorder 线性预览
+- 在 `WorkspaceController` 中增加：
+  - `MoveTabToStack(...)`
+  - `DockTabRelative(...)`
+  - `ExtractTab(...)`
+  - `MergeTabStack(...)`
+- 增加 tree surgery：
+  - 从源 stack 抽 tab
+  - 插入目标 stack
+  - 围绕目标 leaf 生成 split
+  - 空 stack 清理
+  - 单子 split 折叠
+
+### 完成标准
+
+- tab 可从一个 stack 拖到另一个 stack。
+- 可通过 `left/right/top/bottom/center` 形成新布局。
+- 交互有实时 preview。
+
+## Phase E：持久化、回归与测试体系补齐
+
+### 目标
+
+把新 docking 结构正式纳入 `tests/UI/Editor` 的标准回归。
+
+### 任务
+
+- 更新 layout serialization，稳定写回统一 leaf 结构。
+- 旧布局读取时自动升级。
+- 补齐 `tests/UI/Editor/unit`：
+  - 旧布局升级
+  - 同 stack reorder
+  - 跨 stack merge
+  - split docking
+  - cleanup collapse
+  - active/selected 同步
+  - persistence round-trip
+- 补齐 `tests/UI/Editor/integration`：
+  - `shell/dock_header_unified`
+  - `shell/dock_tab_reorder_same_stack`
+  - `shell/dock_tab_move_between_stacks`
+  - `shell/dock_tab_split_targets`
+  - `state/dock_layout_persistence`
+- 每个集成测试 exe 顶部写清楚当前验证目标，不再只写模糊状态文本。
+
+### 完成标准
+
+- `tests/UI/Editor` 对新 docking 具备完整回归入口。
+- 后续业务面板接入时，不需要再倒回头修基础 docking 架构。
+
+## 7. 代码落点
+
+本轮预计主要改动路径：
+
+- `new_editor/include/XCEditor/Shell/UIEditorWorkspaceModel.h`
+- `new_editor/src/Shell/UIEditorWorkspaceModel.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorWorkspaceController.h`
+- `new_editor/src/Shell/UIEditorWorkspaceController.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorWorkspaceLayoutPersistence.h`
+- `new_editor/src/Shell/UIEditorWorkspaceLayoutPersistence.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorWorkspaceSession.h`
+- `new_editor/src/Shell/UIEditorWorkspaceSession.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorDockHost.h`
+- `new_editor/src/Shell/UIEditorDockHost.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorDockHostInteraction.h`
+- `new_editor/src/Shell/UIEditorDockHostInteraction.cpp`
+- `new_editor/include/XCEditor/Collections/UIEditorTabStripInteraction.h`
+- `new_editor/src/Collections/UIEditorTabStripInteraction.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorPanelFrame.h`
+- `new_editor/src/Shell/UIEditorPanelFrame.cpp`
+- `new_editor/include/XCEditor/Shell/UIEditorPanelContentHost.h`
+- `new_editor/src/Shell/UIEditorPanelContentHost.cpp`
+- `new_editor/app/Shell/ProductShellAsset.cpp`
+- `tests/UI/Editor/unit/*dock*`
+- `tests/UI/Editor/unit/*workspace*`
+- `tests/UI/Editor/integration/shell/*dock*`
+- `tests/UI/Editor/integration/state/layout_persistence/*`
+
+## 8. 并行拆分建议
+
+这轮改造可以拆成 4 条可并行子线，但必须按主从顺序集成：
+
+1. `WorkspaceModel / Controller / Persistence`
+2. `DockHost layout / render / hit-test 统一`
+3. `TabStripInteraction / DockHostInteraction` 拖拽状态机
+4. `tests/UI/Editor` 单元与集成回归补齐
+
+并行原则：
+
+- 先以 `Phase A` 的统一 leaf 语义为总前提。
+- `Phase B` 与 `Phase C` 可以在统一模型落定后并行推进。
+- `Phase E` 可以在 `Phase C / D` 功能接口稳定后并行补齐。
+
+## 9. 风险与控制
+
+## 9.1 最大风险
+
+- 旧布局兼容被打断
+- 统一叶子后现有 panel body 定位错位
+- 拖拽状态机与 focus/capture 冲突
+- split tree surgery 产生退化树或悬空 active panel
+
+## 9.2 控制方式
+
+- 先做模型统一，再做交互，不反过来堆补丁
+- 每个 mutation 先补 `unit` 再补 `integration`
+- 任何旧布局兼容问题都在 persistence 层处理，不在渲染层写兼容分叉
+- 任何单面板特殊视觉都回收为单-tab stack，不再恢复 standalone panel 路径
+
+## 10. 收口判定
+
+只有同时满足以下条件，才算这轮 dock 基础层真正收口：
+
+1. 所有 dock 叶子统一为 `TabStackNode`。
+2. `Hierarchy / Inspector` 与 `Scene / Game / Console / Project` 头部视觉完全统一。
+3. tab 可同组重排、跨组合并、左右上下停靠。
+4. 拖拽过程有稳定 preview，释放后结果正确。
+5. 布局可持久化，旧布局可升级。
+6. `tests/UI/Editor/unit + integration` 已覆盖关键回归。
+
+在这 6 条完成前，不进入下一轮业务面板重建。