dukang/杜康好客-v3编码手册.md

杜康好客 · V3 编码手册（交付业务版）

版本定位：V3 是基于当前数据库 v3.1 的完整交付版本，目标不是 Mock 联调，而是把「购酒 → 发券 → 到店核销 → 门店打款 → 合伙人结算 → 总部运营」全流程跑通。
对照文件：V2 手册定义完整产品蓝图；preV1 手册定义 Mock 联调裁剪；本文件定义 V3 的交付口径、核销新规则、两人分工与业务闭环任务口径。
数据库事实：当前 Prisma schema 已是 v3.1，V3 不默认新增大表，优先补齐业务闭环、第三方集成、任务调度、验收测试与运营后台。

---

1. V3 交付目标

V3 必须达到可业务验收状态：

1. C 端用户能登录、选城、浏览商品、下单、支付、查看订单、获得权益、到店核销。
2. 门店端能登录、扫码/输码核销、查看核销记录、管理营业状态，并形成待打款记录。
3. 合伙人端能登录、录入门店、管理门店、查看辖区订单、处理配送/补发、查看账单与经营数据。
4. WebAdmin 能完成开城、商品、门店审核、订单、权益、核销、配送、退款/补发、结算、资源和账号管理。
5. 后端能完成真实支付回调、配送状态推进、退款/补发工单、门店 T+1、合伙人 T+30、日志与审计。
6. 测试能覆盖主链路、关键边界和生产开关，不再只依赖一条 happy path 冒烟。

---

2. V3 端与负责人

