gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-06 16:16:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(core): 补齐 Core XML 覆盖基线清单

Browse Source 
- 补充 Core 与 Core.Abstractions README 的类型族级 XML 覆盖基线入口

- 更新 Core 与 Core.Abstractions landing page 的 XML inventory、代表类型和阅读重点

- 同步刷新 documentation-full-coverage-governance 的 tracking 与 trace 恢复点
This commit is contained in:
GeWuYou 2026-04-22 15:54:12 +08:00
parent 704fdaa2c8
commit af21f16c09
6 changed files with 117 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
GFramework.Core.Abstractions/README.md
View File

@ -34,6 +34,23 @@
| `Data/` `Serializer/` `Storage/` `Versioning/` | 数据装载、序列化、存储与版本化契约 |
| `Enums/` `Properties/` | 架构阶段枚举，以及架构 / logger 相关属性键 |
## XML 覆盖基线
截至 `2026-04-22`，已按顶层目录对 `GFramework.Core.Abstractions` 的公开 / 内部类型声明做过一轮轻量盘点；当前契约目录族的类型声明都已带
XML 注释。这里记录的是类型族级基线，成员级契约细节仍需要在后续波次继续审计。
| 类型族 | 基线状态 | 代表类型 |
| --- | --- | --- |
| `Architectures/` `Lifecycle/` `Registries/` | `20/20` 个类型声明已带 XML 注释 | `IArchitecture`、`IArchitectureContext`、`IServiceModule`、`KeyValueRegistryBase<TKey, TValue>` |
| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncQueryExecutor`、`ICqrsRuntime` |
| `Events/` `Property/` `State/` `StateManagement/` | `25/25` 个类型声明已带 XML 注释 | `IEventBus`、`IBindableProperty<T>`、`IStateMachine`、`IStore<TState>` |
| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `17/17` 个类型声明已带 XML 注释 | `IYieldInstruction`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` |
| `Resource/` `Pool/` `Logging/` `Localization/` | `27/27` 个类型声明已带 XML 注释 | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`ILocalizationManager` |
| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `7/7` 个类型声明已带 XML 注释 | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom<T>`、`ISerializer`、`IStorage` |
| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` |
完整 inventory 与阅读顺序见 `docs/zh-CN/abstractions/core-abstractions.md`。
## 采用建议
- 框架消费者通常同时安装 `GFramework.Core` 与 `GFramework.Core.Abstractions`

17
GFramework.Core/README.md
View File

@ -60,6 +60,23 @@
| `Functional/` | `Option`、`Result` 等轻量函数式工具 |
| `Extensions/` | 上下文与集合等扩展方法 |
## XML 覆盖基线
截至 `2026-04-22`，已按顶层目录对 `GFramework.Core` 的公开 / 内部类型声明做过一轮轻量盘点；当前主目录族的类型声明都已带
XML 注释。这里先保留阅读基线，成员级 ``<param>`` / ``<returns>`` / 生命周期语义审计仍属于后续治理项。
| 类型族 | 基线状态 | 代表类型 |
| --- | --- | --- |
| `Architectures/` `Services/` | `22/22` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ServiceModuleManager` |
| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand<TInput>`、`AbstractQuery<TResult>` |
| `Events/` `Property/` `State/` `StateManagement/` | `29/29` 个类型声明已带 XML 注释 | `EventBus`、`BindableProperty<T>`、`StateMachine`、`Store<TState>` |
| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`PauseStackManager`、`AsyncKeyLockManager` |
| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`AbstractObjectPoolSystem<TKey, TObject>` |
| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `31/31` 个类型声明已带 XML 注释 | `ConsoleLogger`、`LocalizationManager`、`ConfigurationManager`、`DefaultEnvironment`、`MicrosoftDiContainer` |
| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `34/34` 个类型声明已带 XML 注释 | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result<T>` |
完整的模块化阅读顺序和 inventory 说明见 `docs/zh-CN/core/index.md`。
## 最小接入路径
```bash

32
ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md
View File

