docs(plan): refresh API restructuring status

2026-04-10 17:36:25 +08:00
parent 2d8ada03a1
commit 81d0d92aed
3 changed files with 64 additions and 25 deletions
--- a/docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md
+++ b/docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md
@@ -21,6 +21,22 @@

 - `python -B docs/api/_tools/audit_api_docs.py`

+## 2.1 2026-04-10 状态更新
+
+截至 `2026-04-10 17:07:09`，这份计划里最核心的阶段性目标已经完成：
+
+- `XCUIDemoPanel` 已从 canonical 树移除，相关活跃反向链接已清理
+- `Rendering` 旧错位目录与 stale-token 路径已完成一轮归位/回归
+- `Volume / Selection / UI helper / Editor helper` 缺页已补齐
+- `docs/api/XCEditor/**`、`Resources/Model/**`、`Resources/GaussianSplat/**` 已进入 canonical 树
+- 审计当前全绿：
+  - `Invalid header refs = 0`
+  - `Invalid source refs = 0`
+  - `Broken .md links = 0`
+  - `Missing directory index pages = 0`
+
+因此下文第 `3` 节保留的是“本轮原始发现快照”，不是当前仍未处理的实时状态。
+
 ## 3. 已确认的结构性问题

 ### 3.1 Rendering 存在成对重复目录
--- a/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md
+++ b/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md
@@ -4,6 +4,15 @@

 本轮不是普通补页，而是一次“目录归位 + 失效页清理 + 新模块补平”混合重构。

+## 状态更新（2026-04-10 17:07:09）
+
+- 当前 `docs/api/XCEngine/**` + `docs/api/XCEditor/**` + `editor/src/**` 审计已经全绿。
+- `R1` - `R7` 对应的主要结构归位、失效页清理和缺页补齐已经完成。
+- 当前剩余重点不再是“补 XCEditor / Volume / XCUIDemoPanel”，而是：
+  - `R8` 这类残余结构规范化
+  - 更高风险的 `RHI / Rendering / Editor/Viewport` 内容回归
+  - 历史空目录与重复入口的持续收口
+
 已确认的事实来源：

 - 本地源码目录对照
@@ -13,7 +22,7 @@
  - `python -B docs/api/_tools/audit_api_docs.py`
 - 多路 `GPT-5.4 high` 子代理并行审计结论

-## 当前已确认的结构问题
+## 当前已确认的结构问题（原始发现快照）

 ### 1. Rendering 根目录存在明显错位页面

@@ -127,13 +136,13 @@

 | ID | 范围 | 目标改动 | 主要路径 | 状态 | 认领人 |
 |----|------|----------|----------|------|--------|
