v3.5.4版本提交

docs/杜康好客-v3.5.4-开发文档.md

@@ -0,0 +1,62 @@
+# 杜康好客 · v3.5.4 商品规格（SPU + SKU）
+
+> **2026-08-21** · mini-user / admin-web / h5-partner / API / Prisma  
+> 目标：商品详情页内可选销售规格；价格、权益、69 码、履约、上下架按 SKU；箱装按瓶当量起购与物流。
+
+## 范围
+
+| # | 项 | 交付 |
+|---|----|------|
+| 1 | 数据模型 | `common_product_item` 升级为 SPU；新增 `spec_attr` / `spec_value` / `sku` / `sku_spec`；订单快照 `sku_id` / `sale_unit` / `bottles_per_unit` |
+| 2 | 存量迁移 | 每商品 1 个默认瓶装 SKU；SQL：`prisma/migrate-product-sku-v354.sql`；脚本：`prisma/backfill-product-skus.ts` |
+| 3 | Catalog | 列表附加 `specEnabled`/`saleUnit`；详情附加 `specAttrs`/`skus`/`defaultSkuId`；旧字段拍平保留 |
+| 4 | Trade | preview/create 可选 `skuId`；单可售 SKU 自动回落；起购按瓶当量 |
+| 5 | Admin | `PUT /admin/products/:id/specs`、`PUT .../skus`；商品抽屉「规格与 SKU」 |
+| 6 | mini-user | 详情规格 chips；确认页带 `skuId`；箱装数量文案 |
+| 7 | 代下单 | HQ / 合伙人可选规格 SKU |
+| 8 | 权益文案 | 「好客权益券」→「好客权益」；首页角标「享{amount}好客权益」（去掉门店 icon） |
+
+**不做**：SKU 规格图、库存、把现有酒祖 10/15/20 合并为一个 SPU。
+
+## 兼容规则（线上）
+
+- 不改 `/api/v1` 前缀；**只增字段，不删旧字段语义**。
+- 旧客户端不传 `skuId`：若该 SPU **恰好 1 个可售 SKU** → 自动使用（现网行为）；多个可售 → `400 请选择规格`。
+- 旧 admin `PUT /admin/products/:id` 不传规格时：仅同步**唯一**默认 SKU（多规格时不同步，防误改）。
+- SPU 上 `sku_code` / `barcode_69` 去掉唯一约束，唯一下沉到 `common_product_sku`；SPU 列保留为默认 SKU 冗余。
+
+## 发版顺序
+
+1. API + DB 迁移（每商品仅默认 SKU）。**此时不要给任何商品加第二 SKU。**
+2. 发布新 mini-user + admin 规格页 + 代下单 SKU 选择。
+3. 运营再配置「单瓶 / 整箱」等第二规格。
+
+## 起购与物流
+
+- `bottleQty = quantity × bottlesPerUnit`
+- 城市起购阈值仍是瓶；箱装 SKU（`bottlesPerUnit=6`）数量 1 即可过同城 2 / 跨城 6。
+- 大单拦截、承运商 `goodsNum` 使用瓶当量。
+
+## 关键表摘要
+
+- `common_product_spec_attr` / `common_product_spec_value`
+- `common_product_sku`（`sale_unit`=`BOTTLE|BOX`，`bottles_per_unit`）
+- `common_product_sku_spec`
+- `user_order.sku_id` / `sale_unit` / `bottles_per_unit`
+
+## 权益文案（mini-user）
+
+| 位置 | 变更 |
+|------|------|
+| 门店详情等 | 「好客权益券」→「好客权益」（如「好客权益使用规则」） |
+| 首页商品角标 `CouponBadge` | 由「享 + 门店 icon + 金额 + 好客权益」改为纯文案 **「享{amount}好客权益」** |
+
+其它页 `BenefitFigure`（我的/权益/核销等）仍保留门店核销图标，仅首页角标去 icon。
+
+## 验收
+
+- [ ] 未配规格：旧小程序/H5/代下单路径与现网一致
+- [ ] 多规格：详情选规格后价格/权益/履约变化；漏选下单 400
+- [ ] 整箱 SKU：数量 1 过起购；订单快照 `bottles_per_unit=6`
+- [ ] `GET /catalog/products/:id` 仍含 `id/name/price/spec/skuCode/...`
+- [ ] 小程序无「好客权益券」字样；首页角标为「享{金额}好客权益」且无门店 icon