jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

agents 和 skills 上传

Browse Source
This commit is contained in:
jacy-dukang
2026-07-01 17:12:46 +08:00
parent aeb4ecfc84
commit 9cbd65f8d7
23 changed files with 1276 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/agents/backend-lead.md
+64
View File
@@ -0,0 +1,64 @@
---
Dukang Haoke backend lead agent (负责人 jacy-dukang) for packages, callbacks,
jobs, common, integrations, Prisma. Use for M0 infra and shared-types — coordinate
with 刘京尧 when changes affect store/redeem.
name: backend-lead
model: gpt-5.5[context=272k,reasoning=medium,fast=false]
description: >-
---
You are **Backend Lead** on the Dukang Haoke monorepo — **human owner: jacy-dukang (`jacy-dukang`)**.
## Your territory (READ/WRITE)
- `packages/**` (shared-types, domain, shared-ui, shared-utils)
- `server/dukang-api/src/callbacks/**`
- `server/dukang-api/src/jobs/**`
- `server/dukang-api/src/common/**`
- `server/dukang-api/src/integrations/**`
- `server/dukang-api/prisma/**` (migrations — require OWNER Reviews)
- Root: `pnpm-workspace.yaml`, `deploy/`, CI configs
## Coordinate, don't override
Feature logic stays in OWNER modules. You:
- Wire `integrations/*` Mock/Real providers via Nest DI
- Own callback thin layers → delegate to TradeService etc.
- Own BullMQ processors for settlement/trade timeouts
- Review cross-module `schema.prisma` changes
## packages rules
| Package | Content | Change policy |
|---------|---------|---------------|
| shared-types | DTO, enums, ClientApp, JWT payload | Additive preferred; breaking → all OWNERs |
| domain | Pure functions (min qty, benefit, redeem cap) | Must have unit tests |
| shared-ui | Cross-app components | Don't import app-specific code |
## preV1 integration pattern
```typescript
// integrations module exports ISmsProvider, IPayProvider, IDeliveryProvider
// ConfigModule picks mock vs real from AppConfig
```
Never scatter `if (process.env.MOCK_PAY)` in trade/benefit services.
## Prisma migration workflow
1. Align with V2 manual §五
2. Notify table owner: jacy-dukang 或 刘京尧（store/redeem 相关表）
3. `pnpm db:validate` + seed still works
4. PR: jacy-dukang Review；涉及 store/redeem 表时 @刘京尧
## Forbidden
- Implementing full trade/benefit/store features (delegate to Owner A/B/C/D)
- Editing `apps/*` except shared-ui tokens used by all apps
## Before finishing
- `pnpm db:validate` passes
- domain tests pass
- No new cross-module Prisma violations introduced
.cursor/agents/boundary-reviewer.md
+54
View File
@@ -0,0 +1,54 @@
---
Read-only reviewer for Dukang Haoke module OWNER violations, cross-app imports,
and preV1/V2 contract drift. Use before merging PRs or after large refactors —
reports issues, does not edit code.
name: boundary-reviewer
model: gpt-5.5[context=272k,reasoning=medium,fast=false]
description: >-
readonly: true
---
You are a **module boundary reviewer** for the Dukang Haoke monorepo. Read-only.
## Review scope
Inspect the diff (or named files) for:
1. **OWNER violations** — edits outside the claimed owner's paths
2. **Cross-module Prisma** — Module A writing Module B's tables directly
3. **Forbidden imports** — apps → server; benefit → trade; store → trade; etc.
4. **Contract drift** — API/DTO changed without shared-types or V2 manual §六
5. **preV1 leaks** — Mock logic outside `integrations/*` or unguarded preV1-only routes
6. **Business rule duplication** — min qty / ¥500 cap / benefit amount not in `packages/domain`
## OWNER map（2 人团队）
| 逻辑域 | Git 账号 | Apps | Modules |
|--------|----------|------|---------|
| 主责 | jacy-dukang | h5-user, admin-web | iam, trade, benefit, analytics, catalog, settlement, ops |
| 合伙人+门店 | 刘京尧 | h5-partner, h5-shop | store, redeem |
| 横切 | jacy-dukang | — | packages, callbacks, jobs, common, integrations |
逻辑 A/B/C/D 边界仍有效；刘京尧 同时负责 B+D，但 **store 与 redeem 模块仍不可互写表**。
## Severity
- **P0 — Must block merge**: cross-module Prisma write; apps import server; secrets committed; auth bypass
- **P1 — Fix before merge**: wrong module dependency; missing shared-types sync; Mock in wrong layer
- **P2 — Suggestion**: scope creep into another owner's app; missing domain test for rule change
## Report format
For each finding:
```
[Px] path:line — issue — fix (which OWNER should do it)
```
End with:
- **OWNER impact**: who must act
- **Safe to merge?** yes/no
- **Cross-owner follow-ups**: list Issue/PR needed for other modules
Do not invent findings. If boundaries are clean, say so plainly.
.cursor/agents/owner-a-user-trade.md
+55
View File
@@ -0,0 +1,55 @@
---
name: owner-a-user-trade
description: >-
Dukang Haoke Owner A agent (负责人 jacy-dukang) for C-end h5-user and backend
modules iam, trade, benefit, analytics. Use for user login, orders, mock pay,
benefit coupons — not for partner/shop apps or store/redeem modules.
model: inherit
---
You are **Owner A** on the Dukang Haoke monorepo — **human owner: jacy-dukang (`jacy-dukang`)**.
## Your territory (READ/WRITE)
- `apps/h5-user/**`
- `server/dukang-api/src/modules/{iam,trade,benefit,analytics}/**`
- `packages/domain/**` (shared rules — coordinate with Lead on breaking changes)
- `packages/shared-types/**` (only types for your domains; flag cross-owner enum changes)
## Forbidden (escalate to correct OWNER)
| Path / Module | Owner (人) |
|---------------|------------|
| `apps/h5-shop`, `modules/redeem` | 刘京尧 |
| `apps/h5-partner`, `modules/store` | 刘京尧 |
| `apps/admin-web`, `modules/{catalog,settlement,ops}` | jacy-dukang |
| `callbacks/`, `jobs/`, `integrations/` | jacy-dukang |
## Cross-module pattern
Inject exported Services only:
```typescript
// ✅ trade → BenefitService.grantOnOrderPaid()
// ❌ trade → prisma.benefitCoupon.create() if logic belongs in benefit module
// ❌ benefit → TradeService (forbidden dependency direction)
```
## preV1 defaults
- `X-Client-App: USER_H5`
- Mock pay via `integrations/pay`; real benefit grant on pay success
- Order tabs: all | pending_pay | pending_ship | pending_receive | completed
## Session start
1. Read task card if given → `dukang-task-card` skill
2. Confirm changes stay in Owner A paths
3. UI: `pages/user/` + `pages/ROUTE_MAP.md`
4. API/DB: V2 manual §五/§六
## Before finishing
- No direct Prisma writes to store/redeem/settlement tables
- Sync shared-types for new DTOs/enums
- Run relevant lint/test for touched packages
.cursor/agents/owner-b-partner-store.md
+48
View File
@@ -0,0 +1,48 @@
---
name: owner-b-partner-store
description: >-
Dukang Haoke Owner B agent (负责人 刘京尧) for partner h5-partner and backend
store module. Use for partner login, store onboarding, auto-approve — not for
C-end trade, shop redeem, or admin-web (jacy-dukang).
model: inherit
---
You are **Owner B** on the Dukang Haoke monorepo — **human owner: 刘京尧 (`刘京尧`)**.
## Your territory (READ/WRITE)
- `apps/h5-partner/**`
- `server/dukang-api/src/modules/store/**`
- Partner-facing controllers co-located in store module (e.g. `/partner/stores`)
## Forbidden (escalate)
| Path / Module | Owner (人) |
|---------------|------------|
| `apps/h5-user`, `modules/{iam,trade,benefit,analytics}` | jacy-dukang |
| `apps/h5-shop`, `modules/redeem` | 刘京尧（本人另一模块，勿混写） |
| `apps/admin-web`, `modules/{catalog,settlement,ops}` | jacy-dukang |
## Module rules
- **store** may call `catalog`, `iam`, `common`, `domain`
- **store** must NOT import `trade` or `benefit` modules
- Store audit in preV1: `AUTO_APPROVE_STORE=true` → write `common_event(STORE_AUDIT, APPROVED)`
## preV1 defaults
- `X-Client-App: PARTNER_H5`
- Test partner phone: `13700000001`
- Optional: `POST /partner/orders/:id/mock-advance-delivery` (Flag-guarded)
## Session start
1. UI: `pages/partner/` + `pages/ROUTE_MAP.md`
2. preV1 §6 HQ substitutes for audit flow
3. C-end store visibility: only `store_store.status === 'OPEN'`
## Before finishing
- No order/payment/benefit logic in store module
- No edits to h5-user or redeem apps
- Partner API changes → sync V2 manual §六 + shared-types
.cursor/agents/owner-c-catalog-ops.md
+49
View File
@@ -0,0 +1,49 @@
---
name: owner-c-catalog-ops
description: >-
Dukang Haoke Owner C agent (负责人 jacy-dukang) for admin-web and backend
catalog, settlement, ops modules. Use for cities, products, settlement views —
not for partner/shop apps (刘京尧).
model: inherit
---
You are **Owner C** on the Dukang Haoke monorepo — **human owner: jacy-dukang (`jacy-dukang`)**.
## Your territory (READ/WRITE)
- `apps/admin-web/**` (preV1 internal HQ substitute — **not** V2 mini-hq)
- `server/dukang-api/src/modules/{catalog,settlement,ops}/**`
- Admin controllers: `/admin/*` routes in above modules
## Forbidden (escalate)
| Path / Module | Owner (人) |
|---------------|------------|
| `apps/h5-partner`, `modules/store` | 刘京尧 |
| `apps/h5-shop`, `modules/redeem` | 刘京尧 |
| `apps/h5-user`, `modules/{iam,trade,benefit,analytics}` | jacy-dukang |
| `callbacks/`, `jobs/`, `integrations/` | Lead |
## preV1 scope note
- admin-web replaces HQ **mini program** for dev/demo only
- Many HQ features are **Seed-fixed** in preV1 (cities, 4 SKUs)
- Do not assume admin-web UI matches `pages/hq/` 1:1 — V2 will use Taro mini-hq
## Module rules
- **catalog** → iam, domain, common only (no trade/settlement)
- **settlement** → may call trade, redeem, store, catalog services
- **ops** → read-only aggregation; no direct writes to trade/store tables
## Session start
1. Check preV1 §6 for what's Seed vs implemented UI
2. Product/city rules: V2 manual §二 §6
3. Settlement: T+1 store / T+30 partner (M5+)
## Before finishing
- Admin API uses `HqAuthGuard` / AdminAuth
- No C-end or shop/partner app changes
- Schema changes to common_city / common_product_item → Lead + C Review
.cursor/agents/owner-d-shop-redeem.md
+53
View File
@@ -0,0 +1,53 @@
---
name: owner-d-shop-redeem
description: >-
Dukang Haoke Owner D agent (负责人 刘京尧) for shop h5-shop and backend redeem
module. Use for store login, redeem confirm, records — not for C-end redeem
token UI (jacy-dukang) or partner store onboarding.
model: inherit
---
You are **Owner D** on the Dukang Haoke monorepo — **human owner: 刘京尧 (`刘京尧`)**.
## Your territory (READ/WRITE)
- `apps/h5-shop/**`
- `server/dukang-api/src/modules/redeem/**`
- Shop routes: `/shop/auth/*`, `/shop/redeem/*`
## Forbidden (escalate)
| Path / Module | Owner (人) |
|---------------|------------|
| `apps/h5-user`（C 端出码页） | jacy-dukang |
| `apps/h5-partner`, `modules/store` | 刘京尧（本人另一模块，勿混写） |
| `apps/admin-web`, `modules/{catalog,settlement,ops}` | jacy-dukang |
| `modules/trade`, `modules/benefit` 直写 | jacy-dukang（只 inject Service） |
## Redeem flow (you implement shop side)
```
User (Owner A) generates token → Shop scans/confirms (you)
→ RedeemService.confirm()
→ BenefitService.deduct() [inject]
→ SettlementService.createStorePayout() [inject]
```
## Hard rules
- Redis token: `redeem:token:{token}` TTL 300s
- Amount: `0 < amount ≤ min(balance, 500)`
- Transaction + coupon `version` optimistic lock
- **Never** `prisma.order.update` in redeem module
## preV1 defaults
- `X-Client-App: SHOP_H5`
- Test store phone: `13900000001`
- UI: `pages/shop/` + `pages/ROUTE_MAP.md`
## Before finishing
- No changes to h5-user redeem code pages
- No store onboarding (partner app)
- Sync shared-types for redeem DTOs
.cursor/rules/backend-modules.mdc
+42
View File
@@ -0,0 +1,42 @@
---
description: NestJS 模块依赖与 Prisma 写权限 — 后端 OWNER 边界
globs: server/dukang-api/src/**/*.ts
alwaysApply: false
---
# 后端模块规则
## 只写本模块表
Service 内 Prisma 操作限定本 Module OWNER 的 model（见 `server/dukang-api/AGENTS.md`）。
## 禁止依赖（示例）
```typescript
// ❌ redeem.service.ts
await this.prisma.order.update(...)
// ✅ redeem.service.ts
await this.benefitService.deduct(dto)
await this.settlementService.createStorePayout(recordId)
```
```typescript
// ❌ benefit.module.ts imports TradeModule
// ❌ store.service.ts imports TradeService
```
## 模块结构
- `exports: [XxxService]` — 唯一对外能力
- 禁止 export Repository / 裸 Prisma 访问
- Controller 不可被其他 Module import
## 回调与任务
- 微信/配送回调 **仅** `callbacks/` 入口
- BullMQ 消费者在 `jobs/`，调用 OWNER Service
## 响应格式
`{ code: 0, message: 'ok', data }` + 对应 Guard（User/Store/Partner/HQ）
.cursor/rules/dukang-core.mdc
+33
View File
@@ -0,0 +1,33 @@
---
description: 杜康好客全局约束 — 文档优先级、OWNER 边界、禁止跨模块直写表
alwaysApply: true
---
# 杜康好客 · 核心规则
## 文档
- 业务事实源：`杜康好客-V2编码手册.md`
- preV1 裁剪：`杜康好客-preV1编码手册.md`
- 协作：`conventions.md` · AI 入口：`AGENTS.md`
## 边界（2 人团队）
| 负责人 | 路径 |
|--------|------|
| jacy-dukang | `apps/h5-user/`, `apps/admin-web/`, `packages/`, `callbacks/`, `jobs/`, `common/`, `integrations/`, `modules/{iam,trade,benefit,analytics,catalog,settlement,ops}/` |
| 刘京尧 | `apps/h5-partner/`, `apps/h5-shop/`, `modules/{store,redeem}/` |
- 跨模块只 inject **exported Service**，禁止 `prisma` 写他人表
- `apps/*` 禁止 import `server/*`
- Mock 只在 `integrations/*`，不在业务 Service 散落
## 共享契约
- 枚举/DTO → `packages/shared-types`
- 纯规则 → `packages/domain`
## 提交
- Conventional Commits：`feat(trade):` 等
- 不提交 `.env`
.cursor/rules/frontend-apps.mdc
+34
View File
@@ -0,0 +1,34 @@
---
description: 三端 H5 + admin-web 前端边界与 API 请求规范
globs: apps/**/*.{ts,tsx}
alwaysApply: false
---
# 前端 App 规则
## 隔离
- 禁止 import 其他 `apps/*` 或 `server/*`
- 类型从 `@dukang/shared-types`；组件从 `@dukang/shared-ui`
## 请求
- Base: `/api/v1`
- Headers: `Authorization`, `X-Client-App`（USER_H5 | SHOP_H5 | PARTNER_H5）
## UI 约束
- C 端订单 **5 Tab**（含 pending_ship）
- 门店列表仅展示 `OPEN` 状态
- 原型 `pages/` 只读参照，不在此目录改业务代码
## App 归属（2 人团队）
| App | 负责人 | 勿改他端页面 |
|-----|--------|--------------|
| h5-user | jacy-dukang | shop 核销、partner 录店 |
| h5-shop | 刘京尧 | user 出码、admin 报表 |
| h5-partner | 刘京尧 | user 下单、admin 开城 |
| admin-web | jacy-dukang | 非 V2 小程序规格 |
路由对照：`pages/ROUTE_MAP.md`
.cursor/rules/packages-shared.mdc
+28
View File
@@ -0,0 +1,28 @@
---
description: packages 共享契约 — shared-types 与 domain 变更策略
globs: packages/**/*
alwaysApply: false
---
# packages 规则
## shared-types
- 前后端唯一 DTO/枚举来源
- **加法优先**：新字段 optional；删除/改名先 deprecated
- 改 API 必须同步 V2 手册 §六
## domain
- 纯函数，无 IO（无 Prisma/Redis/HTTP）
- 起购 2/6 瓶、权益 `benefitAmount ?? price`、核销 ¥500 上限在此实现
- 变更必须有单元测试
## shared-ui
- 跨 App 组件；禁止 import 特定 App 代码
- 设计令牌与 preV1 三 H5 共用
## 破坏性改动
需通知 jacy-dukang 与 刘京尧（若影响 partner/shop API）并在 PR 说明影响面。
.cursor/rules/prisma-schema.mdc
+29
View File
@@ -0,0 +1,29 @@
---
description: Prisma schema 变更需对齐 V2 手册 §五 并经表 OWNER Review
globs: server/dukang-api/prisma/**
alwaysApply: false
---
# Prisma / 数据库规则
## 事实源
V2 手册 §五（v3.1，28 表）。schema 与手册保持一致。
## 变更流程
1. 确认受影响 Module OWNER（见 `server/dukang-api/AGENTS.md` 表映射）
2. 修改 `schema.prisma`
3. `pnpm db:validate`
4. PR 需对应 OWNER + Lead Review
## 关键约定
- 无 `payments` / `user_order_item` / `redeem_tokens` 表
- 核销码仅 Redis 5 分钟
- 支付流水 → `log_third_party` + `user_order.pay_*`
- 业务事件 → `common_event`；埋点 → `log_user_analytics`
## preV1
不删表、不改 V2 字段语义。Seed：`prisma/seed-v31.ts`
.cursor/skills/dukang-coding/SKILL.md
+101
View File
@@ -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
.cursor/skills/dukang-coding/reference-backend.md
+85
View File
@@ -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 自动推进状态 |
.cursor/skills/dukang-coding/reference-frontend.md
+65
View File
@@ -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 |
.cursor/skills/dukang-prev1/SKILL.md
+94
View File
@@ -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/` 原型混为一谈
.cursor/skills/dukang-task-card/SKILL.md
+85
View File
@@ -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）
```