XCEngine/docs/plan/Editor重构3.26.md

# Editor重构 3.26

## 当前判断

截至 2026-03-26，Editor 的 UI 架构重构如果只计算“架构层整理”，不计算 Viewport/RHI 和 Scene/Game 真正内容开发，整体进度大约在 **92%**。

如果把“编辑器整体可用度”也算进去，则大约在 **65%** 左右，因为 `Scene` / `Game` 面板目前仍然只是占位壳，Viewport 仍未回归，且部分编辑语义与回归验证还未补齐。

## 已完成的架构层

### 1. UI 主题与样式 Token 层

已将大量直接散落在 panel 中的颜色、间距、控件尺寸、Dock 外观收口到统一 UI 基础层。

当前主要入口：

- `editor/src/UI/BaseTheme.h`
- `editor/src/UI/StyleTokens.h`
- `editor/src/UI/DockHostStyle.h`
- `editor/src/UI/PanelChrome.h`
- `editor/src/UI/Core.h`
- `editor/src/UI/Widgets.h`
- `editor/src/UI/PopupState.h`
- `editor/src/UI/PropertyGrid.h`
- `editor/src/UI/UI.h`

这一层的意义是：

- 主题值不再零散写在各个 panel 里
- panel chrome、toolbar、popup、property row、asset tile 等基础外观开始统一
- 后续继续调 UI 观感时，优先改 shared layer，而不是到处修 panel

### 2. 面板共享控件层

已抽出并统一了：

- toolbar 搜索框
- toolbar 按钮 / 切换按钮
- 空状态绘制
- 面包屑
- hierarchy tree node
- asset tile
- deferred popup / modal state
- inline text edit state
- inspector component section
- dialog action row
- property grid / scalar / vector 控件

当前结果是 `Hierarchy / Project / Inspector / Console / MenuBar` 的基础表现逻辑已经大面积转向 shared widget，而不是每个 panel 手搓一遍。

### 3. Command 层

已经从 panel 中抽出了大部分直接业务操作，形成内部命令层：

- `editor/src/Commands/SceneCommands.h`
- `editor/src/Commands/EntityCommands.h`
- `editor/src/Commands/ProjectCommands.h`
- `editor/src/Commands/ComponentCommands.h`

当前已进入 command 的行为包括：

- 新建 / 打开 / 保存场景
- 启动场景加载与退出时脏场景保存
- 创建 / 复制 / 粘贴 / Duplicate / 删除 / 重命名 / 重挂接实体
- 创建文件夹、删除资源、打开资源、移动资源
- 添加 / 移除组件

这一层已经把大量 `undo / dirty / selection reset / scene switch confirm` 从 panel 中剥离出来。

### 4. Action / Shortcut 层

这一层是 3.26 新补上的，用于承接：

- 文案
- shortcut 文本
- enabled 状态
- 文本输入时是否允许触发
- shortcut 触发上下文
- menu 与 shortcut 的统一绑定
- button / toolbar / inspector action 的统一接线

当前文件：

- `editor/src/Actions/ActionBinding.h`
- `editor/src/Actions/EditorActions.h`

已覆盖的区域：

- `MenuBar`
- `Hierarchy`
- `Project`
- `Inspector`
- `Console`

这一层已经不再只是 `MenuBar + Hierarchy` 的试点，而是开始成为 editor 范围内的统一动作定义入口。

当前新增结果：

- 已补 shared shortcut context
- `Global` 与 `FocusedWindow` 两种快捷键路由开始统一
- `Hierarchy` 与 `Project` 已接入同一套 shortcut 分发
- 已补 active action route
- `MenuBar Edit` 已开始跟随 `Hierarchy / Project` 切换动作目标
- `Rename` 这类依赖 panel 内联状态的动作，开始通过 `EventBus` 请求而不是直接耦合 panel 实现
- `Edit` 动作解析与菜单绘制 / shortcut 分发已开始从 `MenuBar` 抽成共享 router
- `Hierarchy / Project` 的上下文菜单与创建弹窗也开始下沉到 shared action router
- `Project` 右键菜单目标已不再依赖 panel 内裸索引字段，而是改成 targeted popup state
- `Inspector / Console` 的局部 action 组装也开始继续下沉到 shared router
- `Inspector` 的 component section header 菜单已开始改成 callback/router 驱动，而不是在 widget 层硬编码动作
- `MenuBar` 的 File / View / Help / global shortcut 也开始继续下沉到 shared main-menu router
- `Hierarchy / Project` 的 drag-drop payload、拖拽接收与部分选择语义也开始继续下沉到 shared action router
- `Hierarchy / Project / Inspector / Console` 的空白点击、popup 请求、日志绘制与 interactive-change 边界也开始继续从 panel 下沉到 shared router/state
- `MainMenu / Edit` 的菜单绘制、shortcut 触发与动作执行路径也开始继续合并成统一 router 入口

