№ · 活跃设计 CH.07.01
主页 · 📐 活跃设计 · 旧存档兼容边界 v1.0

旧存档兼容边界 v1.0

📅 2026-07-01 · 📦 10.4 KB · 📐 活跃设计 · 📝 MD 文档 🏷️ 时间🏷️ 装备🏷️ 设计🏷️ 品质

整理时间:2026-07-01 18:54 +08:00 整理人:Mavis(PM 视角) 依据:

  • docs/design/active/Phase1实施切片-v1.md § 1.1(9 档品质扩展)
  • docs/design/active/跨lane互斥规则-v1.md § 4(道具投放多渠道)
  • docs/specs/data/tongfu-data-structure-and-table-spec.md(存档结构)
  • docs/handoff/roles/pm.md(PM 铁律 + 旧存档优先)
  • AGENTS.md(项目级守则:旧存档优先)
  • docs/daily-plans/2026-06-29.md(SAVE_SCHEMA_VERSION 提升机制) 本文档作用:拍清 9 档品质上线后旧 4 档 rarity 存档的兼容边界,避免 R1 Phase 1 T3 数据迁移 + T7 rollEquipment 派生时改坏旧存档。 本版本只拍边界,不算实现:不写升级代码 / 不动 types.ts / 不动 accountProfileStorage.ts / 不动 playthroughStorage.ts。

0. TL;DR(60 秒版)

  • 3 个核心边界:① 旧字段保留 + 加 TODO ② SAVE_SCHEMA_VERSION 提升 ③ 旧 4 档 → 新 9 档自动映射(玩家不感知)
  • 2 个过渡态:玩家层 "看到 9 档色板" / 数据层 "旧 4 档字段仍可读"
  • 3 个回退:升级失败 → 旧存档保留 / 玩家手动回退 → 旧 4 档恢复 / 跨设备同步 → 旧版本客户端读旧字段
  • 3 个不变量:旧存档不删 / 旧字段不重命名 / 旧存档签名仍可验
  • 不在本 v1.0:跨周目旧存档迁移(留 R6 v1.1)/ 玩家手动改品质(留 v1.1)

1. 现状盘点(2026-07-01)

1.1 旧存档的字段定义(types.ts)

| 字段 | 类型 | 来源 | 现状 | | :--- | :--- | :--- | :--- | | rarity | 'common' \| 'rare' \| 'epic' \| 'legendary' | src/types.ts:137 | 4 档,旧 4 档 | | qualityTier | 'waste' \| 'common' \| 'fine' \| 'rare' \| 'epic' \| 'legend' \| 'mythic' \| 'divine' \| 'celestial' | src/data/items/types.ts | 9 档,新字段 | | affixes | Array<...> | src/data/items/types.ts | 新字段,初始 [] |

1.2 旧 → 新 字段映射(自动)

| 旧 rarity | 新 qualityTier | 映射规则 | | :--- | :--- | :--- | | 'common' | 'common' | 1:1 直映射(语义改变:旧 common = 普通,新 common = Q2 普通) | | 'rare' | 'rare' | 1:1 直映射 | | 'epic' | 'epic' | 1:1 直映射 | | 'legendary' | 'legend' | 改名(避开 JS 保留字 legendary 跟新 legend 撞) |

Q1 / Q3 / Q5-Q9 5 档:waste fine mythic divine celestial 不在旧 4 档映射中,旧存档不会自动升档到这 5 档。只有新 rollEquipment 才会生成这 5 档。

1.3 16 件装备的实际数据(已 1:1 映射)

  • src/data/items/equipment.ts 16 件装备的 rarity 和 qualityTier 都已填:
    • 旧 rarity: 'legendary' → 新 qualityTier: 'legend'(改名)
    • 旧 rarity: 'epic' / 'rare' / 'common' → 新 qualityTier 同名(直映射)
  • 结论:16 件装备当前 rarity 和 qualityTier 字段并存,旧字段不删,新字段已填。

2. 旧存档兼容的 3 个核心边界

2.1 边界 1:旧字段保留 + 加 TODO

  • 行为:rarity 字段不重命名,不删除,不改类型
  • 注释:types.ts:137 加 /** @deprecated Phase 2 删;Phase 1 期间保留,新代码读 qualityTier,旧代码读 rarity */
  • 影响:
    • 旧代码读 rarity 仍可读
    • 新代码读 qualityTier 优先,rarity 作 fallback
    • 旧存档不需要迁移(rarity 字段已存在,无需补)

