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

> **2026-08-26** · catalog / trade / mini-user / admin-web / API  
> **主题**：三种履约起购挂城市；企微通知补字段；结算通知（提现通过 + 四账单）

---

## 1. 版本目标

| # | 任务 | 类型 | 交付 |
|---|------|------|------|
| 1 | 履约起购 | 需求 | 城市三字段：提货 / 同城 / 跨城（瓶当量） |
| 2 | 现场提货 | 体验 | 默认数量对齐起购；文案用销售单位 |
| 3 | 承运商 | 文案 | 「起送瓶数」标明不影响用户起购 |
| 4 | 企微提交人 | 优化 | 门店新建/信息变更/套餐待审显示提交人名称 |
| 5 | 成交播报 | 优化 | 支付成功补规格/物流/收货；核销成功补用户 |
| 6 | 结算通知 | 需求 | `alert.settlement` 改名；提现通过 + 财务四账单（含收款账户） |

**不做**：起购迁到承运商；多城按地址匹配起购（仍读当前 ACTIVE 城市）；HQ 直改已营业门店不发待审通知。

---

## 2. 规则

起购属销售策略，存在 `common_city`：

| 履约 | 字段 | 默认 | 口径 |
|------|------|------|------|
| 现场提货 | `pickup_min_qty` | 2 | 瓶当量 |
| 同城配送 | `local_min_qty` | 2 | 瓶当量 |
| 跨城配送 | `cross_min_qty` | 6 | 瓶当量；箱规 6 瓶/箱 = 最少 1 箱 |

箱装：`quantity × bottlesPerUnit`。承运商 `pricingRules.baseBottles` 只用于物流对账。

---

## 3. 变更面

- Domain：`validateMinPurchase` 接收 `{ pickupMinQty, localMinQty, crossMinQty }`
- Trade：preview / create / 代下单读 `pickupMinQty`
- HQ 城市管理：三字段分组；承运商起送 extra
- mini-user：提货入口瓶装默认 2；确认页 `unitLabel`
- SQL：[`migrate-city-pickup-min-qty-v3511.sql`](../server/dukang-api/prisma/migrate-city-pickup-min-qty-v3511.sql)

---

## 4. 企微通知字段

### 4.1 提交人

| 角色 | 文案 |
|------|------|
| 合伙人 | `{企业} · {姓名}`（企业空则只姓名） |
| HQ | `HqAccount.name` |
| 门店端 | `门店 · {StoreAccount.name}` |

覆盖：`store.audit_pending`（含 HQ 新建）、`store.info_change_pending`、`store.package_audit_pending`。

入库模板若仍是上一版默认 body，启动时升级；HQ 手改过的不覆盖（可「恢复默认」）。

### 4.2 订单支付成功 `order.paid`

- 商品：`{名称} {规格} {瓶\|箱}×{数量}`
- 物流：现场提货 / 同城 / 跨城
- 收货：提货=姓名+手机；同城/跨城=姓名+手机+详细地址
- 测试单不推

### 4.3 核销成功 `redeem.success`

补 `userName`、`userPhone`（脱敏，与支付播报一致）。

---

## 5. 结算通知

条件 key 仍为 `alert.settlement`，HQ 展示 **「结算通知」**（原「结算任务告警」）。分组从「系统与结算」拆为「系统监控」+「结算通知」。

| key | 触发 | 收款账户 |
|-----|------|----------|
| `alert.settlement` | 账单定时任务失败、提现超时未审 | — |
| `store.withdraw_approved` | 门店手动提现审核通过 | 门店主账号卡 |
| `finance.store_bill` | 门店日账单 `created>0` | 各店主账号卡 |
| `finance.partner_bill` | 合伙人月账单生成成功 | 合伙人卡 |
| `finance.winery_bill` | 酒厂日账单未 skip | 系统配置酒厂账户 |
| `finance.logistics_bill` | 物流月账成功且未 skip | 承运商卡 |

账单一次摘要（多店多行，最多 15 行）；缺卡写「未登记收款账户」；内部群账号不脱敏。`created=0` / `skipped` 不推。

启动 upsert「结算通知群」（占位 webhook + 禁用）。已有「运营告警」若勾了 `alert.settlement`，会收到任务失败/超时，**不会**自动勾上 5 个新业务事件。

---

## 6. 验收

- [ ] 城市三字段起购；提货默认数量对齐；承运商起送不影响下单
- [ ] 合伙人新建/信息变更/套餐：企微可见「企业 · 姓名」
- [ ] HQ 新建门店：企微可见 HQ 名称
- [ ] 支付成功：规格单位、物流方式、收货信息按提货/配送分支正确
- [ ] 核销成功：有用户昵称与脱敏手机
- [ ] HQ 推送条件展示「结算通知」，不再出现「结算任务告警」
- [ ] 账单任务失败 / 提现超时出现在勾了「结算通知」的群
- [ ] 提现通过、四类账单生成含收款账户；无账单不刷屏