dukang/.cursor/skills/dukang-coding/reference-backend.md

后端速查（杜康好客 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 自动推进状态