docs: add second-round api structure refactor plan

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

@@ -0,0 +1,92 @@
+# API 文档目录结构第二轮并行任务板（2026-04-09）
+
+## 使用规则
+
+- 每个任务块只允许一个会话领取。
+- 每个任务块必须同时处理：主页面、所属索引页、交叉链接。
+- 每完成一个任务块所在阶段，都要先审计，再提交推送。
+- 如果任务路径命中当前并发热点，先不要直接改。
+
+## 当前并发热点
+
+以下源码区域当前已有并发修改，相关文档任务默认标记为 `high-risk`：
+
+- `editor/src/Viewport/**`
+- `engine/include/XCEngine/RHI/**`
+- `engine/include/XCEngine/Rendering/Passes/**`
+- `engine/include/XCEngine/Rendering/Materials/RenderMaterialResolve.h`
+- `engine/include/XCEngine/UI/Widgets/UISelectionModel.h`
+- `engine/include/XCEngine/UI/Widgets/UIDragDropInteraction.h`
+
+## 任务块
+
+| ID | 范围 | 目标改动 | 主要路径 | 风险 | 状态 | 领取人 |
+|----|------|----------|----------|------|------|--------|
+| `R1` | Rendering / 重复目录归位 | 把旧顶层 `CameraRenderer`、`SceneRenderer`、`CameraRenderRequest`、`SceneRenderRequestPlanner`、`SceneRenderRequestUtils`、`RenderCameraData`、`RenderResourceCache`、`RenderSceneExtractor`、`RenderSceneUtility` 合并到真实子模块位置 | `docs/api/XCEngine/Rendering/**` | `medium` | `pending` | |
+| `R2` | Rendering / 旧命名残留审计 | 处理 `ObjectIdEncoding`、`ObjectIdPass`、`RenderMaterialUtility`、`VisibleRenderObject`，判定迁移到哪里或删除 | `docs/api/XCEngine/Rendering/**` | `medium` | `pending` | |
+| `E1` | Editor / 历史失效页清理 | 移除或降级 `XCUIDemoPanel`，修正 `panels.md`、`ImGuiTransitionBackend.md` 等反向链接 | `docs/api/XCEngine/Editor/panels/**` | `low` | `pending` | |
+| `V1` | Resources / Volume | 建立 `Volume.md`、`VolumeField.md`、`VolumeFieldLoader.md`，同步 `Resources.md` | `docs/api/XCEngine/Resources/Volume/**` | `low` | `pending` | |
+| `V2` | Components / Volume | 建立 `VolumeRendererComponent.md`，同步 `Components.md` | `docs/api/XCEngine/Components/VolumeRendererComponent/**` | `low` | `pending` | |
+| `V3` | Rendering / Volume FrameData | 建立 `VisibleVolumeItem.md`，同步 `FrameData.md` | `docs/api/XCEngine/Rendering/FrameData/**` | `low` | `pending` | |
+| `V4` | Rendering / Volume & Selection Passes | 建立 `BuiltinSelectionMaskPass.md`、`BuiltinSelectionOutlinePass.md`、`BuiltinVolumetricPass.md`，同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `high-risk` | `pending` | |
+| `U1` | UI / Widgets Helpers | 建立 `UIDragDropInteraction.md`、`UIScrollModel.md`，同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `high-risk` | `pending` | |
+| `ED1` | Editor / ComponentEditors | 建立 `VolumeRendererComponentEditor.md`，同步 `ComponentEditors.md` | `docs/api/XCEngine/Editor/ComponentEditors/**` | `low` | `pending` | |
+| `ED2` | Editor / panels Material Authoring | 建立 `MaterialInspectorMaterialState.md`、`MaterialInspectorMaterialStateIO.md`，同步 `panels.md` | `docs/api/XCEngine/Editor/panels/**` | `low` | `pending` | |
+| `RR1` | RHI 内容回归 | 根据当前真实头文件更新 `RHI*`、`D3D12`、`OpenGL`、`Vulkan` 文档内容与结构 | `docs/api/XCEngine/RHI/**` | `high-risk` | `pending` | |
+| `RR2` | Rendering / Passes 内容回归 | 根据当前修改中的 builtin pass 头文件更新文档内容与链接 | `docs/api/XCEngine/Rendering/Passes/**` | `high-risk` | `pending` | |
+| `RR3` | Rendering / Materials 内容回归 | 把 `RenderMaterialResolve` 相关文档与当前头文件重新对齐 | `docs/api/XCEngine/Rendering/Materials/**` | `high-risk` | `pending` | |
+| `G1` | 全量审计与空目录清理 | 跑审计、清空旧重复目录、清理空目录与错链 | `docs/api/_meta/**`, `docs/api/XCEngine/**` | `medium` | `pending` | |
+
+## 推荐阶段顺序
+
+### 第一阶段
+
+- `R1`
+- `R2`
+- `E1`
+
+这一阶段的目标是先把“结构错位”和“失效历史页”清掉。
+
+### 第二阶段
+
+- `V1`
+- `V2`
+- `V3`
+- `ED1`
+- `ED2`
+
+这一阶段优先补低冲突、可快速收口的缺页。
+
+### 第三阶段
+
+- `V4`
+- `U1`
+- `RR1`
+- `RR2`
+- `RR3`
+
+这一阶段等源码波动收敛后再做。
+
+### 第四阶段
+
+- `G1`
+
+## 验收口径
+
+### 结构验收
+
+- 每个 API 只保留一个 canonical 目录位置。
+- 文档目录层级必须与真实源码父目录一致。
+- 不再允许顶层旧路径和子模块新路径并存。
+
+### 审计验收
+
+- `Invalid header refs = 0`
+- `Invalid source refs = 0`
+- `Broken .md links = 0`
+- `Missing directory index pages = 0`
+
+### 协作验收
+
+- 每个阶段完成后立即提交推送。
+- 任务板状态同步更新，避免重复领取。

docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md

@@ -0,0 +1,211 @@
+# API 文档目录结构第二轮重构计划
+
+## 1. 背景
+
+项目最近又经历了一轮较大的源码重构，`docs/api/XCEngine` 当前虽然顶层大类仍然存在，但内部已经出现了两类更严重的问题：
+
+- 目录层级错位：文档页名字还对，但挂在了错误的父目录下。
+- 新旧结构并存：旧位置和新位置同时保留，导致同一 API 在文档树里出现两套入口。
+
+这轮重构不再是简单补页，而是要把 `docs/api` 再次拉回到“与实际源码模块结构平行”的状态。
+
+## 2. 本轮核对基准
+
+本轮计划基于以下真实代码树做对照：
+
+- 运行时 public headers：`engine/include/XCEngine/**`
+- 旧版编辑器 source-backed API：`editor/src/**`
+- 当前文档树：`docs/api/XCEngine/**`
+
+同时参考了最新本地审计结果：
+
+- `python -B docs/api/_tools/audit_api_docs.py`
+
+## 3. 已确认的结构性问题
+
+### 3.1 Rendering 存在成对重复目录
+
+当前已确认以下目录同时出现在“旧顶层位置”和“源码对应的新子模块位置”：
+
+- `docs/api/XCEngine/Rendering/CameraRenderer`
+- `docs/api/XCEngine/Rendering/Execution/CameraRenderer`
+- `docs/api/XCEngine/Rendering/SceneRenderer`
+- `docs/api/XCEngine/Rendering/Execution/SceneRenderer`
+- `docs/api/XCEngine/Rendering/CameraRenderRequest`
+- `docs/api/XCEngine/Rendering/Planning/CameraRenderRequest`
+- `docs/api/XCEngine/Rendering/SceneRenderRequestPlanner`
+- `docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner`
+- `docs/api/XCEngine/Rendering/SceneRenderRequestUtils`
+- `docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils`
+- `docs/api/XCEngine/Rendering/RenderCameraData`
+- `docs/api/XCEngine/Rendering/FrameData/RenderCameraData`
+- `docs/api/XCEngine/Rendering/RenderResourceCache`
+- `docs/api/XCEngine/Rendering/Caches/RenderResourceCache`
+- `docs/api/XCEngine/Rendering/RenderSceneExtractor`
+- `docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor`
+- `docs/api/XCEngine/Rendering/RenderSceneUtility`
+- `docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility`
+
+这说明文档树里同时保留了“旧的平铺布局”和“新的源码子模块布局”。后续必须只保留源码对应路径，旧路径下的内容要迁移或删除，不能继续并存。
+
+### 3.2 Rendering 还有一批疑似旧命名/旧抽象残留
+
+当前已确认下列目录没有直接对应到当前真实头文件命名，属于优先审计对象：
+
+- `docs/api/XCEngine/Rendering/ObjectIdEncoding`
+- `docs/api/XCEngine/Rendering/ObjectIdPass`
+- `docs/api/XCEngine/Rendering/RenderMaterialUtility`
+- `docs/api/XCEngine/Rendering/VisibleRenderObject`
+
+这些目录大概率分别对应：
+
+- 已下沉或改名后的 `Picking/ObjectIdCodec`
+- `Passes/BuiltinObjectIdPass`
+- `Materials/RenderMaterialResolve`
+- `FrameData/VisibleRenderItem`
+
+但不能直接机械删除，必须先做“旧页内容是否需要迁移”的核对。
+
+### 3.3 Editor 仍保留已脱离源码的历史页
+
+当前已确认：
+
+- `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md`
+
+对应源码：
+
+- `editor/src/panels/XCUIDemoPanel.h`
+- `editor/src/panels/XCUIDemoPanel.cpp`
+
+这两个文件都已经不存在。
+
+当前仍引用该历史页的文档包括：
+
+- `docs/api/XCEngine/Editor/panels/panels.md`
+- `docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md`
+
+`docs/api/XCEngine/UI/DrawData/DrawData.md` 里已经改成“旧链路说明”，这类描述可以保留，但不应该继续把 `XCUIDemoPanel` 作为真实 canonical API 页面入口。
+
+### 3.4 审计明确缺页仍然存在
+
+最新审计仍明确指出以下缺口需要补齐：
+
+- `XCEngine/Components/VolumeRendererComponent.h`
+- `XCEngine/Rendering/FrameData/VisibleVolumeItem.h`
+- `XCEngine/Rendering/Passes/BuiltinSelectionMaskPass.h`
+- `XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass.h`
+- `XCEngine/Rendering/Passes/BuiltinVolumetricPass.h`
+- `XCEngine/Resources/Volume/VolumeField.h`
+- `XCEngine/Resources/Volume/VolumeFieldLoader.h`
+- `XCEngine/UI/Widgets/UIDragDropInteraction.h`
+- `XCEngine/UI/Widgets/UIScrollModel.h`
+- `editor/src/ComponentEditors/VolumeRendererComponentEditor.h`
+- `editor/src/panels/MaterialInspectorMaterialState.h`
+- `editor/src/panels/MaterialInspectorMaterialStateIO.h`
+
+同时还缺少：
+
+- `docs/api/XCEngine/Resources/Volume/Volume.md`
+
+### 3.5 当前存在并发修改热点
+
+当前工作区里已有其他会话在修改以下源码区域，对应文档重构要么延后，要么单独协调：
+
+- `editor/src/Viewport/**`
+- `engine/include/XCEngine/RHI/**`
+- `engine/include/XCEngine/Rendering/Passes/**`
+- `engine/include/XCEngine/Rendering/Materials/RenderMaterialResolve.h`
+- `engine/include/XCEngine/UI/Widgets/UISelectionModel.h`
+- `engine/include/XCEngine/UI/Widgets/UIDragDropInteraction.h`
+
+因此本轮执行要按“低冲突优先”组织阶段，避免多个会话同时改同一批文档。
+
+## 4. 本轮目标
+
+### 4.1 结构目标
+
+- `docs/api/XCEngine/**` 内每一个类/模块页都必须与当前真实源码路径平行。
+- 同一 API 只能保留一个 canonical 位置。
+- 旧的错位目录必须迁移或移除，不能继续保留作第二入口。
+
+### 4.2 内容目标
+
+- 在结构对齐完成后，再逐批做内容重构。
+- 内容必须基于当前源码与测试，而不是沿用旧说明。
+
+### 4.3 协作目标
+
+- 每一批任务都要能被多个会话独立领取。
+- 每一阶段结束后立即提交并推送，避免长时间悬空。
+
+## 5. 分阶段执行
+
+## Phase A：建立新计划与任务板
+
+- 新开第二轮计划文件
+- 新开第二轮并行任务板
+- 标清“当前确定的问题”和“并发风险路径”
+
+## Phase B：清理已确认的失效历史页
+
+- 处理 `XCUIDemoPanel`
+- 修复所有反向链接
+- 让 `Invalid source refs` 归零
+
+## Phase C：Rendering 目录结构归位
+
+- 把所有错位的顶层 Rendering 目录迁移到真实子模块
+- 合并旧目录里的方法页/细页到正确的新位置
+- 删除旧顶层重复入口
+
+## Phase D：补齐审计明确缺页
+
+- `Resources/Volume`
+- `Components/VolumeRendererComponent`
+- `Rendering/VisibleVolumeItem`
+- `Rendering` 的体积/选择 pass
+- `UI/Widgets` 新 helper
+- `Editor` 的体积组件编辑器与材质状态页
+
+## Phase E：高风险模块内容回归
+
+在相关源码停止波动后，再处理：
+
+- `RHI`
+- `Rendering/Passes`
+- `Rendering/Materials`
+- `Editor/Viewport`
+- `UI/Widgets`
+
+## Phase F：总回归
+
+- 全量跑审计
+- 清理空目录、错链、旧入口
+- 更新阶段状态并准备下一轮内容重构
+
+## 6. 本轮优先级判断
+
+当前最优先的不是继续写新内容，而是先把“错层级”和“重复入口”消掉。否则后面无论哪个会话补文档，都有较高概率继续写到旧路径。
+
+因此第二轮的第一主战场是：
+
+- `docs/api/XCEngine/Rendering`
+
+第二主战场是：
+
+- `docs/api/XCEngine/Editor` 中仍脱离真实源码的历史页
+
+第三主战场才是：
+
+- 审计明确缺页的 Volume / UI / Editor 补齐
+
+## 7. 阶段收口要求
+
+每完成一个阶段，必须执行：
+
+1. 本地核对改动范围
+2. `python -B docs/api/_tools/audit_api_docs.py`
+3. `git commit`
+4. `git push`
+
+只有在上一阶段已经提交推送后，才进入下一阶段。