# 杜康好客 · AGENTS.md

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

## 项目概览

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

| 阶段 | 手册 | 说明 |
|------|------|------|
| **V3.0 唯一需求源** | [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) | 产品需求与三波交付（**只看这个**） |
| **现状对照** | [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md) | 已完成 / 冲突 / 缺口审计 |
| **V3 实现验收** | [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) | 核销规则、分工、闭环 |
| ~~V2 / preV1~~ | 历史参考（**已压缩**；V2 全文见 git 2026-08-06 前） | **不再作为需求依据** |

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

## 启动命令

```bash
# 基础设施
cd deploy && docker compose up -d   # dukang-v1：MySQL :6016 Redis :6017

# 依赖与数据库
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:3010/api/v1
pnpm dev:user     # :5173
pnpm dev:shop     # :5174
pnpm dev:partner  # :5175
pnpm dev:admin    # preV1 HQ 替代（内部工具，非 V2 小程序）

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

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

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

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

1. `杜康好客-v3-PRD.md` — **唯一需求事实源**
2. `杜康好客-v3-现状对照.md` — 实现进度审计
3. `杜康好客-v3编码手册.md` — 实现验收、核销、分工
4. `conventions.md` — 协作与模块边界
5. V2 手册 §四 §五 §六 — 仅作架构/DB/API **参考**（与 V3 冲突时忽略）
6. `pages/{user,shop,partner,hq}/` — UI 参照

> **V2 / preV1 手册不再作为需求依据。**

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

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

> **临时分工（2026-07）**：刘景尧任务暂由 `jacy-dukang` 全权负责；逻辑 OWNER B+D 路径可改，Prisma 迁移由 jacy 主导。

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

| 逻辑 OWNER | 负责人 | 可改路径 | 后端 Module |
|------------|--------|----------|-------------|
| **A + C + Lead + B + D** | jacy-dukang | `apps/*`, `packages/*`, `callbacks/`, `jobs/`, `common/`, `integrations/` | 全部后端模块 |
| ~~B + D~~ | ~~刘景尧~~ | — | 恢复分工前由 jacy 代管 |

**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 |
| V3.0 需求 Skill | `.cursor/skills/dukang-v3/` | @dukang-v3（PRD、Wave、REQ/ACC） |
| 需求 Skill | `.cursor/skills/dukang-project/` | @dukang-project |
| preV1 Skill | `.cursor/skills/dukang-prev1/` | Mock / Feature Flag |
| 任务卡 Skill | `.cursor/skills/dukang-task-card/` | DLV-W* / P1-* / M*-* |
| 发布 Skill | `.cursor/skills/dukang-release/` | @杜康发布 / @dukang-release |

## 子 Agent（按职责选用）

在 Cursor Agent 输入 `/` 选择：

| 子 Agent | 负责人 | 适用场景 |
|----------|--------|----------|
| `v3-delivery-lead` | jacy-dukang | V3.0 三波交付统筹、DLV 拆分、跨 Owner 协调 |
| `v3-req-reviewer` | — | V3.0 需求只读审查、REQ/ACC 缺口分析 |
| `owner-a-user-trade` | jacy-dukang | C 端、订单、支付、权益、埋点 |
| `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-v3` | V3.0 PRD、现状对照、Wave/REQ/ACC |
| `dukang-coding` | 实现功能、修 Bug（通用编码流程） |
| `dukang-project` | PRD/需求评审、原型对照、任务卡规划（**不用于日常编码**） |
| `dukang-prev1` | Mock 开关、preV1 裁剪、Feature Flag |
| `dukang-task-card` | 领取任务卡 `DLV-W*-*` / `P1-*` / `M*-*` 并按 DoD 交付 |
| `dukang-release`（杜康发布） | `dev_jacy`→`dev` 合并 + `deploy.sh` 发版 |

## 快速指令

- 现状审计：`@dukang-v3` + [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)
- 实现 DLV 任务：`@dukang-coding 实现 DLV-W1-M2`
- 波次规划：`/v3-delivery-lead 拆分 Wave 2 任务`
- 需求缺口审查：`/v3-req-reviewer 审查门店提现`
- PR 前审查：`/boundary-reviewer`
- 原型参照：`pages/{user,shop,partner}/`（只读）

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

```
权益额 = benefit_amount ?? price
同城起购 2 瓶 / 跨城 6 瓶
核销：直接核销 0 < amount ≤ 全部 ACTIVE 权益总余额；带单据核销 0 < amount ≤ 该单据可用金额；Redis 码 3 分钟
C 端门店仅 status=OPEN
订单 Tab：待付款 | 已付款 | 已完成
```

**iOS 微信 H5 JSSDK**：登录/OAuth 后禁止仅 SPA 跳转再调扫码；见 `packages/weixin-sdk/GOTCHAS.md`、知识库「门店端 · 踩坑」。
**微信小程序 open-type**：`chooseAvatar` 等 Button 的祖先禁止 `stopPropagation`（会编成 catchtap）；见知识库「C 端 · 踩坑」、`.cursor/rules/mini-user-weapp-opentype.mdc`。
**微信小程序页面标题**：weapp 只用原生 `navigationBarTitleText`，不要再画一层与导航栏重复的 `SubPageHeader` title；见 `.cursor/rules/mini-user-weapp-nav-title.mdc`。

## 环境与发版

| 环境 | 分支 | 目录 | 端口 | 域名 |
|------|------|------|------|------|
| local | `dev_jacy` | 本机 Docker 6016/6017 | API `:3010` | — |
| **staging 测试** | `dev` | `/opt/dukang-staging` | 8190–8194 | `*-test.dukanghaoke.com` |
| **production 生产** | `main` | `/opt/dukang` | 8090–8094 | `*.dukanghaoke.com` |

- 日常发布 → `deploy/deploy-staging.sh`（`dev`）
- 生产发布 → `deploy/deploy-prod.sh`（`main`，验收后）
- Staging：正式微信 + 全 Mock；配置见 `.env.staging.example`
- 详情：`@dukang-release` / `.cursor/skills/dukang-release/SKILL.md`

## 提交与 PR

- Conventional Commits：`feat(trade):`、`fix(redeem):`；scope = 端或模块
- 跨模块 PR → jacy-dukang + 刘景尧 共同 Review（若涉及双方模块）
- 改 API/表 → 同步 v3-PRD + v3编码手册 + `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)