mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-13 06:04:30 +08:00

gewuyou 88de1235ae refactor(game): 收敛版本迁移链执行器

- 新增 internal 迁移执行器，统一 settings 与 save 的链式版本校验

- 修复 SettingsModel 重复注册、缺链回填与目标版本判定的迁移约束

- 补充 Persistence 与 SettingsModel 定向测试，并更新迁移文档和 ai-plan 跟踪

2026-04-20 09:52:37 +08:00

Data Repository Persistence 追踪

2026-04-19

复核当前工作树后确认：根目录 local-plan/ 只剩一份 settings-persistence-serialization-tracking.md，它同时承担 todo 与 trace 角色
按 ai-plan 治理规则建立 ai-plan/public/data-repository-persistence/ 主题目录，并补齐：
- todos/
- traces/
- archive/todos/
- archive/traces/
将旧混合文件拆分为主题内历史跟踪归档与基于同一材料整理的历史 trace，active 入口只保留当前恢复点、活跃事实、风险与下一步
在 ai-plan/public/README.md 中建立 feat/data-repository-persistence -> data-repository-persistence 的 worktree 映射
同步更新 ai-plan-governance 的 tracking / trace，记录 legacy 单文件计划也已按新目录语义收口

历史跟踪归档：
- ai-plan/public/data-repository-persistence/archive/todos/data-repository-persistence-history-pre-rp001.md
历史 trace 归档：
- ai-plan/public/data-repository-persistence/archive/traces/data-repository-persistence-history-pre-rp001.md

复核 GFramework.Game/Serializer/JsonSerializer.cs 后确认：当前实现直接复用传入的 JsonSerializerSettings，并通过 Settings / Converters 暴露活动配置对象
复核 docs/zh-CN/game/serialization.md 后确认：现有 FAQ 把 JsonSerializer 写成“本身线程安全”，与当前可变配置契约不一致
决定本轮只补齐契约说明而不改变运行时行为：
- 在源码 XML docs 中说明 settings / converters 的生命周期与并发约束
- 在定向单测中固定“序列化器暴露活动配置实例”的当前契约
- 在 docs/zh-CN/game/serialization.md、docs/zh-CN/game/index.md 与 GFramework.Game/README.md 中同步修正接入建议

dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "FullyQualifiedName~JsonSerializerTests" 已通过（9/9）
验证过程中出现的 analyzer warning 为仓库既有 warning，未在本轮扩大
下一步回到 migration abstraction 与 codec / persistence pipeline 的后续评估

对 SettingsModel、DataRepository、UnifiedSettingsDataRepository、SaveRepository<T> 的实现进行并排核对后确认：
- DataRepository 与 UnifiedSettingsDataRepository 不直接承担按版本号推进的迁移链
- 实际重复点只在 SettingsModel 与 SaveRepository<T> 的“版本迁移链执行与校验”逻辑
决定不新增 public migration abstraction，而是抽出 internal VersionedMigrationRunner
- 统一前向注册校验
- 统一缺链失败
- 统一声明目标版本与实际结果版本一致性校验
- 统一非递增 / 超目标版本防护
SettingsModel 本轮额外补强：
- 拒绝同一设置类型同一 FromVersion 的重复注册
- 以当前内存设置实例的 Version 作为目标运行时版本
- 迁移失败时保持当前实例不被旧数据覆盖，并继续记录错误日志
SaveRepository<T> 改为复用同一个 internal runner，但保留“加载成功后自动回写升级结果”的现有仓库语义
同步更新 docs/zh-CN/game/setting.md 与 docs/zh-CN/game/data.md，补迁移链约束说明
新增 / 更新测试：
- SettingsModelTests：重复注册拒绝、不完整链路保持当前实例、缓存失效场景
- PersistenceTests：迁移结果版本与声明版本不一致时显式失败

dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "FullyQualifiedName~SettingsModelTests|FullyQualifiedName~PersistenceTests" 已通过（20/20）
过程中出现的 analyzer warning 来自仓库既有项，未在本轮扩大