数据版本迁移
Data Schema Migration
管理客户端持久化数据的版本演进，确保旧数据平滑升级到新schema
子问题
1.版本号管理与检测
2.迁移函数链式执行
3.向后兼容与数据修复
4.迁移失败的回滚策略
5.Monolith 到多文件的存储架构拆分
6.三源存储（fileStorage/localStorage/IndexedDB）的优先级选择与自动迁移
7.项目切换竞态导致的跨项目数据覆盖防护
各项目的解法1 solutions
Signals
横向对比
| 维度 | moyin-creator |
|---|---|
| 版本管理方式 | Zustand persist version 字段 + if 分支式 migrate 回调，v1→v9 共 9 版本 |
| 迁移执行模式 | 双层迁移：App 启动时架构级拆分 + Zustand rehydrate 时 store 级 schema 变换 |
| 向后兼容策略 | 保留 Legacy 类型定义 + apiKeys 字段保留 + 兜底 string→string[] 兼容 |
| 回滚与恢复 | recoverFromLegacy 每次启动对比数据丰富度，自动从 monolith 恢复被覆盖数据 |
| 存储架构迁移 | Monolith→Per-Project 拆分：Record 型按键拆分 + Flat 型按 projectId 过滤 + shared 分离 |
| 幂等保障 | _p/_migrated 标志文件 + 失败不写标志自动重试 |
最佳实践
1.每个版本定义独立迁移函数便于测试
2.迁移应是幂等的可重复执行
3.保留迁移前数据快照用于回滚
4.迁移失败不写标志位，下次启动自动重试
5.setItem 从 JSON payload 提取 projectId 而非依赖全局状态，防止竞态覆盖
6.用数据丰富度比较（而非版本号）判断是否需要从旧数据恢复
7.保留 Legacy 类型定义确保迁移代码的类型安全