xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ff4e3f639a512d146999a614d2551b8d1cdff551
XCEngine/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md

10 KiB
Raw Blame History

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 相关头文件；真正执行重构时优先选择干净路径，避免和其他会话冲突
  • 如果某个任务块执行过程中发现真实源码再次变动，应先回到本任务板更新状态，不要硬做
Reference in New Issue View Git Blame Copy Permalink