# 杜康好客 · 后端 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`）。

## 常用命令

```bash
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`