161 lines
4.9 KiB
Markdown
161 lines
4.9 KiB
Markdown
# 后端速查（杜康好客 v3.1）
|
||
|
||
> 完整 DDL/API 以 V2 手册 §五/§六 为准。
|
||
|
||
## API Base
|
||
|
||
- Prefix: `/api/v1`
|
||
- Response: `{ code: 0, message: 'ok', data }`
|
||
- JWT: `actorType` + `actorId` + `clientApp`
|
||
- 请求头：`Authorization`、`X-Client-App`
|
||
|
||
## clientApp → actorType → 表
|
||
|
||
| preV1 clientApp | V2 clientApp | actorType | 账号表 |
|
||
|-----------------|--------------|-----------|--------|
|
||
| USER_H5 | USER_MINI | USER | user_user |
|
||
| SHOP_H5 | SHOP_H5 | STORE | store_account |
|
||
| PARTNER_H5 | PARTNER_MINI | PARTNER | partner_account |
|
||
| HQ_WEB | HQ_MINI | HQ | hq_account |
|
||
|
||
## Guard 对照
|
||
|
||
| Guard | 用途 |
|
||
|-------|------|
|
||
| JwtAuthGuard | 需登录 |
|
||
| PhoneVerifiedGuard | （已废弃强制）C 端手机号改为下单页可选绑定 |
|
||
| OptionalJwtAuthGuard | 可选登录（bootstrap） |
|
||
|
||
Admin 路由在 `modules/ops/` 下，前缀 `/admin/*`。
|
||
|
||
## Module → API 前缀
|
||
|
||
| Module | 前缀示例 | 负责人 |
|
||
|--------|----------|--------|
|
||
| iam | `/auth`, `/user` | jacy-dukang |
|
||
| catalog | `/catalog`, `/admin/cities`, `/admin/products` | jacy-dukang |
|
||
| trade | `/trade`, `/partner/orders`, `/admin/orders` | jacy-dukang |
|
||
| benefit | `/benefit` | jacy-dukang |
|
||
| store | `/stores`, `/partner/stores`, `/admin/store-audits` | 刘景尧 |
|
||
| redeem | `/redeem`, `/shop/redeem` | 刘景尧 |
|
||
| settlement | `/settlement`, `/partner/settlement`, `/admin/settlement` | jacy-dukang |
|
||
| ops | `/admin/dashboard`, `/admin/reports` | jacy-dukang |
|
||
| analytics | `/analytics`, `/promo/touch` | jacy-dukang |
|
||
| callbacks | `/callbacks/wechat/pay`, `/callbacks/xfx/delivery` | jacy-dukang |
|
||
|
||
## 表前缀 → Module 写 OWNER
|
||
|
||
| 前缀 | 示例表 | 负责人 |
|
||
|------|--------|--------|
|
||
| user_ | user_user, user_order, user_benefit_coupon | jacy-dukang |
|
||
| store_ | store_store, store_account, store_payout | 刘景尧 / jacy-dukang（settlement） |
|
||
| partner_ | partner_partner, partner_bill | 刘景尧 / jacy-dukang（settlement） |
|
||
| hq_ | hq_account | jacy-dukang |
|
||
| common_ | common_product_item, common_event, common_city | jacy-dukang |
|
||
| log_ | log_third_party, log_user_analytics | 写入方 Module |
|
||
|
||
**无以下 V1 表**：payments、user_order_item、redeem_tokens（DB）。
|
||
|
||
## Controller 路由（当前实现）
|
||
|
||
### iam
|
||
|
||
| 路径 | Controller |
|
||
|------|-----------|
|
||
| `POST /auth/session/bootstrap` | UserAuthController |
|
||
| `POST /auth/sms/send` | UserAuthController |
|
||
| `POST /auth/sms/login` | UserAuthController |
|
||
| `GET /user/me` | UserAuthController |
|
||
| `GET/POST/PUT/DELETE /user/addresses` | UserAddressController |
|
||
| `POST /shop/auth/*` | ShopAuthController |
|
||
| `POST /partner/auth/*` | PartnerAuthController |
|
||
| `POST /admin/auth/login` | AdminAuthController |
|
||
|
||
### catalog / trade / benefit / redeem
|
||
|
||
| 路径 | Module |
|
||
|------|--------|
|
||
| `GET /catalog/*` | catalog |
|
||
| `POST/GET /trade/orders` | trade |
|
||
| `GET/POST /benefit/*` | benefit |
|
||
| `POST /redeem/*` | redeem（C 端） |
|
||
| `POST /shop/redeem/*` | redeem（门店） |
|
||
|
||
### store / settlement
|
||
|
||
| 路径 | Module |
|
||
|------|--------|
|
||
| `GET /stores` | store（C 端门店列表） |
|
||
| `GET/POST /partner/stores` | store |
|
||
| `GET /partner/dashboard` | store |
|
||
| `GET /shop/store` | store |
|
||
| `GET /shop/dashboard` | store |
|
||
| `GET /partner/settlement/*` | settlement |
|
||
| `GET /partner/me` | settlement |
|
||
| `GET /partner/orders` | trade |
|
||
|
||
### ops（admin-web）
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `/admin/dashboard` | 看板 |
|
||
| `/admin/users` | C 端用户 |
|
||
| `/admin/orders` | 订单 |
|
||
| `/admin/stores` | 门店 |
|
||
| `/admin/store-accounts` | 门店账号 |
|
||
| `/admin/store-media` | 门店媒体 |
|
||
| `/admin/partners` | 合伙人 |
|
||
| `/admin/partner-accounts` | 合伙人账号 |
|
||
| `/admin/cities` | 开城 |
|
||
| `/admin/hq-accounts` | 总部账号 |
|
||
| `/admin/benefit/coupons` | 权益券 |
|
||
| `/admin/benefit/ledgers` | 权益流水 |
|
||
| `/admin/redeem-records` | 核销记录 |
|
||
| `/admin/deliveries` | 配送 |
|
||
|
||
### analytics / health
|
||
|
||
| 路径 | Module |
|
||
|------|--------|
|
||
| `POST /analytics/*` | analytics |
|
||
| `GET /health` | health |
|
||
|
||
## 关键跨模块调用链
|
||
|
||
**Mock/真实支付成功**
|
||
|
||
```
|
||
PayProvider → TradeService.handlePaySuccess()
|
||
→ BenefitService.grantOnOrderPaid(orderId)
|
||
→ OrderDelivery 预创建
|
||
→ common_event(ORDER_STATUS)
|
||
```
|
||
|
||
**核销确认**
|
||
|
||
```
|
||
RedeemService.confirm()
|
||
→ BenefitService.deduct(couponId)
|
||
→ SettlementService.createStorePayout(redeemRecordId)
|
||
```
|
||
|
||
## 禁止依赖（PR 拒绝）
|
||
|
||
| # | 禁止 |
|
||
|---|------|
|
||
| F1 | redeem 直写 order |
|
||
| F2 | store → trade/benefit |
|
||
| F3 | benefit → trade/redeem |
|
||
| F4 | trade → redeem |
|
||
| F5 | benefit → redeem |
|
||
| F6 | catalog → trade/settlement |
|
||
| F9 | apps import server 源码 |
|
||
|
||
## integrations（preV1）
|
||
|
||
| Flag | Provider | 行为 |
|
||
|------|----------|------|
|
||
| MOCK_SMS=true | sms.mock | 固定码 123456 |
|
||
| MOCK_PAY=true | pay.mock | 同步 PAID + 发券 |
|
||
| MOCK_DELIVERY_AUTO=true | delivery.mock | BullMQ 自动推进状态 |
|