2.2 边界 2:SAVE_SCHEMA_VERSION 提升

  • 行为:SAVE_SCHEMA_VERSION 从当前值**+1**(留 v1.1 拍具体值)
  • 触发:R1 Phase 1 T3 数据迁移 + T7 rollEquipment 派生时一并提升
  • 机制:
    • 旧存档仍可读(rarity 字段不丢)
    • 新存档写入时,新 SAVE_SCHEMA_VERSION 标在 slot 元数据
    • 旧客户端读新存档不会报错(只读 rarity,不读 qualityTier)
    • 新客户端读旧存档不会报错(读 qualityTier fallback rarity)

2.3 边界 3:旧 4 档 → 新 9 档自动映射

  • 行为:qualityTier 字段未填时,自动 fallback 到 rarity 字段(用 § 1.2 映射表)
  • 触发:每次读 qualityTier 时,先检查是否已填;若未填,fallback 到 rarity 字段的映射值
  • 写入:新 rollEquipment 生成时只写 qualityTier,不清 rarity(旧字段保留)
  • 玩家感知:无 ——玩家只看到 9 档色板,不感知"旧 4 档"和"新 9 档"区别

3. 2 个过渡态(玩家层 vs 数据层)

3.1 玩家层(玩家能看到什么)

| 玩家层 | 旧存档 | 新存档 | | :--- | :--- | :--- | | 装备卡色板 | 显示 9 档(从 rarity 映射) | 显示 9 档(从 qualityTier 读) | | 词条 chip | 显示 5 类(从 affixes: [] 读,空数组不显示) | 显示 5 类(从 affixes 读,T7 后非空) | | 数值区间 | 显示 baseStats.eff 或 statValue | 同左 | | roll 区间 | 不显示(rollValue 字段未填) | 显示 rollValue 0.0~1.0 |

3.2 数据层(数据存什么)

| 数据层 | 旧存档 | 新存档 | | :--- | :--- | :--- | | rarity | ✅ 4 档有值 | ✅ 4 档有值(留作 fallback) | | qualityTier | ⚠️ 字段不存在 → 读时 fallback | ✅ 9 档有值 | | affixes | ⚠️ 字段不存在 → 读时空数组 | ✅ 数组非空(T7 后) | | baseStats | ✅ 有值(可能字段不统一) | ✅ 有值(13 件需 Day 2 短工补) | | buildTag | ✅ 数组 | ✅ 数组 |

4. 3 个回退(出错时怎么办)

4.1 回退 1:升级失败 → 旧存档保留

  • 触发:T3 数据迁移 / T7 rollEquipment 失败
  • 行为:
    1. 升级前先备份旧存档(到 tongfu_save_slot_*_backup_<timestamp>)
    2. 升级失败时,自动读 backup slot
    3. 玩家不感知升级失败,游戏照常可玩
  • 实现位置:accountProfileStorage.ts / playthroughStorage.ts(R1 Day 2 短工)

4.2 回退 2:玩家手动回退 → 旧 4 档恢复

  • 触发:玩家在设置页主动"回退到旧版本"
  • 行为:
    1. 玩家点"回退"按钮
    2. 系统读 backup slot
    3. 玩家后续登录用旧 4 档 UI
  • 不实现:v1.0 不实现玩家手动回退按钮(留 v1.1);自动回退机制已够

4.3 回退 3:跨设备同步 → 旧版本客户端读旧字段

  • 触发:玩家在新设备装旧版本客户端
  • 行为:
    1. 旧版本客户端读新存档
    2. 旧版本客户端只读 rarity 字段,忽略 qualityTier affixes rollValue
    3. 玩家看到旧 4 档 UI
  • 限制:本 v1.0 不支持跨设备同步(项目目前纯本地化)
  • 预留:跨设备同步留 Phase 7 运营准备期

5. 3 个不变量(任何时候都不能破坏)

| # | 不变量 | 为什么 | | :--: | :--- | :--- | | N1 | 旧存档不删 | AGENTS.md 守则:旧存档优先 | | N2 | 旧字段不重命名 | 防止旧存档读不出 / 旧代码读不到 | | N3 | 旧存档签名仍可验 | signature 字段保留,防篡改机制不破 |

派生短工 在 R1 Day 2-3 派生时,必须遵守这 3 个不变量。违反任一 = R1 Phase 1 不算收口。

6. 跟 R1 Phase 1 T3 数据迁移的 acceptance 调整

6.1 原 acceptance(Phase 1 切片 v1.0)

