103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# 杜康好客 · 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 推送条件展示「结算任务失败通知」，在系统监控组
|
||
- [ ] 账单任务失败 / 提现超时出现在勾了「结算任务失败通知」的群
|
||
- [ ] 提现通过、四类账单生成含收款账户；无账单不刷屏
|