171 lines
7.4 KiB
Markdown
171 lines
7.4 KiB
Markdown
# 杜康好客 · 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~~ | 历史参考 | **不再作为需求依据** |
|
||
|
||
**禁止**：臆造 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: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 验证码：`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：待付款 | 已付款 | 已完成
|
||
```
|
||
|
||
## 环境与发版
|
||
|
||
| 环境 | 分支 | 目录 | 端口 | 域名 |
|
||
|------|------|------|------|------|
|
||
| local | `dev_jacy` | 本机 Docker 6016/6017 | API `:3000` | — |
|
||
| **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)
|