145 lines
5.9 KiB
Markdown
145 lines
5.9 KiB
Markdown
# 杜康好客 · AGENTS.md
|
||
|
||
> AI 编码入口。人类协作者仍读 [`agent.md`](./agent.md)；本文件供 Cursor / Codex / Copilot 等自动加载。
|
||
|
||
## 项目概览
|
||
|
||
杜康酒业 O2O 平台：**购酒 → 发券 → 门店核销**。Monorepo + 单体 NestJS（方案三：模块 OWNER）。
|
||
|
||
| 阶段 | 手册 | 说明 |
|
||
|------|------|------|
|
||
| **当前 V3 交付** | [`杜康好客-v3编码手册.md`](./杜康好客-v3编码手册.md) | 业务闭环交付验收标准 |
|
||
| **preV1 历史** | [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md) | Mock 联调裁剪（历史参考） |
|
||
| **V2 蓝图** | [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) | 完整产品蓝图（与 V3 冲突时 V3 优先） |
|
||
|
||
**禁止**：臆造 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-v3.mjs
|
||
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. `杜康好客-v3编码手册.md` — V3 交付业务规则与验收
|
||
2. `杜康好客-V2编码手册.md` §二 — 完整蓝图（与 V3 冲突时 V3 优先）
|
||
3. `杜康好客-preV1编码手册.md` — preV1 裁剪（历史参考）
|
||
4. [`conventions.md`](./conventions.md) — 协作与模块边界
|
||
5. V2 手册 §四 §五 §六 — 架构 / DB / API
|
||
6. `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 ≤ 全部 ACTIVE 权益总余额；带单据核销 0 < amount ≤ 该单据可用金额；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)
|