From f3ae9e6520859332a185b98f50155a2370a2ddb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E4=BA=AC=E5=B0=A7?= Date: Wed, 1 Jul 2026 15:04:53 +0800 Subject: [PATCH] =?UTF-8?q?fix:=E6=9B=B4=E6=96=B0skill=E5=92=8Crules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/rules/backend-nestjs.mdc | 51 ++++++++ .cursor/rules/frontend-h5.mdc | 48 ++++++++ .cursor/rules/git-conventions.mdc | 32 +++++ .cursor/rules/packages-shared.mdc | 36 ++++++ .cursor/rules/project-core.mdc | 48 ++++++++ .cursor/skills/dukang-coding/SKILL.md | 98 +++++++++++++++ .../skills/dukang-coding/reference-backend.md | 113 ++++++++++++++++++ .../dukang-coding/reference-frontend.md | 100 ++++++++++++++++ .cursor/skills/dukang-project/SKILL.md | 68 +++++++++++ AGENTS.md | 40 +++++++ 10 files changed, 634 insertions(+) create mode 100644 .cursor/rules/backend-nestjs.mdc create mode 100644 .cursor/rules/frontend-h5.mdc create mode 100644 .cursor/rules/git-conventions.mdc create mode 100644 .cursor/rules/packages-shared.mdc create mode 100644 .cursor/rules/project-core.mdc create mode 100644 .cursor/skills/dukang-coding/SKILL.md create mode 100644 .cursor/skills/dukang-coding/reference-backend.md create mode 100644 .cursor/skills/dukang-coding/reference-frontend.md create mode 100644 .cursor/skills/dukang-project/SKILL.md create mode 100644 AGENTS.md diff --git a/.cursor/rules/backend-nestjs.mdc b/.cursor/rules/backend-nestjs.mdc new file mode 100644 index 0000000..2e1ade5 --- /dev/null +++ b/.cursor/rules/backend-nestjs.mdc @@ -0,0 +1,51 @@ +--- +description: 杜康好客 NestJS 后端编码规范 +globs: server/**/*.ts +alwaysApply: false +--- + +# 后端规范 + +## 模块目录 + +``` +server/dukang-api/src/ +├── modules/{iam,trade,benefit,catalog,store,redeem,settlement,ops,analytics,health}/ +├── common/{guards,decorators,interceptors,filters,prisma,redis}/ +├── integrations/{pay,sms,delivery}/ +└── jobs/ +``` + +## 新接口流程 + +1. 在 **OWNER 模块** 建 `dto/`、`*.service.ts`、`*.controller.ts` +2. Service 只写本模块 Prisma 表 +3. 跨域 inject 其他 Module 的 exported Service +4. Controller 加对应 Guard（`JwtAuthGuard`、`PhoneVerifiedGuard` 等） +5. 响应 `{ code: 0, message: 'ok', data }` +6. 同步 `packages/shared-types` + +## Controller 示例 + +```typescript +@Controller('trade/orders') +@UseGuards(JwtAuthGuard) +export class TradeController { + constructor(private readonly tradeService: TradeService) {} +} +``` + +## 鉴权路由前缀 + +| 端 | 前缀 | +|----|------| +| C 端 | `/auth`, `/user`, `/catalog`, `/trade`, `/benefit`, `/redeem`, `/stores` | +| 门店 | `/shop/auth`, `/shop/redeem`, `/shop/store` | +| 合伙人 | `/partner/*` | +| 总部 | `/admin/*` | + +## 数据约定 + +- 埋点 → `log_user_analytics`；业务审计 → `common_event` +- 支付 → `log_third_party` + `user_order.pay_*`（无 payments 表） +- 核销码 → Redis 5min（无 DB 表） diff --git a/.cursor/rules/frontend-h5.mdc b/.cursor/rules/frontend-h5.mdc new file mode 100644 index 0000000..8918c1a --- /dev/null +++ b/.cursor/rules/frontend-h5.mdc @@ -0,0 +1,48 @@ +--- +description: 杜康好客前端 H5 / Admin 编码规范 +globs: apps/**/*.{tsx,ts} +alwaysApply: false +--- + +# 前端规范 + +## 目录约定 + +``` +src/ +├── components/ # PascalCase（AppToast.tsx） +├── pages/ # *Page.tsx +├── layouts/ # *Layout.tsx +├── contexts/ # *Context.tsx +├── lib/ # kebab-case（api.ts, client-location.ts） +├── App.tsx +└── main.tsx +``` + +## 四 App 与样式 + +| App | 端口 | 样式 | +|-----|------|------| +| h5-user | 5173 | shared-ui tokens | +| h5-shop | 5174 | shared-ui tokens | +| h5-partner | 5175 | shared-ui tokens | +| admin-web | 5175 | Ant Design 5 | + +H5 三端通过 Vite alias 引用 `@dukang/shared-ui`；admin-web 独立 Ant Design。 + +## API 请求 + +```typescript +export const apiBase = '/api/v1'; +// 请求头：Authorization + X-Client-App +// preV1 值：USER_H5 | SHOP_H5 | PARTNER_H5 | HQ_WEB +``` + +Vite dev 代理 `/api` → `localhost:3000`。 + +## 新页面 + +1. 对照 `pages/{user,shop,partner,hq}/` 原型命名 +2. 类型从 `@dukang/shared-types` 导入 +3. C 端订单列表 **5 Tab**（含 `pending_ship`） +4. 单引号 + 分号，与现有文件保持一致 diff --git a/.cursor/rules/git-conventions.mdc b/.cursor/rules/git-conventions.mdc new file mode 100644 index 0000000..0524e85 --- /dev/null +++ b/.cursor/rules/git-conventions.mdc @@ -0,0 +1,32 @@ +--- +description: Git 提交与 PR 协作规范 +alwaysApply: true +--- + +# Git 规范 + +## 提交格式 + +Conventional Commits，scope = 端或模块名： + +``` +feat(trade): add order preview API +fix(redeem): enforce 500 yuan cap +chore(shared-types): add OrderStatus enum +``` + +## 禁止提交 + +- `.env`、`.env.local` 等敏感配置 +- `node_modules/`、`dist/`（已在 .gitignore） + +## PR 与 Review + +- feature 分支 + 小步 PR +- 跨模块改动需相关双 Owner Review +- Prisma 迁移必须多 Owner Review + +## Agent 行为 + +- **仅用户明确要求时** 才执行 git commit / push +- 不 amend 已推送的 commit，不 force push main/master diff --git a/.cursor/rules/packages-shared.mdc b/.cursor/rules/packages-shared.mdc new file mode 100644 index 0000000..3f0e3d0 --- /dev/null +++ b/.cursor/rules/packages-shared.mdc @@ -0,0 +1,36 @@ +--- +description: 杜康好客共享包（shared-types / domain / shared-ui）规范 +globs: packages/**/*.{ts,tsx} +alwaysApply: false +--- + +# 共享包规范 + +## 包职责 + +| 包 | 用途 | 约束 | +|----|------|------| +| `@dukang/shared-types` | DTO、枚举、错误码、JWT Payload | 前后端唯一契约 | +| `@dukang/domain` | 纯函数业务规则 | **禁止 IO**，含 Vitest 单测 | +| `@dukang/shared-ui` | H5 共享组件 + `tokens.css` | 仅 H5 三端使用 | + +## shared-types + +- 枚举用 `SCREAMING_SNAKE_CASE`（如 `OrderStatus.PENDING_PAY`） +- API Tab 查询用 snake_case（`pending_pay`） +- **加法优先**：新字段 optional；删除/改名先 deprecated +- 改 API 必须同步 V2 手册 §六 与 shared-types + +## domain + +纯规则示例（无数据库/HTTP）： + +```typescript +const benefitAmount = product.benefitAmount ?? product.price; +// 同城起购 2 瓶 / 跨城 6 瓶 +// 核销上限 ¥500 +``` + +## 破坏性改动 + +`packages/*` 改动需全员 + tech-lead Review；Prisma schema 迁移需全部 Owner Review。 diff --git a/.cursor/rules/project-core.mdc b/.cursor/rules/project-core.mdc new file mode 100644 index 0000000..eb4bd7f --- /dev/null +++ b/.cursor/rules/project-core.mdc @@ -0,0 +1,48 @@ +--- +description: 杜康好客 Monorepo 核心规范、事实源与模块边界 +alwaysApply: true +--- + +# 杜康好客 · 项目核心 + +## Monorepo 布局 + +- `apps/` — 前端（preV1：`h5-user`、`h5-shop`、`h5-partner`、`admin-web`） +- `packages/` — `shared-types`、`domain`、`shared-ui` +- `server/dukang-api/` — NestJS 单体 API +- `pages/` — UI 原型（**只读参照**，勿改） + +> V2 目标为 Taro 四端（`mini-user` 等），编码以 **当前实际目录** 为准。 + +## 事实源优先级 + +1. preV1 联调 → `杜康好客-preV1编码手册.md` +2. PRD / DB / API 权威 → `杜康好客-V2编码手册.md` +3. 协作边界 → `conventions.md` +4. Agent 流程 → `agent.md` + `skills.md` + +**禁止**：编码时修改业务规则；需求变更只改 V2 手册。 + +## 模块边界（硬约束） + +- 任一 `apps/*` **禁止** import 其他 app 或 `server/*` 源码 +- 后端 Module **禁止** 跨模块直写 Prisma 表，只 inject 对方 `exports` 的 Service +- 新枚举/DTO → `packages/shared-types`；纯规则 → `packages/domain`（无 IO） + +## 核心业务常量 + +- 权益额 = `benefit_amount ?? price` +- 核销：0 < amount ≤ min(balance, **500**) +- 订单 Tab：`all | pending_pay | pending_ship | pending_receive | completed` +- API：`/api/v1`，响应 `{ code, message, data }` +- JWT：`actorType` + `actorId` + `clientApp` + +## 模块 OWNER + +| Owner | App / Module | +|-------|-------------| +| A | h5-user → iam, trade, benefit, analytics | +| B | h5-partner → store | +| C | admin-web → catalog, settlement, ops | +| D | h5-shop → redeem | +| Lead | packages/*, callbacks/, jobs/ | diff --git a/.cursor/skills/dukang-coding/SKILL.md b/.cursor/skills/dukang-coding/SKILL.md new file mode 100644 index 0000000..db18c55 --- /dev/null +++ b/.cursor/skills/dukang-coding/SKILL.md @@ -0,0 +1,98 @@ +--- +name: dukang-coding +description: >- + Implements 杜康好客 features following preV1/V2 specs: NestJS API, H5 pages, + Prisma schema, shared-types. Use when implementing task cards, writing API/page + code, fixing bugs, or when the user says start coding or @dukang-coding. +disable-model-invocation: true +--- + +# 杜康好客 · 编码 Skill + +## 何时启用 + +- 实现任务卡（`M2-BE-TRD-002`、`P1-M2-002` 等） +- 写 API、页面、数据库逻辑 +- 用户说「开始 coding」或 @dukang-coding +- 修复 V1 范围 Bug + +**不用于**：写 PRD、评审需求（用 @dukang-project） + +## 文档读取顺序 + +1. `杜康好客-preV1编码手册.md` — preV1 联调范围 +2. `杜康好客-V2编码手册.md` — PRD、DB v3.1、API（最高权威） +3. `agent.md` — Agent 流程与 DoD +4. `conventions.md` — 模块边界 +5. `pages/{端}/` — UI 原型 +6. [reference-backend.md](reference-backend.md) / [reference-frontend.md](reference-frontend.md) — 路径速查 + +**需求变更** → 只改 V2 手册，编码时不改业务规则。 + +## 编码前检查清单 + +``` +- [ ] 已确认任务卡 ID 与 OWNER 模块 +- [ ] 已读手册 PRD 对应 § 与 pages/ 原型 +- [ ] 已知 API 路径与 Guard +- [ ] 已知 Prisma model（v3.1 表名） +- [ ] 不跨模块直写他人表 +- [ ] 新枚举/DTO → packages/shared-types +- [ ] 纯规则 → packages/domain（无 IO） +``` + +## 后端工作流 + +1. OWNER 模块建 `dto/`、`controller`、`service` +2. Service 只写本模块表；跨域 inject exported Service +3. Controller 加 Guard；响应 `{ code, message, data }` +4. 同步 `packages/shared-types` + +## 前端工作流 + +1. 对照 `pages/{端}/` 原型命名页面与 Tab +2. 使用 `shared-types`；请求带 `X-Client-App` +3. preV1 App：`h5-user` / `h5-shop` / `h5-partner` / `admin-web` +4. C 端订单 **5 Tab**（含 `pending_ship`） + +## 数据库变更 + +1. 改 `server/dukang-api/prisma/schema.prisma` 对齐手册 §五 +2. 迁移需 OWNER Review +3. 初始化 SQL：`server/dukang-api/prisma/init_v3.sql` + +## 核心业务（勿偏离） + +```typescript +// packages/domain +const benefitAmount = product.benefitAmount ?? product.price; + +// 核销上限 ¥500 +if (amount <= 0 || amount > coupon.balance || amount > 500) throw ... + +// 订单 Tab: all | pending_pay | pending_ship | pending_receive | completed + +// 支付成功 → log_third_party + user_order.pay_status=PAID +// → user_benefit_coupon + common_event(BENEFIT_LEDGER, GRANT) + +// 埋点 → log_user_analytics；业务审计 → common_event +``` + +## 核销并发（必须） + +- Redis：`redeem:token:{token}` EX 300 +- 事务：扣券 balance + version 乐观锁 +- 写 `user_redeem_record` + `store_payout`(PENDING) + `common_event(BENEFIT_LEDGER, REDEEM)` + +## 完成定义 + +- 任务卡验收项全部满足 +- `packages/domain` 相关单测通过 +- 无跨模块 Prisma 直写 +- 改了 API/表 → 同步手册与 shared-types + +## 延伸阅读 + +- 后端路径速查：[reference-backend.md](reference-backend.md) +- 前端页面速查：[reference-frontend.md](reference-frontend.md) +- 详细清单：根目录 `skills.md` diff --git a/.cursor/skills/dukang-coding/reference-backend.md b/.cursor/skills/dukang-coding/reference-backend.md new file mode 100644 index 0000000..6d8e906 --- /dev/null +++ b/.cursor/skills/dukang-coding/reference-backend.md @@ -0,0 +1,113 @@ +# 后端路径速查 + +> Base: `/api/v1` · 响应: `{ code, message, data }` + +## JWT clientApp（preV1 实际值） + +| clientApp | actorType | 账号表 | +|-----------|-----------|--------| +| USER_H5 | USER | user_user | +| SHOP_H5 | STORE | store_account | +| PARTNER_H5 | PARTNER | partner_account | +| HQ_WEB | HQ | hq_account | + +Token 含 `actorType` + `actorId` + `clientApp`。请求头：`Authorization`、`X-Client-App`。 + +## 表前缀 + +| 前缀 | 域 | +|------|-----| +| user_ | C 端用户、订单、权益、核销 | +| store_ | 门店、门店账号、结算 | +| partner_ | 合伙人 | +| hq_ | 总部账号 | +| common_ | 商品、资源、事件、工单 | +| log_ | 第三方、埋点 | + +## Guard 对照 + +| Guard | 用途 | +|-------|------| +| JwtAuthGuard | 需登录 | +| PhoneVerifiedGuard | C 端需绑定手机（下单/支付） | +| OptionalJwtAuthGuard | 可选登录（bootstrap） | + +Admin 路由在 `modules/ops/` 下，前缀 `/admin/*`。 + +## Controller 路由（当前实现） + +### iam + +| 路径 | Controller | +|------|-----------| +| `POST /auth/session/bootstrap` | UserAuthController | +| `POST /auth/sms/send` | UserAuthController | +| `POST /auth/sms/login` | UserAuthController | +| `GET /user/me` | UserAuthController | +| `GET/POST/PUT/DELETE /user/addresses` | UserAddressController | +| `POST /shop/auth/*` | ShopAuthController | +| `POST /partner/auth/*` | PartnerAuthController | +| `POST /admin/auth/login` | AdminAuthController | + +### catalog / trade / benefit / redeem + +| 路径 | Module | +|------|--------| +| `GET /catalog/*` | catalog | +| `POST/GET /trade/orders` | trade | +| `GET/POST /benefit/*` | benefit | +| `POST /redeem/*` | redeem（C 端） | +| `POST /shop/redeem/*` | redeem（门店） | + +### store / settlement + +| 路径 | Module | +|------|--------| +| `GET /stores` | store（C 端门店列表） | +| `GET/POST /partner/stores` | store | +| `GET /partner/dashboard` | store | +| `GET /shop/store` | store | +| `GET /shop/dashboard` | store | +| `GET /partner/settlement/*` | settlement | +| `GET /partner/me` | settlement | +| `GET /partner/orders` | trade | + +### ops（admin-web） + +| 路径 | 说明 | +|------|------| +| `/admin/dashboard` | 看板 | +| `/admin/users` | C 端用户 | +| `/admin/orders` | 订单 | +| `/admin/stores` | 门店 | +| `/admin/store-accounts` | 门店账号 | +| `/admin/store-media` | 门店媒体 | +| `/admin/partners` | 合伙人 | +| `/admin/partner-accounts` | 合伙人账号 | +| `/admin/cities` | 开城 | +| `/admin/hq-accounts` | 总部账号 | +| `/admin/benefit/coupons` | 权益券 | +| `/admin/benefit/ledgers` | 权益流水 | +| `/admin/redeem-records` | 核销记录 | +| `/admin/deliveries` | 配送 | + +### analytics / health + +| 路径 | Module | +|------|--------| +| `POST /analytics/*` | analytics | +| `GET /health` | health | + +## 模块 → OWNER + +| Module | Owner | 主责 | +|--------|-------|------| +| iam, trade, benefit, analytics | A | 交易与权益 | +| store | B | 门店域 | +| catalog, settlement, ops | C | 开城与结算 | +| redeem | D | 核销域 | + +## 禁止 + +- Module A 直写 Module B 的 Prisma 表 +- apps import server 源码 diff --git a/.cursor/skills/dukang-coding/reference-frontend.md b/.cursor/skills/dukang-coding/reference-frontend.md new file mode 100644 index 0000000..9600873 --- /dev/null +++ b/.cursor/skills/dukang-coding/reference-frontend.md @@ -0,0 +1,100 @@ +# 前端页面速查 + +## 四 App 概览 + +| App | 目录 | 端口 | CLIENT_APP | 原型 | +|-----|------|------|------------|------| +| h5-user | apps/h5-user | 5173 | USER_H5 | pages/user/ | +| h5-shop | apps/h5-shop | 5174 | SHOP_H5 | pages/shop/ | +| h5-partner | apps/h5-partner | 5175 | PARTNER_H5 | pages/partner/ | +| admin-web | apps/admin-web | 5175 | HQ_WEB | pages/hq/ | + +> h5-partner 与 admin-web 端口同为 5175，勿同时 dev。 + +Vite 代理：`/api` → `localhost:3000`。 + +## h5-user 路由（C 端） + +| 路由 | Page | 主要 API | +|------|------|----------| +| /login | LoginPage | /auth/* | +| / | HomePage | /catalog | +| /product/:id | ProductDetailPage | /catalog | +| /order/confirm | OrderConfirmPage | /trade/orders/preview | +| /pay | PayPage | /trade/orders/:id/pay | +| /orders | OrderListPage | /trade/orders?tab= | +| /orders/:id | OrderDetailPage | /trade/orders/:id | +| /stores | StoreListPage | /stores | +| /stores/:id | StoreDetailPage | /stores/:id | +| /benefit | BenefitPage | /benefit | +| /benefit/:id | BenefitDetailPage | /benefit/:id | +| /redeem | RedeemPage | /redeem | +| /redeem/code | RedeemCodePage | /redeem | +| /redeem/success | RedeemSuccessPage | — | +| /addresses | AddressListPage | /user/addresses | +| /mine | MinePage | /user/me | + +### 订单 5 Tab + +``` +all | pending_pay | pending_ship | pending_receive | completed +``` + +## h5-shop 路由（门店） + +| 路由 | Page | 主要 API | +|------|------|----------| +| /login | LoginPage | /shop/auth/* | +| / | HomePage | /shop/dashboard | +| /redeem | RedeemConfirmPage | /shop/redeem/* | +| /redeem/success | RedeemSuccessPage | — | +| /records | RecordsPage | /shop/redeem/records | +| /status | StatusPage | /shop/store | +| /mine | MinePage | /shop/store | + +## h5-partner 路由（合伙人） + +| 路由 | Page | 主要 API | +|------|------|----------| +| /login | LoginPage | /partner/auth/* | +| / | HomePage | /partner/dashboard | +| /stores | StoreListPage | /partner/stores | +| /stores/new | StoreCreatePage | /partner/stores | +| /stores/:id | StoreDetailPage | /partner/stores/:id | +| /orders | OrderListPage | /partner/orders | +| /orders/:id | OrderDetailPage | /partner/orders/:id | +| /center | CenterPage | /partner/me | +| /center/bills | BillsPage | /partner/settlement/* | + +## admin-web 路由（总部） + +| 路由 | Page | 主要 API | +|------|------|----------| +| /login | LoginPage | /admin/auth/login | +| / | DashboardPage | /admin/dashboard | +| /users | UsersPage | /admin/users | +| /orders | OrdersPage | /admin/orders | +| /stores | StoresPage | /admin/stores | +| /store-accounts | StoreAccountsPage | /admin/store-accounts | +| /store-media | StoreMediaPage | /admin/store-media | +| /partners | PartnersPage | /admin/partners | +| /partner-accounts | PartnerAccountsPage | /admin/partner-accounts | +| /cities | CitiesPage | /admin/cities | +| /hq-accounts | HqAccountsPage | /admin/hq-accounts | +| /benefit/coupons | BenefitCouponsPage | /admin/benefit/coupons | +| /benefit/ledgers | BenefitLedgersPage | /admin/benefit/ledgers | +| /redeem-records | RedeemRecordsPage | /admin/redeem-records | +| /deliveries | DeliveriesPage | /admin/deliveries | + +## 端 → API 前缀（V2 附录 B） + +| 端 | API 前缀 | NestJS Module | +|----|----------|---------------| +| C 端 | /auth, /user, /catalog, /trade, /benefit, /redeem, /stores | iam, catalog, trade, benefit, redeem, store | +| 门店 | /shop/auth, /shop/redeem, /shop/store | iam, redeem, store | +| 合伙人 | /partner/* | iam, store, trade, settlement | +| 总部 | /admin/* | iam, catalog, store, trade, settlement, ops | + +## 共享 UI + +H5 三端引用 `@dukang/shared-ui`（设计令牌 `tokens.css`）。admin-web 使用 Ant Design 5，不引用 shared-ui。 diff --git a/.cursor/skills/dukang-project/SKILL.md b/.cursor/skills/dukang-project/SKILL.md new file mode 100644 index 0000000..a6fd205 --- /dev/null +++ b/.cursor/skills/dukang-project/SKILL.md @@ -0,0 +1,68 @@ +--- +name: dukang-project +description: >- + Manages 杜康好客 PRD, requirements review, prototype mapping, and task card + planning. Use when writing PRD, reviewing requirements, mapping prototypes to + features, or splitting task cards. Not for daily coding (use @dukang-coding). +disable-model-invocation: true +--- + +# 杜康好客 · 项目/需求 Skill + +## 何时启用 + +- 写或改 PRD、业务规则 +- 评审需求、对照原型 +- 拆分或规划任务卡 +- 用户 @dukang-project + +**不用于**：日常编码、修 Bug（用 @dukang-coding） + +## 文档阅读顺序 + +| 优先级 | 文档 | 用途 | +|--------|------|------| +| 1 | `杜康好客-V2编码手册.md` §二 | **做什么**（业务规则、状态、边界） | +| 2 | `conventions.md` | **怎么协作**（模块边界、提交） | +| 3 | V2 手册 §四 | **怎么架构**（NestJS 模块） | +| 4 | V2 手册 §五 | **表结构**（Prisma / SQL） | +| 5 | V2 手册 §六 | **接口契约**（四端 JWT） | +| 6 | `pages/{user,shop,partner,hq}/` | **UI 参照** | +| 7 | `杜康好客-preV1编码手册.md` | preV1 联调范围 | + +## 需求变更规则 + +- **只改** `杜康好客-V2编码手册.md` 作为业务事实源 +- 编码 Agent **不得**边写代码边改业务规则 +- 改 API/表结构 → 同步手册 §五/§六 + `packages/shared-types` + +## 原型 → 模块映射 + +| 端 | 原型目录 | 主要 API 前缀 | NestJS Module | +|----|----------|---------------|---------------| +| C 端 | pages/user/ | /auth, /user, /catalog, /trade, /benefit, /redeem, /stores | iam, catalog, trade, benefit, redeem, store | +| 门店 | pages/shop/ | /shop/auth, /shop/redeem, /shop/store | iam, redeem, store | +| 合伙人 | pages/partner/ | /partner/* | iam, store, trade, settlement | +| 总部 | pages/hq/ | /admin/* | iam, catalog, store, trade, settlement, ops | + +## 任务卡格式 + +- ID 格式：`Mx-LAYER-NNN`（如 `M2-BE-TRD-002`） +- 任务卡全集：V2 手册 §七 附录 A +- preV1 任务卡：preV1 手册 §9 + +## 团队 OWNER + +| OWNER | 前端 | 后端 Module | +|-------|------|-------------| +| A | h5-user | iam, trade, benefit, analytics | +| B | h5-partner | store | +| C | admin-web | catalog, settlement, ops | +| D | h5-shop | redeem | +| Lead | packages/* | callbacks, jobs, common | + +## 输出要求 + +- 需求文档变更需标注影响模块与 Owner +- 新任务卡需含：PRD §、API 路径、DB 表、原型路径、验收标准 +- 跨模块 PR 需相关双 Owner Review diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8ab20d9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# 杜康好客 Agent 入口 + +> Cursor 标准入口，详细流程见 [`agent.md`](agent.md)。 + +## 会话启动 + +1. [`agent.md`](agent.md) — Agent 流程与 DoD +2. [`skills.md`](skills.md) — 编码检查清单 +3. [`conventions.md`](conventions.md) — 模块边界与协作 +4. [`杜康好客-preV1编码手册.md`](杜康好客-preV1编码手册.md) — preV1 联调范围 +5. [`杜康好客-V2编码手册.md`](杜康好客-V2编码手册.md) — PRD / DB / API 权威 + +## Cursor 规范 + +| 类型 | 路径 | 说明 | +|------|------|------| +| Rules | `.cursor/rules/` | 自动加载的编码规范 | +| 编码 Skill | `.cursor/skills/dukang-coding/` | @dukang-coding | +| 需求 Skill | `.cursor/skills/dukang-project/` | @dukang-project | + +## 快速指令 + +- 实现任务卡：`@dukang-coding 实现 M2-BE-TRD-002` +- 需求评审：`@dukang-project 对照 pages/user/ 评审 PRD` +- 原型参照：`pages/{user,shop,partner,hq}/`（只读） + +## preV1 实际 App + +``` +apps/h5-user → C 端 H5（5173） +apps/h5-shop → 门店 H5（5174） +apps/h5-partner → 合伙人 H5（5175） +apps/admin-web → 总部后台（5175） +``` + +## 硬约束 + +- 编码时不改业务规则；需求变更只改 V2 手册 +- apps 禁止 import 其他 app 或 server 源码 +- 后端禁止跨模块直写 Prisma 表