-| `R1` | Rendering 目录归位 | 把错挂在 `Rendering` 根目录下的页面迁回 `Execution / Planning / Extraction / Caches / FrameData / Passes`，并与已存在的正确目录合并 | `docs/api/XCEngine/Rendering/**` | `pending` | |
-| `R2` | 旧概念 Rendering 清理 | 核查并清理 `RenderMaterialUtility / ObjectIdEncoding / VisibleRenderObject / BuiltinForwardPipelineAsset / ObjectIdOutlineStyle / BuiltinPostProcessPassPlan / BuiltinPostProcessPassSequenceBuilder / ShaderRenderState` | `docs/api/XCEngine/Rendering/**` `docs/api/XCEngine/Resources/Shader/**` | `pending` | |
-| `R3` | Editor 失效页清理 | 删除或退役 `XCUIDemoPanel / SceneViewportOverlayRenderer`，并修正所有反向引用 | `docs/api/XCEngine/Editor/**` | `pending` | |
-| `R4` | Volume 资源与运行时主链 | 补齐 `Volume / VolumeField / VolumeFieldLoader / VolumeRendererComponent / VisibleVolumeItem / BuiltinVolumetricPass` | `docs/api/XCEngine/Resources/**` `docs/api/XCEngine/Components/**` `docs/api/XCEngine/Rendering/**` | `pending` | |
-| `R5` | Selection pass 结构补齐 | 补齐 `BuiltinSelectionMaskPass` 与 `BuiltinSelectionOutlinePass`，并同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `pending` | |
-| `R6` | UI 新 helper | 补齐 `UIDragDropInteraction` 与 `UIScrollModel`，并同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `pending` | |
-| `R7` | Editor 当前真实 helper | 补齐 `VolumeRendererComponentEditor / MaterialInspectorMaterialState / MaterialInspectorMaterialStateIO`，并同步 `ComponentEditors.md` 与 `panels.md` | `docs/api/XCEngine/Editor/**` | `pending` | |
+| `R1` | Rendering 目录归位 | 把错挂在 `Rendering` 根目录下的页面迁回 `Execution / Planning / Extraction / Caches / FrameData / Passes`，并与已存在的正确目录合并 | `docs/api/XCEngine/Rendering/**` | `completed` | 当前会话 |
+| `R2` | 旧概念 Rendering 清理 | 核查并清理 `RenderMaterialUtility / ObjectIdEncoding / VisibleRenderObject / BuiltinForwardPipelineAsset / ObjectIdOutlineStyle / BuiltinPostProcessPassPlan / BuiltinPostProcessPassSequenceBuilder / ShaderRenderState` | `docs/api/XCEngine/Rendering/**` `docs/api/XCEngine/Resources/Shader/**` | `completed` | 当前会话 |
+| `R3` | Editor 失效页清理 | 删除或退役 `XCUIDemoPanel / SceneViewportOverlayRenderer`，并修正所有反向引用 | `docs/api/XCEngine/Editor/**` | `completed` | 当前会话 |
+| `R4` | Volume 资源与运行时主链 | 补齐 `Volume / VolumeField / VolumeFieldLoader / VolumeRendererComponent / VisibleVolumeItem / BuiltinVolumetricPass` | `docs/api/XCEngine/Resources/**` `docs/api/XCEngine/Components/**` `docs/api/XCEngine/Rendering/**` | `completed` | 当前会话 |
+| `R5` | Selection pass 结构补齐 | 补齐 `BuiltinSelectionMaskPass` 与 `BuiltinSelectionOutlinePass`，并同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `completed` | 当前会话 |
+| `R6` | UI 新 helper | 补齐 `UIDragDropInteraction` 与 `UIScrollModel`，并同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `completed` | 当前会话 |
+| `R7` | Editor 当前真实 helper | 补齐 `VolumeRendererComponentEditor / MaterialInspectorMaterialState / MaterialInspectorMaterialStateIO`，并同步 `ComponentEditors.md` 与 `panels.md` | `docs/api/XCEngine/Editor/**` | `completed` | 当前会话 |
 | `R8` | 结构规范补齐 | 修正仍不满足“一类型一文件夹”的点，例如 `Editor/UI/UI`、`Resources/Material/MaterialRenderState` 这类混挂页 | `docs/api/XCEngine/**` | `pending` | |
 | `R9` | 全量回归 | 统一修链、清理空目录、重跑审计、收口索引页 | `docs/api/**` | `pending` | |

--- a/docs/plan/API文档目录重构计划_2026-04-09.md
+++ b/docs/plan/API文档目录重构计划_2026-04-09.md
@@ -5,11 +5,26 @@
 当前 API 文档树已经出现明显的“双主线错位”：

 - `docs/api/XCEngine/Editor/**` 主要对应旧 `editor/src/**` 的 ImGui 编辑器应用层。
- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线，但几乎没有进入当前 canonical API 树。
- 现有审计脚本只覆盖 `engine/include/XCEngine/**` 与 `editor/src/**`，没有覆盖 `new_editor/include/XCEditor/**`。
+- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线。
+- 这条主线最初没有进入当前 canonical API 树，审计脚本也一度没有覆盖 `new_editor/include/XCEditor/**`。

 这意味着继续只在 `docs/api/XCEngine/Editor/**` 上增量修补，会越来越偏离真实代码结构。