@ -12,13 +12,12 @@
## 当前恢复点
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-001`
- 当前阶段：`Phase 1 - Inventory And Governance Bootstrap`
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-002`
- 当前阶段：`Phase 2 - Ecs Runtime Docs Refresh`
- 当前焦点：
- 注册新的长期文档治理 topic，并把当前分支映射到该 topic
- 落第一版模块化 inventory、缺口分级和治理波次顺序
- 立即补齐已确认的 README / 入口缺口：`GFramework.Ecs.Arch.Abstractions`
- 把 `api-reference` 页面改成真实的 API 链路入口，而不是失真的伪 API 列表
- 重写 `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md`
- 为 `Ecs.Arch` / `Ecs.Arch.Abstractions` 建立 runtime / abstractions / XML 阅读链路
- 继续把模块族 inventory 从“入口存在”推进到“可审计的 XML / README / landing 对照表”
## 当前状态摘要
@ -37,12 +36,15 @@
- 为 `GFramework.Core.Abstractions/README.md` 补齐契约族地图与 XML 阅读重点
- 将 `docs/zh-CN/abstractions/core-abstractions.md` 从过时的接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面
- 为 `docs/zh-CN/core/index.md` 补齐 frontmatter、能力域导航和 API / XML 阅读入口
- 为 `GFramework.Core/README.md`、`GFramework.Core.Abstractions/README.md` 补齐类型族级 XML 覆盖基线入口
- 为 `docs/zh-CN/core/index.md`、`docs/zh-CN/abstractions/core-abstractions.md` 增加“类型族 -> XML 覆盖状态 -> 代表类型”的 inventory
- 基于顶层目录轻量盘点确认：`Core` / `Core.Abstractions` 当前公开 / 内部类型声明都已带 XML 注释，成员级审计留待后续波次
## Inventory（第一版）
| 模块族 | 当前状态 | 当前证据 | 下一动作 |
| --- | --- | --- | --- |
| `Core` / `Core.Abstractions` | `入口已收口，XML inventory 待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与采用路径 | 下一恢复点为类型族级 XML 覆盖清单 |
| `Core` / `Core.Abstractions` | `README / landing / 类型族级 XML inventory 已收口，成员级审计待补齐` | 根 README、模块 README、`docs/zh-CN/core/**`、`docs/zh-CN/abstractions/core-abstractions.md` 已对齐当前目录与类型族基线 | 进入巡检；如有新 API 变更，再追加成员级 XML 审计 |
| `Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators` | `待重写` | README 已存在；站内入口目前分散在 `docs/zh-CN/core/cqrs.md` 与 `docs/zh-CN/source-generators/**` | 在 `Cqrs` 波次里补 dedicated landing / API map 审计 |
| `Game` / `Game.Abstractions` / `Game.SourceGenerators` | `已验证` | 根 README、模块 README、`docs/zh-CN/game/**` 和 abstractions 页已存在 | 后续波次补 XML / 教程链路审计 |
| `Godot` / `Godot.SourceGenerators` | `已验证` | 上一轮归档 topic 已完成核心 landing / topic / tutorial 校验 | 进入巡检周期，重点看回漂 |
@ -66,8 +68,10 @@
- `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md` 仍保留较多早期表述，本轮只先完成 inventory 与入口补齐
- 缓解措施：把 `Ecs.Arch` 排进前五波次，并把 runtime docs 重写列为该波次的必做项
- XML 文档尚未按模块做全量类型审计
- 缓解措施：当前已补 `Core` / `Core.Abstractions` 的 XML 阅读入口；下一恢复点继续建立“类型族 -> XML 覆盖状态”清单
- 当前 `Core` / `Core.Abstractions` 只完成了类型族级 XML 基线，不等于成员级契约全审计
- 缓解措施：后续只在共享抽象或高风险生命周期接口发生改动时补成员级细审，不在本轮扩张范围
- 其他模块族尚未全部建立同粒度的 XML inventory
- 缓解措施：按 `Ecs`、`Cqrs`、`Game` 的波次顺序继续推广同一模板
- 新功能分支若修改 README / docs / 公共 API 却不挂文档 topic，仍可能回漂
- 缓解措施：将本 topic 作为长期 active topic 保留，并在后续巡检中记录回漂来源
- VitePress 页面不能直接链接到 `docs/` 目录之外的模块 `README.md`
@ -83,11 +87,13 @@
- 结果：通过
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core/index.md`
- 结果：通过
- 备注：`2026-04-22` 在补充 Core XML inventory 后重新验证
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/abstractions/core-abstractions.md`
- 结果：通过
- 备注：`2026-04-22` 在补充 Core.Abstractions XML inventory 后重新验证
- `cd docs && bun run build`
- 结果：通过
- 备注：仅保留 VitePress 大 chunk warning，无构建失败
- 备注：`2026-04-22` 重新构建通过；仅保留 VitePress 大 chunk warning，无构建失败
- `dotnet build GFramework.Ecs.Arch.Abstractions/GFramework.Ecs.Arch.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
- 结果：通过
- 备注：`0 Warning(s) / 0 Error(s)`
@ -97,6 +103,6 @@
## 下一步
1. 继续 `Core` / `Core.Abstractions` 波次，为公开类型族补一份“类型族 -> XML 覆盖状态”清单
2. 在 `Ecs` 波次重写 `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md`
3. 为每个模块族补一份“README / landing / tutorials / API reference / XML”对照表，持续清零 `P0` / `P1`
1. 进入 `Ecs` 波次，按源码重写 `docs/zh-CN/ecs/index.md` 与 `docs/zh-CN/ecs/arch.md`
2. 为 `Ecs.Arch` / `Ecs.Arch.Abstractions` 建立与 `Core` 同粒度的 XML / README / landing inventory
3. 继续为每个模块族补“README / landing / tutorials / API reference / XML”对照表，持续清零 `P0` / `P1`

32
ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md
View File

@ -21,6 +21,26 @@
- `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
### 当前验证
- 文档校验：
@ -34,7 +54,15 @@
- `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，无构建失败
### 下一步
1. 继续 `Core` / `Core.Abstractions` 波次，按类型族建立 XML 文档覆盖 inventory
2. 在 `Ecs` 波次重写运行时 docs，并把 `Ecs.Arch.Abstractions` 纳入完整模块闭环
1. 在 `Ecs` 波次重写运行时 docs，并把 `Ecs.Arch.Abstractions` 纳入完整模块闭环
2. 为 `Ecs.Arch` / `Ecs.Arch.Abstractions` 建立与 `Core` 同粒度的 XML inventory 基线

17
docs/zh-CN/abstractions/core-abstractions.md
View File

@ -77,6 +77,23 @@ public sealed class DiagnosticsFeature
- 状态与并发能力：`IStateMachine`、`IStore`、`IAsyncKeyLockManager`、`ITimeProvider`
- 迁移与组合边界：`ICommandExecutor`、`IQueryExecutor`、`ICqrsRuntime`
## XML 覆盖基线
下面这份 inventory 记录的是 `2026-04-22` 对 `GFramework.Core.Abstractions` 做的一轮轻量 XML 盘点结果：只统计公开 /
内部类型声明是否带 XML 注释，用来建立契约层阅读入口；成员级参数、返回值、异常与生命周期说明仍需要后续波次继续细化。
| 契约族 | 基线状态 | 代表类型 | 阅读重点 |
| --- | --- | --- | --- |
| `Architectures/` | `12/12` 个类型声明已带 XML 注释 | `IArchitecture`、`IArchitectureContext`、`IArchitectureServices`、`IServiceModule` | 看架构上下文、服务访问面与模块安装 / 生命周期约束 |
| `Lifecycle/` `Registries/` | `8/8` 个类型声明已带 XML 注释 | `ILifecycle`、`IAsyncInitializable`、`IRegistry<T, TR>`、`KeyValueRegistryBase<TKey, TValue>` | 看初始化 / 销毁阶段和注册表抽象边界 |
| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncCommand<TResult>`、`IQueryExecutor`、`ICqrsRuntime` | 看旧命令 / 查询接口与新请求模型之间的兼容和迁移边界 |
| `Events/` `Property/` | `10/10` 个类型声明已带 XML 注释 | `IEventBus`、`IEventFilter<T>`、`IBindableProperty<T>`、`IReadonlyBindableProperty<T>` | 看事件传播、过滤、解绑对象和属性订阅语义 |
| `State/` `StateManagement/` | `15/15` 个类型声明已带 XML 注释 | `IStateMachine`、`IAsyncState`、`IStore<TState>`、`IStoreMiddleware<TState>` | 看状态机契约与 Store 的 reducer / middleware / diagnostics 边界 |
| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `17/17` 个类型声明已带 XML 注释 | `IYieldInstruction`、`ICoroutineStatistics`、`ITimeProvider`、`IPauseStackManager`、`IAsyncKeyLockManager` | 看调度模型、时间源、暂停栈和异步锁契约 |
| `Resource/` `Pool/` `Logging/` `Localization/` | `27/27` 个类型声明已带 XML 注释 | `IResourceManager`、`IObjectPoolSystem`、`ILogger`、`IStructuredLogger`、`ILocalizationManager` | 看资源 / 池化 / 日志 / 本地化这些基础设施的宿主责任 |
| `Configuration/` `Environment/` `Data/` `Serializer/` `Storage/` `Versioning/` | `7/7` 个类型声明已带 XML 注释 | `IConfigurationManager`、`IEnvironment`、`ILoadableFrom<T>`、`ISerializer`、`IStorage`、`IVersioned` | 看配置、环境、序列化和持久化边界，以及谁负责具体实现 |
| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 看基础角色接口、辅助值对象和架构属性键的复用方式 |
## 阅读顺序
1. 先读本页，确认你是否真的只需要契约层

17
docs/zh-CN/core/index.md
View File

@ -82,6 +82,23 @@ dotnet add package GeWuYou.GFramework.Core.Abstractions
统一入口见 [`../api-reference/index.md`](../api-reference/index.md)。
## XML 覆盖基线
下面这份 inventory 记录的是 `2026-04-22` 对 `GFramework.Core` 做的一轮轻量 XML 盘点结果：只统计顶层目录中的公开 /
内部类型声明是否带 XML 注释，用来确认阅读入口和治理优先级；成员级 ``<param>``、``<returns>``、异常语义与线程说明仍需要继续细审。
| 类型族 | 基线状态 | 代表类型 | 阅读重点 |
| --- | --- | --- | --- |
| `Architectures/` | `16/16` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ArchitecturePhaseCoordinator` | 看架构启动、模块安装、阶段切换和上下文暴露边界 |
| `Services/` | `6/6` 个类型声明已带 XML 注释 | `ServiceModuleManager`、`CommandExecutorModule`、`CqrsRuntimeModule` | 看服务模块的注册顺序、销毁语义和默认接线 |
| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand<TInput>`、`AbstractQuery<TResult>` | 看旧入口兼容面与向 `CQRS` 迁移时还保留了哪些执行契约 |
| `Events/` `Property/` | `19/19` 个类型声明已带 XML 注释 | `EventBus`、`EnhancedEventBus`、`BindableProperty<T>`、`OrEvent<T>` | 看事件传播、解绑约束和可绑定属性的订阅语义 |
| `State/` `StateManagement/` | `10/10` 个类型声明已带 XML 注释 | `StateMachine`、`StateMachineSystem`、`Store<TState>`、`StoreBuilder<TState>` | 看状态切换、selector / middleware / dispatch 的单向流边界 |
| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`WaitForSecondsRealtime`、`PauseStackManager`、`AsyncKeyLockManager` | 看调度阶段、等待指令、时间源和暂停 / 锁的线程语义 |
| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`ManualReleaseStrategy`、`AbstractObjectPoolSystem<TKey, TObject>` | 看资源句柄释放策略与对象池复用约束 |
| `Logging/` `Localization/` `Configuration/` `Environment/` `Ioc/` | `31/31` 个类型声明已带 XML 注释 | `ConsoleLogger`、`CompositeLogger`、`LocalizationManager`、`ConfigurationManager`、`MicrosoftDiContainer` | 看日志组装、格式化 / filter、配置监听、环境对象与容器适配 |
| `Model/` `Systems/` `Utility/` `Rule/` `Extensions/` `Functional/` | `34/34` 个类型声明已带 XML 注释 | `AbstractModel`、`AbstractSystem`、`NumericDisplayFormatter`、`ContextAwareBase`、`Result<T>` | 看默认基类、上下文感知 helper、数值格式化和通用扩展的使用边界 |
## 最小接入路径
当前版本的最小运行时入口只有三个关键动作：