30 件历史装备全部补 qualityTier + baseStats + rollValue,旧 rarity 字段保留 + TODO

6.2 调整后 acceptance(基于本边界 v1.0)

  1. 16 件装备补完 baseStats 数值(Day 2 短工,不是 30 件)
  2. 旧 rarity 字段保留 + 加 @deprecated 注释(不动 types.ts:137 类型)
  3. qualityTier 字段在 16 件装备上已填,不需重做
  4. SAVE_SCHEMA_VERSION 提升 +1,旧存档可读
  5. 旧 4 档 → 新 9 档 自动映射(玩家不感知)
  6. 3 个回退机制至少实现 #1(升级失败自动回退 backup)
  7. 3 个不变量 N1-N3 全部遵守

6.3 T7 rollEquipment 派生时的 acceptance 增补

  1. T7 生成新词条时只写 qualityTier + affixes,不清 rarity
  2. T7 单元测试 45 组合中,至少 1 组用"旧存档 fallback 路径"(模拟 qualityTier 未填,从 rarity 映射)

7. 验收口径

R3 旧存档兼容边界派生短工后(5 日计划 Day 2-3 短工参考),完成标准 = 全部满足:

  1. 本文档 § 1-6 全部拍清
  2. R1 Phase 1 切片 § 4 T3 acceptance 调整为本 v1.0 § 6.2
  3. 16 件装备实际 rarity / qualityTier 字段并存且未被改动
  4. types.ts:137 旧 rarity 类型未被重命名,未被删除
  5. SAVE_SCHEMA_VERSION 提升 +1(Day 2-3 短工实现)
  6. 旧存档自动 fallback 路径已实现
  7. 升级失败自动回退 backup slot 机制已实现
  8. 3 个不变量 N1-N3 全部遵守

7.1 不算收口的情形

  • ❌ 改了 types.ts:137 旧 rarity 类型
  • ❌ 删了旧存档
  • ❌ 重命名了旧字段
  • ❌ 升级失败时没有 backup slot
  • ❌ 玩家感知到"旧 4 档 vs 新 9 档"区别

7.2 可保留的 residual risk

  • ✅ 玩家手动回退按钮(留 v1.1)
  • ✅ 跨设备同步(留 Phase 7)
  • ✅ waste / fine / mythic / divine / celestial 5 档装备(留 Phase 2+)
  • ✅ 跨周目旧存档迁移(留 R6 v1.1)

8. 不在本 v1.0 的事项汇总(明确划走)

  • ❌ 改 types.ts:137 旧 rarity 类型
  • ❌ 删旧存档
  • ❌ 重命名旧字段
  • ❌ 玩家手动回退按钮
  • ❌ 跨设备同步
  • ❌ waste / fine / mythic / divine / celestial 5 档装备
  • ❌ 跨周目旧存档迁移
  • ❌ 玩家手动改品质
  • ❌ 跨存档的签名迁移
  • ❌ 旧存档压缩 / 加密升级

9. 参考入口

| 想看什么 | 去这里 | | :--- | :--- | | Phase 1 切片 | docs/design/active/Phase1实施切片-v1.md | | 跨 lane 互斥 | docs/design/active/跨lane互斥规则-v1.md § 4 | | 16 件装备数据 | src/data/items/equipment.ts | | 16 件 × 4 段投放 | docs/design/active/Year1道具投放映射表-v1.md | | 存档结构规范 | docs/specs/data/tongfu-data-structure-and-table-spec.md | | AGENTS.md 守则 | AGENTS.md § 7 | | PM 铁律 | docs/handoff/roles/pm.md | | SAVE_SCHEMA_VERSION 机制 | docs/daily-plans/2026-06-29.md(失败终局存档版本) |

10. 版本与变更记录

| 版本 | 时间 | 整理人 | 关键变更 | | :---: | :---: | :--- | :--- | | v1.0 | 2026-07-01 18:54 | Mavis(PM 视角) | 首版:拍 3 核心边界(旧字段保留 + SAVE_SCHEMA_VERSION 提升 + 旧 4 档自动映射)+ 2 过渡态(玩家/数据)+ 3 回退 + 3 不变量;R1 T3 acceptance 调整(30 件 → 16 件)+ T7 acceptance 增补(旧存档 fallback 路径) | | v1.1(待) | — | — | 待玩家手动回退按钮 + 跨设备同步 + 跨周目旧存档迁移 3 条需求落地后,补本 v1.1 |