mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
docs(documentation-governance): 收口数据与 UI 文档措辞
- 更新 Game 数据与存储页面、Godot UI 页面中的 reader-facing 说明，移除内部证据口吻、外部项目指代和生硬导流 - 更新 CQRS 抽象层与 SourceGenerators.Common README 的标签表述，避免暴露源文件路径列表和实现级打包术语 - 补充 documentation-full-coverage-governance 的 RP-050 恢复点、验证结果与 origin/main stop-condition 计量
This commit is contained in:
gewuyou
parent
e18512f043
commit
1d5404e206
@ -30,27 +30,15 @@
|
||||
本包当前可以分为几类契约：
|
||||
|
||||
- 消息契约
|
||||
- `Cqrs/IRequest.cs`
|
||||
- `Cqrs/INotification.cs`
|
||||
- `Cqrs/IStreamRequest.cs`
|
||||
- `Cqrs/Command/ICommand.cs`
|
||||
- `Cqrs/Query/IQuery.cs`
|
||||
- `Cqrs/Request/IRequestInput.cs`
|
||||
- `Cqrs/Command/ICommandInput.cs`
|
||||
- `Cqrs/Query/IQueryInput.cs`
|
||||
- `Cqrs/Notification/INotificationInput.cs`
|
||||
- `IRequest<TResponse>`、`INotification`、`IStreamRequest<TResponse>`
|
||||
- `ICommand<TInput, TResponse>`、`IQuery<TInput, TResponse>`
|
||||
- `IRequestInput`、`ICommandInput`、`IQueryInput`、`INotificationInput`
|
||||
- 处理器契约
|
||||
- `Cqrs/IRequestHandler.cs`
|
||||
- `Cqrs/INotificationHandler.cs`
|
||||
- `Cqrs/IStreamRequestHandler.cs`
|
||||
- `IRequestHandler<,>`、`INotificationHandler<>`、`IStreamRequestHandler<,>`
|
||||
- 运行时协作接口
|
||||
- `Cqrs/ICqrsRuntime.cs`
|
||||
- `Cqrs/ICqrsContext.cs`
|
||||
- `Cqrs/ICqrsHandlerRegistrar.cs`
|
||||
- `ICqrsRuntime`、`ICqrsContext`、`ICqrsHandlerRegistrar`
|
||||
- 管道与辅助类型
|
||||
- `Cqrs/IPipelineBehavior.cs`
|
||||
- `Cqrs/MessageHandlerDelegate.cs`
|
||||
- `Cqrs/Unit.cs`
|
||||
- `IPipelineBehavior<,>`、`MessageHandlerDelegate<,>`、`Unit`
|
||||
|
||||
## 最小接入路径
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@
|
||||
- `GFramework.Godot.SourceGenerators`
|
||||
- 同样复用这里的公共实现和共享约束。
|
||||
|
||||
这个目录当前 `IsPackable=false`，不作为独立安装包推广。对 NuGet 使用者来说，更实际的入口仍然是具体的
|
||||
这个目录不会单独作为消费包提供。对 NuGet 使用者来说，更实际的入口仍然是具体的
|
||||
`GeWuYou.GFramework.*.SourceGenerators` 包。
|
||||
|
||||
## 什么时候需要读这里
|
||||
|
||||
@ -12,19 +12,21 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-049`
|
||||
- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-050`
|
||||
- 当前阶段：`Phase 5 - Governance Maintenance`
|
||||
- 当前焦点：
|
||||
- 按 `$gframework-batch-boot 50` 恢复 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，继续收口 `Game` / `Godot` 细页与工具 README 中残留的 reader-facing 措辞问题
|
||||
- 按 `$gframework-batch-boot 50` 继续推进 `documentation-full-coverage-governance`，沿用 `origin/main` 作为 stop-condition 基线，收口 `Game` / `Godot` 细页与少量 README 中残留的 reader-facing 措辞与标签问题
|
||||
- `2026-04-29` 重新进入时确认当前分支仍为 `docs/sdk-update-documentation`，但 upstream `origin/docs/sdk-update-documentation` 已不存在；因此本轮不再把旧 PR review 线程作为默认恢复入口，而是以本地 diff vs `origin/main` 为主
|
||||
- 本轮在更新 tracking / trace 之前已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题
|
||||
- 本轮接受了 2 个 explorer 的只读结论：一个负责 `docs/zh-CN/game` 与 `docs/zh-CN/godot` 的热点排序，一个负责模块 README 的 reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写
|
||||
- 本轮仍保持在新的低风险批次窗口内：进入时 committed branch diff 相对 `origin/main` 为 `0` files / `0` lines，当前工作树相对 `origin/main` 为 `13` files / `132` lines，仍明显低于 `50` 文件 stop condition
|
||||
- `2026-04-29` 上一批已完成 11 个低风险文档文件的收口：去掉 `ai-libs`、`旧文档`、`优先看` / `先看` / `转到` 这类内部或指令式措辞，并把 README 中暴露原始路径的链接标签改成 reader-facing 标题
|
||||
- `2026-04-29` 本批次继续接受 2 个 explorer 的只读结论：一个负责 `game/data.md`、`game/storage.md`、`godot/ui.md` 的热点排序，一个负责 README reader-facing 标签巡检；主线程只接受低风险措辞问题，不扩展到结构重写
|
||||
- `2026-04-29` 本批次已收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md` 的文案：把内部证据叙述、外部项目指代、命令式导流、源文件路径列表和 `IsPackable=false` 这类实现术语改成 reader-facing 说明
|
||||
- 本轮仍保持在新的低风险批次窗口内：当前工作树相对 `origin/main` 为 `18` files / `225` lines，仍明显低于 `50` 文件 stop condition
|
||||
- 本轮继续沿用已确认的生命周期事实：`Architecture` 只暴露 `OnInitialize()`，`AbstractArchitecture` 通过 `InstallModules()` 暴露模块注册入口，而组件级 `OnInit()` 仍然是当前有效生命周期
|
||||
|
||||
## 当前状态摘要
|
||||
|
||||
- `Core`、`Ecs.Arch`、`Cqrs`、`Game`、`Godot` 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
|
||||
- `2026-04-29` 新一轮 batch boot 第 2 批次已进一步收口 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 与 `GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`：移除 “仓库和测试确认”“真实消费者 wiring”“CoreGrid 当前的做法”“优先看” 这类内部或生硬口吻，并把 CQRS 抽象层 README 的源文件列表改成契约类型族说明。
|
||||
- `2026-04-29` 新一轮 batch boot 已收口 `docs/zh-CN/godot/storage.md`、`godot/setting.md`、`godot/signal.md`、`godot/logging.md`、`godot/index.md`、`game/scene.md`、`core/index.md`、`game/config-system.md`、`ecs/arch.md` 与 `GFramework.Godot/README.md`、`tools/gframework-config-tool/README.md` 的 reader-facing 文案：移除 `ai-libs`、旧文档对比、命令式跳转和原始路径标签。
|
||||
- `2026-04-29` 当前分支的 upstream `origin/docs/sdk-update-documentation` 已 gone；后续若继续批处理，应继续以 `origin/main` 作为 branch-size stop condition 的 authoritative baseline，而不是默认恢复旧 PR review 状态。
|
||||
- `2026-04-28` 已重新抓取 PR `#299` 并复核 latest-head review：remote 当前只剩 `1` 条 `CodeRabbit` open thread 与 `1` 条 nitpick，且都指向 active tracking 文档；`Greptile` / `Gemini Code Assist` 当前无 open thread，测试汇总为 `2159 passed`，`Title check` 仍是 PR 元数据问题。
|
||||
@ -68,6 +70,7 @@
|
||||
- `dotnet build GFramework.csproj -c Release` 当前仍会输出仓库既有 analyzer warnings（如 `MA0158`、`MA0051`、`MA0004`）；本轮仅修改文档与 package metadata，不扩展到 warning 清理。
|
||||
- 当前分支 upstream 已 gone；在重新建立 remote branch 或新的 PR 之前，不适合再把旧 PR `#299` 的 review 状态当作默认恢复信号。
|
||||
- 当前 batch boot 已从 `origin/main` 零 diff 状态重新起步；本轮仍是低风险措辞收口，但下一轮若继续深入 README 子系统地图或大段采用路径重写，review 面会明显扩大。
|
||||
- `GFramework.Cqrs`、`GFramework.Cqrs.SourceGenerators`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 仍有若干源文件列表式“子系统地图”段落；这些已经接近结构级改写，不适合作为本轮剩余低风险批次继续机械推进。
|
||||
|
||||
## 归档指针
|
||||
|
||||
@ -88,6 +91,16 @@
|
||||
|
||||
## 最新验证
|
||||
|
||||
- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md`
|
||||
- 结果：通过；`game/data.md` 的 frontmatter、链接与代码块校验通过。
|
||||
- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md`
|
||||
- 结果：通过；`game/storage.md` 的 frontmatter、链接与代码块校验通过。
|
||||
- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md`
|
||||
- 结果：通过；`godot/ui.md` 的 frontmatter、链接与代码块校验通过。
|
||||
- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.Abstractions/README.md GFramework.SourceGenerators.Common/README.md`
|
||||
- 结果：通过；本轮 2 个 README 的 reader-facing 标签调整后目标有效。
|
||||
- `2026-04-29` `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；本轮第 2 批 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。
|
||||
- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/storage.md`
|
||||
- 结果：通过；`godot/storage.md` 的 frontmatter、链接与代码块校验通过。
|
||||
- `2026-04-29` `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/setting.md`
|
||||
@ -119,7 +132,7 @@
|
||||
|
||||
## 下一步
|
||||
|
||||
1. 提交本轮低风险 reader-facing 文案批次，并在提交后重新计算 branch diff vs `origin/main`，确认仍明显低于 `50` 文件 stop condition。
|
||||
2. 若继续下一批，优先人工复核 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 以及少量仍暴露原始路径标签的模块 README，而不是进入大段结构改写。
|
||||
1. 提交本轮第 2 批低风险 reader-facing 文案批次，并在提交后重新计算 branch diff vs `origin/main`，确认仍明显低于 `50` 文件 stop condition。
|
||||
2. 若继续下一批，优先挑选仍可“局部改句子”的页面或 README 标签问题；`Cqrs`、`Game.SourceGenerators`、`Ecs.Arch` 这类源文件列表式 README 应视作结构级专题，必要时单独开一轮更明确的写作目标。
|
||||
3. 只有在重新建立 remote branch 或新的 PR 之后，再恢复 `$gframework-pr-review` 作为默认恢复入口；在此之前以本地 diff 与验证结果为准。
|
||||
4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、`storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
|
||||
|
||||
@ -2,6 +2,39 @@
|
||||
|
||||
## 2026-04-29
|
||||
|
||||
### 当前恢复点：RP-050
|
||||
|
||||
- 本轮继续按 `$gframework-batch-boot 50` 推进，并沿用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为唯一 branch-size baseline。
|
||||
- 当前 `HEAD` 相对 baseline 的 committed diff 仍是上一批的 `13` files / `133` lines；在本批次工作树修改与 `RP-050` 恢复文档更新后，working tree 相对 `origin/main` 为 `18` files / `225` lines，离 stop condition 仍有充足余量。
|
||||
- 本轮接受了 2 个 explorer 的只读排序：一个锁定 `docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md` 的低风险措辞问题，一个锁定 README 中仍能局部收口的标签问题。主线程只接受“改句子就能闭环”的项，不扩展到 README 结构重写。
|
||||
- 实际落地的收口集中在 5 个文件：`docs/zh-CN/game/data.md`、`game/storage.md`、`godot/ui.md`、`GFramework.Cqrs.Abstractions/README.md`、`GFramework.SourceGenerators.Common/README.md`。
|
||||
|
||||
### 当前决策（RP-050）
|
||||
|
||||
- 文档页只处理内部证据口吻、命令式导流、外部项目指代和生硬 adoption phrasing；不改示例结构和导航层次。
|
||||
- README 只处理两类低风险项：把源文件路径列表改成类型级契约说明，把 `IsPackable=false` 这类实现术语改成 reader-facing 安装说明。
|
||||
- `GFramework.Cqrs`、`GFramework.Game.SourceGenerators`、`GFramework.Ecs.Arch` 等 README 的大段源文件清单继续留到后续单独批次，因为那已经接近结构级重写，不适合和当前轻量文案收口混在一轮。
|
||||
|
||||
### 当前验证（RP-050）
|
||||
|
||||
- 页面校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/data.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/game/storage.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/godot/ui.md`
|
||||
- 结果：通过；本轮 3 个页面的 frontmatter、链接与代码块校验全部通过。
|
||||
- README 链接校验：
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.Abstractions/README.md GFramework.SourceGenerators.Common/README.md`
|
||||
- 结果：通过；本轮 2 个 README 的 reader-facing 标签调整后目标有效。
|
||||
- 站点构建：
|
||||
- `bun run build`（工作目录：`docs/`）
|
||||
- 结果：通过；本轮第 2 批 reader-facing 收口后站点仍可构建，仅保留既有大 chunk warning。
|
||||
|
||||
### 下一步（RP-050）
|
||||
|
||||
1. 提交本轮第 2 批 reader-facing 文案批次，并更新 committed branch diff vs `origin/main` 的精确计量。
|
||||
2. 若继续下一批，优先挑选仍可局部收口的页面或 README 标签，不把结构级 README 改写混入同一轮。
|
||||
3. 只有在 remote branch / 新 PR 重新建立后，再恢复 `$gframework-pr-review` 作为默认恢复入口。
|
||||
|
||||
### 当前恢复点：RP-049
|
||||
|
||||
- 本轮按 `$gframework-batch-boot 50` 恢复，继续沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`；当前 upstream `origin/docs/sdk-update-documentation` 已 gone，因此改用 `origin/main` `4557dde6`（`2026-04-29 11:14:56 +08:00`）作为新的 branch-size baseline。
|
||||
|
||||
@ -16,7 +16,7 @@ description: 以当前 GFramework.Game 源码与 PersistenceTests 为准，说
|
||||
- `SaveRepository<TSaveData>`
|
||||
- 面向“按槽位组织的版本化存档”
|
||||
|
||||
如果先把这三类入口分开理解，后续采用路径会清晰很多。
|
||||
如果先把这三类入口分开理解，后续接入时会清晰很多。
|
||||
|
||||
## 什么时候用哪个仓库
|
||||
|
||||
@ -83,7 +83,7 @@ settings/
|
||||
|
||||
### `DataRepository`
|
||||
|
||||
`DataRepository` 是最通用的默认实现。当前仓库和测试确认的行为有几条需要特别记住：
|
||||
`DataRepository` 是最通用的默认实现。有几条默认行为需要特别注意：
|
||||
|
||||
- `LoadAsync<T>(location)` 在文件不存在时返回 `new T()`，不是抛异常
|
||||
- `DeleteAsync(location)` 只有在目标数据真实存在并被删除时才发送删除事件
|
||||
|
||||
@ -150,7 +150,7 @@ var cacheStorage = new ScopedStorage(rootStorage, "runtime-cache");
|
||||
|
||||
## 与上层 repository 的关系
|
||||
|
||||
`FileStorage` / `ScopedStorage` 是持久化最底层，不是最终采用入口。当前更常见的实际分工是：
|
||||
`FileStorage` / `ScopedStorage` 是持久化最底层，不是业务层最常直接接入的入口。当前更常见的实际分工是：
|
||||
|
||||
- `DataRepository`
|
||||
- 每个 `IDataLocation` 对应一份独立持久化对象
|
||||
@ -161,8 +161,8 @@ var cacheStorage = new ScopedStorage(rootStorage, "runtime-cache");
|
||||
|
||||
也就是说：
|
||||
|
||||
- 业务层如果想保存一份独立数据，优先看 [数据与存档系统](./data.md)
|
||||
- 业务层如果想保存设置，优先看 [设置系统](./setting.md)
|
||||
- 业务层如果想保存一份独立数据，可继续阅读 [数据与存档系统](./data.md)
|
||||
- 业务层如果想保存设置，可继续阅读 [设置系统](./setting.md)
|
||||
- 业务层如果只是需要底层存储实现，才直接依赖 `IStorage`
|
||||
|
||||
## 当前边界
|
||||
|
||||
@ -38,8 +38,8 @@ Godot 侧 UI 资源表，底层是 `IAssetRegistry<PackedScene>`。它只负责
|
||||
3. 节点必须实现 `IUiPageBehaviorProvider`
|
||||
4. 返回 `provider.GetPage()`
|
||||
|
||||
如果实例化得到的节点没有实现 `IUiPageBehaviorProvider`，当前实现会直接抛 `InvalidCastException`。这也是 UI 页面文档必须强调
|
||||
`GetPage()` / `[AutoUiPage]` 的原因。
|
||||
如果实例化得到的节点没有实现 `IUiPageBehaviorProvider`，当前实现会直接抛 `InvalidCastException`。因此页面节点必须显式提供
|
||||
`GetPage()`，或者通过 `[AutoUiPage]` 生成对应样板。
|
||||
|
||||
### `CanvasItemUiPageBehaviorBase<T>`
|
||||
|
||||
@ -135,7 +135,7 @@ architecture.RegisterSystem(new UiRouter());
|
||||
|
||||
`UiRouterBase` 只负责页面栈、layer UI、输入仲裁和暂停语义；真正把页面挂到 Godot 容器的是项目自己的 `IUiRoot`。
|
||||
|
||||
CoreGrid 当前的 `UiRoot` 做法和源码契约一致：
|
||||
项目侧常见的 `UiRoot` 接法如下：
|
||||
|
||||
- 继承 `CanvasLayer`
|
||||
- 为每个 `UiLayer` 创建一个 `Control` 容器
|
||||
@ -221,7 +221,7 @@ public partial class PauseMenu : Control, IUiPage, IUiPageBehaviorProvider
|
||||
|
||||
#### 方式 B：用 `[AutoUiPage]` 让生成器补样板
|
||||
|
||||
当前更贴近真实消费者 wiring 的方式，是让生成器产出 `UiKeyStr` 和 `GetPage()`：
|
||||
更常见的接法，是让生成器产出 `UiKeyStr` 和 `GetPage()`：
|
||||
|
||||
```csharp
|
||||
using GFramework.Game.Abstractions.UI;
|
||||
@ -297,7 +297,7 @@ uiRouter.Hide(handle, UiLayer.Modal);
|
||||
|
||||
如果页面只实现 `IUiPage`，它只有基础生命周期。
|
||||
|
||||
如果还需要更强的输入仲裁或暂停语义，可以像 CoreGrid 的 `PauseMenu` 一样继续实现：
|
||||
如果还需要更强的输入仲裁或暂停语义，可以继续实现：
|
||||
|
||||
- `IUiInteractionProfileProvider`
|
||||
- `IUiActionHandler`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user