diff --git a/GFramework.Core.Abstractions/README.md b/GFramework.Core.Abstractions/README.md index 410a5822..d6a9753b 100644 --- a/GFramework.Core.Abstractions/README.md +++ b/GFramework.Core.Abstractions/README.md @@ -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` | +| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncQueryExecutor`、`ICqrsRuntime` | +| `Events/` `Property/` `State/` `StateManagement/` | `25/25` 个类型声明已带 XML 注释 | `IEventBus`、`IBindableProperty`、`IStateMachine`、`IStore` | +| `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`、`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` diff --git a/GFramework.Core/README.md b/GFramework.Core/README.md index eaae5ece..61e89a8a 100644 --- a/GFramework.Core/README.md +++ b/GFramework.Core/README.md @@ -60,6 +60,23 @@ | `Functional/` | `Option`、`Result` 等轻量函数式工具 | | `Extensions/` | 上下文与集合等扩展方法 | +## XML 覆盖基线 + +截至 `2026-04-22`，已按顶层目录对 `GFramework.Core` 的公开 / 内部类型声明做过一轮轻量盘点；当前主目录族的类型声明都已带 +XML 注释。这里先保留阅读基线，成员级 ```` / ```` / 生命周期语义审计仍属于后续治理项。 + +| 类型族 | 基线状态 | 代表类型 | +| --- | --- | --- | +| `Architectures/` `Services/` | `22/22` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ServiceModuleManager` | +| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand`、`AbstractQuery` | +| `Events/` `Property/` `State/` `StateManagement/` | `29/29` 个类型声明已带 XML 注释 | `EventBus`、`BindableProperty`、`StateMachine`、`Store` | +| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`PauseStackManager`、`AsyncKeyLockManager` | +| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`AbstractObjectPoolSystem` | +| `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` | + +完整的模块化阅读顺序和 inventory 说明见 `docs/zh-CN/core/index.md`。 + ## 最小接入路径 ```bash diff --git a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md index 22bc302c..1ff39bb7 100644 --- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -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` diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index cb71b105..aefa3a40 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -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` 波次在补齐基线后转入巡检，不继续在本轮展开成员级 ```` / ```` 审计 +- 下一恢复点切换到 `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 基线 diff --git a/docs/zh-CN/abstractions/core-abstractions.md b/docs/zh-CN/abstractions/core-abstractions.md index d42386e1..24a922ab 100644 --- a/docs/zh-CN/abstractions/core-abstractions.md +++ b/docs/zh-CN/abstractions/core-abstractions.md @@ -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`、`KeyValueRegistryBase` | 看初始化 / 销毁阶段和注册表抽象边界 | +| `Command/` `Query/` `Cqrs/` | `10/10` 个类型声明已带 XML 注释 | `ICommandExecutor`、`IAsyncCommand`、`IQueryExecutor`、`ICqrsRuntime` | 看旧命令 / 查询接口与新请求模型之间的兼容和迁移边界 | +| `Events/` `Property/` | `10/10` 个类型声明已带 XML 注释 | `IEventBus`、`IEventFilter`、`IBindableProperty`、`IReadonlyBindableProperty` | 看事件传播、过滤、解绑对象和属性订阅语义 | +| `State/` `StateManagement/` | `15/15` 个类型声明已带 XML 注释 | `IStateMachine`、`IAsyncState`、`IStore`、`IStoreMiddleware` | 看状态机契约与 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`、`ISerializer`、`IStorage`、`IVersioned` | 看配置、环境、序列化和持久化边界，以及谁负责具体实现 | +| `Bases/` `Controller/` `Model/` `Systems/` `Utility/` `Rule/` `Enums/` `Properties/` | `19/19` 个类型声明已带 XML 注释 | `IPrioritized`、`IController`、`IModel`、`ISystem`、`IContextUtility`、`ArchitecturePhase` | 看基础角色接口、辅助值对象和架构属性键的复用方式 | + ## 阅读顺序 1. 先读本页，确认你是否真的只需要契约层 diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index 931197f8..d712b50b 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -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 注释，用来确认阅读入口和治理优先级；成员级 ````、````、异常语义与线程说明仍需要继续细审。 + +| 类型族 | 基线状态 | 代表类型 | 阅读重点 | +| --- | --- | --- | --- | +| `Architectures/` | `16/16` 个类型声明已带 XML 注释 | `Architecture`、`ArchitectureContext`、`ArchitectureLifecycle`、`ArchitecturePhaseCoordinator` | 看架构启动、模块安装、阶段切换和上下文暴露边界 | +| `Services/` | `6/6` 个类型声明已带 XML 注释 | `ServiceModuleManager`、`CommandExecutorModule`、`CqrsRuntimeModule` | 看服务模块的注册顺序、销毁语义和默认接线 | +| `Command/` `Query/` | `15/15` 个类型声明已带 XML 注释 | `CommandExecutor`、`AsyncQueryExecutor`、`AbstractCommand`、`AbstractQuery` | 看旧入口兼容面与向 `CQRS` 迁移时还保留了哪些执行契约 | +| `Events/` `Property/` | `19/19` 个类型声明已带 XML 注释 | `EventBus`、`EnhancedEventBus`、`BindableProperty`、`OrEvent` | 看事件传播、解绑约束和可绑定属性的订阅语义 | +| `State/` `StateManagement/` | `10/10` 个类型声明已带 XML 注释 | `StateMachine`、`StateMachineSystem`、`Store`、`StoreBuilder` | 看状态切换、selector / middleware / dispatch 的单向流边界 | +| `Coroutine/` `Time/` `Pause/` `Concurrency/` | `43/43` 个类型声明已带 XML 注释 | `CoroutineScheduler`、`CoroutineHandle`、`WaitForSecondsRealtime`、`PauseStackManager`、`AsyncKeyLockManager` | 看调度阶段、等待指令、时间源和暂停 / 锁的线程语义 | +| `Resource/` `Pool/` | `8/8` 个类型声明已带 XML 注释 | `ResourceManager`、`AutoReleaseStrategy`、`ManualReleaseStrategy`、`AbstractObjectPoolSystem` | 看资源句柄释放策略与对象池复用约束 | +| `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` | 看默认基类、上下文感知 helper、数值格式化和通用扩展的使用边界 | + ## 最小接入路径 当前版本的最小运行时入口只有三个关键动作：