# 杜康好客 · AGENTS.md

> AI 编码入口。人类协作者仍读 [`agent.md`](./agent.md)；本文件供 Cursor / Codex / Copilot 等自动加载。

## 项目概览

杜康酒业 O2O 平台：**购酒 → 发券 → 门店核销**。Monorepo + 单体 NestJS（方案三：模块 OWNER）。

| 阶段 | 手册 | 说明 |
|------|------|------|
| **当前 preV1** | [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md) | 三端 H5 + Mock 联调，同库同 API |
| **目标 V2** | [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) | 四端小程序 + 真实第三方（唯一事实源） |

**禁止**：臆造 PRD 未定义规则；依赖 `doc/` 下过时文档；跨 OWNER 直写他人 Prisma 表。

## 启动命令

```bash
# 基础设施
cd deploy && docker compose up -d

# 依赖与数据库
pnpm install
cp server/dukang-api/.env.example server/dukang-api/.env
pnpm db:generate && pnpm db:validate
cd server/dukang-api && npx prisma db push && pnpm prisma:seed

# 开发（分终端）
pnpm dev:api      # http://localhost:3000/api/v1
pnpm dev:user     # :5173
pnpm dev:shop     # :5174
pnpm dev:partner  # :5175
pnpm dev:admin    # preV1 HQ 替代（内部工具，非 V2 小程序）

# 验证
node scripts/smoke-prev1.mjs
pnpm lint && pnpm test
```

Mock 验证码：`123456`。测试账号见 [`README.md`](./README.md)。

> **端口冲突**：`h5-partner` 与 `admin-web` 同为 5175，勿同时 `dev:partner` + `dev:admin`。

## 文档优先级（冲突时）

1. `杜康好客-V2编码手册.md` §二 — 业务规则
2. `杜康好客-preV1编码手册.md` — preV1 裁剪（Mock / Flag）
3. [`conventions.md`](./conventions.md) — 协作与模块边界
4. V2 手册 §四 §五 §六 — 架构 / DB / API
5. `pages/{user,shop,partner}/` + [`pages/ROUTE_MAP.md`](./pages/ROUTE_MAP.md) — UI 参照

## 团队与 OWNER 边界（2 人）

| 负责人 | Git 账号 | 职责 |
|--------|----------|------|
| **Jacy**（管理员） | `jacy-dukang` | C 端、admin-web、后端主模块、packages、Prisma 迁移主 Review |
| **刘京尧** | `刘京尧` | 合伙人 H5、门店 H5、`store` / `redeem` 模块 |

逻辑模块边界仍按 A/B/C/D 划分（便于 Agent 隔离），**人员合并**如下：

| 逻辑 OWNER | 负责人 | 可改路径 | 后端 Module |
|------------|--------|----------|-------------|
| **A + C + Lead** | jacy-dukang | `apps/h5-user/`, `apps/admin-web/`, `packages/*`, `callbacks/`, `jobs/`, `common/`, `integrations/` | `iam`, `trade`, `benefit`, `analytics`, `catalog`, `settlement`, `ops` |
| **B + D** | 刘京尧 | `apps/h5-partner/`, `apps/h5-shop/` | `store`, `redeem` |

**Prisma 迁移**：jacy-dukang 主 Review；若改 `store_*` / 核销相关表，需 `@刘京尧` 共同 Review。

### 跨模块规则（R1–R8 摘要）

- 只 inject 对方 Module **exports 的 Service**，禁止 `prisma.xxx` 写他人表
- `apps/*` 禁止 import `server/*` 源码；只走 HTTP + `packages/shared-types`
- 业务纯规则 → `packages/domain`；枚举/DTO → `packages/shared-types`
- 微信/配送回调入口 **仅** `callbacks/`；Mock 实现 **仅** `integrations/*`

## Cursor 规范

| 类型 | 路径 | 说明 |
|------|------|------|
| Rules | `.cursor/rules/` | 自动加载的编码规范 |
| 编码 Skill | `.cursor/skills/dukang-coding/` | @dukang-coding |
| 需求 Skill | `.cursor/skills/dukang-project/` | @dukang-project |
| preV1 Skill | `.cursor/skills/dukang-prev1/` | Mock / Feature Flag |
| 任务卡 Skill | `.cursor/skills/dukang-task-card/` | P1-* / M*-* |

## 子 Agent（按职责选用）

在 Cursor Agent 输入 `/` 选择：

| 子 Agent | 负责人 | 适用场景 |
|----------|--------|----------|
| `owner-a-user-trade` | jacy-dukang | C 端 H5、订单、支付、权益、埋点 |
| `owner-c-catalog-ops` | jacy-dukang | admin-web、开城商品、结算、运营 |
| `backend-lead` | jacy-dukang | packages、callbacks、jobs、Prisma 横切 |
| `owner-b-partner-store` | 刘京尧 | 合伙人 H5、门店 CRUD/审核 |
| `owner-d-shop-redeem` | 刘京尧 | 门店 H5、核销 |
| `boundary-reviewer` | — | PR 前只读审查跨模块违规 |

## Skills（按需 @）

| Skill | 何时用 |
|-------|--------|
| `dukang-coding` | 实现功能、修 Bug（通用编码流程） |
| `dukang-project` | PRD/需求评审、原型对照、任务卡规划（**不用于日常编码**） |
| `dukang-prev1` | Mock 开关、preV1 裁剪、Feature Flag |
| `dukang-task-card` | 领取任务卡 `P1-*` / `M*-*` 并按 DoD 交付 |

## 快速指令

- 实现任务卡：`@dukang-coding 实现 P1-M2-002`
- 需求评审：`@dukang-project 对照 pages/partner/ 评审 PRD`
- PR 前审查：`/boundary-reviewer`
- 原型参照：`pages/{user,shop,partner}/`（只读）

## 核心业务常量（不可偏离）

```
权益额 = benefit_amount ?? price
同城起购 2 瓶 / 跨城 6 瓶
核销：0 < amount ≤ min(balance, 500)；Redis 码 5 分钟
C 端门店仅 status=OPEN
订单 Tab：all | pending_pay | pending_ship | pending_receive | completed
```

## 提交与 PR

- Conventional Commits：`feat(trade):`、`fix(redeem):`；scope = 端或模块
- 跨模块 PR → jacy-dukang + 刘京尧 共同 Review（若涉及双方模块）
- 改 API/表 → 同步 V2 手册 §五/§六 + `shared-types`
- 不提交 `.env`、`dist/`、`node_modules/`

## 完成定义（DoD）

- [ ] 任务卡验收项全部满足
- [ ] 未跨模块直写 Prisma 表
- [ ] 枚举/DTO 在 `shared-types`；纯规则在 `domain`
- [ ] `pnpm lint` 无新增错误；相关 domain 单测通过

## 嵌套指引

- 后端细节：[`server/dukang-api/AGENTS.md`](./server/dukang-api/AGENTS.md)
- 前端四 App：[`apps/AGENTS.md`](./apps/AGENTS.md)