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

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	completed	当前会话
R2	Rendering / 旧命名残留审计	处理 ObjectIdEncoding、ObjectIdPass、RenderMaterialUtility、VisibleRenderObject，判定迁移到哪里或删除	docs/api/XCEngine/Rendering/**	medium	completed	当前会话
E1	Editor / 历史失效页清理	移除 XCUIDemoPanel canonical 页面，修正 panels.md、ImGuiTransitionBackend.md 等反向链接	docs/api/XCEngine/Editor/panels/**	low	completed	当前会话
V1	Resources / Volume	建立 Volume.md、VolumeField.md、VolumeFieldLoader.md，同步 Resources.md	docs/api/XCEngine/Resources/Volume/**	low	completed	当前会话
V2	Components / Volume	建立 VolumeRendererComponent.md，同步 Components.md	docs/api/XCEngine/Components/VolumeRendererComponent/**	low	completed	当前会话
V3	Rendering / Volume FrameData	建立 VisibleVolumeItem.md，同步 FrameData.md	docs/api/XCEngine/Rendering/FrameData/**	low	completed	当前会话
V4	Rendering / Volume & Selection Passes	建立 BuiltinSelectionMaskPass.md、BuiltinSelectionOutlinePass.md、BuiltinVolumetricPass.md，同步 Passes.md	docs/api/XCEngine/Rendering/Passes/**	high-risk	completed	当前会话
U1	UI / Widgets Helpers	建立 UIDragDropInteraction.md、UIScrollModel.md，同步 Widgets.md	docs/api/XCEngine/UI/Widgets/**	high-risk	completed	当前会话
ED1	Editor / ComponentEditors	建立 VolumeRendererComponentEditor.md，同步 ComponentEditors.md	docs/api/XCEngine/Editor/ComponentEditors/**	low	completed	当前会话
ED2	Editor / panels Material Authoring	建立 MaterialInspectorMaterialState.md、MaterialInspectorMaterialStateIO.md，同步 panels.md	docs/api/XCEngine/Editor/panels/**	low	completed	当前会话
RR1	RHI 内容回归	根据当前真实头文件更新 RHI*、D3D12、OpenGL、Vulkan 文档内容与结构	docs/api/XCEngine/RHI/**	high-risk	completed	当前会话
RR2	Rendering / Passes 内容回归	根据当前修改中的 builtin pass 头文件更新文档内容与链接	docs/api/XCEngine/Rendering/Passes/**	high-risk	completed	当前会话
RR3	Rendering / Materials 内容回归	把 RenderMaterialResolve 相关文档与当前头文件重新对齐	docs/api/XCEngine/Rendering/Materials/**	high-risk	completed	当前会话
G1	全量审计与空目录清理	跑审计、清空旧重复目录、清理空目录与错链	docs/api/_meta/**, docs/api/XCEngine/**	medium	pending

最新进度

• 截至 2026-04-10 18:36，docs/api/_tools/audit_api_docs.py 审计已全绿：
  • Invalid header refs = 0
  • Invalid source refs = 0
  • Broken .md links = 0
  • Missing directory index pages = 0
• 当前第二轮任务板里真正剩余的结构性收口项主要是 G1，即历史空目录与重复目录的继续清理。

推荐阶段顺序

第一阶段

• 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

协作验收

• 每个阶段完成后立即提交推送。
• 任务板状态同步更新，避免重复领取。