dukang/server/dukang-api/AGENTS.md

杜康好客 · 后端 AGENTS.md

父级：../AGENTS.md · API 契约：V2 手册 §六 · 表结构：§五

范围

本目录 = 唯一后端进程 dukang-api（NestJS 10 + Prisma 5）。

模块 → 表 OWNER（写权限）

Module	主要 Prisma Model	负责人
iam	User, UserAddress, …	jacy-dukang
catalog	CommonCity, CommonProductItem, …	jacy-dukang
store	Store, Partner	刘景尧
trade	Order, OrderDelivery	jacy-dukang
benefit	BenefitCoupon	jacy-dukang
redeem	RedeemRecord, StoreRating	刘景尧
settlement	StorePayout, PartnerBill	jacy-dukang
ops	只读聚合	jacy-dukang
analytics	LogUserAnalytics	jacy-dukang
common	CommonResource, CommonEvent, CommonTicket	jacy-dukang
integrations	无表	jacy-dukang

log_*：LogThirdParty 由写入方 Module 负责（支付→trade，短信→iam/notify）。

允许依赖（摘要）

trade → catalog, store, benefit, iam, notify, common, domain
benefit → iam, common, domain（禁止 → trade/redeem）
redeem → benefit, store, settlement, iam, notify, common, domain
store → catalog, iam, common, domain（禁止 → trade/benefit）
settlement → trade, redeem, store, catalog, iam, notify, common, domain
callbacks → trade, benefit, settlement, common（薄层，无业务表）
jobs → trade, settlement, notify, common

完整矩阵见 V2 手册 §四 §2.5.2。

新接口 checklist

1. 在 OWNER 模块 建 dto/、*.controller.ts、*.service.ts
2. Service 只写本模块表；跨域 inject exported Service
3. Guard：JwtAuthGuard + actorType 校验（User/Store/Partner/HQ）
4. 响应 { code: 0, message: 'ok', data }（ResponseInterceptor）
5. DTO/枚举同步 packages/shared-types
6. preV1 Mock：改 integrations/*，不在 Controller 散落 if (mock)

Mock 集成（preV1）

integrations/
├── sms/sms.mock.provider.ts
├── pay/pay.mock.provider.ts
└── delivery/delivery.mock.provider.ts

开关见 packages/shared-types/src/config.ts（MOCK_SMS, MOCK_PAY, MOCK_DELIVERY_AUTO）。

常用命令

pnpm dev:api
pnpm db:validate
pnpm db:seed
cd server/dukang-api && npx prisma studio

禁止

• 在 redeem 里 prisma.order.update → 调 TradeService
• 在 benefit 里 inject TradeService / RedeemService
• 多个 Module 注册同一 callback 路由
• 复制起购/核销规则到 Controller → 用 packages/domain