XCEngine/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md

# API 文档目录结构重构并行任务板（第二轮，2026-04-09）

## 背景

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

## 状态更新（2026-04-10 17:07:09）

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

已确认的事实来源：

- 本地源码目录对照
  - `engine/include/XCEngine/**`
  - `editor/src/**`
- 最新审计
  - `python -B docs/api/_tools/audit_api_docs.py`
- 多路 `GPT-5.4 high` 子代理并行审计结论

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

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

以下文档目录名是对的，但父目录已经错了，应该先迁回真实源码子模块：

- `docs/api/XCEngine/Rendering/CameraRenderer`
  - 实际应对应 `engine/include/XCEngine/Rendering/Execution/CameraRenderer.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Execution/CameraRenderer`
- `docs/api/XCEngine/Rendering/SceneRenderer`
  - 实际应对应 `engine/include/XCEngine/Rendering/Execution/SceneRenderer.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Execution/SceneRenderer`
- `docs/api/XCEngine/Rendering/CameraRenderRequest`
  - 实际应对应 `engine/include/XCEngine/Rendering/Planning/CameraRenderRequest.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Planning/CameraRenderRequest`
- `docs/api/XCEngine/Rendering/SceneRenderRequestPlanner`
  - 实际应对应 `engine/include/XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner`
- `docs/api/XCEngine/Rendering/SceneRenderRequestUtils`
  - 实际应对应 `engine/include/XCEngine/Rendering/Planning/SceneRenderRequestUtils.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils`
- `docs/api/XCEngine/Rendering/RenderSceneExtractor`
  - 实际应对应 `engine/include/XCEngine/Rendering/Extraction/RenderSceneExtractor.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor`
- `docs/api/XCEngine/Rendering/RenderSceneUtility`
  - 实际应对应 `engine/include/XCEngine/Rendering/Extraction/RenderSceneUtility.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility`
- `docs/api/XCEngine/Rendering/RenderResourceCache`
  - 实际应对应 `engine/include/XCEngine/Rendering/Caches/RenderResourceCache.h`
  - 目标路径：`docs/api/XCEngine/Rendering/Caches/RenderResourceCache`
- `docs/api/XCEngine/Rendering/RenderCameraData`
  - 实际应对应 `engine/include/XCEngine/Rendering/FrameData/RenderCameraData.h`
  - 目标路径：`docs/api/XCEngine/Rendering/FrameData/RenderCameraData`
- `docs/api/XCEngine/Rendering/ObjectIdPass`
  - 当前属于旧命名
  - 实际应归入 `docs/api/XCEngine/Rendering/Passes/BuiltinObjectIdPass`

### 1.1 已确认“正确目录已存在，但错位旧目录仍保留”的重复区

以下区域不是“目标目录不存在”，而是“新目录已经有页，旧错位目录还没清掉”：

- `Rendering/CameraRenderer` 与 `Rendering/Execution/CameraRenderer`
- `Rendering/SceneRenderer` 与 `Rendering/Execution/SceneRenderer`
- `Rendering/RenderSceneExtractor` 与 `Rendering/Extraction/RenderSceneExtractor`
- `Rendering/RenderSceneUtility` 与 `Rendering/Extraction/RenderSceneUtility`
- `Rendering/RenderResourceCache` 与 `Rendering/Caches/RenderResourceCache`
- `Rendering/RenderCameraData` 与 `Rendering/FrameData/RenderCameraData`
- `Rendering/CameraRenderRequest` 与 `Rendering/Planning/CameraRenderRequest`
- `Rendering/SceneRenderRequestPlanner` 与 `Rendering/Planning/SceneRenderRequestPlanner`
- `Rendering/SceneRenderRequestUtils` 与 `Rendering/Planning/SceneRenderRequestUtils`

### 2. 已经脱离源码现实的失效页

- `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md`
  - 当前仍引用不存在的 `editor/src/panels/XCUIDemoPanel.h`
  - 这是当前审计里唯一明确的失效源文件引用
- `docs/api/XCEngine/Editor/Viewport/SceneViewportOverlayRenderer`
  - 当前 `editor/src/Viewport` 下已无对应头文件
  - 优先视为待清理历史目录
