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

18 KiB
Raw Blame History

杜康好客 · preV1 编码手册（Mock 联调版）

V3 交付提示：preV1 不再作为交付验收标准。核销规则以 杜康好客-v3编码手册.md §3 为准（无 ¥500 上限）。

版本：preV1（在 V2 完整规格之上的裁剪实现阶段）
完整规格（V2）：杜康好客-V2编码手册.md — PRD、DB v3.1、API、任务卡均以 V2 为准
原则：不删表、不删 V2 API 路径、不改 V2 字段语义；preV1 用 Mock / Feature Flag / Seed 跳过外部依赖，开关关闭即切回 V2 真实流程。

文档索引

章节 内容
§0 版本关系（preV1 vs V2）
§1 preV1 范围：六条裁剪规则
§2 三端 H5 与仓库结构
§3 认证 Mock（无微信）
§4 支付 Mock
§5 配送与订单状态 Mock
§6 无总部端：能力替代
§7 preV1 功能清单
§8 Feature Flag 与 V2 切换
§9 preV1 里程碑与任务卡
§10 API / 数据行为差异速查

§0、版本关系

维度 preV1（本文） V2（完整版）
定位 三端 H5 联调，跑通购酒→发券→核销主链路 四端小程序/H5 + 真实微信/物流/支付
客户端 用户 / 门店 / 合伙人 均为 H5 C端+合伙人+总部小程序，门店 H5
总部 HQ 无独立端 pages/hq/ + AdminAuth
登录 仅手机号 + 固定验证码 短信 + 微信授权/绑定
支付 Mock 即时成功 微信 JSAPI + 回调
配送 Mock 状态推进 小飞侠/物流回调
数据库 同 V2 v3.1（28 表） 同左
API 路径 同 V2 §六（行为可 Mock） 完整实现

升级路径：preV1 完成后，按 §8 逐项打开 Flag、补小程序端与 HQ 端，无需重构表结构。

§1、preV1 范围：六条裁剪规则

