62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
# 杜康好客 · V3 编码手册（交付业务版）
|
||
|
||
> **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)
|
||
> V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。
|
||
|
||
## 1. 交付目标（六条）
|
||
|
||
C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAdmin 运营 · 后端支付/配送/结算/审计 · 主链路冒烟+边界测试。
|
||
|
||
## 2. 分工
|
||
|
||
| 负责人 | 范围 |
|
||
|--------|------|
|
||
| jacy-dukang | 全部 apps、packages、server 模块、Prisma（2026-07 起代管 B+D） |
|
||
| ~~刘景尧~~ | ~~h5-shop/partner、store/redeem~~（暂停） |
|
||
|
||
**四端**：C=`mini-user`/h5-user · 门店=h5-shop · 合伙人=h5-partner · 总部=**admin-web**（`/admin/*`，`HQ_WEB`）。
|
||
|
||
**边界**：apps 只 HTTP+shared-types；跨模块只 inject exported Service；枚举/DTO→shared-types；纯规则→domain。
|
||
|
||
**日志**：见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md)
|
||
|
||
## 3. 核销规则（V3）
|
||
|
||
| 入口 | 入参 | 上限 |
|
||
|------|------|------|
|
||
| 直接核销 | `{ amount }` | ≤ 全部 ACTIVE 权益总余额（FIFO） |
|
||
| 单据核销 | `{ couponId, amount }` | ≤ 该单据可用金额 |
|
||
|
||
- Redis 码 TTL **3 分钟**；确认时二次校验 + 券 version 乐观锁
|
||
- 成功写：`user_redeem_record` · `common_event(BENEFIT_LEDGER)` · `store_payout(PENDING)`
|
||
- 绑定门店则仅该店可确认；`OPEN` 门店；暂停/关闭不可核销
|
||
- UI 无「单次 ¥500」文案
|
||
|
||
## 4. 业务闭环（摘要）
|
||
|
||
| 链路 | 关键节点 |
|
||
|------|----------|
|
||
| C 购酒 | 登录→开城商品→起购(同城2/跨城6)→支付→权益1:1→出码/核销→评价 |
|
||
| 门店 | 登录→扫码确认→记录→store_payout T+1 |
|
||
| 合伙人 | 拓店三步→HQ审核→辖区订单/账单 |
|
||
| HQ | 开城/商品/审核/订单/权益/核销/结算/工单 |
|
||
|
||
**HQ 权限（v3.5.8）**：生效 =（角色 ∪ 追加）− 撤销。城市范围绑在账号上（空=全国；「城市门店服务」必须勾城）。门店 API 按 `cityIds` 强制过滤。城市门店服务可新增分类、不可删除；概览按权限与城市范围裁剪。
|
||
|
||
**HQ 列表（v3.5.9）**：主表不省略号、可横滑；最左序号；列设置（显隐/顺序）存 `hq_account.list_column_prefs`。门店列表「累计核销好客权益」= 该店 `RedeemRecord.amount` 合计。用户列表双击昵称、离开即保存；列表手机号不脱敏。
|
||
|
||
## 5. 验收用例（必过）
|
||
|
||
**主链路 15 项**：登录、4 SKU、起购、支付+权益、双通道核销、payout、关店不可见、拓店审核、配送完成、退款、T+1/T+30…
|
||
**后台 8 项**：商品/门店/订单/权益/核销/工单/日志/财务。
|
||
|
||
## 6. 技术债（摘要）
|
||
|
||
P0：旧文档¥500 · lint 占位 · smoke 窄覆盖
|
||
P1：DTO 不全 · 跨模块 prisma · 真实短信/配送
|
||
P2：mini-hq vs admin-web 重叠
|
||
|
||
## 7. 版本与波次
|
||
|
||
规则变更先改 **v3-PRD**。Wave 1/2/3 见 PRD §9。
|