杜康好客 · V3.0 产品需求文档（PRD）
版本：v3.0（源自产品 PRD v1.3，2026-07-10）
作者：吕丹（产品）· 工程对齐：jacy-dukang
状态：本期交付事实源（与 V2 蓝图冲突时 V3.0 优先）
关联：杜康好客-v3编码手册.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 订单状态机
- 同城：仓配履约——有仓且绑 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。
三步录入：
- 基础信息（门头展示名/执照全称、筛选：面积≥200㎡、客单价≥60、包房≥5 等）
- 证照/合同/照片 + 附件一结构化规则
- 结算信息（法人收款或授权书+银行卡短信校验）
流程：暂存 → 待负责人复核 → 待总部审核 → 通过(待试核销) → 试核销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
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
| 类别 |
代表 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 · 需求变更流程
- 业务规则变更 → 先改本文件 → 同步
杜康好客-v3编码手册.md + shared-types/domain
- 编码 Agent 不得边写代码边改业务规则
- 跨模块改动 → 相关双 Owner Review；Prisma 迁移 jacy-dukang 主 Review（store/redeem 需刘景尧）
jacy
eb96b36d0b