76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
# 杜康好客 · 后端 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`
|