agents 和 skills 上传

AGENTS.md

@@ -0,0 +1,121 @@
+# 杜康好客 · 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)。
+
+## 文档优先级（冲突时）
+
+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/*`
+
+## 子 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-prev1` | Mock 开关、preV1 裁剪、Feature Flag |
+| `dukang-task-card` | 领取任务卡 `P1-*` / `M*-*` 并按 DoD 交付 |
+
+## 核心业务常量（不可偏离）
+
+```
+权益额 = 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 → 相关双 OWNER 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)