diff --git a/docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md b/docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md index dab89127..35d4eebf 100644 --- a/docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md +++ b/docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md @@ -21,6 +21,22 @@ - `python -B docs/api/_tools/audit_api_docs.py` +## 2.1 2026-04-10 状态更新 + +截至 `2026-04-10 17:07:09`，这份计划里最核心的阶段性目标已经完成： + +- `XCUIDemoPanel` 已从 canonical 树移除，相关活跃反向链接已清理 +- `Rendering` 旧错位目录与 stale-token 路径已完成一轮归位/回归 +- `Volume / Selection / UI helper / Editor helper` 缺页已补齐 +- `docs/api/XCEditor/**`、`Resources/Model/**`、`Resources/GaussianSplat/**` 已进入 canonical 树 +- 审计当前全绿： + - `Invalid header refs = 0` + - `Invalid source refs = 0` + - `Broken .md links = 0` + - `Missing directory index pages = 0` + +因此下文第 `3` 节保留的是“本轮原始发现快照”，不是当前仍未处理的实时状态。 + ## 3. 已确认的结构性问题 ### 3.1 Rendering 存在成对重复目录 diff --git a/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md b/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md index bb504cce..9eed8a3d 100644 --- a/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md +++ b/docs/plan/API文档目录结构重构并行任务板_2026-04-09_第二轮.md @@ -4,6 +4,15 @@ 本轮不是普通补页，而是一次“目录归位 + 失效页清理 + 新模块补平”混合重构。 +## 状态更新（2026-04-10 17:07:09） + +- 当前 `docs/api/XCEngine/**` + `docs/api/XCEditor/**` + `editor/src/**` 审计已经全绿。 +- `R1` - `R7` 对应的主要结构归位、失效页清理和缺页补齐已经完成。 +- 当前剩余重点不再是“补 XCEditor / Volume / XCUIDemoPanel”，而是： + - `R8` 这类残余结构规范化 + - 更高风险的 `RHI / Rendering / Editor/Viewport` 内容回归 + - 历史空目录与重复入口的持续收口 + 已确认的事实来源： - 本地源码目录对照 @@ -13,7 +22,7 @@ - `python -B docs/api/_tools/audit_api_docs.py` - 多路 `GPT-5.4 high` 子代理并行审计结论 -## 当前已确认的结构问题 +## 当前已确认的结构问题（原始发现快照） ### 1. Rendering 根目录存在明显错位页面 @@ -127,13 +136,13 @@ | ID | 范围 | 目标改动 | 主要路径 | 状态 | 认领人 | |----|------|----------|----------|------|--------| -| `R1` | Rendering 目录归位 | 把错挂在 `Rendering` 根目录下的页面迁回 `Execution / Planning / Extraction / Caches / FrameData / Passes`，并与已存在的正确目录合并 | `docs/api/XCEngine/Rendering/**` | `pending` | | -| `R2` | 旧概念 Rendering 清理 | 核查并清理 `RenderMaterialUtility / ObjectIdEncoding / VisibleRenderObject / BuiltinForwardPipelineAsset / ObjectIdOutlineStyle / BuiltinPostProcessPassPlan / BuiltinPostProcessPassSequenceBuilder / ShaderRenderState` | `docs/api/XCEngine/Rendering/**` `docs/api/XCEngine/Resources/Shader/**` | `pending` | | -| `R3` | Editor 失效页清理 | 删除或退役 `XCUIDemoPanel / SceneViewportOverlayRenderer`，并修正所有反向引用 | `docs/api/XCEngine/Editor/**` | `pending` | | -| `R4` | Volume 资源与运行时主链 | 补齐 `Volume / VolumeField / VolumeFieldLoader / VolumeRendererComponent / VisibleVolumeItem / BuiltinVolumetricPass` | `docs/api/XCEngine/Resources/**` `docs/api/XCEngine/Components/**` `docs/api/XCEngine/Rendering/**` | `pending` | | -| `R5` | Selection pass 结构补齐 | 补齐 `BuiltinSelectionMaskPass` 与 `BuiltinSelectionOutlinePass`，并同步 `Passes.md` | `docs/api/XCEngine/Rendering/Passes/**` | `pending` | | -| `R6` | UI 新 helper | 补齐 `UIDragDropInteraction` 与 `UIScrollModel`，并同步 `Widgets.md` | `docs/api/XCEngine/UI/Widgets/**` | `pending` | | -| `R7` | Editor 当前真实 helper | 补齐 `VolumeRendererComponentEditor / MaterialInspectorMaterialState / MaterialInspectorMaterialStateIO`，并同步 `ComponentEditors.md` 与 `panels.md` | `docs/api/XCEngine/Editor/**` | `pending` | | +| `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` | | diff --git a/docs/plan/API文档目录重构计划_2026-04-09.md b/docs/plan/API文档目录重构计划_2026-04-09.md index 0fbdb7ce..ed3c8207 100644 --- a/docs/plan/API文档目录重构计划_2026-04-09.md +++ b/docs/plan/API文档目录重构计划_2026-04-09.md @@ -5,11 +5,26 @@ 当前 API 文档树已经出现明显的“双主线错位”： - `docs/api/XCEngine/Editor/**` 主要对应旧 `editor/src/**` 的 ImGui 编辑器应用层。 -- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线，但几乎没有进入当前 canonical API 树。 -- 现有审计脚本只覆盖 `engine/include/XCEngine/**` 与 `editor/src/**`，没有覆盖 `new_editor/include/XCEditor/**`。 +- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线。 +- 这条主线最初没有进入当前 canonical API 树，审计脚本也一度没有覆盖 `new_editor/include/XCEditor/**`。 这意味着继续只在 `docs/api/XCEngine/Editor/**` 上增量修补，会越来越偏离真实代码结构。 +## 1.1 2026-04-10 状态更新 + +截至 `2026-04-10 17:07:09`，以下阶段已经落地： + +- `docs/api/XCEditor/**` 已建立并进入 canonical 根树 +- 审计脚本已经覆盖： + - `engine/include/XCEngine/**` + - `new_editor/include/XCEditor/**` + - `editor/src/**` +- `docs/api/main.md` 已建立 `XCEngine + XCEditor` 双根入口 +- `XCUIDemoPanel` 已退出当前 canonical API 树 +- `Resources/Model` 与 `Resources/GaussianSplat` 已补齐 canonical 入口 + +因此这份计划里“为什么要拆出 `XCEditor` 根树”的判断仍然有效，但 `Phase B / C` 不再是未来动作，而是已完成事实。 + ## 2. 当前判断 ### 2.1 旧 `Editor` 文档树继续保留，但必须收紧边界 @@ -18,9 +33,9 @@ - 不再把它当成未来 Editor 主线 API 树。 - 其中 `Application / EditorResources / Theme / XCUIBackend / panels / Viewport` 等内容，明确视为旧编辑器应用层。 -### 2.2 新主线应拆出独立文档树 +### 2.2 新主线已拆出独立文档树 -建议新增： +当前已新增： - `docs/api/XCEditor/` @@ -57,24 +72,24 @@ - `XCEditor/Shell/*` - `XCEditor/Widgets/*` -但 `docs/api` 里没有对应的 `XCEditor` 根树。 +现在 `docs/api` 里已经有对应的 `XCEditor` 根树。 ### 3.2 旧树中仍混有已经过时的过渡页 -当前至少已经发现： +当前这类问题已经完成清理，最典型的是： - `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md` - 仍引用已不存在的 `editor/src/panels/XCUIDemoPanel.h` -这类页面需要单独清理，不能继续假设旧源码路径仍成立。 +这类页面已经从 active canonical 树移除，不再继续假设旧源码路径仍成立。 ### 3.3 审计工具口径落后 -当前 `docs/api/_tools/audit_api_docs.py` 的覆盖口径没有把： +当前这项问题已经收口；审计脚本现在已经把： - `new_editor/include/XCEditor/**/*.h` -纳入 canonical 统计，所以即使新主线完全缺文档，审计也不会报警。 +纳入 canonical 统计，`XCEditor` 缺页会直接出现在审计结果里。 ## 4. 分阶段执行 @@ -84,7 +99,7 @@ - 修掉旧树里已经失效的 source refs。 - 继续补齐旧 `editor/src/**` 当前缺失的 canonical 页，避免现有审计长期失真。 -## Phase B：建立 `XCEditor` 新根树 +## Phase B：建立 `XCEditor` 新根树（已完成） - 新建 `docs/api/XCEditor/XCEditor.md` - 新建 5 个首层 overview： @@ -95,7 +110,7 @@ - `Widgets` - 建立 `docs/api/main.md` 到新根树的入口链接 -## Phase C：接入新审计口径 +## Phase C：接入新审计口径（已完成） - 扩展审计脚本识别 `new_editor/include/XCEditor/**/*.h` - 统计 `docs/api/XCEditor/**` 的 canonical 覆盖率 @@ -103,7 +118,7 @@ - 旧 `editor/src/**` 应用层源码页 - 新 `XCEditor/**` public header 页 -## Phase D：按新主线分批补页 +## Phase D：按新主线分批补页（进行中） 推荐顺序： @@ -119,7 +134,7 @@ - `Collections` / `Fields` 数量多，但结构相对规整，适合并行。 - `Shell` 依赖最多，最好放后面统一写。 -## Phase E：旧树去历史包袱 +## Phase E：旧树去历史包袱（进行中） - 删除或改写已经脱离旧源码的过渡页 - 把“旧 editor 参考实现”和“new_editor 正式主线”在相关 overview 中互相链接，但不再混放 @@ -127,8 +142,7 @@ ## 5. 本轮执行口径 -本轮先按两条线同时推进： - -1. 先把现有审计缺口补齐，保证旧树不继续烂下去。 -2. 同时开始落 `XCEditor` 文档树重构计划和入口边界说明，为下一轮结构迁移做准备。 +当前后续重点已经转到： +1. 继续回归高风险 `RHI / Rendering / Editor/Viewport` 内容页，避免源码继续演进后文档再次漂移。 +2. 继续清理旧树里的历史空目录、重复入口和剩余结构噪音。