### 5. Dock / Layout 层

`Dock / Layout` 已从 `EditorLayer::setupDockspace()` 中抽出，形成独立 layout controller：

- `editor/src/Layout/DockLayoutController.h`

当前已完成：

- dock host 渲染与默认布局重建从 `EditorLayer` 中移出
- `Reset Layout` 已接入真正行为
- `MenuBar -> EventBus -> DockLayoutController` 的事件链已经打通
- ImGui layout 已持久化到 `<project>/.xceditor/imgui_layout.ini`

当前仍待完成：

- 默认布局参数进一步数据化
- 更细致的 layout 状态管理

### 6. Panel 生命周期层

已开始把 `EditorLayer` 内手写的 panel 创建、context 注入、attach、detach、update、event、render 流程，收口到统一 panel collection。

当前意义是：

- `EditorLayer` 不再保存一串分散的 panel 生命周期样板代码
- panel 的 attach / detach / render 顺序有了统一入口
- 后续继续拆 panel 或补 panel 时，不需要再改一大片壳层代码
- startup scene / dock attach / panel tree 组装已继续从 `EditorLayer` 收口到 `EditorWorkspace`
- `Inspector` 的 selection 订阅已从 `Render()` 懒接线改回生命周期接线
- `Hierarchy` 的事件订阅也已从析构清理改回显式 `OnAttach / OnDetach` 生命周期清理

### 7. Application / ImGui Session 层

`Application` 中原先混在一起的 ImGui context 创建、字体加载、ini 路径配置、layout 持久化，已经开始抽成独立 session：

- `editor/src/UI/ImGuiSession.h`
- `editor/src/UI/ImGuiBackendBridge.h`

这一层的意义是：

- `Application` 更接近窗口 / 设备 / layer host
- ImGui 生命周期不再继续堆在 `Application.cpp`
- Win32 / DX12 backend API 不再散落在 `Application.cpp` 与 `main.cpp`
- 后续继续清理 backend 初始化边界时，有稳定落点
- Win32 window/message pump 已抽成 `Platform/Win32EditorHost.h`
- DX12 swapchain / render target / present / resize 已抽成 `Platform/D3D12WindowRenderer.h`
- scene title 拼装已抽成 `Core/EditorWindowTitle.h`
- crash filter / stderr redirect / logging sink 初始化已继续从 `Application.cpp` 抽离
- editor context 初始化、ImGui backend/session 初始化、layer attach/detach 与 frame render 壳方法也已继续从 `Application::Initialize/Shutdown/Render` 主流程中拆出

## 主要面板状态

### MenuBar

已完成：

- 文件菜单场景动作走 command
- undo / redo / copy / paste 动作开始统一
- shortcut 接入 action 层
- scene 状态显示统一
- `Reset Layout` 已接入事件驱动行为
- `About` 已接入真实 modal popup
- `Exit` 已通过事件驱动关闭 editor
- `Edit` 菜单已开始跟随 active action route 在 `Hierarchy / Project` 之间切换
- `Edit` 菜单与上下文快捷键开始共享同一套 edit action router
- `File / View / Help / global shortcut` 已开始继续从 panel 下沉到 shared main-menu router
- scene status 与 about dialog 已开始继续从 panel 下沉到共享 UI widget/dialog
- `MenuBar` 已进一步退化为 router 驱动的薄壳，File/View/Help/Edit 的拼装继续从 panel 移出

仍待完成：

- help / app 级动作继续向更统一的 application shell 收口

### Hierarchy

已完成：

- 搜索栏、节点样式、上下文菜单、创建菜单已共享化
- 创建 / 删除 / 重命名 / 复制 / 粘贴 / Duplicate / 重挂接走 command
- 快捷键已接 action 层
- 重命名状态已收成 `Begin / Commit / Cancel`
- 重命名交互已从 panel 局部字段收口到 shared inline edit state
- `Rename` 请求已能从 `MenuBar -> EventBus -> Hierarchy inline edit` 触发
- entity drag payload / 目标接收 / root drop / selection click 语义已开始继续从 panel 下沉到 shared hierarchy router
- hierarchy 空白点击清空选择与排序 popup 请求/菜单也已开始继续从 panel 下沉
- hierarchy 背景 / entity context popup 与 root drop target 入口也已开始继续从 panel 下沉
- rename commit 也已开始继续从 panel 直连 command 改成 shared hierarchy router 入口

仍待完成：

- 拖拽 / 空白区域目标等细节继续统一

### Project

已完成：

