agents 和 skills 上传

2026-07-01 17:12:46 +08:00
parent aeb4ecfc84
commit 9cbd65f8d7
23 changed files with 1276 additions and 34 deletions
@@ -0,0 +1,75 @@
+# 杜康好客 · 后端 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`