+## 1.1 2026-04-10 状态更新
+
+截至 `2026-04-10 17:07:09`，以下阶段已经落地：
+
+- `docs/api/XCEditor/**` 已建立并进入 canonical 根树
+- 审计脚本已经覆盖：
+  - `engine/include/XCEngine/**`
+  - `new_editor/include/XCEditor/**`
+  - `editor/src/**`
+- `docs/api/main.md` 已建立 `XCEngine + XCEditor` 双根入口
+- `XCUIDemoPanel` 已退出当前 canonical API 树
+- `Resources/Model` 与 `Resources/GaussianSplat` 已补齐 canonical 入口
+
+因此这份计划里“为什么要拆出 `XCEditor` 根树”的判断仍然有效，但 `Phase B / C` 不再是未来动作，而是已完成事实。
+
 ## 2. 当前判断

 ### 2.1 旧 `Editor` 文档树继续保留，但必须收紧边界
@@ -18,9 +33,9 @@
 - 不再把它当成未来 Editor 主线 API 树。
 - 其中 `Application / EditorResources / Theme / XCUIBackend / panels / Viewport` 等内容，明确视为旧编辑器应用层。

-### 2.2 新主线应拆出独立文档树
+### 2.2 新主线已拆出独立文档树

-建议新增：
+当前已新增：

 - `docs/api/XCEditor/`

@@ -57,24 +72,24 @@
 - `XCEditor/Shell/*`
 - `XCEditor/Widgets/*`

-但 `docs/api` 里没有对应的 `XCEditor` 根树。
+现在 `docs/api` 里已经有对应的 `XCEditor` 根树。

 ### 3.2 旧树中仍混有已经过时的过渡页

-当前至少已经发现：
+当前这类问题已经完成清理，最典型的是：

 - `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md`
  - 仍引用已不存在的 `editor/src/panels/XCUIDemoPanel.h`

-这类页面需要单独清理，不能继续假设旧源码路径仍成立。
+这类页面已经从 active canonical 树移除，不再继续假设旧源码路径仍成立。

 ### 3.3 审计工具口径落后

-当前 `docs/api/_tools/audit_api_docs.py` 的覆盖口径没有把：
+当前这项问题已经收口；审计脚本现在已经把：

 - `new_editor/include/XCEditor/**/*.h`

-纳入 canonical 统计，所以即使新主线完全缺文档，审计也不会报警。
+纳入 canonical 统计，`XCEditor` 缺页会直接出现在审计结果里。

 ## 4. 分阶段执行

@@ -84,7 +99,7 @@
 - 修掉旧树里已经失效的 source refs。
 - 继续补齐旧 `editor/src/**` 当前缺失的 canonical 页，避免现有审计长期失真。

-## Phase B：建立 `XCEditor` 新根树
+## Phase B：建立 `XCEditor` 新根树（已完成）

 - 新建 `docs/api/XCEditor/XCEditor.md`
 - 新建 5 个首层 overview：
@@ -95,7 +110,7 @@
  - `Widgets`
 - 建立 `docs/api/main.md` 到新根树的入口链接

-## Phase C：接入新审计口径
+## Phase C：接入新审计口径（已完成）

 - 扩展审计脚本识别 `new_editor/include/XCEditor/**/*.h`
 - 统计 `docs/api/XCEditor/**` 的 canonical 覆盖率
@@ -103,7 +118,7 @@
  - 旧 `editor/src/**` 应用层源码页
  - 新 `XCEditor/**` public header 页

-## Phase D：按新主线分批补页
+## Phase D：按新主线分批补页（进行中）

 推荐顺序：

@@ -119,7 +134,7 @@
 - `Collections` / `Fields` 数量多，但结构相对规整，适合并行。
 - `Shell` 依赖最多，最好放后面统一写。

-## Phase E：旧树去历史包袱
+## Phase E：旧树去历史包袱（进行中）

 - 删除或改写已经脱离旧源码的过渡页
 - 把“旧 editor 参考实现”和“new_editor 正式主线”在相关 overview 中互相链接，但不再混放
@@ -127,8 +142,7 @@

 ## 5. 本轮执行口径

-本轮先按两条线同时推进：
-
-1. 先把现有审计缺口补齐，保证旧树不继续烂下去。
-2. 同时开始落 `XCEditor` 文档树重构计划和入口边界说明，为下一轮结构迁移做准备。
+当前后续重点已经转到：

+1. 继续回归高风险 `RHI / Rendering / Editor/Viewport` 内容页，避免源码继续演进后文档再次漂移。
+2. 继续清理旧树里的历史空目录、重复入口和剩余结构噪音。