- toolbar、breadcrumb、search、asset grid、empty state 已共享化
- 打开资源、删除资源、创建文件夹、拖拽移动走 command
- 上下文菜单、返回按钮、创建文件夹对话框已接 action 层
- 资源图标绘制与图标配色已下沉到 shared UI token / widget
- 创建文件夹弹窗已改成 shared popup state 驱动
- `Back / Open / Delete` 已接 panel-focused keyboard action
- asset drag payload / folder drop / 拖拽预览高亮已开始继续从 panel 下沉到 shared project router
- item 选择 / item context 请求 / 空白区 context popup 请求也已开始继续从 panel 下沉
- asset open 请求也已开始继续从 panel 直连 command 改成 shared project router 入口

仍待完成：

- 更多资源对话框 / 多选语义继续统一

### Inspector

已完成：

- component section 已共享化
- Add Component 已放到底部
- 组件增删已走 command
- 组件内容编辑大部分已走 property grid
- Add Component 按钮与 popup 项已接 action 层
- Add Component popup 已接 shared popup state
- Add Component popup 菜单项组装已开始从 panel 下沉到 shared inspector action router
- 组件 section header 的移除动作已开始从 widget 层硬编码迁回 inspector action router
- selection 切换时的 interactive undo finalize、Add Component 按钮与 popup 绘制也已开始继续从 panel 下沉

仍待完成：

- section header 的动作继续统一
- 组件编辑交互与 undo 提交边界继续收口

### Console

已完成：

- 工具栏与内容区布局已共享化
- 日志行 hover 表现已统一
- `Clear / Filter` 已接 action 层
- console filter 状态已从 panel 裸布尔字段收成独立 state object
- console toolbar action 与日志文本格式化已继续从 panel 下沉到共享层
- log row 列表绘制与复制语义也已开始继续从 panel 下沉到 console router

仍待完成：

- 控制台状态与动作定义继续统一

### Scene / Game

当前状态：

- 只保留空壳 panel
- 暂时不做内容

这符合当前阶段决策，因为 Viewport 依赖的 RHI 模块仍在重构中。

## 还未完成的架构事项

### 高优先级

1. 整理 `Application.cpp` 和 `EditorLayer.cpp` 中剩余的 UI 壳逻辑  
   包括 backend 初始化边界、主循环中剩余 ImGui / render 壳逻辑、部分样式 push / pop 的收口。

### 中优先级

2. 继续将 panel 的本地状态机抽离  
   包括：
   - console filter state
   - 其他仍散落在 panel 内的临时交互状态

3. 将剩余少量视觉硬编码继续下沉到 token / widget 层  
   尤其是 `ProjectPanel` 中的 icon color 和一部分 panel 局部尺寸。

4. 统一 editor 范围内的编辑语义  
   例如：
   - 哪些 panel 消费 Copy / Paste / Delete / Open / Back
   - 哪些动作受 selection 驱动
   - 哪些动作在文本输入时必须屏蔽
   - 哪些动作通过 command，哪些动作通过 event 请求 panel 内联状态

### 低优先级

5. 再整理一次目录边界  
   当前 `UI / Commands / Actions / Layout` 方向是对的，但后续还可以再决定哪些继续 header-only，哪些拆 `.cpp` 更合适。

6. 补一份更正式的 editor 架构说明  
   说明 panel、actions、commands、layout、managers 的职责边界，便于后续继续迭代。

7. 根据条件补最小回归测试或最小验证脚本  
   重点验证 shortcut、undo、scene dirty/save switch、drag-drop/reparent。

当前新增验证：

- 已新增 `tests/editor/test_action_routing.cpp`
- 已新增 `tests/editor/CMakeLists.txt` 与 `editor_tests` target
- 已覆盖 `Hierarchy Edit route` 的 copy / paste / duplicate / delete / rename request
- 已覆盖 `Project Edit route` 的 open / back / delete
- 已覆盖 `scene dirty save + load` 后的 selection / undo reset
- 已覆盖 `reparent` 的 parent 切换、cycle 拦截与 world position / scale 保持

## 下一阶段建议执行顺序

### 第一阶段

1. 清理 `Application + EditorLayer` UI 壳层
2. 清理 panel 内剩余局部状态逻辑

### 第二阶段

3. 收口剩余视觉硬编码
4. 统一 editor 范围内的编辑语义

### 第三阶段

5. 根据需要继续细分 `Actions / Commands / Layout` 的目录边界
6. 补最小回归验证
7. 为 Viewport 回归预留 editor shell 接口

## 阶段性结论

当前 editor 重构已经从“到处修视觉 bug”切换到了“逐层收口架构”的状态，方向是正确的。

最关键的变化不是某个 panel 看起来更像 Unity，而是已经开始形成稳定分层：

- `UI` 负责外观与共享控件
- `Actions` 负责动作定义与 shortcut / button 绑定
- `Commands` 负责编辑器业务行为
- `Layout` 负责 dock host 与默认布局
- `Panels` 逐步退化为纯 UI 壳

只要继续沿这个方向收口，后面再做 Scene/Game 接入、Viewport 回归时，成本会明显低于继续在 panel 内部堆逻辑。