汽车电商双模块规格

源文件 04-ecommerce-spec.txt ｜ 由 Markdown 渲染，内容与原文一致

版本 v1.0 ｜ 2026-10-30 ｜ 覆盖两个独立业务模块：整车商城、零配件商城

配套接口：/api/sr3/*（15 条，见第 6 节）

---

1. 为什么两个模块共用一个数据库

整车和零配件看起来是两门生意，但它们共享同一份车型主数据，这是整个系统不散架的前提。

                        ┌──────────────┐
                        │  sr3_brands  │  33 个国产品牌
                        └──────┬───────┘
                               │ 1:N
                        ┌──────▼───────┐
     模块① 整车商城  ──▶│   sr3_cars   │  100 台车型（当前 1 台上架）
                        └──────┬───────┘
                               │ N:M  ← sr3_part_fitment（适配关系）
                        ┌──────▼───────┐
     模块② 零配件商城 ──▶│  sr3_parts   │  480 个 SKU
                        └──────┬───────┘
                               │ N:1
                        ┌──────▼─────────────┐
                        │ sr3_part_categories │  10 总成 + 41 子系统
                        └────────────────────┘

如果不共用会怎样：整车表里写「SU7 Ultra 敞篷版」，配件表里另写一份车型名字符串，两边改名就不同步， 买家点「适配我的车」查不到件。所以配件不存车型名字，只存 car_id 外键。

---

2. 数据结构

2.1 主数据（运营维护）

2.2 玩家侧（每用户一份）

2.3 运营侧

---

3. 页面结构与交互逻辑

3.1 商城首页（Hub）

一个页面两个入口，不混排：

┌─────────────────────────────────────────────────────┐
│  极速狂飙3 · 商城                                    │
├──────────────────────┬──────────────────────────────┤
│  🚗 整车商城          │  🔧 零配件商城                │
│  100 台国产车         │  480 个零件 · 10 大总成        │
│  按品牌 / 车身 / 分级  │  按车型 / 总成 / 品质          │
│  [进入选车]           │  [进入配件]                   │
└──────────────────────┴──────────────────────────────┘

为什么分成两个入口而不是一个混合列表：整车的决策链路是「我想要什么车」（横向比性能、比外形）， 配件的决策链路是「我的车缺什么」（纵向找件）。两种心智完全不同，混在一起两边都难用。

3.2 整车商城

筛选维度（四组可叠加）：品牌 → 车身类型 → 能源类型 → 分级 排序：首发优先 / 价格升降 / 马力降 列表卡片：

┌────────────────────┐
│   [原厂 GLB 渲染]   │  ← 直接用 GLB 出缩略图，后台批渲染，不手工做图
│ 小米汽车             │
│ SU7 Ultra 敞篷版     │
│ 敞篷 · 纯电 · 2 座   │
│ ★★★ 顶级             │
│ 免费（首发）         │
│ 可装 238 个零件  ▸   │  ← 关键：卡片上就告诉你能改多少，直接导流到配件商城
└────────────────────┘

详情页：3D 预览（GLB 实时渲染）→ 性能参数 → 可改装件分区（点击某个分区直接跳配件商城并预选该车型 + 该总成）

3.3 零配件商城

筛选维度：车型（必选，可切「全部车型」）→ 总成 → 品质 → 搜索 列表卡片：

┌──────────────────────┐
│  [零件图标]           │
│ 前大灯总成 左          │
│ 灯光系统 · 前大灯总成  │
│ 原厂件                │
│ 880 分                │
│ 适配 SU7 Ultra 敞篷版 │  ← 车型角标，一眼确认装得上
└──────────────────────┘

详情页三块：

1. 零件信息（材质、是否消耗品、性能加成、耐久）
2. 适配车型清单（fits，明确列出能装哪些车，带 fit_note 条件说明）
3. 同槽位替代件对比（alternatives）—— 这是改装商城的关键：玩家买前必比

性价比对比
  副厂件   720 分   brake +0
  原厂件   880 分   brake +0
  碳陶件  2280 分   brake +22  weight -3.2kg   ← 高亮推荐

3.4 结算流程（一条链路，两类商品同一套逻辑）

加购 → 购物车（服务端重算价） → 下单（生成 pending 单） → 支付（事务扣积分+发放）

三个硬约束：

1. 价格永远服务端重算，不信客户端传的总价
2. 下单幂等：前端每次结算生成一个 idem_key，重试复用同一个；服务端命中即返回原单，不重复落单
3. 支付幂等：同一 order_no 重复支付返回 idempotent:true，绝不二次扣费

免费首发车特判：price_points=0 的车加购直接入库（返回 granted:true），不生成 0 元订单 —— 0 元订单会污染订单列表，也会让「支付」逻辑处理 0 分钱的边界。

---

4. 零配件分类体系

10 个总成 → 41 个子系统 → 480 个 SKU（当前 SU7 238 件 + 宋 Plus 242 件）。

分类设计的一个取舍：左右对称件（前大灯、翼子板、门把手、轮毂×4）在库里是独立 SKU， 不是一条记录带数量。原因：撞坏左前大灯不该让你买一对；而且左右件在游戏里挂在不同骨骼节点上， 必须能独立装备、独立损伤。

---

5. 车型匹配方式

5.1 三级匹配

当前 480 件全部 exact + 一条 fitment 记录。接入更多车型后，通用件只需把 fit_mode 改成 universal，查询时 OR fit_mode='universal' 即自动出现在所有车型下。

5.2 为什么要 slot + anchor

只靠分类不够。分类回答「这是什么」（灯），slot 回答「装哪儿」（hl_lens_l）， anchor 回答「对齐到哪个点」（引擎里的插槽名）。

• 同一 slot 只能装一件 → 换件自动替换，不会叠加成两个尾翼
• anchor 是引擎侧的对齐基准点，美术做新件只要把模型原点对到锚点，玩家点装备即自动就位，无需逐件调坐标
• sr3_garage.installed 就是 {slot: part_id} 的字典，存档与商城共用同一套键

---

6. 接口清单

---

7. 每日迭代闭环

每天：
  ① 客户端本地跑 e2e_full_flow（从新用户登录 → 选车 → 改装 → 比赛 → 商城 → 退出全链路）
  ② 不过 → sr3_daily_build.local_test 置 fail，deployed 保持 0，拒绝发布
  ③ 过了 → 写 sr3_daily_build（local_test=pass, e2e=pass, assets_added=[今日新增车型/零件]）
  ④ 出包 → 写 sr3_releases（manifest 快照 + sha1 + 灰度百分比）→ OTA 主动推送
  ⑤ 次日拉 sr3_telemetry 漏斗 + sr3_client_log，定位流失点与崩溃

闸门为什么必须写库：只靠脚本 exit code 拦不住人。sr3_daily_build.deployed 是唯一真相， 部署脚本必须先 SELECT local_test,e2e_full_flow FROM sr3_daily_build WHERE build_date=CURDATE()， 不是双 pass 就 exit(3) —— 这和论坛现有的部署闸门是同一套规矩。