102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
# 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`
|
||
|
||
### 协作验收
|
||
|
||
- 每个阶段完成后立即提交推送。
|
||
- 任务板状态同步更新，避免重复领取。
|