dukang/杜康好客-v3-PRD.md

# 杜康好客 · V3.0 产品需求文档（PRD）

> **版本**：v3.0（源自产品 PRD v1.3，2026-07-10）  
> **作者**：吕丹（产品）· 工程对齐：jacy-dukang  
> **状态**：本期交付事实源（与 V2 蓝图冲突时 **V3.0 优先**）  
> **关联**：[`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md)（实现与验收口径）· [`AGENTS.md`](./AGENTS.md)（AI 入口）

---

## 0. 文档说明

| 字段 | 内容 |
|------|------|
| 项目名称 | 杜康好客 — 四端系统 |
| 覆盖端 | 用户端（**微信小程序**）、门店端（H5）、城市合伙人端（H5）、总部端（H5） |
| 试点城市 | 郑州 |
| 配送 | 同城小飞侠；跨城总部物流到付 |
| 主销场景 | 品鉴会 + 小程序 |

### 0.1 与仓库现状的差异（实现迁移注记）

| PRD v3.0 目标 | 当前 preV1/V3 代码现状 | 处理 |
|---------------|------------------------|------|
| C 端微信小程序 | `apps/h5-user`（H5） | V3.0 以小程序为交付形态；H5 可作联调过渡 |
| 总部 H5 | `apps/admin-web`（WebAdmin） | V3.0 功能对齐总部 H5 职责；形态可暂用 admin-web |
| 核销码 TTL 3 分钟 | 编码手册写 5 分钟 | **以本 PRD 3 分钟为准** |
| 订单 Tab 三态 | preV1 五 Tab | **以本 PRD 待付款/已付款/已完成为准** |

---

## 1. 背景与目标

### 1.1 商业模型

总部供酒 → 城市合伙人分销拓店 → 门店核销好客权益 → C 端买酒送 **1:1 等价好客权益**，覆盖「酒 + 餐」。

**成本与分润锚点**：

- 酒水成本约售价 **3 折**
- 门店结算 = 核销金额 × **60%**
- 单合伙人佣金池：订单佣金比例 + 核销佣金比例 ≤ 订单金额 **5%**（默认 **0% + 3%**）
- 权益：支付成功赠送订单实付金额 **1:1**，永久有效

### 1.2 本期目标 G1–G5

| ID | 目标 |
|----|------|
| G1 | 四端上线并可独立闭环运营 |
| G2 | 购酒履约（同城/跨城/现场提货）跑通 |
| G3 | 好客权益发放 → 门店核销 → 门店 6 折结算 + 手动提现跑通 |
| G4 | 合伙人拓店审核、多合伙人管辖、佣金配置、独立对账打款 |
| G5 | 售后工单、发票、代下单、问卷、门店评价、推广码归因本期交付 |

### 1.3 成功标准

**核心（门禁）**

| ID | 标准 | 波次 |
|----|------|------|
| S1 | 用户可下单（含支付与权益发放） | Wave 1（7.10） |
| S2 | 门店可核销 | Wave 1（7.10） |
| S3 | 城市合伙人可添加门店 | Wave 1（7.10） |
| S4 | 门店佣金（结算款）可手动提现 | Wave 2（7.15） |

**链路验收**

| ID | 标准 |
|----|------|
| S5 | 郑州用户：浏览→下单支付→履约/提货→权益到账→门店核销 |
| S6 | 跨城推总部物流；现场提货提交即完成 |
| S7 | 门店 T+1 按核销额 6 折出账；各合伙人按配置比例独立对账 |
| S8 | 工单四类型总部可审；发票可申请可回传 |
| S9 | 推广码归因合伙人；订单佣金按履约规则解析（跨城归总部） |

---

## 2. 角色与场景

### 2.1 角色

| 角色 | 端 | 核心诉求 |
|------|-----|----------|
| C 端用户 | 小程序 | 买酒、收权益、门店核销、售后/发票 |
| 门店主账号 | H5 | 核销、子账号管理、营业状态、结算提现 |
| 门店店员子账号 | H5 | 仅核销 + 本店记录（Wave 2） |
| 合伙人管理员 | H5 | 子账号、管辖范围经营数据、代下单等 |
| 合伙人推广员 | H5 | 仅门店入驻 + 看自己提交的店 |
| 总部运营/客服/财务 | H5 | 商品、审核、工单、发票、结算打款、报表 |

### 2.2 主场景 SC-01 ~ SC-09

| ID | 场景 | 路径摘要 |
|----|------|----------|
| SC-01 | 同城购酒 | 浏览→≥2瓶→微信支付→小飞侠→确认/24h自动→权益→核销 |
| SC-02 | 现场提货 | 隐藏入口→支付→直接已完成→权益 |
| SC-03 | 跨城购酒 | 未开通城市→≥1箱→总部物流到付→权益；订单佣金归总部 |
| SC-04 | 门店核销 | 出码/报手机号→核销→权益扣减→门店账本×60% |
| SC-05 | 拓店入驻 | 合伙人录入→负责人复核→总部审核→试核销100元→营业 |
| SC-06 | 售后工单 | 用户四类型→总部审→仓/合伙人协同→补发/退款 |
| SC-07 | 代下单 | 总部/合伙人手机号建用户下单（Wave 3） |
| SC-08 | 问卷+评价 | 成交后问卷；核销后门店评价 |
| SC-09 | 推广归因 | 推广码进小程序→绑定合伙人→统计成交/佣金 |

### 2.3 权限摘要

- 合伙人数据**平级隔离**（全城/区域不可互查）
- 推广员：仅门店入驻 + 看自己提交的店（须在管辖范围内）
- 门店主账号：子账号、核销、提现、营业状态；店员：仅核销+本店记录
- 总部：审核、管辖与佣金配置、打款、全数据
- 手机号脱敏：门店/合伙人中间 4 位加密；总部仅管理员看全号

---

## 3. 业务闭环与核心规则

### 3.1 五条主闭环

| 闭环 | 触发 | 关键节点 | 终点 |
|------|------|----------|------|
| 购酒履约 | 用户下单 | 同城小飞侠/跨城总部物流/现场提货 | 已完成 + 权益 1:1 |
| 权益核销 | 用户出码/报号 | 门店确认 | 权益扣减 + 门店账本×60% + 核销佣金释放 |
| 拓店入驻 | 合伙人录入 | 总部审核 + 试核销 | 营业中 C 端可见 |
| 售后工单 | 用户发起 | 总部审 + 协同 | 补发/退款或驳回 |
| 结算提现 | 核销入账 | T+1 出账 + 未出账可提 | 总部审后打款 |

### 3.2 订单状态机

```
待付款 ──支付成功──► 已付款 ──履约完成/确认收货/24h自动──► 已完成
  └─ 30 分钟未付取消
```

- **同城**：仓配履约——有仓且绑 API 承运商则自动推单（首期小飞侠）；有仓选自管则管仓方手工填单；**无仓**则总部传统快递填单
- **跨城**：总部传统快递到付填单；订单佣金归总部
- **现场提货**：支付后直接已完成；有现场推广码则订单佣金归码所属合伙人，无码归总部

### 3.3 佣金与结算

| 类型 | 比例 | 归属 | 释放时机 |
|------|------|------|----------|
| 订单佣金 | 按合伙人配置（默认 0%） | §3.3.1 解析 | 支付成功落快照 |
| 核销佣金 | 按合伙人配置（默认 3%） | 核销门店归属合伙人 | 按核销金额占比释放 |
| 门店结算 | 核销额×60% | 该门店 | T+1 出账；未出账可提现 |

**约束**：单合伙人订单+核销佣金 ≤ 5%；比例变更仅对新单/新核销生效；账单展示快照。

#### 3.3.1 多合伙人管辖（v1.2）

| 类型 | 管辖范围 | 限制 |
|------|----------|------|
| 全城合伙人 | 该城未被区域占用的区县 | 每城最多 1 名 |
| 区域合伙人 | 总部勾选的区县 | 每城多名；同一区县不可重复 |

**同城订单佣金解析**：收货区县→区域合伙人；未命中→全城合伙人；再无→总部。

**核销佣金**：归核销门店归属合伙人（拓店绑定，总部可调整；变更后仅影响新核销）。

**推广码**：归因统计；除现场提货「有码归码」外，不决定同城/跨城订单佣金。

#### 3.3.2 门店结算与提现

| 规则 | 结论 |
|------|------|
| 结算金额 | 核销金额 × 60% |
| T+1 出账 | 自然日统计，次日形成账期；法定节假日顺延 |
| 手动提现 | 未出账金额可提现（不必等出账日） |
| 打款 | 提现申请→总部审核→打款至入驻收款账户 |
| 结算异议 | 核销后 3 个工作日内（附凭证） |

**试点护栏 FIN-001~003**：

| ID | 规则 |
|----|------|
| FIN-001 | 未出账提现仅总部白名单门店 |
| FIN-002 | 单店单日上限默认 ¥5,000（可配置） |
| FIN-003 | 工作日提现 T+0 审完；超时看板预警 |

各合伙人独立 **T+30** 月账单、独立确认、独立打款（无上下级二次分账）。

### 3.4 门店账号模型（Wave 2）

- **一号多店**：同一手机号可作多家店主账号
- **主账号唯一**：每店入驻第三步负责人手机号，每店仅一个主账号
- **店员子账号**：主账号创建，仅归属单店
- **多店登录**：多店时选店列表；7 天免登记住上次所选

### 3.5 门店入驻 SOP

对齐《门店签约 SOP v3.0》S1–S12。

**三步录入**：

1. 基础信息（门头展示名/执照全称、筛选：面积≥200㎡、客单价≥60、包房≥5 等）
2. 证照/合同/照片 + **附件一结构化规则**
3. 结算信息（法人收款或授权书+银行卡短信校验）

**流程**：`暂存 → 待负责人复核 → 待总部审核 → 通过(待试核销) → 试核销100元 → 正式入驻 + 短信`

合伙人创建门店时，手机号已关联其他店 → 提示确认后可继续。

### 3.6 工单四类型（§4.4）

| 类型 | 总部决策 | 通过后 |
|------|----------|--------|
| 仅退款 | 同意/驳回 | 原路退款 |
| 破损补发 | 同意/驳回 | 负责仓配送+取回；通知管仓合伙人 |
| 破损退货 | 同意/驳回 | 负责仓取回→退款 |
| 退货退款 | 同意/驳回 | 通知归属合伙人+负责仓取回→退款 |

### 3.7 城市多仓与仓配（Wave 3）

- 一城多仓；每仓最多关联 1 名管仓合伙人
- **仓配管理**（总部）：注册第三方履约接口（小飞侠、京东、顺丰等）；启用后仓库方可选择
- **仓库设置**：履约方式 = API 自动推单（选已注册承运商）或 **自管**（手工填运单号 + 查询链接模板）
- 同城有仓订单支付后自动按仓配置推单；自管仓由管仓合伙人/总部代填单
- 同城无仓 / 跨城：总部传统快递填单
- 佣金与仓无关（订单佣金仍按 §3.3.1）；仓用于履约与工单协同
- 未关联合伙人的仓 → 总部直派

### 3.8 弱网核销兜底（Wave 3 · OPT-006）

- Wave 1~2：网络异常明确提示+重试；总部预警+人工补核销
- Wave 3：连续**网络类**失败 5 次→拍照兜底→上传→总部 T+0 补核销
- 业务错误（码过期、余额不足等）不计入 5 次；幂等防重复扣款

---

## 4. 功能需求（REQ 索引）

> 完整 REQ 结论见 [`.cursor/skills/dukang-v3/reference-req-index.md`](./.cursor/skills/dukang-v3/reference-req-index.md)

### 4.1 用户端（小程序）— REQ-U-001 ~ 026

| 模块 | 要点 |
|------|------|
| 导航账号 | 四 Tab；无感登录；确认下单提示绑定手机号（可选、不强制）；仅微信支付；7 天免登 |
| 商品下单 | 4 款酒祖杜康 SKU；同城≥2瓶免运费；跨城≥1箱；现场提货隐藏；锁单30分钟 |
| 权益核销 | 1:1 发放；出码 3 分钟；核销前规则弹窗（OPT-011）；附件一规则详情 |
| 门店 | 列表/详情/搜索/省市区筛选；仅营业中展示；立即核销 |
| 增长售后 | 四类型工单；发票四组合；成交问卷（无激励）；推广码；微信商品分享 |
| 评价 | 核销后门店评价 |

**SKU 价格锚点**

| 商品 | 瓶价 | 箱价(6瓶) |
|------|------|-----------|
| 酒祖杜康（国标特级10）53° | ¥128 | ¥768 |
| 酒祖杜康（国标特级15）53° | ¥168 | ¥1008 |
| 酒祖杜康（国标特级20）53° | ¥298 | ¥1788 |
| 酒祖杜康（国标特级30）53° | ¥498 | ¥2988 |

### 4.2 门店端（H5）— REQ-S-001 ~ 020

| 模块 | 要点 |
|------|------|
| 登录 | 主账号/店员；多店选店（Wave 2）；7 天免登 |
| 核销 | 扫码大按钮 + 手机号通道；今日汇总；弱网处理 |
| 记录结算 | 筛今日/7日/1月/全部；到账金额×60%；T+1 出账 |
| 提现 | 未出账可提（FIN 护栏）；提现记录；结算异议 3 工作日 |
| 账号 | 主账号管理店员（Wave 2）；待处理核销单（Wave 3） |

### 4.3 合伙人端（H5）— REQ-P-001 ~ 026

| 模块 | 要点 |
|------|------|
| 权限 | 管理员 vs 推广员菜单裁剪 |
| 拓店 | 三步录入；一号多店确认；负责人复核；试核销100元；附件一 |
| 经营 | 首页三卡；排行；订单/权益/工单；佣金快照下钻 |
| 财务 | 本合伙人月账对账（Wave 2/3） |
| 扩展 | 代下单（Wave 3）；管仓只读（Wave 3） |

### 4.4 总部端（H5）— REQ-H-001 ~ 024

| 模块 | 要点 |
|------|------|
| 基础 | 商品管理；营销规则 1:1 权益；签约主体：山西领势酒业有限责任公司 |
| 城市合伙人 | 开通城市；创建合伙人（全城/区域+佣金）；仓库管理（Wave 3） |
| 审核交易 | 门店审核；全量订单/权益/工单；发票 2 工作日；补核销 |
| 结算 | 门店+合伙人双 Tab；提现审；白名单配置 |
| 增长 | 推广码；问卷；评价；腾讯位置热力图 |

### 4.5 端职责矩阵

| 能力 | 用户端 | 门店端 | 合伙人端 | 总部端 |
|------|:------:|:------:|:--------:|:------:|
| 下单/支付/权益 | ● | | 代下单 | 代下单 |
| 核销 | 出码 | ● | 看记录 | 看全量 |
| 拓店 | 看门店 | 改营业 | ●录入 | ●审核 |
| 工单 | ●发起 | 查看 | 查看 | ●决策 |
| 结算提现 | | ● | 对账确认 | ●审打款 |
| 推广码/问卷/评价 | ● | 被评价 | 看数据 | 配置/看板 |

---

## 5. 非功能需求

| ID | 类别 | 结论 |
|----|------|------|
| NFR-001 | 登录态 | 四端 7 天免登 |
| NFR-002 | 支付 | 仅微信支付；待付款锁单 30 分钟 |
| NFR-003 | 短信 | 登录/核销验证码 3 分钟；核销成功必发短信 |
| NFR-004 | 安全 | 按端/角色脱敏与鉴权 |
| NFR-005 | 幂等 | 支付回调、核销、提现、补核销 |
| NFR-006 | 可用性 | Wave 1~2 弱网重试；Wave 3 拍照兜底 |
| NFR-007 | 兼容 | 小程序两主版本；H5 微信内置浏览器 |
| NFR-008 | 审计 | 工单、审核、打款、分账配置留痕 |
| NFR-009 | 履约 | 同城目标 24h；送达未确认 24h 自动完成 |
| NFR-010 | 归因 | 推广码与佣金归属下单时落库 |

---

## 6. 数据实体与外部依赖

### 6.1 核心实体（TECH-001 ~ 019）

用户、商品、订单（含佣金快照）、好客权益账本、门店（主账号/店员）、核销单、工单、结算/提现、合伙人（管辖+佣金）、推广码、仓库（W3）、待处理核销单（W3）、门店账号（W2）。

### 6.2 外部对接

| ID | 系统 | 用途 |
|----|------|------|
| TECH-011 | 微信支付 | 下单、原路退 |
| TECH-012 | 短信网关 | 登录/核销验证码、成功通知 |
| TECH-013 | 小飞侠 | 同城推单、状态、取送拍照 |
| TECH-014 | 微信能力 | 手机号、定位、客服、分享 |
| TECH-015 | 微信商品分享 | 分享归因 |
| TECH-016 | 腾讯位置服务 | 总部热力图 |

### 6.3 金额落库口径

- 权益入账 = 订单实付 × 1:1
- 订单佣金 = 订单金额 × 归属合伙人 order_commission_rate（支付成功快照）
- 核销佣金 = 按核销金额占比从 verify_commission_rate 池释放（核销时快照）
- 门店结算 = 核销金额 × 60%
- 核销码 TTL = **3 分钟**；试核销固定 **100 元**

---

## 7. UI 规范（§8 摘要）

- **主色** 杜康红 `#8B1E1E`~`#A12828`；**权益金** `#C4A35A`；**价格** `#C62828`
- C 端：品牌优先、商品大图；B 端：核销效率 / 经营看板 / 中控后台
- 四端统一「好客权益」图标与权益数字样式
- 空态：一句人话 + 可执行下一步

---

## 8. 验收标准（ACC 索引）

> 完整 ACC 见 [`.cursor/skills/dukang-v3/reference-acc.md`](./.cursor/skills/dukang-v3/reference-acc.md)

| 类别 | 代表 ACC |
|------|----------|
| 交易 | ACC-001~004 下单/同城/现场/跨城 |
| 核销 | ACC-005、ACC-017 两通道+弱网 |
| 组织 | ACC-006~007 一号多店/拓店 |
| 资金 | ACC-008~009 提现/佣金 |
| 售后增长 | ACC-010~014 工单/发票/代下单/问卷/推广码 |
| 多合伙人 | ACC-P21~P28 管辖/快照/隔离 |
| 多仓弱网 | ACC-W01~W03、ACC-017a |

---

## 9. 三波交付计划

| 波次 | 日期 | 门禁 | 包含 | 不含 |
|------|------|------|------|------|
| **Wave 1** | 7.10 | W1-S1~S4 | 登录、商品、同城支付、小飞侠、核销、拓店、试核销、合伙人子账号 | 提现、推广码、现场提货、跨城、工单、发票、门店子账号、多合伙人 |
| **Wave 2** | 7.15 | W2-S1~S5 | 未出账提现+FIN、打款、推广码、现场提货、门店子账号、多合伙人 | 代下单、弱网拍照、多仓、跨城、工单、发票、问卷、热力图 |
| **Wave 3** | 7.22 | 全量 | 代下单、弱网5次拍照、多仓、跨城、工单、发票、月账、问卷/评价/热力图 | — |

### 9.1 阶段映射（DLV）

| ID | 波次 | 内容 |
|----|------|------|
| DLV-W1-M1 | W1 | 四端登录、权限、UI Token、商品 |
| DLV-W1-M2 | W1 | 支付、锁单、同城小飞侠、权益 1:1 |
| DLV-W1-M3 | W1 | 出码/扫码/手机号核销、规则弹窗 |
| DLV-W1-M4 | W1 | 合伙人子账号、门店三步、审核、试核销 |
| DLV-W2-M1 | W2 | T+1、未出账提现、总部审打款 |
| DLV-W2-M2 | W2 | 现场提货、推广码 |
| DLV-W2-M3 | W2 | 多合伙人管辖/佣金 |
| DLV-W2-M4 | W2 | 门店子账号、多店选店 |
| DLV-W3-M1 | W3 | 代下单 |
| DLV-W3-M2 | W3 | 弱网拍照兜底 |
| DLV-W3-M3 | W3 | 多仓、跨城、工单、发票 |
| DLV-W3-M4 | W3 | 月账、问卷/评价/热力图 |
| DLV-W3-M5 | W3 | ACC 全量回归 |

### 9.2 OPT 波次口径

| OPT | 波次 | 说明 |
|-----|------|------|
| OPT-002 代下单 | W3 | W2 前运营人工代下单 |
| OPT-006 弱网 | W3 | W1~2 重试+人工补核销 |
| OPT-010 未出账提现 | W2 | 含 FIN-001~003 |
| OPT-005 现场提货 | W2 | — |
| OPT-001 发票 | W3 | — |
| OPT-004 问卷 | W3 | 无权益激励 |
| OPT-012 话术 | W3 | 上线后 3 日内对齐 |

---

## 10. 风险（R1~R8）

| ID | 风险 | 处置 |
|----|------|------|
| R1 | 小飞侠对接延期 | 并行联调；备选手动改状态 |
| R2 | 弱网重复扣款 | 幂等键 + OPT-006 |
| R3 | 三波排期 | 严格 W1→W2→W3；人工补核销/代下单 SOP |
| R4 | 发票 SLA | 看板预警 |
| R5 | 话术不同步 | OPT-012 3 日内更新 |
| R6 | 腾讯位置服务 | P2 不阻塞 L1 |
| R7 | 未出账提现资金 | FIN 护栏 |
| R8 | 多合伙人管辖冲突 | 区县互斥 + 快照 + 全覆盖校验 |

---

## 11. 变更记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v3.0 | 2026-07-11 | 由产品 PRD v1.3 整理为工程 V3.0 事实源；配套 `@dukang-v3` skill 与 `v3-delivery-lead` agent |

---

## 附录 A · 需求变更流程

1. 业务规则变更 → **先改本文件** → 同步 `杜康好客-v3编码手册.md` + `shared-types`/`domain`
2. 编码 Agent **不得**边写代码边改业务规则
3. 跨模块改动 → 相关双 Owner Review；Prisma 迁移 jacy-dukang 主 Review（store/redeem 需刘景尧）