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

9.8 KiB
Raw Permalink Blame History

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

版本定位：V3 实现与验收补充；产品事实源见 杜康好客-v3-PRD.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：

  • 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 为准；本编码手册为实现与验收补充。
  • 总部端：交付载体固定为 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