- 以下页面仍引用或延续了这条旧链路：
  - `docs/api/XCEngine/Editor/panels/panels.md`
  - `docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md`
  - `docs/api/XCEngine/UI/DrawData/DrawData.md`

### 3. 旧概念或旧结构残留页

以下目录需要先做“是否仍有真实源码对应物”的确认，再决定迁移还是删除：

- `docs/api/XCEngine/Rendering/RenderMaterialUtility`
- `docs/api/XCEngine/Rendering/ObjectIdEncoding`
- `docs/api/XCEngine/Rendering/VisibleRenderObject`
- `docs/api/XCEngine/Rendering/Pipelines/BuiltinForwardPipelineAsset`
- `docs/api/XCEngine/Rendering/Passes/ObjectIdOutlineStyle`
- `docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassPlan`
- `docs/api/XCEngine/Rendering/Passes/BuiltinPostProcessPassSequenceBuilder`
- `docs/api/XCEngine/Resources/Shader/ShaderRenderState`

### 4. 本轮新暴露出来的结构缺页

这些目录现在是真实源码节点，且已经进入主链，应尽快补平：

- `docs/api/XCEngine/Resources/Volume/Volume`
- `docs/api/XCEngine/Resources/Volume/VolumeField`
- `docs/api/XCEngine/Resources/Volume/VolumeFieldLoader`
- `docs/api/XCEngine/Components/VolumeRendererComponent`
- `docs/api/XCEngine/Rendering/FrameData/VisibleVolumeItem`
- `docs/api/XCEngine/Rendering/Passes/BuiltinSelectionMaskPass`
- `docs/api/XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass`
- `docs/api/XCEngine/Rendering/Passes/BuiltinVolumetricPass`
- `docs/api/XCEngine/UI/Widgets/UIDragDropInteraction`
- `docs/api/XCEngine/UI/Widgets/UIScrollModel`
- `docs/api/XCEngine/Editor/ComponentEditors/VolumeRendererComponentEditor`
- `docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialState`
- `docs/api/XCEngine/Editor/panels/MaterialInspectorMaterialStateIO`

## 并行认领规则

- 一次只认领一个任务块
- 认领人必须同时处理：
  - 目标页面
  - 所在模块索引页
  - 交叉引用修正
- 做删除前先执行：
  - `rg -n "<名称>" docs/api/XCEngine docs/api/_guides docs/plan`
- 每完成一个任务块后必须执行：
  - `python -B docs/api/_tools/audit_api_docs.py`
- 每完成一个阶段后必须：
  - `git commit`
  - `git push`

## 并行任务块

| ID | 范围 | 目标改动 | 主要路径 | 状态 | 认领人 |
|----|------|----------|----------|------|--------|
| `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` | |

## 推荐阶段顺序

### Phase 1

- `R3`
- `R1`
- `R2`

说明：

- 先把失效页和错位目录处理掉，后续内容重写才不会继续落在错误路径上

### Phase 2

- `R4`
- `R5`
- `R6`
- `R7`
- `R8`

说明：

- 这一阶段是把新主链和当前真实 helper 补平

### Phase 3

- `R9`

说明：

- 统一收口、审计、整理最终状态

## 最低验收标准

### `R1`

- 所有迁移后的页面目录与真实头文件父目录一致
- 原路径不再保留 active canonical 页面

### `R2`

- 每个旧概念页都给出明确结论：
  - 删除
  - 迁移
  - 改写为真实对应页

### `R3`

- `Invalid source refs` 归零
- `XCUIDemoPanel` 不再作为当前有效 API 页面存在于 canonical 树

### `R4` - `R8`

- 每个类型都是“一文件夹 + 一主页面”
- 页面描述必须基于当前源码与测试
- 模块索引页同步更新

### `R9`

- `Invalid header refs = 0`
- `Invalid source refs = 0`
- `Broken .md links = 0`
- `Missing directory index pages = 0`

## 备注

- 当前仓库存在多会话并行改动，尤其是 `Rendering`、`RHI`、`Editor/Viewport` 相关头文件；真正执行重构时优先选择干净路径，避免和其他会话冲突
- 如果某个任务块执行过程中发现真实源码再次变动，应先回到本任务板更新状态，不要硬做