gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-13 22:25:37 +08:00
Code Issues Packages Projects Releases Wiki Activity
GFramework/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
gewuyou 007c33f772 docs(game): 刷新 Game 模块文档基线 
- 更新 Game family README、landing 与 abstractions 页面，补齐声明级 XML inventory 入口

- 修复 Game.Abstractions 页面与当前源码不一致的旧接口摘录，改写为真实契约边界与最小接入路径

- 补充 ai-plan 跟踪与 trace，推进恢复点到 RP-005 并记录验证结果
2026-04-23 07:30:03 +08:00

181 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Documentation Full Coverage Governance Trace
## 2026-04-22
### 当前恢复点：RP-001
- 按长期治理计划新建 active topic `documentation-full-coverage-governance`
- 在 `ai-plan/public/README.md` 中将当前分支 `docs/sdk-update-documentation` 映射到该 topic
- 复核已知缺口模块的 `*.csproj` 后确认：
- `GFramework.Ecs.Arch.Abstractions` 是可打包消费模块，需要独立 README
- `GFramework.Core.SourceGenerators.Abstractions`、`GFramework.Godot.SourceGenerators.Abstractions`、
`GFramework.SourceGenerators.Common` 都是 `IsPackable=false` 的内部支撑模块
- 基于该结论，本轮没有为内部支撑模块新增独立 README，而是在根 README 与 abstractions / API 入口中明确其 owner
### 当前决策
- 新主题的完成条件采用长期治理口径：`P0` 清零、无 README 缺失、无导航死链，并完成连续两轮稳定巡检
- 本轮先做治理基础设施与 inventory，不把整个长期计划伪装成单轮完成
- `api-reference` 页面改为“模块 -> README / docs / XML / tutorial”的阅读链路入口，避免继续维护失真的伪签名列表
- `Ecs.Arch` family 被列为高优先 backlog：抽象层入口已补齐，但 runtime docs 仍需按源码重写
- `Core` / `Core.Abstractions` 波次先收口 README、landing page 和 abstractions 页的目录映射，再补显式 XML 覆盖 inventory
- VitePress 站内页面不直接链接仓库根模块 `README.md`；站内仅保留可构建的 docs 链接，模块 README 以文本路径或仓库 README 承接
### 当前恢复点：RP-002
- 完成 `Core` / `Core.Abstractions` 的类型族级 XML inventory：
- `GFramework.Core/README.md`
- `GFramework.Core.Abstractions/README.md`
- `docs/zh-CN/core/index.md`
- `docs/zh-CN/abstractions/core-abstractions.md`
- 通过顶层目录轻量盘点确认：
- `GFramework.Core` 当前各目录族的公开 / 内部类型声明都已带 XML 注释
- `GFramework.Core.Abstractions` 当前各契约目录族的公开 / 内部类型声明都已带 XML 注释
- 这轮 inventory 明确限定为“类型声明级基线”，不把结果表述成成员级 XML 合规审计
### 当前决策（RP-002）
- XML inventory 同时落在模块 README 和站内 landing page：
- README 提供仓库侧入口，方便从包目录直接恢复上下文
- docs landing 提供更细的类型族 / 代表类型 / 阅读重点表格，方便站内导航
- `Core` 波次在补齐基线后转入巡检，不继续在本轮展开成员级 ``<param>`` / ``<returns>`` 审计
- 下一恢复点切换到 `Ecs` 波次，优先处理仍明显失真的 runtime docs
### 当前验证
- 文档校验：
- `validate-all.sh docs/zh-CN/abstractions/index.md`：通过
- `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
- `validate-all.sh docs/zh-CN/api-reference/index.md`：通过
- `validate-all.sh docs/zh-CN/core/index.md`：通过
- `validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`：通过
- 构建校验：
- `cd docs && bun run build`：通过
- `DOTNET_CLI_HOME=/tmp/dotnet-home dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)`
- `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`：通过，`0 Warning(s) / 0 Error(s)`
### 当前验证（RP-002）
- 文档校验：
- `validate-all.sh docs/zh-CN/core/index.md`：通过
- `validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`：通过
- 构建校验：
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
### 当前恢复点：RP-003
- 完成 `Ecs.Arch` 波次的运行时文档刷新：
- `docs/zh-CN/ecs/index.md`
- `docs/zh-CN/ecs/arch.md`
- `GFramework.Ecs.Arch/README.md`
- 为 `Ecs.Arch.Abstractions` 补齐与运行时页同粒度的 XML inventory：
- `GFramework.Ecs.Arch.Abstractions/README.md`
- `docs/zh-CN/abstractions/ecs-arch-abstractions.md`
- 明确记录一个关键采用事实：
- `UseArch(...)` 必须早于 `Initialize()` 调用
- 该结论以 `ArchExtensions` 的模块注册方式和 `ExplicitRegistrationTests` 为证据
- 将 `Ecs.Arch` family 从“入口存在但失真”推进到“README / landing / abstractions / XML inventory 已对齐源码与测试”
### 当前决策（RP-003）
- `Ecs` 波次继续采用与 `Core` 相同的治理粒度：
- 模块 README 承担仓库入口
- `docs/zh-CN/ecs/index.md` 承担模块族 landing
- `docs/zh-CN/ecs/arch.md` 承担运行时默认实现专题页
- `docs/zh-CN/abstractions/ecs-arch-abstractions.md` 承担契约边界专题页
- `EnableStatistics` 当前仅保留在公开配置面上；文档不再把它写成已验证的运行时行为
- 下一恢复点切换到 `Cqrs` 波次，优先解决入口分散和 API / XML 阅读链路不统一的问题
### 当前验证（RP-003）
- 文档校验：
- `validate-all.sh docs/zh-CN/ecs/index.md`：通过
- `validate-all.sh docs/zh-CN/ecs/arch.md`：通过
- `validate-all.sh docs/zh-CN/abstractions/ecs-arch-abstractions.md`：通过
- 构建校验：
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
### 下一步
1. 在 `Cqrs` 波次核对模块 README、`docs/zh-CN/core/cqrs.md` 与 `docs/zh-CN/source-generators/**` 的真实 owner
2. 决定 `Cqrs` family 是补 dedicated landing 还是拆分现有入口页
### 当前恢复点：RP-004
- 完成 `Cqrs` 波次的模块族入口刷新：
- 重写 `docs/zh-CN/core/cqrs.md`
- 新建 `docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`
- 更新 `docs/zh-CN/source-generators/index.md`
- 更新 `docs/zh-CN/api-reference/index.md`
- 更新 `docs/.vitepress/config.mts`
- 将 `Cqrs` family 从“README 已存在但 generator 入口分散”推进到“runtime / abstractions / source generator 都有明确站内入口”
- 为 `GFramework.Cqrs/Internal/CqrsHandlerRegistrar.cs` 与
`GFramework.Cqrs.SourceGenerators/Cqrs/CqrsHandlerRegistryGenerator.cs` 中缺失的内部类型补齐 XML 注释
- 基于轻量扫描确认：
- `GFramework.Cqrs.Abstractions/Cqrs/` 当前类型声明级 XML 覆盖为 `20/20`
- `GFramework.Cqrs` 根入口与 `Internal/` 已补到 `19/19`
- `GFramework.Cqrs.SourceGenerators/Cqrs/` 当前类型声明级 XML 覆盖为 `3/3`
### 当前决策（RP-004）
- `docs/zh-CN/core/cqrs.md` 继续保留在 `Core` 栏目，但其角色调整为 `Cqrs` family landing，而不再只是 runtime 简介页
- `Cqrs.SourceGenerators` 不单独新建一级导航栏目，而是在 `source-generators` 栏目内补一个专用专题页，保持站点 taxonomy 稳定
- generator 入口以“专题页 + API reference 链接 + sidebar”三点联动，而不是只在 `source-generators/index.md` 留一个段落链接
- XML inventory 仍维持“类型声明级基线”口径，不在本轮扩展成成员级 `param/returns/exception` 细审
### 当前验证（RP-004）
- 文档校验：
- `validate-all.sh docs/zh-CN/core/cqrs.md`：通过
- `validate-all.sh docs/zh-CN/source-generators/cqrs-handler-registry-generator.md`：通过
- 轻量 XML inventory：
- `GFramework.Cqrs/Internal/`：`14/14`
- `GFramework.Cqrs.Abstractions/Cqrs/`：`20/20`
- `GFramework.Cqrs.SourceGenerators/Cqrs/`：`3/3`
- 构建校验：
- `dotnet build GFramework.Cqrs.SourceGenerators/GFramework.Cqrs.SourceGenerators.csproj -c Release -p:RestoreFallbackFolders=`：通过
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
- `dotnet build GFramework.Cqrs/GFramework.Cqrs.csproj -c Release`：失败；当前 WSL / dotnet 环境仍引用失效的 Windows fallback package folder，并在多目标 inner build 阶段触发 `MSB4276` / `MSB4018`
### 下一步
1. 切换到 `Game` family 波次，按 `Core` / `Ecs` / `Cqrs` 已验证模板继续补 XML inventory 与教程链路
2. 把 `GFramework.Cqrs` 的本地构建阻塞留给后续环境治理或构建脚本清理，不在本 topic 内扩张为环境修复任务
### 当前恢复点：RP-005
- 完成 `Game` 波次的模块族入口刷新：
- 更新 `GFramework.Game/README.md`
- 更新 `GFramework.Game.Abstractions/README.md`
- 更新 `GFramework.Game.SourceGenerators/README.md`
- 更新 `docs/zh-CN/game/index.md`
- 重写 `docs/zh-CN/abstractions/game-abstractions.md`
- 将 `Game` family 从“README / 页面存在但缺少可审计 XML 入口，且 abstractions 页失真”推进到“runtime / abstractions / source generator 都有声明级 XML inventory 与真实采用边界”
- 基于轻量扫描确认：
- `GFramework.Game` 当前类型声明级 XML 覆盖为 `56/56`
- `GFramework.Game.Abstractions` 当前类型声明级 XML 覆盖为 `80/80`
- `GFramework.Game.SourceGenerators` 当前类型声明级 XML 覆盖为 `2/2`
### 当前决策（RP-005）
- `docs/zh-CN/abstractions/game-abstractions.md` 不再维护虚构接口摘录，而是与源码中的 `Config` / `Data` / `Setting` / `Scene` / `UI` / `Routing` 契约分组保持一致
- `Game.SourceGenerators` 继续以 `README + docs/zh-CN/game/config-system.md + docs/zh-CN/source-generators/index.md` 组成入口，不额外新增只为凑数量的专题页
- `docs/zh-CN/game/index.md` 补 frontmatter，并承担 `Game` family 的 XML 基线入口；更细的类型族说明继续留在模块 README 与 abstractions 页
### 当前验证（RP-005）
- 文档校验：
- `validate-all.sh docs/zh-CN/abstractions/game-abstractions.md`：通过
- `validate-all.sh docs/zh-CN/game/index.md`：通过
- 轻量 XML inventory：
- `GFramework.Game`：`56/56`
- `GFramework.Game.Abstractions`：`80/80`
- `GFramework.Game.SourceGenerators`：`2/2`
- 构建校验：
- `cd docs && bun run build`：通过；仅保留 VitePress 大 chunk warning，无构建失败
### 下一步
1. 进入 `Game` family 巡检，优先检查 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 的交叉引用是否回漂
2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic，减少对 archive 的依赖
Reference in New Issue View Git Blame Copy Permalink