杜康好客 · v3.5.4 开发文档
2026-08-21 · mini-user / admin-web / h5-partner / API / Prisma
生产 commit：5fdddae（规格主图与门店使用规则合并入 main）及后续客户端版本号 3.5.4
主题：商品规格（SPU + SKU）上线 + 同批次发票 / 文案 / 门店详情体验
1. 版本目标
- 商品由单规格升级为 SPU + 多 SKU：价格、权益、69 码、履约、上下架、主图按规格。
- 箱装按 瓶当量 起购与物流，不改城市起购阈值口径。
- 旧客户端兼容：不传
skuId 仍可下单；无 SKU 回落 SPU，禁止「商品暂无可售规格」误伤。
- 同批次补齐：发票品类、权益文案、收银台 logo、门店详情「使用规则」、C 端版本号。
不做：SKU 库存、把现有酒祖 10/15/20 合并为一个 SPU。
2. 功能清单（完整）
2.1 商品规格（核心）
| # |
模块 |
交付说明 |
| 1 |
数据模型 |
common_product_item 作 SPU；新增 spec_attr / spec_value / sku / sku_spec；订单快照 sku_id / sale_unit / bottles_per_unit |
| 2 |
存量迁移 |
每商品默认 1 个瓶装 SKU；SQL migrate-product-sku-v354.sql；脚本 backfill-product-skus.ts |
| 3 |
Catalog |
列表 specEnabled/saleUnit；详情 specAttrs/skus/defaultSkuId；旧字段拍平保留 |
| 4 |
Trade |
preview/create 可选 skuId；有可售 SKU → 默认/唯一；0 可售 → 回落 SPU；订单 sku_id 可空 |
| 5 |
Domain |
起购/大单/物流按 quantity × bottlesPerUnit 瓶当量 |
| 6 |
Admin |
PUT .../specs、PUT .../skus；抽屉加宽；「填写」弹窗；规格轴 + SKU 矩阵 |
| 7 |
mini-user |
详情规格 chips；确认页带 skuId；箱装数量文案；选规格切主图 |
| 8 |
代下单 |
HQ / 合伙人可选规格 SKU |
2.2 SKU 码与 69 码
| # |
项 |
说明 |
| 9 |
SKU 码 |
系统生成 DK + 6 位数字，后台不可手填；脚本 rewrite-sku-codes-dk.ts 改存量 |
| 10 |
69 码 |
每规格独立；同商品内 + 跨商品唯一；不可与其它 SKU 冲突 |
2.3 规格主图
| # |
项 |
说明 |
| 11 |
DB |
common_product_sku.image_url（migrate-sku-image.sql） |
| 12 |
Admin |
弹窗可为每 SKU 上传主图 |
| 13 |
C 端 |
选规格优先 SKU 主图，空则回落商品封面 |
2.4 发票（同批次）
| # |
项 |
说明 |
| 14 |
品类 |
user_invoice.invoice_category：LIQUOR 酒水类 / CATERING 餐饮类 |
| 15 |
C 端申请 |
票种写死「增值税普通发票」；类型选酒水/餐饮；备注写入申请 |
| 16 |
抬头 |
必填项打 *；强调邮箱必填 |
| 17 |
Admin |
发票列表展示品类；专票仍可走后台 |
2.5 文案与 UI（同批次）
| # |
位置 |
变更 |
| 18 |
全局权益文案 |
「好客权益券」→「好客权益」 |
| 19 |
首页角标 |
「享{amount}好客权益」，去掉门店 icon |
| 20 |
商品详情 |
规格区与「好客权益」说明加大间距 |
| 21 |
待支付/收银台 |
顶部 logo 用 logo2.png（杜康印章） |
| 22 |
门店详情 |
「使用规则」红色，置于「门店详情」上方；详情正文限高可滚动 |
| 23 |
客户端版本号 |
package.json + client-version.ts → 3.5.4（「我的」页展示） |
3. 兼容规则（线上）
- 不改
/api/v1；只增字段，不删旧字段语义。
- 旧客户端不传
skuId：
- ≥1 个可售 SKU → 默认（或第一个）可售 SKU
- 0 个可售 SKU → 回落 SPU，照常下单
- 新客户端传
skuId → 按该 SKU 校验。
- 旧 admin 不传规格：仅同步唯一默认 SKU；不覆盖已生成的 DK 码。
- SPU 上
sku_code / barcode_69 唯一约束下沉到 SKU；SPU 列保留冗余。
4. 发版与生产执行记录
按序在目标库执行（先测后产）。本机脚本只打本地 .env。
| 步骤 |
动作 |
生产状态（2026-08-21） |
| 1 |
migrate-product-sku-v354.sql / Prisma sync |
✅ db push 已对齐 |
| 2 |
backfill-product-skus.ts |
✅ 回填 9 个默认 SKU（扫 10 商品） |
| 3 |
migrate-sku-image.sql / schema image_url |
✅ |
| 4 |
rewrite-sku-codes-dk.ts |
✅ 13 条均已 DK，改写 0 |
| 5 |
migrate-invoice-category.sql |
✅ schema 已含 |
| 6 |
发 API + mini-user H5 + admin |
✅ mini-user 200 / api 200 |
| 7 |
微信小程序 weapp 上传 |
⚠️ 需单独上传后「我的」页才见 v3.5.4 |
运营注意：新包上线前不要给商品加第二规格；上线后再配「单瓶 / 整箱」。
5. 起购与物流
bottleQty = quantity × bottlesPerUnit- 城市起购仍按瓶；箱装（
bottlesPerUnit=6）数量 1 即可过同城 2 / 跨城 6
- 大单拦截、承运商
goodsNum 用瓶当量
6. 关键表 / 字段摘要
common_product_spec_attr / common_product_spec_valuecommon_product_sku（sale_unit、bottles_per_unit、image_url）common_product_sku_specuser_order.sku_id / sale_unit / bottles_per_unituser_invoice.invoice_category
7. 关键路径（便于排查）
| 域 |
路径 |
| Prisma / 脚本 |
server/dukang-api/prisma/migrate-product-sku-v354.sql、backfill-product-skus.ts、rewrite-sku-codes-dk.ts、migrate-sku-image.sql、migrate-invoice-category.sql |
| 规格工具 |
server/.../catalog/product-sku.util.ts |
| Admin 规格 |
apps/admin-web/src/components/ProductSpecsEditor.tsx |
| C 端详情 |
apps/mini-user/src/pages/product-detail/ |
| 版本号 |
apps/mini-user/src/lib/client-version.ts |
| 门店详情 |
apps/mini-user/src/pages/store-detail/ |
| 发票 |
apps/mini-user/src/pages/invoice-apply/、invoice-titles/ |
8. 验收清单
