1888 lines
48 KiB
Markdown
1888 lines
48 KiB
Markdown
# New Editor Win32 窗口架构重构总计划
|
||
|
||
## 1. 文档目的
|
||
|
||
本计划用于指导 `new_editor/app/Platform/Win32` 相关窗口系统的彻底重构。
|
||
|
||
这不是一次“把大类再拆小一点”的整理，而是一次底层架构重建。核心目标是把当前体系改造成：
|
||
|
||
**状态机 + 单向事件流 + 平台投影**
|
||
|
||
本计划覆盖：
|
||
|
||
- `new_editor/app/Platform/Win32/Windowing`
|
||
- `new_editor/app/Platform/Win32/Runtime`
|
||
- `new_editor/app/Platform/Win32/Chrome`
|
||
- `new_editor/app/Platform/Win32/Content`
|
||
- `new_editor/app/Platform/Win32/System`
|
||
- `new_editor/app/Composition` 中与窗口、workspace、utility window、全局上下文相关的部分
|
||
|
||
---
|
||
|
||
## 2. 当前系统的根因
|
||
|
||
### 2.1 根因结论
|
||
|
||
当前最根本的问题只有一个：
|
||
|
||
**`EditorWindow` 没有形成真正的状态边界，窗口相关状态被多个类共同持有、共同修改、相互穿透。**
|
||
|
||
这带来的直接后果是：
|
||
|
||
1. 单窗口状态没有唯一所有者。
|
||
2. 跨窗口状态没有唯一所有者。
|
||
3. `WndProc` 路径承担了过多业务编排职责。
|
||
4. 稳态渲染与即时渲染双轨并存，且存在重入。
|
||
5. transfer request、binding 探测、兼容状态机大量出现，本质上都在给“边界失效”打补丁。
|
||
|
||
### 2.2 当前系统的派生问题
|
||
|
||
#### 2.2.1 `EditorWindow` 变成了共享可变状态包
|
||
|
||
它同时挂着：
|
||
|
||
- lifecycle
|
||
- HWND / title / dpi / size
|
||
- input controller
|
||
- chrome controller
|
||
- runtime controller
|
||
- frame orchestrator
|
||
- queued transfer requests
|
||
|
||
但这些状态不由它自己独占修改，而是被 `MessageDispatcher`、`ChromeController`、`HostRuntime`、`LifecycleCoordinator`、`WorkspaceCoordinator` 等对象直接穿透读写。
|
||
|
||
#### 2.2.2 Win32 消息分发承担了应用层职责
|
||
|
||
当前 `WM_*` 消息路径中，除了输入翻译，还直接做了：
|
||
|
||
- 生命周期推进
|
||
- resize / dpi 响应
|
||
- 立即帧渲染
|
||
- global tab drag 编排
|
||
- workspace 事务提交
|
||
- utility window 打开
|
||
- chrome 命令执行
|
||
|
||
这说明当前平台层已经不是适配层，而是业务主链的一部分。
|
||
|
||
#### 2.2.3 渲染链路是双轨的
|
||
|
||
现状存在两条渲染主链：
|
||
|
||
- 稳态帧：主循环统一 `RenderAllWindows`
|
||
- 即时帧：消息回调里直接 render / present
|
||
|
||
这会造成：
|
||
|
||
1. 消息回调重入渲染。
|
||
2. transfer request 需要额外缓冲。
|
||
3. resize / dpi / paint 顺序变得脆弱。
|
||
|
||
#### 2.2.4 `WorkspaceCoordinator` 已经偷偷变成状态源
|
||
|
||
当前 `EditorWindowWorkspaceCoordinator` 不只是协调器，而是同时承担：
|
||
|
||
- window set 构造
|
||
- workspace 同步
|
||
- 快照回滚
|
||
- 新窗口创建
|
||
- 窗口关闭编排
|
||
- global tab drag 会话
|
||
- 标题刷新
|
||
|
||
但它并没有被正式定义为“权威状态源”，所以职责和边界都不稳定。
|
||
|
||
#### 2.2.5 全局 `EditorContext` 混入了窗口局部能力
|
||
|
||
当前每个窗口 runtime 都会把自己的局部能力挂到全局 context 上，例如：
|
||
|
||
- text measurer
|
||
- utility window request 消费
|
||
- capture 状态文本依赖
|
||
|
||
这让全局上下文和局部窗口能力耦在了一起。
|
||
|
||
### 2.3 代码层证据
|
||
|
||
下面这些不是推测，而是当前代码直接暴露出来的结构事实：
|
||
|
||
1. `new_editor/app/Platform/Win32/Windowing/EditorWindowState.h`
|
||
中所谓 `EditorWindowState` 实际只保存了 `HWND`、`windowId`、`title`、`primary`、`lifecycle`。输入、chrome、resize、dpi、capture、frame、content 相关真实状态都不在这个“状态对象”里，这说明系统从命名层面就在伪装一个并不存在的统一状态边界。
|
||
2. `new_editor/app/Platform/Win32/Windowing/EditorWindow.h`
|
||
通过 `friend class` 把 `EditorWindowChromeController`、`EditorWindowFrameDriver`、`EditorWindowHostRuntime`、`EditorWindowMessageDispatcher`、`EditorWindowLifecycleCoordinator`、`EditorWindowWorkspaceCoordinator` 全部放进 `EditorWindow` 内部。这意味着窗口对象没有封装，只是一个公开状态袋。
|
||
3. `new_editor/app/Platform/Win32/Windowing/EditorWindowMessageDispatcher.cpp`
|
||
在 `WM_DPICHANGED`、`WM_EXITSIZEMOVE`、`WM_SIZE`、`WM_PAINT` 中直接触发 `RenderAndHandleWindowFrame` 或 `OnPaintMessage`。也就是说 Win32 消息回调直接参与渲染、事务完成和跨模块编排。
|
||
4. `new_editor/app/Platform/Win32/Windowing/EditorWindowHostRuntime.cpp`
|
||
中的 `RenderAllWindows` 不只是“遍历窗口”，它同时承担帧驱动、presentation 刷新、transfer request 聚合和后续分发。平台宿主已经兼任应用层调度器。
|
||
5. `new_editor/app/Platform/Win32/Windowing/EditorWindowWorkspaceCoordinator.cpp`
|
||
通过 `BuildLiveWindowWorkspaceSet(...)` 从 live windows 反推当前窗口集合，再基于这个集合做同步、提交和回滚。这说明跨窗口 topology 并没有显式权威状态，只能从现场对象拼出来。
|
||
6. `new_editor/app/Platform/Win32/Content/EditorWindowContentController.h`
|
||
暴露 `TryGetWorkspaceBinding`、`TryGetDockHostBinding`、`TryGetInputFeedbackBinding`、`TryGetTitleBarBinding`。应用层必须去“探测内容层支持哪些能力”，再临时决定走哪条逻辑分支，本质上是拿 capability probing 代替正式协议。
|
||
7. `new_editor/app/Platform/Win32/Runtime/EditorWindowRuntimeController.h`
|
||
同时持有 D3D12 renderer、texture host、text system、window render loop、screenshot controller、content controller、frame timing、dpi scale。render host、content host、diagnostic host 被揉成了一个类。
|
||
8. `new_editor/app/Platform/Win32/Content/EditorWorkspaceWindowContentController.cpp`
|
||
里 workspace 内容控制器一边对外暴露 binding，一边直接驱动 shell runtime 和 frame orchestrator。说明“内容输出”不是一个结构化结果，而是一堆散落接口和副作用。
|
||
|
||
因此，当前问题不是“某几个类太大”，而是根本没有形成：
|
||
|
||
- 单窗口状态所有权
|
||
- 跨窗口拓扑状态所有权
|
||
- 事件到 effect 的正式管线
|
||
- 平台层与应用层的稳定边界
|
||
|
||
---
|
||
|
||
## 3. 重构目标
|
||
|
||
### 3.1 总目标
|
||
|
||
建立以下新的权责模型：
|
||
|
||
1. **单窗口状态**
|
||
只能由 `WindowSession` 持有。
|
||
2. **跨窗口拓扑状态**
|
||
只能由 `WindowTopologyService` 持有。
|
||
3. **平台对象**
|
||
由 Win32 / D3D12 backend 持有，但只作为投影结果，不作为业务状态源。
|
||
4. **内容层**
|
||
不再通过 binding 探测链暴露能力，而是统一返回 `ContentOutput`。
|
||
5. **帧调度**
|
||
统一由 `FrameScheduler` 管理，消息回调只登记帧请求，不直接渲染。
|
||
|
||
### 3.2 完成后必须满足的硬约束
|
||
|
||
1. 新窗口架构中禁止 `friend` 穿透状态。
|
||
2. domain / application 头文件中禁止出现 `HWND`、`WPARAM`、`LPARAM`、`RECT`、`POINT`。
|
||
3. `WndProc` 路径中禁止直接 render / present。
|
||
4. `EditorWindowFrameTransferRequests` 必须删除。
|
||
5. `TryGetWorkspaceBinding` / `TryGetDockHostBinding` / `TryGetInputFeedbackBinding` / `TryGetTitleBarBinding` 必须退出主干架构。
|
||
6. 跨窗口状态必须显式保存在 `WindowTopologyState` 中，禁止从 live windows 反推。
|
||
7. `EditorContext` 中禁止挂载窗口私有能力对象。
|
||
|
||
---
|
||
|
||
## 4. 目标架构
|
||
|
||
## 4.1 分层模型
|
||
|
||
```text
|
||
Domain
|
||
状态、事件、命令、意图、effect 定义
|
||
|
||
Application
|
||
WindowSession / WindowTopologyService / FrameScheduler / Projector
|
||
|
||
Content
|
||
WorkspaceContentHost / UtilityContentHost
|
||
|
||
Platform
|
||
Win32 事件适配、native window backend、D3D12 render host
|
||
```
|
||
|
||
## 4.2 状态所有权
|
||
|
||
### 单窗口状态：`WindowState`
|
||
|
||
由 `WindowSession` 独占持有，建议至少包含：
|
||
|
||
- identity
|
||
- `windowId`
|
||
- `windowKind`
|
||
- lifecycle
|
||
- `PendingCreate`
|
||
- `NativeAttached`
|
||
- `Initializing`
|
||
- `Running`
|
||
- `Closing`
|
||
- `Destroyed`
|
||
- presentation
|
||
- `title`
|
||
- `dpi`
|
||
- `dpiScale`
|
||
- `focused`
|
||
- `visible`
|
||
- `minimized`
|
||
- size
|
||
- `clientPixelWidth`
|
||
- `clientPixelHeight`
|
||
- `predictedClientPixelWidth`
|
||
- `predictedClientPixelHeight`
|
||
- input
|
||
- `pointerCaptureOwner`
|
||
- `trackingMouseLeave`
|
||
- `modifierSnapshot`
|
||
- `pendingEvents`
|
||
- `pendingDoubleClickMask`
|
||
- chrome
|
||
- `hoveredChromeTarget`
|
||
- `pressedChromeTarget`
|
||
- `hoveredResizeEdge`
|
||
- `activeResizeEdge`
|
||
- `maximized`
|
||
- `restoreRect`
|
||
- `dragRestoreState`
|
||
- frame
|
||
- `needsFrame`
|
||
- `framePriority`
|
||
- `frameSerial`
|
||
- `resizeEpoch`
|
||
- content
|
||
- `cursorKind`
|
||
- `captureDemand`
|
||
- `titleBarMode`
|
||
- `contentStatus`
|
||
|
||
### 跨窗口状态：`WindowTopologyState`
|
||
|
||
由 `WindowTopologyService` 独占持有，至少包含：
|
||
|
||
- `primaryWindowId`
|
||
- `activeWindowId`
|
||
- `orderedWindowIds`
|
||
- `workspaceWindowIds`
|
||
- `utilityWindowIds`
|
||
- `windowProjections`
|
||
- `workspaceProjectionSnapshots`
|
||
- `workspaceSessionSnapshots`
|
||
- `globalTabDragState`
|
||
- `pendingUtilityRequests`
|
||
- `pendingDetachTransactions`
|
||
- `pendingDropTransactions`
|
||
|
||
说明：
|
||
|
||
- `WindowTopologyState` 不要求吞掉整个 workspace runtime 对象，但必须显式持有“窗口到 workspace 的权威投影真相”。
|
||
- 至少要能按 `windowId` 解释：window kind / role、workspace projection snapshot、workspace session snapshot、utility window kind、primary / active 标记、正在进行的 detach / drop / reuse 事务。
|
||
- 禁止再通过 live window、content controller、workspace controller 临时拼装当前业务 window set。
|
||
|
||
### 平台状态
|
||
|
||
平台状态由 platform backend 持有，但不作为业务真状态：
|
||
|
||
- `HWND`
|
||
- Win32 class registration
|
||
- OS capture / cursor
|
||
- D3D12 device / swapchain / renderer
|
||
|
||
---
|
||
|
||
## 5. 核心抽象
|
||
|
||
## 5.1 Domain 抽象
|
||
|
||
建议新增目录：
|
||
|
||
```text
|
||
new_editor/app/Windowing/Domain/
|
||
```
|
||
|
||
建议新增类型：
|
||
|
||
- `WindowId.h`
|
||
- `WindowState.h`
|
||
- `WindowTopologyState.h`
|
||
- `WindowEvent.h`
|
||
- `WindowIntent.h`
|
||
- `WindowCommand.h`
|
||
- `WindowEffect.h`
|
||
- `WindowCursorKind.h`
|
||
- `WindowCaptureOwner.h`
|
||
- `FramePriority.h`
|
||
|
||
### `WindowEvent`
|
||
|
||
平台层只负责把 `WM_*` 转成这些事件：
|
||
|
||
- 生命周期
|
||
- `NativeAttached`
|
||
- `NativeDestroyed`
|
||
- `CloseRequested`
|
||
- 输入
|
||
- `PointerMoved`
|
||
- `PointerLeft`
|
||
- `PointerButtonDown`
|
||
- `PointerButtonUp`
|
||
- `PointerWheel`
|
||
- `KeyDown`
|
||
- `KeyUp`
|
||
- `Character`
|
||
- `FocusGained`
|
||
- `FocusLost`
|
||
- `CaptureChanged`
|
||
- 尺寸
|
||
- `ClientResized`
|
||
- `InteractiveResizeStarted`
|
||
- `InteractiveResizeEnded`
|
||
- `DpiChanged`
|
||
- 帧
|
||
- `FrameTick`
|
||
- `PaintRequested`
|
||
- `FramePresented`
|
||
- 内容
|
||
- `ContentOutputReady`
|
||
|
||
### `WindowIntent`
|
||
|
||
内容层不再返回 transfer request，而是返回正式意图：
|
||
|
||
- `StartGlobalTabDrag`
|
||
- `DetachPanel`
|
||
- `OpenUtilityWindow`
|
||
- `RequestCursor`
|
||
- `RequestCapture`
|
||
- `ReleaseCapture`
|
||
- `RequestImmediateFrame`
|
||
- `RequestInvalidate`
|
||
- `ProposeWorkspaceMutation`
|
||
|
||
### `WindowEffect`
|
||
|
||
应用层最终向平台层发 effect：
|
||
|
||
- `CreateNativeWindow`
|
||
- `DestroyNativeWindow`
|
||
- `ShowWindow`
|
||
- `FocusWindow`
|
||
- `MoveWindow`
|
||
- `ResizeWindow`
|
||
- `SetWindowTitle`
|
||
- `SetCursor`
|
||
- `AcquireCapture`
|
||
- `ReleaseCapture`
|
||
- `TrackMouseLeave`
|
||
- `ScheduleFrame`
|
||
- `ApplyRenderResize`
|
||
|
||
---
|
||
|
||
## 6. 目标模块设计
|
||
|
||
## 6.1 `WindowSession`
|
||
|
||
职责：
|
||
|
||
- 持有 `WindowState`
|
||
- 接收 `WindowEvent`
|
||
- 演进单窗口状态
|
||
- 触发内容更新
|
||
- 生成窗口级命令和 effect
|
||
|
||
禁止：
|
||
|
||
- 直接调用 Win32 API
|
||
- 直接调用 D3D12 present
|
||
- 直接修改其它窗口状态
|
||
- 直接创建 utility window
|
||
|
||
## 6.2 `WindowTopologyService`
|
||
|
||
职责：
|
||
|
||
- 持有 `WindowTopologyState`
|
||
- 处理跨窗口事务
|
||
- 统一管理：
|
||
- primary / active window
|
||
- panel detach
|
||
- cross-window drop
|
||
- global tab drag
|
||
- utility window 去重与重用
|
||
|
||
它必须替代：
|
||
|
||
- `EditorWindowWorkspaceCoordinator`
|
||
- `EditorUtilityWindowCoordinator`
|
||
|
||
## 6.3 `FrameScheduler`
|
||
|
||
职责：
|
||
|
||
- 统一登记所有窗口帧请求
|
||
- 合并稳态帧与优先帧
|
||
- 对 resize / dpi / paint 恢复设定显式优先级
|
||
|
||
关键规则：
|
||
|
||
1. 消息回调只登记帧请求。
|
||
2. 所有 render / present 集中在调度点执行。
|
||
3. 不允许出现新的“隐式即时帧”路径。
|
||
|
||
## 6.4 `IWindowContentHost`
|
||
|
||
内容层改成统一宿主接口，而不是多 binding 探测。
|
||
|
||
输入：`WindowContentInput`
|
||
|
||
- workspace bounds
|
||
- input events
|
||
- frame context
|
||
- capture status text
|
||
- topology snapshot
|
||
- window role
|
||
|
||
输出：`WindowContentOutput`
|
||
|
||
- draw data
|
||
- cursor kind
|
||
- capture demand
|
||
- title bar mode
|
||
- workspace mutation intent
|
||
- utility window intent
|
||
- focus hints
|
||
- status text
|
||
|
||
## 6.5 `WorkspaceContentHost`
|
||
|
||
替代：
|
||
|
||
- `EditorWorkspaceWindowContentController`
|
||
|
||
职责：
|
||
|
||
- 持有 `EditorShellRuntime`
|
||
- 更新 shell
|
||
- 输出统一 `WindowContentOutput`
|
||
|
||
## 6.6 `UtilityContentHost`
|
||
|
||
替代：
|
||
|
||
- `EditorUtilityWindowContentController`
|
||
|
||
职责：
|
||
|
||
- 承载 utility panel
|
||
- 输出聚焦态、绘制结果、最小尺寸和内容状态
|
||
|
||
## 6.7 `Win32WindowProcAdapter`
|
||
|
||
替代：
|
||
|
||
- `EditorWindowMessageDispatcher`
|
||
|
||
职责：
|
||
|
||
- `WM_* -> WindowEvent`
|
||
- 不做业务决策
|
||
- 不持有业务状态
|
||
- 不 render / present
|
||
|
||
## 6.8 `Win32WindowBackend`
|
||
|
||
职责：
|
||
|
||
- `CreateWindowExW`
|
||
- `DestroyWindow`
|
||
- `SetWindowPos`
|
||
- `SetWindowTextW`
|
||
- `ShowWindow`
|
||
- `SetForegroundWindow`
|
||
- `TrackMouseEvent`
|
||
- `SetCapture / ReleaseCapture`
|
||
|
||
原则：
|
||
|
||
- 只执行 effect
|
||
- 不知道 workspace
|
||
- 不知道 topology
|
||
- 不知道 content host
|
||
|
||
## 6.9 `D3D12WindowRenderHost`
|
||
|
||
替代旧 `EditorWindowRuntimeController` 中的 D3D12 部分。
|
||
|
||
职责：
|
||
|
||
- 初始化窗口 renderer
|
||
- resize
|
||
- begin frame
|
||
- present
|
||
- viewport surface presentation capability
|
||
|
||
它是渲染宿主，不是业务控制器。
|
||
|
||
## 6.10 Chrome 子层
|
||
|
||
当前 stateful `EditorWindowChromeController` 需要拆为：
|
||
|
||
- `ChromeGeometry`
|
||
- 纯几何、纯 hit test
|
||
- `ChromeReducer`
|
||
- hover / press / resize / drag restore 状态机
|
||
- `ChromeEffectsBuilder`
|
||
- 根据状态变化生成 effect
|
||
|
||
纯 helper 如 `BorderlessWindowChrome.*`、`BorderlessWindowFrame.*` 可以保留或收缩。
|
||
|
||
## 6.11 关键接口草案
|
||
|
||
下面给的是目标结构草案，不要求首阶段一次到位，但最终主干必须收敛到类似形态。
|
||
|
||
### `WindowSession`
|
||
|
||
```cpp
|
||
class WindowSession final {
|
||
public:
|
||
explicit WindowSession(WindowId id, WindowKind kind);
|
||
|
||
const WindowState& Snapshot() const;
|
||
|
||
WindowSessionResult ApplyEvent(const WindowEvent& event);
|
||
WindowSessionResult ApplyContentOutput(const WindowContentOutput& output);
|
||
WindowSessionResult ApplyTopologyFeedback(const WindowTopologyFeedback& feedback);
|
||
|
||
private:
|
||
WindowState m_state = {};
|
||
};
|
||
```
|
||
|
||
约束：
|
||
|
||
- `WindowSession` 是单窗口真状态唯一可写者。
|
||
- 外部只能拿 snapshot，不能直接改字段。
|
||
- chrome、input、lifecycle、frame 都通过 reducer 更新，不允许 controller 私改。
|
||
|
||
### `WindowTopologyService`
|
||
|
||
```cpp
|
||
class WindowTopologyService final {
|
||
public:
|
||
const WindowTopologyState& Snapshot() const;
|
||
|
||
TopologyResult ApplyIntent(
|
||
WindowId sourceWindowId,
|
||
const WindowIntent& intent,
|
||
const WindowTopologySnapshot& snapshot);
|
||
|
||
void OnWindowClosed(WindowId windowId);
|
||
void OnWindowCreated(WindowId windowId, WindowRole role);
|
||
|
||
private:
|
||
WindowTopologyState m_state = {};
|
||
};
|
||
```
|
||
|
||
约束：
|
||
|
||
- 所有跨窗口事务统一进这里。
|
||
- 不允许在别处直接增删 `workspaceWindowIds` / `utilityWindowIds`。
|
||
- global tab drag 只能由它维护完整会话状态。
|
||
|
||
### `FrameScheduler`
|
||
|
||
```cpp
|
||
class FrameScheduler final {
|
||
public:
|
||
void RequestFrame(WindowId windowId, FramePriority priority, FrameReason reason);
|
||
bool HasPendingFrame() const;
|
||
FrameBatch DequeueReadyBatch(const WindowSessionStore& sessions);
|
||
void NotifyFramePresented(WindowId windowId, std::uint64_t frameSerial);
|
||
};
|
||
```
|
||
|
||
约束：
|
||
|
||
- 只有 `FrameScheduler` 可以决定某一帧何时真正执行。
|
||
- `WM_PAINT`、`WM_SIZE`、`WM_DPICHANGED` 只产生请求，不直接 render。
|
||
- steady frame / immediate frame 不再是两条链，而是一个调度器内的不同优先级。
|
||
|
||
### `FrameScheduler` 帧事务模型
|
||
|
||
单帧事务顺序必须固定，不允许实现时自由发挥。标准顺序定义为：
|
||
|
||
1. drain window events
|
||
2. merge frame requests
|
||
3. build `WindowContentInput`
|
||
4. update content hosts
|
||
5. submit topology intents / effect intents
|
||
6. finalize render plan
|
||
7. execute render subpasses / viewport work
|
||
8. present
|
||
9. publish `FramePresented` / frame feedback
|
||
10. validate paint / clear frame debt / decide requeue
|
||
|
||
必须同时定义以下语义：
|
||
|
||
- `WM_PAINT` 只产生 `FrameReason::PaintValidation`
|
||
- `WM_SIZE` 只产生 `FrameReason::Resize`
|
||
- `WM_DPICHANGED` 只产生 `FrameReason::DpiChange`
|
||
- steady tick 只产生 `FrameReason::SteadyTick`
|
||
- global tab drag / capture 恢复只产生显式 interaction continuation reason
|
||
|
||
优先级规则必须显式写死：
|
||
|
||
- `DpiChange` = `Critical`
|
||
- `Resize` = `High`
|
||
- `PaintValidation` = `High`
|
||
- `InteractionContinuation` = `High`
|
||
- `SteadyTick` = `Normal`
|
||
|
||
旧语义替代关系必须明确：
|
||
|
||
- `DriveFrame` -> steady tick frame request
|
||
- `DriveImmediateFrame` -> high/critical priority frame request
|
||
- `RequestSkipNextSteadyStateFrame` -> scheduler suppression rule
|
||
- queued completed immediate frame -> scheduler-owned post-present topology transaction queue
|
||
|
||
### `IWindowContentHost`
|
||
|
||
```cpp
|
||
class IWindowContentHost {
|
||
public:
|
||
virtual ~IWindowContentHost() = default;
|
||
virtual void Initialize(const WindowContentHostInitContext&) = 0;
|
||
virtual WindowContentOutput Update(const WindowContentInput&) = 0;
|
||
virtual void RenderSubpasses(const WindowRenderSubpassContext&) = 0;
|
||
virtual void Shutdown() = 0;
|
||
};
|
||
```
|
||
|
||
约束：
|
||
|
||
- 内容层统一返回 `WindowContentOutput`。
|
||
- 应用层不再 `TryGet*Binding`。
|
||
- 内容层如果需要表达 cursor、capture、detach、utility window、title bar mode，都在 output 中显式返回。
|
||
|
||
### `Win32WindowProcAdapter`
|
||
|
||
```cpp
|
||
class Win32WindowProcAdapter final {
|
||
public:
|
||
std::optional<WindowEvent> Translate(
|
||
HWND hwnd,
|
||
UINT message,
|
||
WPARAM wParam,
|
||
LPARAM lParam) const;
|
||
};
|
||
```
|
||
|
||
约束：
|
||
|
||
- 只做消息翻译，不做业务分支。
|
||
- 不调用 workspace coordinator。
|
||
- 不调用 utility coordinator。
|
||
- 不调用 render / present。
|
||
|
||
---
|
||
|
||
## 7. 旧模块到新模块的映射
|
||
|
||
| 现有模块 | 目标归宿 | 最终命运 |
|
||
| --- | --- | --- |
|
||
| `EditorWindow` | `WindowSession` + 轻量 native facade | 大幅收缩或删除 |
|
||
| `EditorWindowManager` | `WindowSessionStore` + `WindowTopologyService` + `FrameScheduler` | 删除 |
|
||
| `EditorWindowHostRuntime` | `WindowSessionStore` + `Win32WindowBackend` | 删除 |
|
||
| `EditorWindowMessageDispatcher` | `Win32WindowProcAdapter` | 删除 |
|
||
| `EditorWindowLifecycleCoordinator` | `WindowSession` + topology service | 删除 |
|
||
| `EditorWindowWorkspaceCoordinator` | `WindowTopologyService` | 删除 |
|
||
| `EditorUtilityWindowCoordinator` | `WindowTopologyService` | 删除 |
|
||
| `EditorWindowFrameDriver` | `FrameScheduler` | 删除 |
|
||
| `EditorWindowRuntimeController` | `D3D12WindowRenderHost` + content host bridge | 拆分后删除旧形态 |
|
||
| `EditorWorkspaceWindowContentController` | `WorkspaceContentHost` | 替换 |
|
||
| `EditorUtilityWindowContentController` | `UtilityContentHost` | 替换 |
|
||
| `EditorWindowTransferRequests` | `WindowIntent / WindowCommand / WindowEffect` | 删除 |
|
||
| `TryGet*Binding` 链 | `WindowContentOutput` | 删除 |
|
||
|
||
## 7.1 最终顶层编排者
|
||
|
||
最终必须引入新的顶层运行时，建议命名：
|
||
|
||
- `WindowApplicationRuntime`
|
||
|
||
它的职责只能是：
|
||
|
||
- 持有 `WindowSessionStore`
|
||
- 持有 `WindowTopologyService`
|
||
- 持有 `FrameScheduler`
|
||
- 持有 content host factory
|
||
- 持有 `Win32WindowBackend`
|
||
- 持有 `Win32WindowProjector`
|
||
- 持有 `D3D12WindowRenderHost` registry
|
||
- 驱动主循环调度
|
||
|
||
它明确禁止做的事：
|
||
|
||
- 不新增业务可写状态真相
|
||
- 不直接执行 Win32 API
|
||
- 不直接做 workspace 事务
|
||
- 不把 topology / session / frame 规则塞回 `Application`
|
||
|
||
`Application` 最终只保留：
|
||
|
||
- 进程级初始化
|
||
- crash / log / DPI bootstrap
|
||
- 创建 `WindowApplicationRuntime`
|
||
- 调用 runtime run / shutdown
|
||
|
||
---
|
||
|
||
## 8. 目录重组建议
|
||
|
||
建议新增目录：
|
||
|
||
```text
|
||
new_editor/app/Windowing/Domain/
|
||
new_editor/app/Windowing/Application/
|
||
new_editor/app/Windowing/Content/
|
||
new_editor/app/Platform/Win32/Adapter/
|
||
new_editor/app/Platform/Win32/Backend/
|
||
new_editor/app/Platform/Win32/Projection/
|
||
new_editor/app/Platform/Win32/Rendering/
|
||
```
|
||
|
||
旧目录的处理策略：
|
||
|
||
- `Platform/Win32/Windowing`
|
||
先收缩为迁移桥，最终清空或仅保留少量 native glue
|
||
- `Platform/Win32/Runtime`
|
||
D3D12 相关迁出后删除旧 driver / controller
|
||
- `Platform/Win32/Content`
|
||
迁入 `Windowing/Content`
|
||
- `Platform/Win32/Chrome`
|
||
仅保留纯 helper，删除 stateful controller
|
||
|
||
## 8.1 依赖与边界规则
|
||
|
||
重构过程中必须同时执行“依赖收口”，否则类名换了，旧问题会原样复活。
|
||
|
||
### 允许的依赖方向
|
||
|
||
```text
|
||
Domain <- Application <- Content
|
||
<- Platform Projection
|
||
Platform Backend 只被 Application/Projection 调用
|
||
Rendering Host 只被 FrameScheduler/Render Pipeline 调用
|
||
```
|
||
|
||
### 明确禁止的依赖
|
||
|
||
1. `Windowing/Domain` 禁止包含 `windows.h`、D3D12、swapchain、renderer 头文件。
|
||
2. `Windowing/Application` 禁止直接调用 `CreateWindowExW`、`SetWindowPos`、`SetCapture`、`Present`。
|
||
3. `Windowing/Content` 禁止感知 `HWND`、`RECT`、`POINT`、`WPARAM`、`LPARAM`。
|
||
4. `Platform/Win32/Adapter` 禁止包含 workspace 事务逻辑。
|
||
5. `Platform/Win32/Backend` 禁止读取 workspace/session/content 模型。
|
||
6. `WindowTopologyService` 之外禁止直接维护 global tab drag 会话。
|
||
7. `FrameScheduler` 之外禁止新增任何“临时立即帧”入口。
|
||
8. `EditorContext` 之外的全局单例禁止继续扩散；新增全局能力必须先证明不是 per-window。
|
||
|
||
### include 审核规则
|
||
|
||
审核员在代码审查时必须额外检查：
|
||
|
||
- 新建 domain 头文件是否仍然引用 Win32 类型。
|
||
- 新建 content host 是否仍然暴露 binding 探测接口。
|
||
- 新建 platform 代码是否偷偷包含 `UIEditorWorkspaceController`。
|
||
- 任何新类是否再次通过 `friend` 穿透 `WindowSession`。
|
||
|
||
## 8.2 迁移期间的反腐层规则
|
||
|
||
迁移不是一口气删光旧代码，而是分期替换。但桥接层必须受限，否则过渡层会永久化。
|
||
|
||
### 允许存在的临时桥
|
||
|
||
1. `EditorWindowManager`
|
||
只允许暂时作为启动入口和 legacy facade。
|
||
2. `EditorWindow`
|
||
过渡期允许保留，但只能逐步退化为：
|
||
- `windowId`
|
||
- native handle facade
|
||
- 指向 `WindowSession` / backend 的轻量桥
|
||
3. `EditorWindowRuntimeController`
|
||
只允许短期作为 `content host + render host` 的组合桥，后续必须拆解。
|
||
4. `EditorWindowMessageDispatcher`
|
||
只允许短期 forward 到 `Win32WindowProcAdapter`，不能继续长逻辑。
|
||
|
||
所有临时桥都必须同时满足以下硬约束：
|
||
|
||
1. 只允许做机械转发或数据形状适配。
|
||
2. 不允许持有业务可写状态。
|
||
3. 不允许做条件分支决策。
|
||
4. 不允许生成新的业务语义。
|
||
5. 不允许吞掉 effect、intent、错误或反馈。
|
||
6. 必须在计划中绑定删除阶段和删除条件。
|
||
7. 做不到以上约束的桥，不允许“先留着”，必须在当前阶段直接拆掉。
|
||
|
||
### 迁移期明确禁止
|
||
|
||
1. 禁止新增任何新的 `friend class`。
|
||
2. 禁止给 `EditorWindowFrameTransferRequests` 再加字段。
|
||
3. 禁止新增新的 `TryGet*Binding`。
|
||
4. 禁止在 `WM_*` 路径里新增 render / present / workspace 事务代码。
|
||
5. 禁止在旧 coordinator 中继续沉积新业务。
|
||
6. 禁止从 live windows 再推导新的“临时全局状态”。
|
||
|
||
### 判断一个桥是否可以删除的标准
|
||
|
||
同时满足以下条件时，桥必须进入删除阶段：
|
||
|
||
1. 新结构已经有等价状态对象。
|
||
2. 新结构已经有等价命令或 effect。
|
||
3. 旧桥只剩转发，不再做决策。
|
||
4. 已有回归覆盖该路径。
|
||
|
||
## 9.0 所有阶段通用门禁
|
||
|
||
下面这些门禁不是某一阶段独有，而是从 Phase 1 开始到 Phase 8 都必须成立：
|
||
|
||
1. 本阶段新增桥接层只能是机械转发 adapter，不能业务化。
|
||
2. 任何单窗口状态在同一时刻只能有一个可写源。
|
||
3. 任何跨窗口状态在同一时刻只能有一个可写源。
|
||
4. 新增类型不得把 Win32 类型重新包装后带回 domain / application。
|
||
5. 没有对应测试门禁和回归命令的结构，不允许宣称阶段完成。
|
||
|
||
---
|
||
|
||
## 9. 分阶段执行方案
|
||
|
||
## Phase 0：基线冻结与护栏建立
|
||
|
||
### 目标
|
||
|
||
在动架构前冻结当前行为基线。
|
||
|
||
### 工作项
|
||
|
||
1. 记录旧系统关键链路：
|
||
- 建窗
|
||
- 关闭
|
||
- steady frame
|
||
- immediate frame
|
||
- resize
|
||
- dpi change
|
||
- utility window open / reuse
|
||
- panel detach
|
||
- global tab drag
|
||
2. 补最小回归清单。
|
||
3. 建立 trace / log 基线。
|
||
4. 标记本计划的阶段门禁。
|
||
|
||
### 退出条件
|
||
|
||
- 关键行为已文档化。
|
||
- 有最小回归检查项。
|
||
- 已定义测试 target 规划、fake 对象职责和阶段门禁命令。
|
||
- 评论区已登记 Phase 0 启动记录。
|
||
|
||
## Phase 1：新协议落地
|
||
|
||
### 目标
|
||
|
||
先引入新的 domain 抽象，不替换旧主链。
|
||
|
||
### 工作项
|
||
|
||
1. 新增 `WindowState`、`WindowTopologyState`、`WindowEvent`、`WindowIntent`、`WindowEffect`。
|
||
2. 新增 `WindowContentInput`、`WindowContentOutput`。
|
||
3. 新增纯 reducer 雏形：
|
||
- lifecycle
|
||
- input
|
||
- chrome
|
||
4. 保持旧主链不动。
|
||
|
||
### 退出条件
|
||
|
||
- 新类型不依赖 Win32 类型。
|
||
- 新类型足以表达旧主链中的关键意图。
|
||
- 已把 `window_session_tests`、`window_topology_tests`、`frame_scheduler_tests`、`win32_message_translator_tests`
|
||
纳入 CMake 目标规划与目录规划。
|
||
|
||
## Phase 2：单窗口状态迁入 `WindowSession`
|
||
|
||
### 目标
|
||
|
||
解决最底层的状态 ownership 问题。
|
||
|
||
### 工作项
|
||
|
||
1. 创建 `WindowSession`。
|
||
2. 把单窗口状态迁入 `WindowSession`。
|
||
3. `EditorWindow` 退化为兼容外壳。
|
||
4. 开始消灭外部对 `EditorWindow` 内部状态的直接访问。
|
||
|
||
### 退出条件
|
||
|
||
- 单窗口真状态只在 `WindowSession` 或其 reducer 中可写。
|
||
- 旧 `EditorWindow` / `EditorWindowInputController` / `EditorWindowChromeController`
|
||
不能再持有独立业务状态真相。
|
||
- 不允许存在新旧双写路径。
|
||
- `EditorWindow` 不再是共享可变状态包。
|
||
|
||
## Phase 3：消息路径改造
|
||
|
||
### 目标
|
||
|
||
把 `WndProc` 路径变成纯事件适配。
|
||
|
||
### 工作项
|
||
|
||
1. 新建 `Win32WindowProcAdapter`。
|
||
2. 所有 `WM_*` 转成 `WindowEvent`。
|
||
3. 移出消息路径中的：
|
||
- render / present
|
||
- workspace 事务
|
||
- utility window 打开
|
||
- chrome 直接 effect
|
||
|
||
### 退出条件
|
||
|
||
- `WndProc` 中不再直接调用渲染入口。
|
||
|
||
## Phase 4：统一帧调度
|
||
|
||
### 目标
|
||
|
||
消灭稳态帧与即时帧的双轨结构。
|
||
|
||
### 工作项
|
||
|
||
1. 建立 `FrameScheduler`。
|
||
2. 消息路径只登记帧请求。
|
||
3. 稳态帧和优先帧统一调度。
|
||
4. 定义完整 frame lifecycle、`FrameReason` 和 `FramePriority`。
|
||
5. 删除 `DriveImmediateFrame` 思维模式。
|
||
|
||
### 退出条件
|
||
|
||
- 没有消息路径直接 render / present。
|
||
- `FrameScheduler` 生命周期顺序、reason 映射、priority 映射、失败/跳帧规则已落成文档并对应旧语义。
|
||
- 不再需要 queued completed immediate frame 补偿逻辑。
|
||
|
||
## Phase 5：内容层协议替换
|
||
|
||
### 目标
|
||
|
||
删除 binding 探测链。
|
||
|
||
### 工作项
|
||
|
||
1. 建立 `IWindowContentHost`。
|
||
2. 实现 `WorkspaceContentHost`。
|
||
3. 实现 `UtilityContentHost`。
|
||
4. 让内容层统一返回 `WindowContentOutput`。
|
||
5. 删除 `TryGet*Binding` 链。
|
||
|
||
### 退出条件
|
||
|
||
- 应用层不再感知内容层内部的 binding 形状。
|
||
|
||
## Phase 6：拓扑服务落地
|
||
|
||
### 目标
|
||
|
||
建立显式 `WindowTopologyState`。
|
||
|
||
### 工作项
|
||
|
||
1. 建立 `WindowTopologyService`。
|
||
2. 迁移：
|
||
- primary / active window
|
||
- panel detach
|
||
- cross-window drop
|
||
- global tab drag
|
||
- utility window 管理
|
||
3. 停止从 live windows 反推业务 window set。
|
||
|
||
### 退出条件
|
||
|
||
- 系统里只有一个跨窗口拓扑状态源。
|
||
- `WindowTopologyState` 已显式保存 window projection / workspace projection / session snapshot / 事务快照。
|
||
- `BuildLiveWindowWorkspaceSet(...)` 不再承担业务真相恢复职责。
|
||
|
||
## Phase 7：平台投影与后端收口
|
||
|
||
### 目标
|
||
|
||
把 Win32 / D3D12 执行逻辑从业务决策中彻底剥离。
|
||
|
||
### 工作项
|
||
|
||
1. 新建 `WindowApplicationRuntime`。
|
||
1. 新建 `Win32WindowBackend`。
|
||
2. 新建 `Win32WindowProjector`。
|
||
3. 新建 `D3D12WindowRenderHost`。
|
||
4. 把 `Application` 收缩为 bootstrap，主循环调度迁给 `WindowApplicationRuntime`。
|
||
5. 所有 Win32 effect 都通过 backend 执行。
|
||
|
||
### 退出条件
|
||
|
||
- `EditorWindowManager` 删除后的顶层调用链已经明确落到 `WindowApplicationRuntime`。
|
||
- 应用层不再直接调用 Win32 API。
|
||
- 会话层不再直接持有 D3D12 业务控制职责。
|
||
|
||
## Phase 8：删除旧结构与最终清理
|
||
|
||
### 目标
|
||
|
||
删掉所有旧桥、旧接口、旧控制器。
|
||
|
||
### 工作项
|
||
|
||
1. 删除旧 coordinator / driver / dispatcher / transfer request。
|
||
2. 删除旧 binding 探测链。
|
||
3. 收缩 `EditorContext`。
|
||
4. 清理 include 方向和目录结构。
|
||
|
||
### 退出条件
|
||
|
||
- 本计划第 3 节的硬约束全部满足。
|
||
|
||
## 9.1 文件级实施矩阵
|
||
|
||
这一节是执行时的真正落地清单。阶段说明解决“做什么”，这一节解决“先动哪些文件、怎么桥接、删哪些旧件”。
|
||
|
||
### Phase 0 文件级动作
|
||
|
||
目标：冻结现状，不改行为。
|
||
|
||
重点读取与建档文件：
|
||
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindow.h/.cpp`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowMessageDispatcher.cpp`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowHostRuntime.cpp`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowWorkspaceCoordinator.cpp`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorUtilityWindowCoordinator.cpp`
|
||
- `new_editor/app/Platform/Win32/Runtime/EditorWindowFrameDriver.cpp`
|
||
- `new_editor/app/Platform/Win32/Runtime/EditorWindowRuntimeController.h/.cpp`
|
||
- `new_editor/app/Platform/Win32/Chrome/EditorWindowChromeController.h/.cpp`
|
||
|
||
必须沉淀的基线：
|
||
|
||
- 消息到渲染路径时序图
|
||
- steady frame 时序图
|
||
- immediate frame 时序图
|
||
- global tab drag 时序图
|
||
- detach panel -> 新窗口创建时序图
|
||
- utility window open / reuse 时序图
|
||
|
||
审核检查点：
|
||
|
||
- 文档是否覆盖所有 `WM_*` 关键路径
|
||
- 是否识别了所有 direct Win32 API 调用点
|
||
- 是否列出当前 transfer request 生产者和消费者
|
||
|
||
### Phase 1 文件级动作
|
||
|
||
目标：先落地新协议，不改主行为。
|
||
|
||
新增文件建议：
|
||
|
||
- `new_editor/app/Windowing/Domain/WindowId.h`
|
||
- `new_editor/app/Windowing/Domain/WindowKind.h`
|
||
- `new_editor/app/Windowing/Domain/WindowState.h`
|
||
- `new_editor/app/Windowing/Domain/WindowTopologyState.h`
|
||
- `new_editor/app/Windowing/Domain/WindowEvent.h`
|
||
- `new_editor/app/Windowing/Domain/WindowIntent.h`
|
||
- `new_editor/app/Windowing/Domain/WindowCommand.h`
|
||
- `new_editor/app/Windowing/Domain/WindowEffect.h`
|
||
- `new_editor/app/Windowing/Domain/WindowContentInput.h`
|
||
- `new_editor/app/Windowing/Domain/WindowContentOutput.h`
|
||
- `new_editor/app/Windowing/Domain/FramePriority.h`
|
||
|
||
新增 reducer 建议：
|
||
|
||
- `new_editor/app/Windowing/Application/Reducers/WindowLifecycleReducer.*`
|
||
- `new_editor/app/Windowing/Application/Reducers/WindowInputReducer.*`
|
||
- `new_editor/app/Windowing/Application/Reducers/WindowChromeReducer.*`
|
||
|
||
桥接策略：
|
||
|
||
- 旧 `EditorWindow` 继续跑，但开始把内部可见状态映射到新的 `WindowState` 草案。
|
||
- 新 domain 类型只作为纯类型定义，不接管现网行为。
|
||
|
||
本阶段不能做的事：
|
||
|
||
- 不能让新 domain 类型依赖 `windows.h`
|
||
- 不能在新协议里出现 `HWND`
|
||
- 不能为了兼容旧代码把 Win32 类型偷偷包一层再塞回 domain
|
||
|
||
### Phase 2 文件级动作
|
||
|
||
目标：把单窗口真状态收回到 `WindowSession`。
|
||
|
||
新增文件建议：
|
||
|
||
- `new_editor/app/Windowing/Application/WindowSession.h`
|
||
- `new_editor/app/Windowing/Application/WindowSession.cpp`
|
||
- `new_editor/app/Windowing/Application/WindowSessionStore.h`
|
||
- `new_editor/app/Windowing/Application/WindowSessionStore.cpp`
|
||
- `new_editor/app/Windowing/Application/WindowSessionResult.h`
|
||
|
||
优先迁移状态来源：
|
||
|
||
1. `EditorWindowState.h`
|
||
2. `EditorWindowInputController`
|
||
3. `EditorWindowChromeController`
|
||
4. `EditorWindow` 中与 resize / dpi / queued immediate frame 相关的状态
|
||
|
||
具体做法：
|
||
|
||
- 先把当前 scattered state 建成 `WindowState` 快照字段，不立即删旧控制器。
|
||
- 让 `EditorWindow` 只通过 `WindowSession` 读写窗口状态。
|
||
- 外部模块改成读取 `WindowSession::Snapshot()`，不再读 `EditorWindow` 私有成员。
|
||
- 旧 controller 如果暂时还存在，只允许退化为无状态 helper，不允许继续做独立状态持有者。
|
||
|
||
必须优先清掉的穿透点：
|
||
|
||
- `EditorWindow.h` 中的 `friend class` 链
|
||
- `EditorWindowMessageDispatcher` 对 `m_inputController` / `m_chromeController` / `m_runtime` 的直接访问
|
||
- `EditorWindowFrameDriver` 对 `window.m_chromeController` 的直接访问
|
||
|
||
阶段验收：
|
||
|
||
- 所有单窗口状态写入都只经由 `WindowSession` 或 reducer
|
||
- `EditorWindow` 不再是唯一可写状态袋
|
||
- 不存在旧 controller 与 `WindowSession` 双写
|
||
- `friend class` 不再承担状态穿透写入入口
|
||
|
||
### Phase 3 文件级动作
|
||
|
||
目标：把消息路径收口成纯适配层。
|
||
|
||
新增文件建议：
|
||
|
||
- `new_editor/app/Platform/Win32/Adapter/Win32WindowProcAdapter.h`
|
||
- `new_editor/app/Platform/Win32/Adapter/Win32WindowProcAdapter.cpp`
|
||
- `new_editor/app/Platform/Win32/Adapter/Win32MessageTranslator.*`
|
||
|
||
旧文件处理：
|
||
|
||
- `EditorWindowMessageDispatcher.cpp` 第一阶段变薄，只保留：
|
||
- `HWND -> WindowId` 查找
|
||
- 调用 `Win32WindowProcAdapter`
|
||
- 把事件送给 `WindowSession`
|
||
- 后续删除 `EditorWindowMessageDispatcher.*`
|
||
|
||
需要迁出的逻辑：
|
||
|
||
- `WM_SIZE` 内直接 immediate frame
|
||
- `WM_DPICHANGED` 内直接 render
|
||
- `WM_PAINT` 内直接 `OnPaintMessage`
|
||
- `WM_CLOSE` 中对生命周期的复杂编排
|
||
- `WM_MOUSE*` 中直接 global tab drag / chrome action 决策
|
||
|
||
阶段验收：
|
||
|
||
- `WndProc` 中只剩翻译和转发
|
||
- 业务层收到的是 `WindowEvent`，不是 `WM_*`
|
||
|
||
### Phase 4 文件级动作
|
||
|
||
目标：建立统一帧调度器。
|
||
|
||
新增文件建议：
|
||
|
||
- `new_editor/app/Windowing/Application/FrameScheduler.h`
|
||
- `new_editor/app/Windowing/Application/FrameScheduler.cpp`
|
||
- `new_editor/app/Windowing/Application/FrameRequestQueue.h`
|
||
- `new_editor/app/Windowing/Application/FrameRequestQueue.cpp`
|
||
|
||
旧文件收缩：
|
||
|
||
- `Runtime/EditorWindowFrameDriver.*` 先转成 scheduler 内部 helper，再删除
|
||
- `EditorWindowHostRuntime::RenderAllWindows(...)` 改为委托 `FrameScheduler`
|
||
|
||
关键迁移动作：
|
||
|
||
- 把 `DriveFrame` / `DriveImmediateFrame` 收束成统一请求模型
|
||
- 把 `RequestSkipNextSteadyStateFrame` 这种补丁语义转为显式调度规则
|
||
- 把 `HasQueuedCompletedImmediateFrame` / `ConsumeQueuedCompletedImmediateFrameTransferRequests`
|
||
转换为 scheduler 完成回调或拓扑事务队列
|
||
- 把 frame transaction 顺序固定到：
|
||
event drain -> request merge -> content update -> topology submit -> render -> present -> feedback -> paint validation
|
||
- 为 `WM_PAINT` / `WM_SIZE` / `WM_DPICHANGED` 建立明确的 `FrameReason` / `FramePriority` 映射
|
||
|
||
阶段验收：
|
||
|
||
- steady frame / immediate frame 共享同一套调度实体
|
||
- 新代码里不存在“为了某个消息直接 present 一帧”的入口
|
||
|
||
### Phase 5 文件级动作
|
||
|
||
目标：把内容层从 binding 探测链改成正式输出协议。
|
||
|
||
新增文件建议：
|
||
|
||
- `new_editor/app/Windowing/Content/IWindowContentHost.h`
|
||
- `new_editor/app/Windowing/Content/WorkspaceContentHost.h`
|
||
- `new_editor/app/Windowing/Content/WorkspaceContentHost.cpp`
|
||
- `new_editor/app/Windowing/Content/UtilityContentHost.h`
|
||
- `new_editor/app/Windowing/Content/UtilityContentHost.cpp`
|
||
|
||
重点改造旧文件：
|
||
|
||
- `Platform/Win32/Content/EditorWindowContentController.h`
|
||
- `Platform/Win32/Content/EditorWorkspaceWindowContentController.*`
|
||
- `Platform/Win32/Content/EditorUtilityWindowContentController.*`
|
||
|
||
替换策略：
|
||
|
||
1. 先让旧 content controller 内部构造 `WindowContentOutput`
|
||
2. 再让应用层只消费 output，不再 `TryGet*Binding`
|
||
3. 等应用层不再 probe binding 后，删除 binding 接口
|
||
|
||
必须退出主干的接口：
|
||
|
||
- `TryGetWorkspaceBinding`
|
||
- `TryGetDockHostBinding`
|
||
- `TryGetInputFeedbackBinding`
|
||
- `TryGetTitleBarBinding`
|
||
- `EditorWindowFrameTransferRequests`
|
||
|
||
阶段验收：
|
||
|
||
- 内容层对外只暴露一个宿主接口
|
||
- cursor / capture / title / utility / detach 等信号都能通过 output 表达
|
||
|
||
### Phase 6 文件级动作
|
||
|
||
目标：建立显式拓扑状态源。
|
||
|
||
新增文件建议：
|
||
|
||
- `new_editor/app/Windowing/Application/WindowTopologyService.h`
|
||
- `new_editor/app/Windowing/Application/WindowTopologyService.cpp`
|
||
- `new_editor/app/Windowing/Application/WindowTopologyResult.h`
|
||
- `new_editor/app/Windowing/Application/WindowTopologySnapshot.h`
|
||
|
||
优先迁移旧文件职责：
|
||
|
||
- `Windowing/EditorWindowWorkspaceCoordinator.*`
|
||
- `Windowing/EditorUtilityWindowCoordinator.*`
|
||
|
||
必须先抽离的事务：
|
||
|
||
- active / primary window 管理
|
||
- global tab drag 会话
|
||
- panel detach -> 新窗口创建
|
||
- cross-window drop
|
||
- utility window open / reuse / focus
|
||
|
||
核心要求：
|
||
|
||
- `BuildLiveWindowWorkspaceSet(...)` 只能作为短期兼容代码，最终删除
|
||
- topology state 必须显式保存，而不是运行时临时拼装
|
||
- topology state 必须持有按 `windowId` 建立的权威 workspace projection / session snapshot
|
||
|
||
阶段验收：
|
||
|
||
- 任何跨窗口行为都能从 `WindowTopologyState` 解释
|
||
- 不再需要从 live windows 反推出唯一真相
|
||
|
||
### Phase 7 文件级动作
|
||
|
||
目标：把平台执行层和业务决策彻底分开。
|
||
|
||
新增文件建议：
|
||
|
||
- `new_editor/app/Windowing/Application/WindowApplicationRuntime.h`
|
||
- `new_editor/app/Windowing/Application/WindowApplicationRuntime.cpp`
|
||
- `new_editor/app/Platform/Win32/Backend/Win32WindowBackend.h`
|
||
- `new_editor/app/Platform/Win32/Backend/Win32WindowBackend.cpp`
|
||
- `new_editor/app/Platform/Win32/Projection/Win32WindowProjector.h`
|
||
- `new_editor/app/Platform/Win32/Projection/Win32WindowProjector.cpp`
|
||
- `new_editor/app/Platform/Win32/Rendering/D3D12WindowRenderHost.h`
|
||
- `new_editor/app/Platform/Win32/Rendering/D3D12WindowRenderHost.cpp`
|
||
|
||
迁移来源：
|
||
|
||
- `EditorWindowHostRuntime.cpp` 中的 Win32 建窗、ShowWindow、UpdateWindow
|
||
- `EditorWindowWorkspaceCoordinator.cpp` 中的 `SetWindowTextW`
|
||
- `EditorWindowChromeController.cpp` 中的窗口移动/缩放/最大化相关 Win32 调用
|
||
- `EditorWindowRuntimeController.*` 中的渲染宿主职责
|
||
|
||
投影规则：
|
||
|
||
- `WindowApplicationRuntime` 只做依赖组装和主循环调度
|
||
- `WindowSession` / `WindowTopologyService` 只产生命令和 effect
|
||
- `Win32WindowProjector` 把状态变化映射成 effect 列表
|
||
- `Win32WindowBackend` 执行 effect
|
||
- `D3D12WindowRenderHost` 只执行渲染宿主职责
|
||
|
||
阶段验收：
|
||
|
||
- 应用层不直接包含 Win32 行为代码
|
||
- render host 不直接承担内容决策
|
||
|
||
### Phase 8 文件级动作
|
||
|
||
目标：删掉旧骨架，只保留新主干。
|
||
|
||
计划删除的旧文件范围：
|
||
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowManager.*`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowHostRuntime.*`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowMessageDispatcher.*`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowLifecycleCoordinator.*`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowWorkspaceCoordinator.*`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorUtilityWindowCoordinator.*`
|
||
- `new_editor/app/Platform/Win32/Runtime/EditorWindowFrameDriver.*`
|
||
- `new_editor/app/Platform/Win32/Windowing/EditorWindowTransferRequests.h`
|
||
|
||
高风险清理项：
|
||
|
||
- `EditorContext` 中所有 per-window capability
|
||
- 旧 chrome controller 中残留的状态机
|
||
- 所有 `TryGet*Binding` 调用点
|
||
- 所有 `friend class` 穿透
|
||
|
||
最终收口标准：
|
||
|
||
- 旧桥只剩零或极薄 facade
|
||
- include 方向符合第 8.1 节规则
|
||
- 代码库中查不到 transfer request 和 binding probe 主干调用
|
||
|
||
---
|
||
|
||
## 10. `EditorContext` 重构要求
|
||
|
||
当前 `EditorContext` 必须被收缩，只保留全局状态和全局服务。
|
||
|
||
### 可以继续保留在全局中的内容
|
||
|
||
- shell asset
|
||
- selection service
|
||
- command focus service
|
||
- project runtime
|
||
- scene runtime
|
||
- system interaction host
|
||
- session store
|
||
|
||
### 必须移出的内容
|
||
|
||
- per-window text measurer
|
||
- per-window render host
|
||
- per-window capture / presentation capability
|
||
- 任何依赖“当前窗口实例”的局部能力
|
||
|
||
建议拆分为：
|
||
|
||
- `EditorAppContext`
|
||
- `EditorSessionStore`
|
||
- per-window capability context
|
||
|
||
---
|
||
|
||
## 11. 测试策略
|
||
|
||
## 11.1 测试 target 与目录规划
|
||
|
||
必须落成以下 target 规划：
|
||
|
||
- `window_session_tests`
|
||
- `window_topology_tests`
|
||
- `frame_scheduler_tests`
|
||
- `win32_message_translator_tests`
|
||
- `new_editor_windowing_tests` 作为聚合 target
|
||
|
||
建议目录：
|
||
|
||
- `new_editor/tests/windowing/window_session/`
|
||
- `new_editor/tests/windowing/window_topology/`
|
||
- `new_editor/tests/windowing/frame_scheduler/`
|
||
- `new_editor/tests/platform/win32_message_translator/`
|
||
|
||
## 11.2 fake 组件要求
|
||
|
||
为保证这些测试不是空壳，必须同时定义：
|
||
|
||
- `FakeWindowBackend`
|
||
- 记录 effect 执行顺序，不实际调用 Win32
|
||
- `FakeRenderHost`
|
||
- 记录 resize / render / present / feedback 顺序
|
||
- `FakeContentHost`
|
||
- 可配置输出 `WindowContentOutput`
|
||
- `FakeTopologyObserver` 或 `FakeTopologySink`
|
||
- 校验 topology transaction 提交顺序
|
||
- `FakeFrameClock`
|
||
- 控制 steady tick / priority frame 时序
|
||
|
||
## 11.3 阶段门禁命令
|
||
|
||
计划执行时必须收口到明确命令，不能只写“补测试”。最低门禁如下：
|
||
|
||
- 编译门禁：
|
||
- `cmake --build build --config Debug --target XCUIEditorApp`
|
||
- 单元测试门禁：
|
||
- `cmake --build build --config Debug --target new_editor_windowing_tests`
|
||
- `ctest --test-dir build --config Debug --output-on-failure -R "window_session|window_topology|frame_scheduler|win32_message_translator"`
|
||
- 启动级冒烟：
|
||
- 启动 `build/new_editor/Debug/XCUIEditor.exe`，确认能稳定启动并进入主循环
|
||
|
||
阶段要求：
|
||
|
||
- Phase 0 结束前必须把这些命令和 target 写进计划。
|
||
- Phase 1 结束前必须把 target scaffold 和 fake 组件接口纳入 CMake 与目录结构。
|
||
- Phase 2 及之后每个阶段结束时，未通过本阶段门禁不得进入下一阶段。
|
||
|
||
### 单元测试
|
||
|
||
必须补：
|
||
|
||
- `WindowSession` 生命周期测试
|
||
- 输入 reducer 测试
|
||
- chrome reducer 测试
|
||
- topology service 拖拽事务测试
|
||
- frame scheduler 优先级测试
|
||
|
||
### 平台适配测试
|
||
|
||
- `Win32WindowProcAdapter`
|
||
- `Win32WindowProjector`
|
||
- `Win32WindowBackend` effect 执行桩
|
||
|
||
### 集成测试
|
||
|
||
至少覆盖：
|
||
|
||
1. 建窗 / 关窗
|
||
2. 主窗口关闭触发全局回收
|
||
3. resize / dpi change 后的帧调度
|
||
4. panel detach -> 新窗口创建
|
||
5. global tab drag -> cross-window drop
|
||
6. utility window open / reuse / focus
|
||
|
||
### 高频回归项
|
||
|
||
每阶段后都要回归：
|
||
|
||
- capture 是否正确
|
||
- chrome hover / press / resize 是否正常
|
||
- resize 时是否抖动或错帧
|
||
- utility window 是否重复创建
|
||
- 跨窗口拖拽是否残留 preview
|
||
- DPI 切换后 cursor / title / size 是否一致
|
||
|
||
---
|
||
|
||
## 12. 风险与控制
|
||
|
||
### 风险 A：新旧状态双写
|
||
|
||
控制：
|
||
|
||
- 每阶段明确唯一可写状态源。
|
||
- 审核员重点检查是否存在双写。
|
||
|
||
### 风险 B：移除即时帧后交互变钝
|
||
|
||
控制：
|
||
|
||
- `FrameScheduler` 必须支持优先帧。
|
||
- resize / paint 恢复链必须做延迟对比。
|
||
|
||
### 风险 C：拓扑迁移时语义漂移
|
||
|
||
控制：
|
||
|
||
- 先冻结旧行为。
|
||
- 每个事务都要有明确测试和日志。
|
||
|
||
### 风险 D：`EditorContext` 收缩影响外围模块
|
||
|
||
控制：
|
||
|
||
- 先加新接口，再迁移调用点。
|
||
- 兼容桥必须有明确删除阶段。
|
||
|
||
---
|
||
|
||
## 13. 完成定义
|
||
|
||
当且仅当以下条件同时满足时，重构完成：
|
||
|
||
1. 新窗口体系不存在 `friend` 穿透状态。
|
||
2. domain / application 中没有 Win32 类型泄漏。
|
||
3. `WndProc` 路径中不存在直接 render / present。
|
||
4. `EditorWindowFrameTransferRequests` 已删除。
|
||
5. `TryGet*Binding` 探测链已删除。
|
||
6. `WindowTopologyService` 是唯一跨窗口状态源。
|
||
7. `EditorContext` 不再挂载窗口局部能力。
|
||
8. 旧 coordinator / dispatcher / driver 已退出主干。
|
||
9. blocker / major 级审核评论全部关闭。
|
||
|
||
---
|
||
|
||
## 14. 审核评论规则
|
||
|
||
这部分直接作为本计划的附录使用，规则保持简单。
|
||
|
||
### 规则 1：评论必须带阶段和严重度
|
||
|
||
严重度只允许：
|
||
|
||
- `BLOCKER`
|
||
- `MAJOR`
|
||
- `MINOR`
|
||
- `QUESTION`
|
||
|
||
### 规则 2：评论必须有证据
|
||
|
||
证据至少包含一项：
|
||
|
||
- 文件路径
|
||
- 类名 / 函数名
|
||
- 可复现行为
|
||
- 测试或日志
|
||
|
||
没有证据的评论不进入正式台账。
|
||
|
||
### 规则 3：一条评论只打一个核心问题
|
||
|
||
不要把多个无关问题塞进同一条评论。
|
||
|
||
### 规则 4：`BLOCKER` 直接卡阶段
|
||
|
||
有未关闭的 `BLOCKER` 时，不允许进入下一阶段。
|
||
|
||
### 规则 5：`MAJOR` 必须在当前阶段关闭
|
||
|
||
`MAJOR` 不一定立即停工，但当前阶段结束前必须处理完。
|
||
|
||
### 规则 6：执行者必须逐条回复
|
||
|
||
回复至少包含：
|
||
|
||
- 处理动作
|
||
- 证据
|
||
- 当前剩余风险
|
||
|
||
### 规则 7：评论只能追加，不删除历史
|
||
|
||
即使评论被驳回，也要保留记录。
|
||
|
||
### 规则 8：计划变更必须先记评论区
|
||
|
||
如果实施过程中要改阶段目标、改边界、改顺序，必须先在评论区登记“计划变更请求”。
|
||
|
||
---
|
||
|
||
## 15. 评论区
|
||
|
||
### 15.1 使用说明
|
||
|
||
以下评论区用于登记：
|
||
|
||
- 阶段开始
|
||
- 阶段结束
|
||
- 审核员评论
|
||
- 执行者回复
|
||
- 审核结论
|
||
- 计划变更请求
|
||
|
||
### 15.2 状态总览
|
||
|
||
| Phase | Status | Start Date | End Date | Executor Summary | Reviewer Summary |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| Phase 0 | Not Started | | | | |
|
||
| Phase 1 | Not Started | | | | |
|
||
| Phase 2 | Not Started | | | | |
|
||
| Phase 3 | Not Started | | | | |
|
||
| Phase 4 | Not Started | | | | |
|
||
| Phase 5 | Not Started | | | | |
|
||
| Phase 6 | Not Started | | | | |
|
||
| Phase 7 | Not Started | | | | |
|
||
| Phase 8 | Not Started | | | | |
|
||
|
||
### 15.3 评论模板
|
||
|
||
```md
|
||
Comment ID:
|
||
Phase:
|
||
Severity:
|
||
Status: Open
|
||
|
||
Summary:
|
||
|
||
Evidence:
|
||
-
|
||
|
||
Impact:
|
||
|
||
Required Action:
|
||
|
||
Close Condition:
|
||
|
||
Reviewer:
|
||
Date:
|
||
```
|
||
|
||
### 15.4 回复模板
|
||
|
||
```md
|
||
Response To:
|
||
Status: Answered
|
||
Executor:
|
||
Date:
|
||
|
||
Action Taken:
|
||
-
|
||
|
||
Evidence:
|
||
-
|
||
|
||
Residual Risk:
|
||
|
||
Requested Status:
|
||
```
|
||
|
||
### 15.5 计划变更请求模板
|
||
|
||
```md
|
||
Plan Change Request ID:
|
||
Affected Phase:
|
||
Date:
|
||
Executor:
|
||
|
||
Reason:
|
||
|
||
Requested Change:
|
||
|
||
Impact:
|
||
-
|
||
|
||
Rollback Condition:
|
||
```
|
||
|
||
---
|
||
|
||
## 16. 阶段评论记录区
|
||
|
||
## Phase 0
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
_No open comments. 2026-04-23 的 REVIEW-P0-001 ~ REVIEW-P0-006 已吸收到计划正文。_
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 1
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 2
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 3
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 4
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 5
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 6
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 7
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|
||
|
||
---
|
||
|
||
## Phase 8
|
||
|
||
### Start
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Goal:
|
||
- Exit Criteria:
|
||
|
||
### Comments
|
||
|
||
_No comments yet._
|
||
|
||
### End
|
||
|
||
- Date:
|
||
- Executor:
|
||
- Requested Review Decision:
|
||
|
||
### Reviewer Decision
|
||
|
||
- Decision:
|
||
- Reviewer:
|
||
- Notes:
|