From d21f573cc5d3fa0eb9b33e14d6897d595c2f5e53 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Wed, 22 Apr 2026 02:47:26 +0800
Subject: [PATCH] docs(new_editor): archive legacy closure plan

---
 ...itor_ArchitectureClosurePlan_2026-04-22.md | 196 ++++++++++++++++++
 ...gacyD2DClosurePlan_完成归档_2026-04-22.md} |   0
 2 files changed, 196 insertions(+)
 create mode 100644 docs/plan/NewEditor_ArchitectureClosurePlan_2026-04-22.md
 rename docs/{plan/NewEditor_D3D12_LegacyD2DClosurePlan_2026-04-22.md => used/NewEditor_D3D12_LegacyD2DClosurePlan_完成归档_2026-04-22.md} (100%)

diff --git a/docs/plan/NewEditor_ArchitectureClosurePlan_2026-04-22.md b/docs/plan/NewEditor_ArchitectureClosurePlan_2026-04-22.md
new file mode 100644
index 00000000..635e10d4
--- /dev/null
+++ b/docs/plan/NewEditor_ArchitectureClosurePlan_2026-04-22.md
@@ -0,0 +1,196 @@
+# NewEditor Architecture Closure Plan
+
+Date: 2026-04-22
+
+## 1. Objective
+
+彻底收口 `new_editor` 当前仍然残留的旧语义、冗余结构和重复控制面。
+
+这次不是补丁式修正，而是把当前主架构重新收成单一路径：
+
+1. 主窗口 UI 渲染只保留一条 `D3D12` 实例化 primitive pass。
+2. 启动截图策略只保留一个控制源。
+3. `Rendering/Native` 这层已经失效的旧模块边界被移除。
+4. 已确认无用的死代码和错误语义命名被清理。
+
+## 2. Confirmed Root Issues
+
+### 2.1 D3D12 UI renderer still contains a legacy geometry sub-pipeline
+
+当前 `D3D12UiRenderer` 虽然已经是 `D3D12` 主路径，但内部仍然并存两套 UI 几何编译/提交策略：
+
+1. `QuadInstanced`
+2. `LegacyIndexed`
+
+其中绝大多数 UI 命令已经走实例化 primitive 路径，只有少量三角形命令仍然维持整套：
+
+- legacy vertex buffer
+- legacy index buffer
+- legacy pipeline state
+- legacy batch kind
+
+这会导致：
+
+- UI renderer 不是单一路径
+- 缓冲管理、缓存结构、绘制分发继续为旧几何方案付复杂度成本
+- “legacy” 语义真正活着，而不是只有名字没改
+
+### 2.2 Startup auto-capture ownership is split across two layers
+
+当前 startup capture 既在 `EditorWindowScreenshotController::Initialize(...)` 内通过环境变量触发，
+又在 `EditorWindowRuntimeController::Initialize(...)` 内通过
+`autoCaptureOnStartup + env` 触发。
+
+这导致：
+
+- 策略决定权不是单点
+- `autoCaptureOnStartup` 形参不是唯一真实来源
+- 非主窗口也可能被环境变量隐式触发 startup request
+
+### 2.3 Rendering/Native module boundary is obsolete
+
+`app/Rendering/Native/` 目录现在只剩 `AutoScreenshot.*`。
+
+它已经不再承担旧的 native renderer backend 职责，但目录和 include 关系仍然保留旧时代边界。
+
+### 2.4 Confirmed dead code remains in the hot renderer unit
+
+`D3D12UiRenderer.cpp` 里存在已无调用方的辅助函数，说明之前的旧几何阶段没有清理彻底。
+
+## 3. Target End State
+
+完成后应满足：
+
+1. `D3D12UiRenderer` 不再存在 `LegacyIndexed` / `legacy*` 动态几何资源。
+2. 所有 UI draw command 都编译为同一类实例化 primitive 数据。
+3. 渲染时只绑定一套 UI primitive pipeline。
+4. `EditorWindowScreenshotController` 不再自行读取 startup env，也不再拥有策略判断权。
+5. startup capture 是否发生，只由窗口创建策略单点决定。
+6. `Rendering/Native` 目录被清空或完全移除。
+7. 已确认无调用的渲染死代码删除。
+
+## 4. Refactor Strategy
+
+### Phase A. Collapse UI geometry into one primitive pipeline
+
+把当前 UI pass 改成单一实例化 primitive 方案：
+
+- 保留单位 quad carrier vertex/index buffer
+- 删除动态 legacy vertex/index buffer
+- 删除 legacy pipeline state
+- 删除 legacy batch kind
+- 统一 batch 为 instance range + texture + scissor
+
+需要新增的 primitive 能力：
+
+- 现有 rect / outline / circle / text / image / gradient
+- 新增 triangle primitive，让 `FilledTriangle` 也走实例化路径
+
+triangle 的正确实现目标：
+
+- 不是回退到 indexed geometry
+- 不是临时特判 draw call
+- 而是作为实例化 primitive 的一种 kind，被统一编译、缓存、上传和绘制
+
+### Phase B. Rebuild renderer data model around the unified path
+
+同步调整：
+
+- `UiBatchKind` 去除或退化
+- `UiQuadInstance` 升级为更通用的 `UiPrimitiveInstance`
+- `CompiledDrawList` 不再缓存 legacy vertices / indices
+- `EnsureFrameBufferCapacity(...)` 只维护 primitive instance buffer
+- render dispatch 只保留单一 pipeline bind 分支
+
+### Phase C. Collapse startup capture ownership to one source of truth
+
+把 startup capture 的策略权上移并单点化：
+
+- `Application` 或窗口创建层读取 env / policy
+- `CreateParams.autoCaptureOnStartup` 成为唯一窗口级输入
+- `EditorWindowRuntimeController` 只消费该参数
+- `EditorWindowScreenshotController` 只做请求/路径/结果管理，不做策略判断
+
+### Phase D. Remove obsolete Native module shell
+
+将截图控制器从 `app/Rendering/Native/` 迁移到更合理的位置，
+预计是窗口运行时或通用 support/capture 模块。
+
+要求：
+
+- 迁移后 active include 不再引用 `Rendering/Native`
+- `new_editor/CMakeLists.txt` 同步更新
+
+### Phase E. Delete dead helpers and normalize semantics
+
+删除已经确认无调用的旧辅助函数，并统一命名：
+
+- `legacy*` -> 按真实职责改名，或随着删除一起消失
+- 清理无用 helper
+- 保证 renderer 术语与当前架构一致
+
+## 5. File-Level Work
+
+### 5.1 UI renderer core
+
+Primary:
+
+- `new_editor/app/Rendering/D3D12/D3D12UiRenderer.h`
+- `new_editor/app/Rendering/D3D12/D3D12UiRenderer.cpp`
+
+### 5.2 Startup capture boundary
+
+Primary:
+
+- `new_editor/app/Bootstrap/Application.cpp`
+- `new_editor/app/Platform/Win32/EditorWindow.cpp`
+- `new_editor/app/Platform/Win32/EditorWindowRuntimeController.h`
+- `new_editor/app/Platform/Win32/EditorWindowRuntimeController.cpp`
+- `new_editor/app/Platform/Win32/EditorWindowManager.h`
+
+### 5.3 Screenshot controller relocation
+
+Current source:
+
+- `new_editor/app/Platform/Win32/EditorWindowScreenshotController.h`
+- `new_editor/app/Platform/Win32/EditorWindowScreenshotController.cpp`
+
+Target:
+
+- move into non-legacy module location
+
+### 5.4 Build graph cleanup
+
+- `new_editor/CMakeLists.txt`
+
+## 6. Validation
+
+### 6.1 Structural validation
+
+完成后搜索应满足：
+
+- no `LegacyIndexed` in active UI renderer
+- no `m_legacyPipelineState`
+- no `legacyVertexBuffer`
+- no `legacyIndexBuffer`
+- no `app/Rendering/Native/AutoScreenshot.*` active include path
+
+### 6.2 Runtime validation
+
+必须验证：
+
+1. `XCUIEditorApp` Debug 构建通过
+2. editor 正常启动
+3. 主窗口 UI 正常显示与交互
+4. startup auto-capture 正常生成
+5. detached window 不会错误触发 startup capture
+
+## 7. Completion Criteria
+
+只有满足以下条件，这个 plan 才算真正收口：
+
+1. UI 渲染路径内部不再存在旧几何子管线
+2. startup capture 策略控制权单点化
+3. 旧 `Native` 模块边界消失
+4. 死代码删除
+5. 构建、启动、截图验证全部通过
diff --git a/docs/plan/NewEditor_D3D12_LegacyD2DClosurePlan_2026-04-22.md b/docs/used/NewEditor_D3D12_LegacyD2DClosurePlan_完成归档_2026-04-22.md
similarity index 100%
rename from docs/plan/NewEditor_D3D12_LegacyD2DClosurePlan_2026-04-22.md
rename to docs/used/NewEditor_D3D12_LegacyD2DClosurePlan_完成归档_2026-04-22.md