负责人	主责端	主责后端/公共范围	说明
jacy-dukang	apps/h5-user、apps/admin-web	packages/*、iam、catalog、trade、benefit、settlement、ops、callbacks、jobs、integrations、Prisma	Tech lead，负责架构、主交易链路、支付退款、后台运营、交付验收
刘景尧	apps/h5-shop、apps/h5-partner	store、redeem，并配合 settlement、配送/核销联调	负责门店、合伙人、录店、核销、门店体验与辖区履约

协作规则：

• apps/* 只走 HTTP API 与 packages/shared-types，禁止 import server/* 或其他 app。
• 后端跨模块只调用 exported Service，禁止为了赶进度直接写他人领域表。
• 涉及 API、枚举、DTO、业务规则变更，必须同步 packages/shared-types、packages/domain 与本手册。
• Prisma 迁移由 jacy-dukang 主导；涉及 store / redeem 表或核销流程时 刘景尧 必须 Review。

---

3. V3 核销规则（已替代 V2 的 ¥500 上限）

3.1 两种核销入口

入口	前端表现	API 入参	限制规则	券扣减方式
直接点核销	用户在权益首页点击「去使用」	{ amount }，不带 couponId	0 < amount <= 用户全部 ACTIVE 权益总余额	按券创建时间 FIFO 扣减，可跨多张权益
指向单据核销	用户在某张权益/核销单点击「立即核销」	{ couponId, amount }	0 < amount <= 该单据当前可用金额	只扣减该单据

3.2 后端不变量

• 核销码只存在 Redis，TTL = 5 分钟。
• 生成核销码前必须校验金额，门店确认核销时必须二次校验。
• 门店确认时使用券 version 乐观锁，避免并发重复扣减。
• 核销成功后写入：
  • user_redeem_record
  • common_event(BENEFIT_LEDGER, REDEEM)
  • store_payout(PENDING)
• 若核销码绑定门店，确认核销时只能由该门店使用；若未绑定门店，任意 OPEN 门店可确认。
• 已关闭或暂停门店不可核销。

3.3 前端提示

• 直接核销：显示「最高可核销 = 当前好客权益总余额」。
• 单据核销：显示「最高可核销 = 当前单据可用金额」。
• 不再展示「单次最高可核销 ¥500.00」。

---

4. V3 完整业务闭环

4.1 C 端购酒与权益

1. 用户打开 H5，完成手机号/微信登录。
2. 选择城市，首页展示已开城商品。
3. 进入商品详情，选择数量与收货地址。
4. 订单预览校验同城 2 瓶、跨城 6 瓶。
5. 创建订单，状态 PENDING_PAY。
6. 发起支付，Mock 环境同步成功，生产环境走微信 JSAPI。
7. 支付成功回调幂等更新订单为 PENDING_SHIP。
8. 根据商品 benefitAmount ?? price 发放好客权益。
9. 用户在权益页直接核销或指定单据核销。
10. 门店确认核销后，用户可评价，权益余额与流水更新。

4.2 门店核销与打款

1. 门店账号登录。
2. 首页扫码或输入核销码。
3. 后端校验核销码、门店状态、权益余额、单据金额。
4. 核销成功生成记录。
5. 系统创建 store_payout(PENDING)，预计 T+1 打款。
6. 系统按门店绑定关系计算并记录对应合伙人的核销收益，用于合伙人账单与经营统计。
7. WebAdmin 财务确认或 Job 自动推进打款状态。
8. 门店端可查看核销记录与打款状态。
9. 绑定合伙人端可查看辖区门店对应的核销订单、核销金额、门店打款状态与合伙人收益。

4.3 合伙人拓店与履约

1. 合伙人登录工作台。
2. 录入门店资料、门头/环境图、合同资料、银行卡信息。
3. V3 由 WebAdmin 审核门店，审核通过后门店才可对 C 端可见并参与核销。
4. 合伙人查看辖区订单。
5. 配送 Mock 或真实配送推进订单。
6. 异常时发起/处理补发、改址拦截、配送异常。
7. 合伙人查看月度账单、佣金、经营周报。

4.4 WebAdmin 运营

1. 管理员登录。
2. 配置开城、商品、合伙人、门店分类。
3. 审核门店。
4. 查看订单与配送。
5. 处理退款、补发、客服工单。
6. 管理权益、核销、资源、账号。
7. 财务确认门店 T+1 和合伙人 T+30 结算。
8. 查看运营报表、异常预警、第三方日志。

---

5. V3 验收用例清单

必过主链路

1. C 端手机号登录成功。
2. 首页展示郑州 4 个上架商品。
3. 同城 1 瓶下单失败，2 瓶成功。
4. 跨城 5 瓶下单失败，6 瓶成功。
5. 支付成功后订单进入待发货，并发放权益。
6. 直接核销不带 couponId，金额可达到总余额。
7. 单据核销带 couponId，金额不能超过该单据余额。
8. 门店扫码确认核销成功。
9. 核销后生成 store_payout(PENDING)。
10. 门店关闭后不可核销，C 端不可见关闭门店。
11. 合伙人录店后进入审核流，审核通过后 C 端可见。
12. 配送自动或真实回调推进到完成。
13. 退款工单通过后订单/权益/第三方日志一致。
14. 门店 T+1 打款状态可确认。
15. 合伙人 T+30 账单可生成并确认。

必过后台链路

1. WebAdmin 登录成功。
2. 创建/编辑/上下架商品。
3. 审核门店。
4. 查询订单与配送单。
5. 查询权益券、核销记录、打款记录。
6. 处理退款/补发/异常工单。
7. 查看第三方日志与运营报表。
8. 导出或核对财务数据。

---

6. 当前已知技术债

优先级	技术债	处理要求
P0	旧文档与规则仍有 ¥500 上限描述	V3 以后以本手册为准；后续批量清理 V2/preV1 中过时描述
P0	lint 多数为 echo ok	交付验收前必须接入有效检查
P0	smoke 覆盖不足	按 4.x 业务闭环补齐主流程冒烟
P1	shared-types DTO 不全	按接口稳定度分批上提
P1	跨模块直写 Prisma 表	逐步改为 exported Service
P1	真实短信、配送、退款未闭环	按 4.1、4.3、4.4 对应业务闭环完成
P2	admin-web 与 V2 HQ 小程序形态不一致	V3 先以 WebAdmin 交付，是否迁小程序另立版本

---

7. 版本冻结规则

• V3 业务规则以本文件为准。
• V2 手册仍作为完整蓝图参考，但与 V3 冲突时，V3 优先。
• preV1 手册只作为 Mock 联调历史参考，不再作为交付验收标准。
• 未写入本文件的新增需求，不进入 V3 交付范围；如必须加入，先更新本手册与任务表负责人。