jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions 8 Packages Projects Releases Wiki Activity
Files
22845e5d5f0a05c284507536bc5f8f55c519c343
dukang/杜康好客-v3编码手册.md
T

206 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 杜康好客 · V3 编码手册（交付业务版）
> **版本定位**：V3 实现与验收补充；**产品事实源**见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。
> **现状审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)（已完成/冲突/缺口）
> **对照文件**：V2 / preV1 手册**不再作为需求依据**，仅作历史参考。
> **数据库事实**：当前 Prisma schema 已是 v3.1，优先按 V3.0 PRD 补齐业务闭环。
---
## 1. V3 交付目标
V3 必须达到可业务验收状态：
1. C 端用户能登录、选城、浏览商品、下单、支付、查看订单、获得权益、到店核销。
2. 门店端能登录、扫码/输码核销、查看核销记录、管理营业状态，并形成待打款记录。
3. 合伙人端能登录、录入门店、管理门店、查看辖区订单、处理配送/补发、查看账单与经营数据。
4. WebAdmin 能完成开城、商品、门店审核、订单、权益、核销、配送、退款/补发、结算、资源和账号管理。
5. 后端能完成真实支付回调、配送状态推进、退款/补发工单、门店 T+1、合伙人 T+30、日志与审计。
6. 测试能覆盖主链路、关键边界和生产开关，不再只依赖一条 happy path 冒烟。
---
## 2. V3 端与负责人
| 负责人 | 主责端 | 主责后端/公共范围 | 说明 |
|---|---|---|---|
| `jacy-dukang` | **全部四端**（含 `h5-shop`、`h5-partner`） | **全部模块** + `packages/*`、Prisma | Tech lead；**2026-07 起暂代刘景尧 B+D 职责** |
| `刘景尧` | ~~`apps/h5-shop`、`apps/h5-partner`~~ | ~~`store`、`redeem`~~ | **暂停分工**，恢复前由 jacy 代管 |
### 2.1 四端交付形态（工程口径）
产品 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 |
Reference in New Issue View Git Blame Copy Permalink