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

杜康好客 · 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