# 杜康好客 · 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 交付范围；如必须加入，先更新本手册与任务表负责人。