Phase 1 装备 Code-Layer 真值快照 v1.0 · 活跃设计

整理时间:2026-07-03 16:55 +08:00 整理人:Mavis(PM / 制作人视角) 本文档作用:把 Phase 1 装备系统的 code-layer 当前真实状态快照落档,5 日计划派工时直接引用,不再重复扫描源码 快照扫描范围:

src/data/items/**(数据层)

src/components/item/**(UI 层)

src/utils/items/**(逻辑层)

src/index.css(色板 CSS 变量)

src/version.ts(存档架构版本)

src/utils/saveVersioning.ts(存档版本管理基础设施)

src/types.ts(根 type,旧 rarity 字段位置) 本次不做的事:不修改任何项目代码;只快照 / 对照 / 引用

0. TL;DR(60 秒版)

| 项 | v3.1.5 阶段已做完 | 5 日计划 v1.2 仍待做 | | :--- | :---: | :--- | | T3 装备 16 件 4 字段(qualityTier / affixes / baseStats / buildTag) | ✅ 已补(baseStats 只 eff 单维) | ❌ rollValue 由 Day 5 T7 rollEquipment 生,不在 T3 范围 | | T4 9 档色板 CSS 变量 + @theme | ✅ 已落(src/index.css) | ⚠️ 清旧 .rarity-* class 残留(Day 2 R1.2 短工) | | T5 QualityFrame + AffixChip 组件 | ✅ 已落(src/components/item/) | ⚠️ 视觉对照 + 跟视觉规范 v1.0 比对(Day 3 R1.3) | | T6 装备卡 UI 升级 | ⚠️ ItemGallery.tsx 已落(可能替代路径) | ⚠️ 确认 BaggageTab 是否对接 + 视觉对照(Day 3 R1.4) | | T7 rollEquipment({ tier, category }) 函数 | ✅ 已落(src/utils/items/rollEquipment.ts) | ⚠️ Day 5 R1.5 单元测试 46 组 PASS 验证 | | 旧 rarity 字段(src/types.ts:186) | ✅ 保留(向后兼容) | ⚠️ 加 @deprecated 注释(Weekend 已撤回,留 Day 1 决定) | | SAVE_SCHEMA_VERSION | ⚠️ 当前 1.9(浮点) | ⚠️ Day 2 升 1.9 → 2.0(整数化 Phase 1 milestone) | | legacyAdapter.ts(旧存档兼容 helper) | ❌ 未新建 | ⚠️ Day 2 新建(upgradeLegacyEquippable + migratePayloadEquippableTier) | | saveVersioning.ts 注册 v1.9 → v2.0 migration step | ⚠️ SAVE_PAYLOAD_MIGRATIONS = [] 空数组 | ⚠️ Day 2 注册 | | 单元测试 46 组(rollEquipment.regression.ts) | ✅ 脚本已落 | ⚠️ Day 5 跑测 PASS 验证 |

核心结论:Phase 1 v3.1.5 阶段做的工作远超 5 日计划 v1.2 验收假设;5 日计划真实剩余工作量集中在 3 块:

R1.0 type 头真活(@deprecated + legacyAdapter.ts + saveVersioning 注册)
R6 字段净化(JSX 5 处真行号 + AGENTS.md 新段落)
R5 5 日收口文档 + 视觉对照 checklist

1. 文件级真值清单(按目录分)

1.1 数据层 `src/data/items/`

| 文件 | 行数 | 内容要点 | 跟 R1 对齐状态 | | :--- | ---: | :--- | :--- | | equipment.ts | 765 | 16 件装备(EQUIPMENT_ITEMS 数组),v3.1.5 头部明示"每件已补齐 4 字段" | ✅ 已 16/16 全填;baseStats 当前只 eff 单维(没 atk/def) | | quality.ts | 101 | 9 档 QualityTier 类型 + QUALITY_TIERS 元数据常量表 + QUALITY_ORDER 排序数组 + 5 → 9 档 RARITY_TO_QUALITY 映射常量表 | ✅ 数据层全部就位;cssVar 字段对应 src/index.css --color-q-* | | types.ts | 281 | BaseItem / ConsumableItem / EquipmentItem(v3.1.5 增强含 qualityTier / affixes / baseStats / buildTag 4 字段)/ StoryItem / LegacyItem / GameItem 联合类型 | ✅ 类型已升级 v1.1 | | affixes.ts | (未读全文,grep 过存在) | 词条定义表 | ⚠️ Day 5 R1.5 短工沿用 + PASS | | consumables.ts | 不在本快照核心范围 | 消耗品 | — | | legacyItems.ts | 不在本快照核心范围 | 传承道具 | — | | storyItems.ts | 不在本快照核心范围 | 剧情道具 | — | | itemConfigs.ts | 不在本快照核心范围 | 道具配置 | — | | index.ts | 不在本快照核心范围 | 模块索引 | — |

关键真值(equipment.ts 数据样本 — 1 件):

{
  id: 'item_abacus_gold',
  name: '金算盘',
  // ... 常规字段 ...
  rarity: 'epic',              // ← 旧 4 档,保留
  qualityTier: 'epic',         // ← 新 9 档(v3.1.5 已填)
  affixes: [],                 // ← 初始空(等 Day 5 roll)
  baseStats: { eff: 10 },      // ← 只 eff 单维(没 atk/def)
  buildTag: ['management'],    // ← 已改数组
}

1.2 数据层 `src/data/multiplayer/`

| 文件 | 状态 | | :--- | :--- | | types.ts + roomStateMachine.ts(均已落) | ✅ Day 4 R3 集成测已就位 |

1.3 UI 层 `src/components/item/`

| 文件 | 状态 | 对应 5 日计划 R | | :--- | :--- | :--- | | QualityFrame.tsx | ✅ 已落 | R1.3 T5 | | AffixChip.tsx | ✅ 已落 | R1.3 T5 | | ItemGallery.tsx | ✅ 已落(可能替代 R1.4 T6 路径,跟 BaggageTab 是否对接待 Day 3 校对) | R1.4 T6 |

1.4 逻辑层 `src/utils/items/`

| 文件 | 行数 | 内容 | 对应 R | | :--- | ---: | :--- | :--- | | qualityLogic.ts | 49 | getQualityRank / getQualityByRank / mapItemRarityToQuality / isHighQuality / isCelestial / isEquippableQuality | ✅ R1.3 / R1.5 部分 | | affixLogic.ts | (存在) | 词条逻辑工具 | ✅ | | itemGen.ts(不是 rollEquipment.ts,注意名字相似) | (存在) | 物品生成 utility | ⚠️ Day 5 R1.5 校对 | | rollEquipment.ts | (已落) | rollEquipment({ tier, category }) 主函数 | ⚠️ Day 5 R1.5 跑测 | | rollEquipment.regression.ts | (已落) | 单元测试 46 组脚本 | ⚠️ Day 5 R1.5 PASS 验证 | | index.ts | (存在) | 模块索引 | — | | legacyAdapter.ts | ❌ 未新建 | Day 2 R1.1 短工新建 | ⚠️ R1.1 待做 |

1.5 色板 CSS `src/index.css`

已落 @theme + 9 档 --color-q-*:

--color-q-waste:     #9ca3af;
--color-q-common:    #6b7280;
--color-q-fine:      #10b981;
--color-q-rare:      #3b82f6;
--color-q-epic:      #8b5cf6;
--color-q-legend:    #f59e0b;
--color-q-mythic:    #dc2626;
--color-q-divine:    #ea580c;
--color-q-celestial-from / mid / to: 金色渐变

✅ R1.2 T4 已落;Day 2 R1.2 真活 = 清旧 .rarity-* class 残留(短工)

1.6 存档架构 `src/version.ts`

export const APP_VERSION = '1.15.1';
export const ROADMAP_VERSION = '0.9.3';
export const SAVE_SCHEMA_VERSION = 1.9;          // ← 浮点 1.9,不是整数
export const LEGACY_SAVE_SCHEMA_VERSION = 1.0;

⚠️ Day 2 R1.1 真活 = 升 1.9 → 2.0(整数化 Phase 1 milestone,触发 migration step 自动跑)

1.7 存档版本管理基础设施 `src/utils/saveVersioning.ts`(347 行)

✅ 完整落地:

SAVE_VERSION_MANIFEST(3 个 namespace:active / archived / deprecated)
SAVE_PAYLOAD_MIGRATIONS: SavePayloadMigrationStep[] ← 当前 = [] 空数组(Day 2 R1.1 注册)
migratePayloadThroughRegisteredSteps / bootstrapReleaseSaveStorage(backup slot 自动恢复)/ readLiveSavePayload / writeLiveSavePayload / deleteLiveSavePayload / migrateLoadedSavePayload / promoteLoadedSavePayloadToActiveNamespace / purgeDeprecatedLiveSavePayloads / createSaveVersionReport

⚠️ Day 2 R1.1 真活 = 在 SAVE_PAYLOAD_MIGRATIONS 数组注册 {fromVersion: 1.9, toVersion: 2.0, description: 'phase1-equipment-tier', migrate: migratePayloadEquippableTier}

1.8 根 type `src/types.ts`(757 行)

line 186:EquippableItem.rarity: 'common' | 'rare' | 'epic' | 'legendary'(4 档旧字段,保留做向后兼容)
line 187:EquippableItem.qualityTier?: QualityTier(已存在,可选,fallback 路径入口)
line 299:AdventureRelic.rarity: 'common' | 'rare' | 'legendary'(跟 R1 装备系统不相关,不动)

✅ 旧字段保留;⚠️ @deprecated 注释(Weekend 已撤回,Day 1 R1.0 短工自行决定)

2. 已做完 vs 待做 lane-by-lane(对应 5 日计划 R1.0 - R1.6)

3. 与 5 日计划 v1.2 acceptance 的偏差清单(逐条对)

docs/handoff/tasks/2026-07-07-to-08-phase1-equipment.md 当前 acceptance:

| # | 原文(偏差前) | 真值校对后 | 修订动作 | | :-: | :--- | :--- | :--- | | 1 | T3 装备模型:30 件历史装备全部补 qualityTier + baseStats + rollValue | 16 件(v3.1.5 已补 4 字段;rollValue 由 Day 5 滚出,不在 T3) | 修订 | | 2 | T3 类型:EquippableItem v2 类型通过 tsc,QualityTier 9 档可 import | ✅ 数据层 + 根 type 都已含 | 修订(明确"rollValue 不在 T3") | | 3 | T4 色板:src/index.css 9 档品质色板 CSS 变量 + Tailwind v4 @theme 接入完成,旧 .rarity-* 删除 | ✅ CSS 变量落;⚠️ 旧 .rarity-* 待清 | 修订(明确"色板变量已落,清旧 class 是 Day 2 短工活") | | 4 | T5 组件:src/components/item/QualityFrame.tsx + src/components/item/AffixChip.tsx 2 个组件落盘,Storybook 或 quick demo 可见 9 档 + 5 类词条 | ✅ 2 个组件已落;⚠️ 视觉对照未做 | 修订(明确"视觉对照 = Day 3 短工活") | | 5 | T6 UI 升级:src/components/BaggageTab.tsx 升级后,装备卡入口位替换为 <QualityFrame>,词条展示位替换为 <AffixChip> 列表,鼠标悬停可见数值区间 | ⚠️ ItemGallery.tsx 已落替代路径;BaggageTab.tsx 是否对接未知 | 修订(明确"BaggageTab 对接验证 = Day 3 短工活") | | 6 | cmd /c npm run build 通过,npm run lint 无新增错误 | (未变) | 不动 | | 7 | 视觉对照 9 档 + 5 类词条跟 道具系统新核心UI视觉规范-v1.md 吻合 | (待 Day 3 R1.3 R1.4 做) | 不动(保留作为验收条件) | | 8 | src/App.tsx 任何代码未被改动 | (本快照未扫 App.tsx 装备相关调用,假设未变) | 不动 | | 9 | src/utils/items/** 现有工具函数未被改动(Day 5 才动) | ✅ 当前 qualityLogic.ts / rollEquipment.ts 都未动(只读判断用) | 不动 |

本节总结:acceptance 1-5 条需要"修订"(动 tasks/2026-07-07-to-08-phase1-equipment.md 文件),acceptance 6-9 条保留。修订动作只动 task 卡文档,不涉及项目代码。

4. 不在真值快照范围的事(明确划走)

❌ 不修改任何项目代码(周末 + 5 日全程)
❌ 不动 Phase 2+ 的设计(强化 / 跨周目 / 装备系统第二阶段)
❌ 不动 docs/specs/** / docs/story/** / docs/design/completed/**(只读,校对用)
❌ 不改 AGENTS.md § 0-§ 7 守则(本快照是补充 § 后续,不进守则)
❌ 不动胜利终局 / 剧情线 / 联机 P2P(已收口,留 W28+ 续推)

5. 后续真值校对节奏

6. 参考入口

7. 版本与变更记录

| 版本 | 时间 | 整理人 | 关键变更 | | :---: | :--- | :--- | :--- | | v1.0 | 2026-07-03 16:55 | Mavis(主会话拍板 / 只快照口径) | 首版:Phase 1 装备 code-layer 真值快照(7 目录扫描 + 1 文档 9 表格);明确 5 日计划 v1.2 acceptance 与真值的偏差清单(5 条 acceptance 修订动作);不动项目代码 | | (预计 v1.1) | Day 2 R1.1 派工后 | Day 2 短工 | 加 legacyAdapter.ts 真值确认 + saveVersioning.ts migration step 注册结果 | | (预计 v1.2) | Day 3 R1.3 R1.4 派工后 | Day 3 短工 | 加 BaggageTab.tsx 对接验证 + 视觉对照结果 | | (预计 v1.3) | Day 5 R1.5 跑测后 | Day 5 短工 | 加 rollEquipment.regression.ts 46 组 PASS 状态 |

(End of document — § 0 - § 7,预计 10 - 14 KB)

0. TL;DR(60 秒版)

1. 文件级真值清单(按目录分)

1.1 数据层 src/data/items/

1.2 数据层 src/data/multiplayer/

1.3 UI 层 src/components/item/

1.4 逻辑层 src/utils/items/

1.5 色板 CSS src/index.css

1.6 存档架构 src/version.ts

1.7 存档版本管理基础设施 src/utils/saveVersioning.ts(347 行)

1.8 根 type src/types.ts(757 行)