jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

压缩文档

Browse Source
This commit is contained in:
jacy
2026-08-06 01:09:19 +08:00
parent 4f363fa9e7
commit 53a79d1255
14 changed files with 469 additions and 7237 deletions
Download Patch File Download Diff File Expand all files Collapse all files
杜康好客-v3编码手册.md
+45 -193
View File
@@ -1,205 +1,57 @@
# 杜康好客 · V3 编码手册（交付业务版）
> **版本定位**：V3 实现与验收补充；**产品事实源**见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。
> **现状审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)（已完成/冲突/缺口）
> **对照文件**：V2 / preV1 手册**不再作为需求依据**，仅作历史参考。
> **数据库事实**：当前 Prisma schema 已是 v3.1，优先按 V3.0 PRD 补齐业务闭环。
> **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)
> V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。
---
## 1. 交付目标（六条）
## 1. V3 交付目标
C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAdmin 运营 · 后端支付/配送/结算/审计 · 主链路冒烟+边界测试。
V3 必须达到可业务验收状态：
## 2. 分工
1. C 端用户能登录、选城、浏览商品、下单、支付、查看订单、获得权益、到店核销。
2. 门店端能登录、扫码/输码核销、查看核销记录、管理营业状态，并形成待打款记录。
3. 合伙人端能登录、录入门店、管理门店、查看辖区订单、处理配送/补发、查看账单与经营数据。
4. WebAdmin 能完成开城、商品、门店审核、订单、权益、核销、配送、退款/补发、结算、资源和账号管理。
5. 后端能完成真实支付回调、配送状态推进、退款/补发工单、门店 T+1、合伙人 T+30、日志与审计。
6. 测试能覆盖主链路、关键边界和生产开关，不再只依赖一条 happy path 冒烟。
| 负责人 | 范围 |
|--------|------|
| 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`）。
## 2. V3 端与负责人
**边界**：apps 只 HTTP+shared-types；跨模块只 inject exported Service；枚举/DTO→shared-types；纯规则→domain。
| 负责人 | 主责端 | 主责后端/公共范围 | 说明 |
|---|---|---|---|
| `jacy-dukang` | **全部四端**（含 `h5-shop`、`h5-partner`） | **全部模块** + `packages/*`、Prisma | Tech lead；**2026-07 起暂代刘景尧 B+D 职责** |
| `刘景尧` | ~~`apps/h5-shop`、`apps/h5-partner`~~ | ~~`store`、`redeem`~~ | **暂停分工**，恢复前由 jacy 代管 |
**日志**：见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md)
### 2.1 四端交付形态（工程口径）
## 3. 核销规则（V3）
产品 PRD 中总部端写作「H5」；**V3 工程交付以 `apps/admin-web`（WebAdmin）为准，不改为 H5，也不以迁移 H5 为验收项。**
| 角色端 | V3 交付 App | 形态 | 说明 |
|--------|-------------|------|------|
| C 端用户 | `apps/h5-user`（过渡）→ 目标微信小程序 | H5 / 小程序 | 按 v3-PRD 逐步迁小程序 |
| 门店 | `apps/h5-shop` | H5（微信内） | 与 PRD 一致 |
| 城市合伙人 | `apps/h5-partner` | H5（微信内） | 与 PRD 一致 |
| **总部** | **`apps/admin-web`** | **WebAdmin（Ant Design）** | **保持 WebAdmin；REQ-H 能力在本端实现** |
- 总部 API 前缀仍为 `/admin/*`，`X-Client-App: HQ_WEB`。
- `apps/mini-hq` 若有能力重叠，**不作为 V3 主交付端**；缺的功能补在 `admin-web`（如推广码管理页）。
- UI 参照 `pages/hq/` 原型时，按 **信息架构与字段对齐**，不要求 1:1 复刻 H5/小程序交互。
协作规则：
- `apps/*` 只走 HTTP API 与 `packages/shared-types`，禁止 import `server/*` 或其他 app。
- 后端跨模块只调用 exported Service，禁止为了赶进度直接写他人领域表。
- 涉及 API、枚举、DTO、业务规则变更，必须同步 `packages/shared-types`、`packages/domain` 与本手册。
- Prisma 迁移由 `jacy-dukang` 主导；涉及 `store` / `redeem` 表或核销流程时 `刘景尧` 必须 Review（**恢复分工前由 jacy 全权**）。
### 2.2 日志与审计（新业务）
城市 / 仓库 / 账号 / 子账号 CRUD 须落入对应日志表，规范见 [`杜康好客-v3-城市仓库与日志架构.md`](./杜康好客-v3-城市仓库与日志架构.md)：
- **HQ 写操作** → `common_event(HQ_OPERATION)`，经 `@HqOperation` 装饰器
- **合伙人端子账号** → `log_partner_analytics`（`partner_staff_*`）
- **城市多合伙、仓库表** → schema 待建；action 常量已预留
## 3. V3 核销规则（已替代 V2 的 ¥500 上限）
### 3.1 两种核销入口
| 入口 | 前端表现 | API 入参 | 限制规则 | 券扣减方式 |
|---|---|---|---|---|
| 直接点核销 | 用户在权益首页点击「去使用」 | `{ amount }`，不带 `couponId` | `0 < amount <= 用户全部 ACTIVE 权益总余额` | 按券创建时间 FIFO 扣减，可跨多张权益 |
| 指向单据核销 | 用户在某张权益/核销单点击「立即核销」 | `{ couponId, amount }` | `0 < amount <= 该单据当前可用金额` | 只扣减该单据 |
### 3.2 后端不变量
核销码只存在 Redis，TTL = **3 分钟**（与 v3-PRD 一致）。
- 生成核销码前必须校验金额，门店确认核销时必须二次校验。
- 门店确认时使用券 `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 运营（总部端）
> 交付载体：`apps/admin-web`。本节即总部端验收口径，**不要求改为 H5**。
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 | `mini-hq` 与 `admin-web` 能力重叠 | V3 以 **admin-web** 为总部唯一交付端；`mini-hq` 不阻塞验收，缺项补 admin-web |
---
## 7. 版本冻结规则
- **V3.0 业务规则**以 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) 为准；本编码手册为实现与验收补充。
- **总部端**：交付载体固定为 **`apps/admin-web`（WebAdmin）**；PRD「总部 H5」按 REQ-H 功能对齐，**不要求改为 H5**。
- V2 手册仍作为完整蓝图参考，但与 V3.0 冲突时，**V3 PRD 优先**。
- preV1 手册只作为 Mock 联调历史参考，不再作为交付验收标准。
- 未写入 v3-PRD 的新增需求，不进入 V3 交付范围；如必须加入，先更新 v3-PRD 与本手册。
## 8. V3.0 三波交付（摘要）
详见 v3-PRD §9 与 `@dukang-v3` skill。
| 波次 | 日期 | 门禁 |
| 入口 | 入参 | 上限 |
|------|------|------|
| Wave 1 | 7.10 | 下单+核销+拓店+合伙人子账号 |
| Wave 2 | 7.15 | 提现+推广码+现场提货+门店子账号+多合伙人 |
| Wave 3 | 7.22 | 代下单+弱网+多仓+跨城+工单+发票+全量 ACC |
| 直接核销 | `{ 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 | 开城/商品/审核/订单/权益/核销/结算/工单 |
## 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。