GFramework/local-plan/todos/cqrs-rewrite-migration-tracking.md

CQRS 重写迁移跟踪

目标

围绕 GFramework 当前的双轨 CQRS 现状，完成一轮以“去 Mediator 外部依赖”为目标的架构迁移：

• 将 Mediator 从 GFramework 公共 API 和运行时主路径中移除
• 基于 GFramework 自有抽象重建正式 CQRS runtime、行为管道和注册机制
• 保留 EventBus 作为框架级事件系统，不与 CQRS notification 混同
• 让 CoreGrid-Migration 直连本地 GFramework，作为真实迁移验证工程
• 为复杂迁移建立明确恢复点与进度追踪，避免上下文过长或中断后失去状态

当前恢复点

• 恢复点编号：CQRS-REWRITE-RP-002
• 当前阶段：Phase 4
• 当前焦点：
  • 清理剩余 Mediator 包依赖与文档残留
  • 评估是否继续把协程扩展和测试项目中的 Mediator.Abstractions 完全移除
  • 规划第二阶段优化：代码生成注册、性能收敛、行为 API 命名统一

本轮计划

Phase 0：工作流基础

• 在 local-plan/todos/ 建立本任务跟踪文档
• 在 local-plan/traces/ 建立本任务追踪文档
• 将恢复点 / trace / subagent 协作规范写入 AGENTS.md

Phase 1：本地验证链路

• 确认 CoreGrid-Migration 当前引用形态
• 将 CoreGrid-Migration 从 NuGet 包切到本地 GFramework 工程引用
• 让 CoreGrid-Migration 使用本地 Source Generator 而不是外部已发布版本
• 验证本地引用链路至少能完成 restore / build

Phase 2：CQRS 基础重建

• 在 GFramework.Core.Abstractions 定义自有 CQRS 契约
• 在 GFramework.Core 落地 dispatcher / handler registry / behavior pipeline
• 清理 IArchitectureContext 中对 Mediator.* 的公共签名依赖
• 设计 CQRS 模块启用方式，替代 Configurator => AddMediator(...)

Phase 3：接入迁移

• 迁移 GFramework.Core.Cqrs.* 基类到新契约
• 迁移 ContextAwareMediator*Extensions 与协程扩展
• 迁移 CoreGrid-Migration/scripts/cqrs/** 到新契约
• 删除 GameArchitecture.Configurator 中的 AddMediator(...)

Phase 4：收尾

• 移除 Mediator 包依赖与相关测试/文档残留
• 运行目标构建与测试
• 记录剩余风险与下一恢复点

当前完成结果

• CoreGrid-Migration 已直连本地 GFramework 源码与本地 source generators。
• GameArchitecture 已不再依赖 collection.AddMediator(...) 即可使用 CQRS。
• GFramework.Core.Abstractions 新增自有 CQRS 契约：
  • IRequest<TResponse> / INotification / IStreamRequest<TResponse>
  • IRequestHandler<,> / INotificationHandler<> / IStreamRequestHandler<,>
  • Unit
  • IPipelineBehavior<,> / MessageHandlerDelegate<,>
• ArchitectureBootstrapper 会在初始化阶段自动扫描并注册当前架构程序集与 GFramework.Core 程序集中的 CQRS handlers。
• CqrsDispatcher 已支持：
  • request dispatch
  • notification publish
  • stream dispatch
  • context-aware handler 注入
  • request pipeline behavior 链式执行
• GFramework.Core.Tests 中原依赖 Mediator 注册路径的测试已切换到框架内建 CQRS 注册路径。
• 当前验证状态：
  • dotnet build GFramework/GFramework.sln 通过
  • dotnet test GFramework/GFramework.Core.Tests/GFramework.Core.Tests.csproj --no-build 通过，1621 个测试全部通过
  • dotnet build CoreGrid-Migration/CoreGrid.sln 通过

当前已知事实

• GFramework 当前仍同时维护：
  • 基于 CommandExecutor / QueryExecutor / EventBus 的轻量旧 CQRS
  • 基于 GFramework 自有抽象的新 CQRS runtime
• 仍存在 Mediator 残留的区域主要集中在：
  • 文档中的历史说明
  • MediatorCoroutineExtensions 及对应测试
  • 测试项目对 Mediator.Abstractions 的少量残余依赖
• CoreGrid-Migration 已切到本地源码引用，并在当前恢复点完成构建验证

当前风险

• GFramework 仓库存在与本任务无关的既有改动，提交时必须避免覆盖
• CoreGrid-Migration 是 worktree，WSL 下原生 git 解析该 worktree 路径有兼容问题
• 当前 RegisterMediatorBehavior 命名仍保留历史前缀，但底层已切换为框架自有 CQRS pipeline；若后续要彻底脱媒介命名，需要一次 API 命名迁移
• 当前 handler 自动注册基于运行时反射扫描；若后续追求冷启动与 AOT 友好性，需要补 source-generator 注册路径

下次恢复建议

若本轮中断，优先从以下顺序恢复：

1. 查看 local-plan/traces/cqrs-rewrite-migration-trace.md
2. 确认当前恢复点 CQRS-REWRITE-RP-002 已对应到最新提交
3. 优先决定是否继续移除 Mediator.Abstractions 包与 MediatorCoroutineExtensions 历史兼容层
4. 若继续演进，再处理 CQRS 注册的生成器化与 API 命名统一

备注

• 本文档是当前任务的主恢复点，后续每个关键阶段完成后都要更新
• 发生方向调整时，不覆盖旧结论，直接追加阶段记录与新的恢复点编号