agents 和 skills 上传

2026-07-01 17:12:46 +08:00
parent aeb4ecfc84
commit 9cbd65f8d7
23 changed files with 1276 additions and 34 deletions
@@ -0,0 +1,101 @@
+---
+name: dukang-coding
+description: >-
+  Implements Dukang Haoke (杜康好客) features following V2/preV1 coding manuals,
+  module OWNER boundaries, and shared-types contracts. Use when coding APIs,
+  pages, Prisma logic, task cards, or fixing bugs in this monorepo.
+---
+
+# 杜康好客 · 编码 Skill
+
+## 何时启用
+
+- 实现/修复 `apps/*`、`server/dukang-api`、`packages/*` 功能
+- 用户给出任务卡 ID 或 @ 本 skill
+- **不要**用于纯文档问答（直接读手册即可）
+
+## 会话启动（按序）
+
+1. 确认阶段：preV1 → 读 `杜康好客-preV1编码手册.md`；V2 能力 → 读 V2 手册对应 §
+2. 读 [`AGENTS.md`](../../AGENTS.md) OWNER 表 → **只改本 OWNER 路径**
+3. 有任务卡 ID → 配合 `dukang-task-card` skill 或查 preV1 §9 / V2 §七
+4. UI 任务 → `pages/ROUTE_MAP.md` + 对应 `pages/{端}/` 原型
+5. 编码前过一遍下方 Checklist
+
+## 编码前 Checklist
+
+```
+- [ ] 任务所属 OWNER 与目标路径已确认
+- [ ] API 路径、Guard、表名已从 V2 §六/§五 核对
+- [ ] 跨模块需求 → 只 inject 对方 exported Service
+- [ ] 新枚举/DTO → packages/shared-types
+- [ ] 起购/权益/核销规则 → packages/domain（禁止 Controller 硬编码）
+- [ ] preV1 Mock → integrations/*，非业务 Service 内散落 if
+```
+
+## 后端（OWNER 模块内）
+
+```
+modules/{name}/
+├── {name}.module.ts    # exports: [XxxService] 唯一出口
+├── {name}.controller.ts
+├── {name}.service.ts   # 仅写本模块 Prisma 表
+└── dto/
+```
+
+Workflow：DTO → Service（本模块表）→ Controller + Guard → 同步 shared-types。
+
+跨模块示例（允许）：
+
+```typescript
+// trade.service.ts — OWNER A
+constructor(
+  private readonly benefitService: BenefitService, // from BenefitModule
+  private readonly catalogService: CatalogService,
+) {}
+await this.benefitService.grantOnOrderPaid(orderId);
+```
+
+跨模块示例（禁止）：
+
+```typescript
+// redeem.service.ts — ❌ 禁止
+await this.prisma.order.update({ ... });
+```
+
+## 前端（单 App 内）
+
+1. 路由对照 `pages/ROUTE_MAP.md`
+2. `src/lib/api.ts` 统一 fetch + `X-Client-App`
+3. 类型从 `@dukang/shared-types` import
+4. C 端订单 Tab：`all | pending_pay | pending_ship | pending_receive | completed`
+
+## 核心业务（packages/domain）
+
+```typescript
+const benefitAmount = product.benefitAmount ?? product.price;
+// 核销：0 < amount ≤ min(balance, 500)
+// 同城 min 2 瓶 / 跨城 min 6 瓶
+```
+
+## 核销并发（M3+）
+
+- Redis `redeem:token:{token}` EX 300
+- 事务 + `user_benefit_coupon.version` 乐观锁
+- 写 `user_redeem_record` + `store_payout`(PENDING) + `common_event(BENEFIT_LEDGER, REDEEM)`
+
+## 资源上传
+
+`POST /common/resources/upload-token` → OSS 直传 → `POST /common/resources`
+
+## 完成定义
+
+- 任务卡验收项全部满足
+- 无跨模块 Prisma 直写
+- `pnpm lint` 无新增错误；domain 相关单测通过
+
+## 延伸阅读
+
+- 模块/表/依赖矩阵：[reference-backend.md](reference-backend.md)
+- 页面↔API 速查：[reference-frontend.md](reference-frontend.md)
+- preV1 Mock 细节：`dukang-prev1` skill
@@ -0,0 +1,85 @@
+# 后端速查（杜康好客 v3.1）
+
+> 完整 DDL/API 以 V2 手册 §五/§六 为准。
+
+## API Base
+
+- Prefix: `/api/v1`
+- Response: `{ code: 0, message: 'ok', data }`
+- JWT: `actorType` + `actorId` + `clientApp`
+
+## clientApp → actorType → 表
+
+| preV1 clientApp | V2 clientApp | actorType | 账号表 |
+|-----------------|--------------|-----------|--------|
+| USER_H5 | USER_MINI | USER | user_user |
+| SHOP_H5 | SHOP_H5 | STORE | store_account |
+| PARTNER_H5 | PARTNER_MINI | PARTNER | partner_account |
+| — | HQ_MINI | HQ | hq_account |
+
+## Module → API 前缀
+
+| Module | 前缀示例 | OWNER |
+|--------|----------|-------|
+| iam | `/auth`, `/user` | A |
+| catalog | `/catalog`, `/admin/cities`, `/admin/products` | C |
+| trade | `/trade`, `/partner/orders`, `/admin/orders` | A |
+| benefit | `/benefit` | A |
+| store | `/stores`, `/partner/stores`, `/admin/store-audits` | B |
+| redeem | `/redeem`, `/shop/redeem` | D |
+| settlement | `/settlement`, `/partner/settlement`, `/admin/settlement` | C |
+| ops | `/admin/dashboard`, `/admin/reports` | C |
+| analytics | `/analytics`, `/promo/touch` | A |
+| callbacks | `/callbacks/wechat/pay`, `/callbacks/xfx/delivery` | Lead |
+
+## 表前缀 → Module 写 OWNER
+
+| 前缀 | 示例表 | OWNER Module |
+|------|--------|--------------|
+| user_ | user_user, user_order, user_benefit_coupon | iam / trade / benefit |
+| store_ | store_store, store_account, store_payout | store / iam / settlement |
+| partner_ | partner_partner, partner_bill | store(B) / settlement(C) |
+| hq_ | hq_account | iam |
+| common_ | common_product_item, common_event, common_city | catalog / common |
+| log_ | log_third_party, log_user_analytics | 写入方 Module |
+
+**无以下 V1 表**：payments、user_order_item、redeem_tokens（DB）。
+
+## 关键跨模块调用链
+
+**Mock/真实支付成功**
+
+```
+PayProvider → TradeService.handlePaySuccess()
+  → BenefitService.grantOnOrderPaid(orderId)
+  → OrderDelivery 预创建
+  → common_event(ORDER_STATUS)
+```
+
+**核销确认**
+
+```
+RedeemService.confirm()
+  → BenefitService.deduct(couponId)
+  → SettlementService.createStorePayout(redeemRecordId)
+```
+
+## 禁止依赖（PR 拒绝）
+
+| # | 禁止 |
+|---|------|
+| F1 | redeem 直写 order |
+| F2 | store → trade/benefit |
+| F3 | benefit → trade/redeem |
+| F4 | trade → redeem |
+| F5 | benefit → redeem |
+| F6 | catalog → trade/settlement |
+| F9 | apps import server 源码 |
+
+## integrations（preV1）
+
+| Flag | Provider | 行为 |
+|------|----------|------|
+| MOCK_SMS=true | sms.mock | 固定码 123456 |
+| MOCK_PAY=true | pay.mock | 同步 PAID + 发券 |
+| MOCK_DELIVERY_AUTO=true | delivery.mock | BullMQ 自动推进状态 |
@@ -0,0 +1,65 @@
+# 前端速查（preV1 三 H5 + admin-web）
+
+> 路由事实源：[`pages/ROUTE_MAP.md`](../../../pages/ROUTE_MAP.md)
+
+## App 配置
+
+| App | Filter | Dev | X-Client-App |
+|-----|--------|-----|--------------|
+| h5-user | @dukang/h5-user | pnpm dev:user | USER_H5 |
+| h5-shop | @dukang/h5-shop | pnpm dev:shop | SHOP_H5 |
+| h5-partner | @dukang/h5-partner | pnpm dev:partner | PARTNER_H5 |
+| admin-web | @dukang/admin-web | pnpm dev:admin | AdminAuth（内部） |
+
+## 共享包
+
+```typescript
+import { OrderStatus, ClientApp } from '@dukang/shared-types';
+import { PageHeader } from '@dukang/shared-ui';
+```
+
+## h5-user 主路由（OWNER A）
+
+| Route | 页面 | 关键 API |
+|-------|------|----------|
+| `/login` | 登录 | POST /auth/sms/send, /auth/login/sms |
+| `/` | 首页 | GET /catalog/products |
+| `/product/:id` | 详情 | GET /catalog/products/:id |
+| `/order/confirm` | 确认订单 | POST /trade/orders/preview, /trade/orders |
+| `/pay` | Mock 支付 | POST /trade/orders/:id/pay |
+| `/orders` | 5 Taber | GET /trade/orders?tab= |
+| `/benefit` | 权益 | GET /benefit/coupons |
+| `/redeem` | 出码 | POST /redeem/token |
+| `/stores` | 门店 | GET /stores（仅 OPEN） |
+
+## h5-shop 主路由（OWNER D）
+
+| Route | 页面 | 关键 API |
+|-------|------|----------|
+| `/login` | 登录 | POST /shop/auth/login/sms |
+| `/redeem` | 核销确认 | POST /shop/redeem/confirm |
+| `/records` | 核销记录 | GET /shop/redeem/records |
+
+## h5-partner 主路由（OWNER B）
+
+| Route | 页面 | 关键 API |
+|-------|------|----------|
+| `/stores/new` | 录店 | POST /partner/stores |
+| `/stores` | 门店管理 | GET /partner/stores |
+| `/orders` | 辖区订单 | GET /partner/orders |
+| — | Mock 推进配送 | POST /partner/orders/:id/mock-advance-delivery |
+
+## UI 硬约束
+
+- C 端订单 **5 Tab**（含 pending_ship）
+- 个人中心无会员等级（V1 不做会员体系）
+- 清香型 4 SKU 可购；酱香/浓香灰态
+- 原型只读：`pages/{端}/*/code.html`，勿改原型目录
+
+## preV1 与 V2 UI 差异
+
+| 项 | preV1 | V2 |
+|----|-------|-----|
+| C/合伙人载体 | H5 | 微信小程序 |
+| 总部 | admin-web 内部 | mini-hq 小程序 |
+| 支付页 | Mock 同步成功 | 微信 JSAPI |
@@ -0,0 +1,94 @@
+---
+name: dukang-prev1
+description: >-
+  Guides preV1 Mock integration phase for Dukang Haoke: H5 three-client setup,
+  MOCK_SMS/MOCK_PAY/MOCK_DELIVERY flags, Seed data, and V2 upgrade path.
+  Use when working on Mock providers, feature flags, preV1 task cards P1-*,
+  or smoke tests — not for V2 WeChat/payment production integration.
+---
+
+# 杜康好客 · preV1 Mock Skill
+
+## 定位
+
+preV1 = V2 之上的**裁剪实现**：**不删表、不删 API 路径、不改字段语义**。
+
+权威文档：[`杜康好客-preV1编码手册.md`](../../杜康好客-preV1编码手册.md)
+
+## 六条裁剪（必记）
+
+1. **无 HQ 小程序** → `admin-web` 内部替代；`/admin/*` 保留，前端不暴露 AdminAuth 给 C/B/D 端
+2. **三端均 H5** → `USER_H5` / `SHOP_H5` / `PARTNER_H5`
+3. **无微信登录** → 仅 SMS；wechat 路由返回 501 或 Flag 关闭
+4. **验证码 Mock** → `123456`，`MOCK_SMS=true`
+5. **配送 Mock** → BullMQ 自动推进或合伙人 `mock-advance-delivery`
+6. **支付 Mock** → `POST /trade/orders/:id/pay` 同步成功 + **真实发券**
+
+## 环境变量（`.env.example`）
+
+```bash
+MOCK_SMS=true
+MOCK_SMS_CODE=123456
+MOCK_PAY=true
+MOCK_DELIVERY_AUTO=true
+AUTO_APPROVE_STORE=true
+```
+
+配置加载：`packages/shared-types/src/config.ts` → `loadAppConfig()`
+
+## Mock 代码位置（禁止散落）
+
+```
+server/dukang-api/src/integrations/
+├── sms/sms.interface.ts + sms.mock.provider.ts
+├── pay/pay.interface.ts + pay.mock.provider.ts
+└── delivery/delivery.interface.ts + delivery.mock.provider.ts
+```
+
+业务 Module 只 inject **interface**，由 Nest DI 切换 Mock/Real。
+
+## preV1 必做 vs 跳过
+
+| 必做 | 跳过（V2 补） |
+|------|---------------|
+| 三端 SMS 登录 | 微信登录/支付/退款 |
+| Mock 支付 + 真实发券 | 微信 prepay/回调验签 |
+| 5 Tab 订单 | HQ 小程序 UI |
+| Redis 核销码 + 门店核销 | 真实小飞侠/物流 |
+| 合伙人录店 + AUTO_APPROVE | 总部人工审核 UI |
+| 可选埋点 | 推广码 HQ UI、T+30 真实打款 |
+
+## HQ 能力替代（Seed）
+
+| V2 HQ | preV1 |
+|-------|-------|
+| 开城/商品 CRUD | Seed 固定 + admin-web 或改 seed |
+| 门店审核 | AUTO_APPROVE_STORE=true |
+| 退款/客服 | 跳过 |
+| 结算 | store_payout PENDING；可 Seed 演示账单 |
+
+Seed：`server/dukang-api/prisma/seed-v31.ts`
+
+## 测试账号
+
+| 角色 | 手机号 |
+|------|--------|
+| C 端 | 13800000001 |
+| 门店 | 13900000001 |
+| 合伙人 | 13700000001 |
+
+## 冒烟
+
+```bash
+node scripts/smoke-prev1.mjs
+```
+
+## preV1 → V2 切换检查
+
+按 preV1 手册 §8.2 逐项关闭 Mock Flag，**无需重构表结构**。
+
+## 边界提醒
+
+- preV1 skill **不负责**实现 V2 微信 SDK；遇到真实支付/短信需求 → 停止并切换 V2 手册 §九
+- 改 Mock 行为时 **仍须** 遵守 OWNER 模块边界
+- admin-web 是 preV1 内部工具，勿与 V2 `pages/hq/` 原型混为一谈
@@ -0,0 +1,85 @@
+---
+name: dukang-task-card
+description: >-
+  Executes Dukang Haoke task cards (P1-M* or M0-M6) one at a time with DoD
+  verification. Use when the user provides a task ID like P1-M2-002 or M2-FE-U-003,
+  or asks to start/implement a milestone card from the coding manuals.
+---
+
+# 杜康好客 · 任务卡 Skill
+
+## 原则
+
+- **一次只做一个任务卡**
+- 任务卡 ID 命名空间：`P1-*`（preV1）与 `M*-*`（V2）并行，勿混用验收标准
+- 需求变更只改 V2 手册，不在任务实现中私改业务规则
+
+## 领取流程
+
+1. **解析 ID** → 确定里程碑与 OWNER
+   - `P1-M2-002` → preV1 §9 + OWNER 见卡片内容
+   - `M2-BE-TRD-002` → V2 §七 附录 A
+2. **读验收标准** → 手册中该 ID 的「验收」列
+3. **读依赖** → PRD §、API 路径、DB 表、原型路径
+4. **确认边界** → 只改 [`AGENTS.md`](../../AGENTS.md) OWNER 表内路径
+5. **实现** → 配合 `dukang-coding` skill
+6. **自验 DoD** → 下方清单
+
+## OWNER 快速映射（2 人）
+
+| 领域 | 负责人 | 典型 ID |
+|------|--------|---------|
+| C 端 FE、h5-user、交易后端 | jacy-dukang | P1-M1-002, M2-* |
+| admin、catalog、settlement | jacy-dukang | M1-BE-CAT-* |
+| 合伙人、store | 刘京尧 | P1-M4-001 |
+| 门店核销、h5-shop | 刘京尧 | P1-M3-002 |
+| Monorepo/integrations | jacy-dukang | P1-M0-* |
+
+## preV1 任务卡（精简）
+
+| ID | 验收要点 |
+|----|----------|
+| P1-M0-001 | 三端 `pnpm dev` 可编译 |
+| P1-M0-003 | `pnpm db:validate` 通过 |
+| P1-M0-004 | Seed 郑州+4SKU+测试账号 |
+| P1-M1-001 | 123456 三端登录 |
+| P1-M1-002 | C 端首页 4 款酒 |
+| P1-M2-001 | 起购校验 2/6 瓶 |
+| P1-M2-002 | Mock 支付发券 |
+| P1-M2-003 | 5 Tab 含 pending_ship |
+| P1-M3-001 | 核销 ¥500 上限 |
+| P1-M3-002 | 门店扫码核销 |
+| P1-M4-001 | 录店 AUTO_APPROVE → C 端可见 |
+| P1-M5-001 | 配送自动推进到 COMPLETED |
+
+完整列表：preV1 手册 §9。
+
+## 完成定义（每个任务卡）
+
+```
+- [ ] 验收列每一条可演示/可脚本验证
+- [ ] 改动在 OWNER 路径内（跨模块需 inject Service + 双 OWNER 知晓）
+- [ ] 新枚举/DTO → shared-types
+- [ ] 纯规则 → domain + 单测（若涉及起购/权益/核销）
+- [ ] API/表变更 → 同步 V2 手册 §五/§六
+- [ ] pnpm lint 无新增错误
+```
+
+## 里程碑顺序
+
+**preV1**：P1-M0 → P1-M1 → P1-M2 → P1-M3 → P1-M4 → P1-M5 → P1-M6
+
+**V2**：M0 → M1 → … → M6 → 上线
+
+除非用户指定，默认从当前里程碑**下一个未完成**任务卡开始；不确定时先问用户或跑 smoke 判断进度。
+
+## 输出格式（任务完成时）
+
+```markdown
+## 任务卡 {ID} 完成
+
+**改动范围**：（路径列表）
+**验收**：（逐条 ✓）
+**未做/阻塞**：（如有，需其他 OWNER 配合的项）
+**建议下一步**：（下一任务卡 ID）
+```