mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-07 00:39:00 +08:00

GeWuYou 5353d5bd45 fix(game): 修复设置迁移缓存并发一致性

- 修复 SettingsModel 迁移注册与缓存重建的并发竞争

- 新增 SettingsModel 并发回归测试并更新 ai-plan 跟踪

2026-04-20 13:02:49 +08:00

Data Repository Persistence 跟踪

目标

继续收敛 GFramework.Game 当前的数据仓库持久化、设置模型与序列化语义，确保第一轮高优先级修复、测试与文档同步之后，剩余设计性 follow-up 仍有清晰、可共享的恢复入口。

高优先级实现、测试与文档对齐已在本主题历史阶段完成，当前 active 入口主要保留后续 design/backlog 恢复点
当前分支 feat/data-repository-persistence 已在 ai-plan/public/README.md 建立 topic 映射
旧单文件不再同时承担 todo 与 trace 角色，后续恢复统一从本 topic 的 active tracking / trace 进入
SettingsModel 与 SaveRepository<T> 的版本迁移链现在共用同一个 internal runner；继续沿这条线扩展时应优先复用而不是再复制链式迁移逻辑

原 local-plan 只有一份混合 tracking 文件，没有独立的 todos/ 与 traces/
详细历史已拆分迁入主题内 archive/，active tracking / trace 只保留当前恢复点、风险与下一步
历史已验证结果包括 GFramework.Game.Tests 的定向与全量通过，以及 docs/zh-CN/game/* 的同步更新
GFramework.Game.Serializer.JsonSerializer 当前直接暴露活动中的 JsonSerializerSettings 与 converters 集合，配置不会被复制
GFramework.Game.Internal.VersionedMigrationRunner 已统一前向迁移注册校验、缺链失败、声明版本一致性与非递增防护
SettingsModel 现在以当前内存设置实例的 Version 作为目标运行时版本；若迁移失败则保留当前实例并记录错误日志
SaveRepository<T> 继续在 LoadAsync(slot) 期间迁移并回写，但其核心链式校验已与设置迁移共用同一实现
PR #260 review follow-up 已完成：VersionedMigrationRunner / SettingsModel 的 XML 异常契约已补齐， SaveRepository<T> 单次加载已切换为迁移表快照，避免并发注册期间读取变化中的迁移链
SettingsModel 现已通过 _migrationMapLock 串行化迁移注册与 cache miss 时的按类型缓存重建，避免并发注册把旧快照重新写回 _migrationCache
docs/zh-CN/game/index.md 当前仍承担最低接入示例，因此其中的 JsonSerializer 配置必须避免鼓励对用户可篡改存档启用不受限的多态反序列化

codec / persistence pipeline 边界风险：压缩、加密、元数据与备份策略还散落在仓库与存储语义之间
- 缓解措施：下一轮先梳理现有 Serializer / Storage / Repository 的责任边界，再决定是否需要新的 pipeline abstraction
Active 入口回膨胀风险：若后续把实现细节继续堆回 active 文档，会重新退化成旧 local-plan
- 缓解措施：后续阶段完成并验证后，继续迁入本 topic 的 archive/

旧混合 local-plan 已拆分迁入主题内 archive
active 跟踪文件已按 ai-plan 治理规则精简为当前恢复入口
已补充 JsonSerializer XML docs、文档示例与最小契约测试
dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "FullyQualifiedName~JsonSerializerTests" 已通过（9/9）
已完成 VersionedMigrationRunner 抽取，并让 SettingsModel / SaveRepository<T> 共用链式迁移校验
dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "FullyQualifiedName~SettingsModelTests|FullyQualifiedName~PersistenceTests" 已通过（20/20）
已完成 PR #260 follow-up，并新增定向回归测试锁定迁移快照与失败不污染持久化数据的约束
dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "FullyQualifiedName~SettingsModelTests|FullyQualifiedName~PersistenceTests" -m:1 -nodeReuse:false 已通过（21/21）
已新增 SettingsModelTests 并发回归测试，锁定迁移注册与 cache miss 重建不会留下 stale cache
dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "FullyQualifiedName~SettingsModelTests" -m:1 -nodeReuse:false 已通过（5/5）
本次定向验证过程中出现的 analyzer warning 来自仓库既有代码，不属于本轮新增问题