# 杜康好客 · v3.5.4 开发文档

> **2026-08-21** · mini-user / admin-web / h5-partner / API / Prisma  
> **生产 commit**：`5fdddae`（规格主图与门店使用规则合并入 `main`）及后续客户端版本号 `3.5.4`  
> **主题**：商品规格（SPU + SKU）上线 + 同批次发票 / 文案 / 门店详情体验

---

## 1. 版本目标

1. 商品由单规格升级为 **SPU + 多 SKU**：价格、权益、69 码、履约、上下架、主图按规格。
2. 箱装按 **瓶当量** 起购与物流，不改城市起购阈值口径。
3. **旧客户端兼容**：不传 `skuId` 仍可下单；无 SKU 回落 SPU，禁止「商品暂无可售规格」误伤。
4. 同批次补齐：发票品类、权益文案、收银台 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_value`
- `common_product_sku`（`sale_unit`、`bottles_per_unit`、`image_url`）
- `common_product_sku_spec`
- `user_order.sku_id` / `sale_unit` / `bottles_per_unit`
- `user_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. 验收清单

- [ ] 未配规格：旧端下单与现网一致（无 SKU 也能下）
- [ ] 多规格：选规格后价格/权益/履约/主图变化；漏选 400
- [ ] 整箱：数量 1 过起购；订单 `bottles_per_unit=6`
- [ ] 详情 API 仍含 `id/name/price/spec/skuCode/...`
- [ ] 后台 SKU 码 DK 开头不可手填；每规格独立 69 码与主图
- [ ] 无「好客权益券」；首页角标「享{金额}好客权益」无门店 icon
- [ ] 门店详情「使用规则」红色且在详情上方；详情超长可滚
- [ ] 待支付页为 logo2 印章
- [ ] 发票：普票固定 + 酒水/餐饮品类 + 邮箱必填
- [ ] 「我的」页版本 **杜康好客 v3.5.4**（需 weapp 新包）