1.1 删掉 HQ 端

  • 不做：apps/mini-hq、pages/hq/ 任何页面、AdminAuth 前端。
  • 保留：hq_account 表、§六 全部 /admin/* 路由（preV1 可不实现 Controller，或仅内部/脚本调用）。
  • 替代：见 §6。

1.2 用户 / 门店 / 合伙人 均改为 H5

V2 端 preV1 App X-Client-App 原型参照
C端小程序 apps/h5-user USER_H5 pages/user/
门店 H5 apps/h5-shop SHOP_H5 pages/shop/
合伙人小程序 apps/h5-partner PARTNER_H5 pages/partner/
  • JWT actorType 不变：USER / STORE / PARTNER。
  • V2 的 USER_MINI / PARTNER_MINI / HQ_MINI 枚举保留，preV1 不用即可。

1.3 微信登录与授权暂不走

  • 不调用：微信 code2session、获取手机号组件、微信 OAuth。
  • 不写入：wx_open_id / wx_union_id（保持 NULL）。
  • 仅实现：POST /auth/sms/send + POST /auth/login/sms（及三端等价路径 /shop/auth/*、/partner/auth/*）。
  • V2 的 POST /auth/login/wechat、/auth/wechat/bind-phone：保留路由，preV1 返回 501 FEATURE_DISABLED 或 Flag 关闭时不注册。

1.4 手机号验证固定 Mock

项 preV1 约定
验证码 固定 123456（全端、全 scene 通用）
开关 MOCK_SMS=true 时：不调用短信网关，不写入 log_third_party(SMS) 真实外呼
校验 AuthService.verifyCode(phone, code) 内：if (MOCK_SMS && code === '123456') return ok
限流 preV1 可放宽；V2 打开真实短信后启用频率限制

测试账号（Seed，见 §6.1）

角色 手机号 表
C端用户 13800000001 user_user
门店 13900000001 store_account
合伙人主账号 13700000001 partner_account

1.5 配送与订单状态 Mock（跳过第三方）

  • 不调用：小飞侠 API、物流查询 API；log_third_party 的 XFX / LOGISTICS 在 preV1 可不写入（或写 MOCK 占位）。
  • 仍创建：支付成功后 user_order_delivery 空壳（与 V2 一致 1:1）。
  • 状态推进（任选其一，推荐 A+B）：
    • A. 自动任务：MOCK_DELIVERY_AUTO=true 时，支付成功 30s 后 BullMQ 任务：PENDING_SHIP → OUT_WAREHOUSE → SHIPPING → PENDING_RECEIVE → COMPLETED，并写 common_event(ORDER_STATUS)。
    • B. 合伙人手动：POST /partner/orders/:id/mock-advance-delivery（preV1 专用，V2 可保留为内部测试接口或 Flag 保护）。
  • user_order 冗余时间字段 shipped_at / completed_at 与 user_order_delivery.shipping_at / delivered_at 双写（同 V2）。

1.6 跳过支付

  • 不调用：微信统一下单、支付回调验签。
  • 用户侧：确认订单页按钮文案可为「提交订单（Mock 支付）」；仍调用 POST /trade/orders/:id/pay（路径与 V2 相同）。
  • 服务端：MOCK_PAY=true 时 PayService 同步：
    1. user_order.pay_status=PAID，paid_at=NOW()，pay_external_no='MOCK-{orderNo}'
    2. 可选写 log_third_party(WECHAT_PAY, scene=ORDER_PAY, status=SUCCESS, external_no=MOCK-...)
    3. 订单 status=PENDING_SHIP + common_event(ORDER_STATUS)
    4. 调用 BenefitService.grantOnOrderPaid(orderId)（真实发券逻辑，非 Mock）
    5. 预创建 user_order_delivery
  • V2 切换：MOCK_PAY=false 时走 wechatpay-node-v3 + /callbacks/wechat/pay。

§2、三端 H5 与仓库结构

preV1 Monorepo（在 V2 目标结构上演进，暂不建 mini- / mini-hq*）：

dukang/
├── apps/
│   ├── h5-user/          # C端 H5（Taro H5 或 Vite+React，与 V2 技术栈一致即可）
│   ├── h5-shop/          # 门店 H5
│   └── h5-partner/       # 合伙人 H5
├── packages/
│   ├── shared-types/     # 含 USER_H5 / PARTNER_H5 / SHOP_H5
│   └── domain/
├── server/dukang-api/    # 同 V2 单体 NestJS
├── pages/{user,shop,partner}/   # UI 参照（hq 仅 V2 用）
├── 杜康好客-V2编码手册.md
└── 杜康好客-preV1编码手册.md   # 本文

请求头：各 H5 固定 X-Client-App: USER_H5 | SHOP_H5 | PARTNER_H5。

页面实现：字段、Tab、跳转以 V2 手册 §二、§三 原型为准；C 端订单 5 Tab（含待发货） 不变。

§3、认证 Mock（无微信）

3.1 实现的登录路径

端 发送验证码 登录
C端 POST /auth/sms/send scene=USER_LOGIN POST /auth/login/sms
门店 POST /auth/sms/send scene=STORE_LOGIN POST /shop/auth/login/sms
合伙人 POST /auth/sms/send scene=PARTNER_LOGIN POST /partner/auth/login/sms

3.2 preV1 不实现的登录路径

路径 preV1 行为
POST /auth/login/wechat 501 或 Flag 关闭
POST /auth/wechat/bind-phone 501
POST /shop/auth/login/wechat 501
POST /partner/auth/login/wechat 501
POST /admin/auth/* 不暴露给前端（无 HQ 端）

3.3 实现要点（便于 V2 切换）

// packages/shared-types 或 server config
export const AppConfig = {
  mockSms: process.env.MOCK_SMS === 'true',
  mockSmsCode: process.env.MOCK_SMS_CODE ?? '123456',
  mockPay: process.env.MOCK_PAY === 'true',
  mockDeliveryAuto: process.env.MOCK_DELIVERY_AUTO === 'true',
};

// AuthService — 单一验证码入口，V2 只改内部实现
async verifySmsCode(phone: string, code: string, scene: string) {
  if (AppConfig.mockSms && code === AppConfig.mockSmsCode) return;
  // V2: 查 Redis / log_third_party / 真实短信平台
}

§4、支付 Mock

4.1 用户流程（与 V2 UI 一致，跳过收银台）

确认订单 → POST /trade/orders（锁单 PENDING_PAY）
         → POST /trade/orders/:id/pay
              [MOCK_PAY=true] 同步成功，无跳转微信
         → 订单列表可见「待发货」
         → 权益页可见新券

4.2 字段与表（与 V2 相同）

写入 说明
user_order.pay_status PAID
user_order.paid_at 当前时间
user_order.pay_external_no MOCK-{orderNo}
user_order.status PENDING_SHIP
log_third_party 可选 MOCK 记录，便于 V2 对账逻辑联调
user_benefit_coupon + common_event(BENEFIT_LEDGER,GRANT) 真实业务，非 Mock

4.3 preV1 不做的支付相关能力

  • 微信 prepay 参数、支付回调、/callbacks/wechat/pay 验签（路由保留，Mock 模式不触发）。
  • 退款微信 API：preV1 整模块可跳过（§7）；表与 common_ticket(REFUND) 仍保留。

§5、配送与订单状态 Mock

5.1 自动推进状态机（推荐默认开启）

MOCK_DELIVERY_AUTO=true 时，支付成功后注册延时任务：

延时 from → to 配送表
T+0 PENDING_SHIP → OUT_WAREHOUSE out_warehouse_at
T+10s → SHIPPING shipping_at，user_order.shipped_at
T+30s → PENDING_RECEIVE —
T+60s → COMPLETED delivered_at，user_order.completed_at

每次 transition 写 common_event(ORDER_STATUS)；provider 填 MANUAL 或 MOCK。

5.2 合伙人端手动推进（可选）

POST /partner/orders/:id/mock-advance-delivery

  • Guard：PartnerAuth + 订单 city_id 属合伙人辖区。
  • Body：{ targetStatus: 'SHIPPING' | 'COMPLETED' | ... }
  • preV1 专用；V2 生产环境 MOCK_DELIVERY=false 时返回 403。

5.3 改址拦截（preV1 简化）

  • V2 PRD：用户改址 → 合伙人拦截配送。
  • preV1：PUT /trade/orders/:id/address 仅更新 user_order 收货字段 + common_event；不调第三方、不建复杂 intercept 表（V2 仍用 common_ticket(ALERT)，preV1 可省略工单）。

§6、无总部端：能力替代

HQ 能力在 preV1 通过 Seed + 合伙人 H5 子集 + 可选内部 API 覆盖，表结构不删。

6.1 启动 Seed（prisma/seed-prev1.ts 或 SQL）

数据 内容
common_city 郑州 ACTIVE，local_min_qty=2，cross_min_qty=6
common_city_commission_rule 默认佣金比例
common_product_item 4 款清香型 ON_SALE，含 barcode_69
common_store_category 火锅/地方菜等
partner_partner + partner_account 郑州合伙人 + 主账号 13700000001
store_store + store_account 至少 2 家 OPEN 门店
user_user 测试用户 13800000001
hq_account 可 Seed 1 条供未来 V2，preV1 无 UI

商品图/门头图：preV1 可用 占位 URL 或 common_resource 写死 CDN；V2 换 OSS 上传流程即可。

6.2 原 HQ 功能 → preV1 替代

V2 HQ 功能 preV1 替代
开城 / 商品 CRUD Seed 固定；变更改 Seed 或直连 DB（开发环境）
门店审核 合伙人提交后 AUTO_APPROVE_STORE=true 自动通过，写 common_event(STORE_AUDIT,APPROVED)
订单中心 / 发货 合伙人 H5 看辖区订单；跨城发货 preV1 跳过或 Mock 运单号
推广码 跳过 UI；channel_source 可手填或 Seed 一条 common_promo_code
退款 / 客服工单 跳过（或合伙人 H5 仅查看，不发起微信退款）
结算中心 T+1/T+30 Mock 状态：核销后 store_payout.status=PENDING；合伙人 partner_bill 可 Seed 一条 CONFIRMED 演示
数据报表 / 埋点 埋点 可写 log_user_analytics；总部报表 不做

6.3 合伙人 H5 在 preV1 的扩展（承接部分 HQ）

在 V2 合伙人 API 基础上，preV1 额外开放（Flag 保护）：

能力 说明
门店审核自动通过 配置项，非新表
Mock 推进配送 §5.2
查看辖区订单 V2 已有 GET /partner/orders

§7、preV1 功能清单

7.1 必做（跑通主链路）

模块 功能 V2 预留
IAM 三端短信 Mock 登录 微信登录路由保留
Catalog 读商品/开城（Seed） /admin/products 未实现
Trade 预览、下单、Mock 支付、5 Tab 订单、改址 真实微信支付
Benefit 发券、券列表、明细 同 V2
Redeem Redis 核销码、门店扫码确认、评价 同 V2
Store C 端门店列表/详情；合伙人录店；自动审核 HQ 人工审核
Settlement 核销后 store_payout PENDING T+1 打款任务可 Mock 为手动改 PAID
Analytics 可选：批量写 log_user_analytics 同 V2

7.2 preV1 明确跳过（V2 补）

模块 跳过内容
HQ 端 全部页面与 AdminAuth 前端
微信 登录、支付、退款、订阅消息
第三方 小飞侠、物流、真实短信
运营 退款工单、推广码管理 UI、总部报表
合伙人 拦截配送完整流程、T+30 真实打款、提现
小程序 全部（preV1 仅 H5）

7.3 业务规则（与 V2 相同，Mock 不减免）

  • 同城起购 2 瓶 / 跨城 6 瓶（packages/domain）
  • 权益金额 benefit_amount ?? price
  • 核销上限 ¥500，Redis 码 5 分钟
  • C 端门店仅 OPEN
  • 订单 5 Tab（含 pending_ship）

§8、Feature Flag 与 V2 切换

8.1 环境变量（.env.example）

# preV1 Mock 开关（true = Mock 模式）
MOCK_SMS=true
MOCK_SMS_CODE=123456
MOCK_PAY=true
MOCK_DELIVERY_AUTO=true
AUTO_APPROVE_STORE=true

# V2 就绪后逐项 false，并配置真实密钥
WECHAT_PAY_ENABLED=false
WECHAT_AUTH_ENABLED=false
XFX_ENABLED=false
SMS_PROVIDER=mock

8.2 切换检查表（preV1 → V2）

步骤 动作
1 MOCK_PAY=false，配置商户号，启用 /callbacks/wechat/pay
2 MOCK_SMS=false，接入短信，log_third_party(SMS)
3 MOCK_DELIVERY_AUTO=false，对接小飞侠/物流回调
4 AUTO_APPROVE_STORE=false，上线 apps/mini-hq + 门店审核
5 新增 apps/mini-user、apps/mini-partner，X-Client-App 改 MINI
6 WECHAT_AUTH_ENABLED=true，实现 wechat 登录/bind-phone
7 启用退款、结算 Job、推广码 HQ 页面

8.3 代码组织（避免 Mock 散落）

server/dukang-api/src/
├── integrations/
│   ├── sms/
│   │   ├── sms.interface.ts      # ISmsProvider
│   │   ├── sms.mock.provider.ts  # preV1
│   │   └── sms.aliyun.provider.ts # V2
│   ├── pay/
│   │   ├── pay.interface.ts
│   │   ├── pay.mock.provider.ts
│   │   └── pay.wechat.provider.ts
│   └── delivery/
│       ├── delivery.interface.ts
│       ├── delivery.mock.provider.ts
│       └── delivery.xfx.provider.ts

TradeModule / AuthModule 只依赖 interface，由 ConfigModule 注入 Mock 或 Real 实现。

§9、preV1 里程碑与任务卡

详细 API/表结构见 V2 手册 §五、§六；任务 ID 前缀 P1-，与 V2 M0~M6 并行命名空间。

里程碑 交付 出口标准
P1-M0 Monorepo 三 H5 + API 骨架 + Seed 三端登录页、GET /health、Seed 郑州+4 SKU
P1-M1 IAM Mock + 商品/门店读 三端 Mock 登录；C 端首页 4 款酒
P1-M2 下单 + Mock 支付 + 5 Tab 订单 2 瓶起购；支付后待发货+发券
P1-M3 权益 + 核销 + 门店 H5 端到端核销；store_payout PENDING
P1-M4 合伙人录店 + 自动审核 C 端可见新门店
P1-M5 Mock 配送自动推进 订单可到已完成
P1-M6 埋点可选 + 联调修复 主链路冒烟通过

任务卡（精简）

ID 任务 验收
P1-M0-001 pnpm workspace + h5-user/shop/partner 三端 dev 可编译
P1-M0-002 shared-types + Mock Flags 导出 AppConfig
P1-M0-003 NestJS + Prisma + init_v3.sql prisma validate
P1-M0-004 seed-prev1.ts 郑州/4SKU/测试账号
P1-M1-001 SmsMockProvider + 三端 login/sms 123456 登录
P1-M1-002 C 端首页/详情 Public catalog 对照 pages/user/2,3
P1-M2-001 preview + create order 起购校验
P1-M2-002 PayMockProvider + grant benefit Mock 支付发券
P1-M2-003 订单 5 Tab pending_ship 有数据
P1-M3-001 权益页 + redeem token ¥500 上限
P1-M3-002 门店扫码核销 pages/shop/3~5
P1-M4-001 合伙人录店 + AUTO_APPROVE C 端门店可见
P1-M5-001 DeliveryMockProvider 自动推进 订单 COMPLETED

§10、API / 数据行为差异速查

API / 行为 V2 preV1
X-Client-App USER_MINI / … USER_H5 / SHOP_H5 / PARTNER_H5
/admin/* AdminAuth 小程序 无前端；Seed/脚本
/auth/login/wechat 实现 501 或 Flag 关
/auth/sms/send 真实短信 固定码，不外呼
/trade/orders/:id/pay 微信 prepay 同步 Mock 成功
/callbacks/wechat/pay 验签回调 不触发
/callbacks/xfx/delivery 配送回调 不触发
log_third_party 真实流水 可选 MOCK 行或跳过
门店审核 HQ 审 AUTO_APPROVE_STORE
退款 HQ 工单+微信退款 跳过
推广码 UI HQ 跳过
核销 / 权益 / 订单表 真实 真实（同 V2）

原型参照（preV1 仍用 V2 映射）

H5 App 原型目录
h5-user pages/user/
h5-shop pages/shop/
h5-partner pages/partner/

C 端订单列表：5 Tab（含待发货）；个人中心无会员标签；城市示例以 郑州 为准。

preV1 为 V2 的 Mock 联调阶段；完整 PRD、DB DDL、全量 API 见 杜康好客-V2编码手册.md。

Reference in New Issue View Git Blame Copy Permalink