agents 和 skills 上传

.cursor/agents/backend-lead.md

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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）
+```

.github/CODEOWNERS

@@ -0,0 +1,43 @@
+# 杜康好客 CODEOWNERS（2 人团队）
+# 仓库：阿里云 Codeup · 用户名与平台成员账号一致
+#
+# jacy-dukang   — 管理员 + 主责（C 端、admin、后端主模块、横切）
+# 刘京尧        — 合伙人端 + 门店端（h5-partner、h5-shop、store、redeem）
+
+# 文档 / 横切 / 基础设施
+/AGENTS.md                           @jacy-dukang
+/agent.md                            @jacy-dukang
+/conventions.md                      @jacy-dukang
+/skills.md                           @jacy-dukang
+/杜康好客-V2编码手册.md               @jacy-dukang
+/杜康好客-preV1编码手册.md            @jacy-dukang
+/.cursor/                            @jacy-dukang
+/deploy/                             @jacy-dukang
+/packages/                           @jacy-dukang @刘京尧
+
+# jacy-dukang — C 端 + 交易/权益域 + 总部 admin
+/apps/h5-user/                       @jacy-dukang
+/apps/admin-web/                      @jacy-dukang
+/server/dukang-api/src/modules/iam/ @jacy-dukang
+/server/dukang-api/src/modules/trade/ @jacy-dukang
+/server/dukang-api/src/modules/benefit/ @jacy-dukang
+/server/dukang-api/src/modules/analytics/ @jacy-dukang
+/server/dukang-api/src/modules/catalog/ @jacy-dukang
+/server/dukang-api/src/modules/settlement/ @jacy-dukang
+/server/dukang-api/src/modules/ops/  @jacy-dukang
+
+# 刘京尧 — 合伙人端 + 门店端
+/apps/h5-partner/                    @刘京尧
+/apps/h5-shop/                       @刘京尧
+/server/dukang-api/src/modules/store/ @刘京尧
+/server/dukang-api/src/modules/redeem/ @刘京尧
+
+# 横切（主责 jacy-dukang；改接口时 @刘京尧 若影响 partner/shop）
+/server/dukang-api/src/callbacks/    @jacy-dukang
+/server/dukang-api/src/jobs/         @jacy-dukang @刘京尧
+/server/dukang-api/src/common/       @jacy-dukang
+/server/dukang-api/src/integrations/ @jacy-dukang
+/server/dukang-api/prisma/           @jacy-dukang @刘京尧
+
+# 原型参照
+/pages/                              @jacy-dukang

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)

agent.md

@@ -1,6 +1,9 @@
 # 杜康好客 · Cursor Agent 指引
 
-> 本文件供 **下一个 Cursor Agent** 在编码前阅读。与 `skills.md`、`杜康好客-V2编码手册.md` 配合使用。
+> 本文件供 **人类与 Agent** 在编码前阅读。  
+> **AI 自动加载入口**：[`AGENTS.md`](./AGENTS.md)（跨工具通用）  
+> **Skills / 子 Agent**：`.cursor/skills/`、`.cursor/agents/`（Cursor 2.4+）  
+> 与 [`skills.md`](./skills.md)、[`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) 配合使用。
 
 ---
 
@@ -17,12 +20,14 @@
 
 ## 2. 启动流程（每次会话）
 
-1. 阅读 [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)；细节查 V2 手册对应 §
-2. 阅读 [`skills.md`](./skills.md) 中的编码检查清单
-3. 阅读 [`conventions.md`](./conventions.md) 模块边界
-4. 若用户给出任务卡 ID（如 `P1-M2-002` 或 V2 的 `M2-*`）→ 在 preV1 §9 或 V2 §七 查验收标准
-5. 对照 `pages/{user,shop,partner}/` 原型图（preV1 无 hq）
-6. 一次只完成一个任务卡；完成后自验 DoD
+1. 阅读 [`AGENTS.md`](./AGENTS.md) 确认 OWNER 边界与当前阶段（preV1）
+2. 阅读 [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)；细节查 V2 手册对应 §
+3. 启用 Skill：`@dukang-coding`（通用）或 `@dukang-prev1` / `@dukang-task-card`（按需）
+4. 按 OWNER 选择子 Agent：`/owner-a-user-trade` 等（见 AGENTS.md §子 Agent）
+5. 阅读 [`conventions.md`](./conventions.md) 模块边界
+6. 若用户给出任务卡 ID（如 `P1-M2-002` 或 V2 的 `M2-*`）→ preV1 §9 或 V2 §七
+7. 对照 `pages/{user,shop,partner}/` 原型图（preV1 无 hq 小程序；HQ 用 admin-web）
+8. 一次只完成一个任务卡；PR 前可用 `/boundary-reviewer` 审查跨模块违规
 
 ---
 
@@ -71,15 +76,13 @@
 
 ---
 
-## 6. 模块 OWNER（写代码时只改自己的目录）
+## 6. 模块 OWNER（2 人团队）
 
-| OWNER | App | Module |
-|-------|-----|--------|
-| A | mini-user | iam, trade, benefit, analytics |
-| B | mini-partner | store |
-| C | mini-hq | catalog, settlement, ops |
-| D | h5-shop | redeem |
-| Lead | packages/*, callbacks/, jobs/ | 横切 |
+| 负责人 | Git 账号 | App（preV1 → V2） | Module |
+|--------|----------|-------------------|--------|
+| Jacy | jacy-dukang | h5-user、admin-web → mini-user/mini-hq | iam, trade, benefit, analytics, catalog, settlement, ops |
+| 刘京尧 | 刘京尧 | h5-partner、h5-shop → mini-partner | store, redeem |
+| Jacy（横切） | jacy-dukang | packages/*, callbacks/, jobs/, integrations/ | 基础设施 |
 
 **禁止**：Module A 直写 Module B 的 Prisma 表；apps  import server 源码。
 
@@ -132,4 +135,4 @@ dukang/
 
 ---
 
-*编码时 @ 本文件或阅读 `skills.md`；需求变更只改 `杜康好客-V2编码手册.md`。*
+*编码时 @ [`AGENTS.md`](./AGENTS.md) 或 Skill `dukang-coding`；需求变更只改 `杜康好客-V2编码手册.md`。*

apps/AGENTS.md

@@ -0,0 +1,61 @@
+# 杜康好客 · 前端 Apps AGENTS.md
+
+> 父级：[`../AGENTS.md`](../AGENTS.md) · 路由映射：[`../pages/ROUTE_MAP.md`](../pages/ROUTE_MAP.md)
+
+## App 一览（preV1）
+
+| App | 端口 | X-Client-App | 负责人 | 原型 |
+|-----|------|--------------|--------|------|
+| `h5-user` | 5173 | `USER_H5` | jacy-dukang | `pages/user/` |
+| `h5-shop` | 5174 | `SHOP_H5` | 刘京尧 | `pages/shop/` |
+| `h5-partner` | 5175 | `PARTNER_H5` | 刘京尧 | `pages/partner/` |
+| `admin-web` | — | （Admin JWT） | jacy-dukang | preV1 内部 HQ 替代 |
+
+V2 目标：`mini-user` / `mini-partner` / `mini-hq` 替换对应 H5（除门店仍 H5）。
+
+## 前端硬规则
+
+- 请求基址 `/api/v1`；Header：`Authorization` + `X-Client-App`
+- 类型从 `@dukang/shared-types` import，禁止复制枚举字符串
+- 禁止 import `server/` 或另一个 `apps/*` 的源码
+- UI 共享组件优先 `@dukang/shared-ui`
+- C 端订单列表 **5 Tab**（含 `pending_ship`）
+
+## 新页面 workflow
+
+1. 在 `pages/ROUTE_MAP.md` 查 Stitch screen ↔ route
+2. 对照 `pages/{端}/*/code.html` + `screen.png`（只读参照）
+3. 在对应 App 的 `src/pages/` 实现；API 封装放 `src/lib/api.ts`
+4. 登录态：各 App 自有 Context/Storage，不跨 App 共享
+
+## 各 App 职责边界
+
+### h5-user（jacy-dukang）
+
+主链路：登录 → 首页/详情 → 下单 Mock 支付 → 5 Tab 订单 → 权益 → 核销码 → 门店列表
+
+**勿改**：门店核销确认 UI（属 h5-shop）、合伙人录店（属 h5-partner）
+
+### h5-shop（刘京尧）
+
+主链路：门店登录 → 首页 → 扫码/输入核销 → 确认 → 记录 → 营业状态
+
+**勿改**：C 端出码页面（属 h5-user）
+
+### h5-partner（刘京尧）
+
+主链路：登录 → 工作台 → 录店 → 门店列表 → 辖区订单 → Mock 推进配送（preV1）
+
+**勿改**：C 端商品/订单页、总部报表（admin-web / V2 mini-hq）
+
+### admin-web（jacy-dukang，preV1 限定）
+
+内部 Web 管理：开城、商品、订单、门店审核、结算查看。**不是** V2 总部小程序规格。
+
+变更 admin-web 时勿假设与 `pages/hq/` 原型 1:1；V2 需另建 `mini-hq`。
+
+## 启动
+
+```bash
+pnpm dev:user | dev:shop | dev:partner | dev:admin
+```

conventions.md

@@ -7,21 +7,28 @@
 
 ## 1. 代码所有权
 
-见 [`.github/CODEOWNERS`](./.github/CODEOWNERS)。端与后端模块边界：
+见 [`.github/CODEOWNERS`](./.github/CODEOWNERS)。**2 人团队**（Git 账号）：
 
-| 目录 | Owner | 说明 |
-|------|-------|------|
-| `apps/mini-user` | @dev-a | C端小程序 |
-| `apps/mini-partner` | @dev-b | 城市合伙人小程序 |
-| `apps/mini-hq` | @dev-c | 总部管理小程序 |
-| `apps/h5-shop` | @dev-d | 门店 H5 |
-| `server/.../modules/{iam,trade,benefit,analytics}` | @dev-a | 交易与权益域 |
-| `server/.../modules/store` | @dev-b | 门店域 |
-| `server/.../modules/{catalog,settlement,ops}` | @dev-c | 开城与结算域 |
-| `server/.../modules/redeem` | @dev-d | 核销域 |
-| `server/.../callbacks`, `jobs`, `common` | @backend-lead | 回调与任务 |
-| `packages/*` | 全员 + @tech-lead | 公共契约，破坏性改动谨慎 |
-| `server/dukang-api/prisma` | 全部 Owner | 迁移必须多人 Review |
+| Git 账号 | 角色 | 主责 |
+|----------|------|------|
+| `jacy-dukang` | 管理员 + 主责开发 | C 端、admin-web、后端主模块、横切 |
+| `刘京尧` | 开发 | 合伙人 H5、门店 H5、store/redeem 模块 |
+
+端与后端模块边界：
+
+| 目录 | 负责人 | 说明 |
+|------|--------|------|
+| `apps/h5-user` | jacy-dukang | C 端 H5（V2 → mini-user） |
+| `apps/admin-web` | jacy-dukang | preV1 总部替代 |
+| `apps/h5-partner` | 刘京尧 | 合伙人 H5 |
+| `apps/h5-shop` | 刘京尧 | 门店 H5 |
+| `server/.../modules/{iam,trade,benefit,analytics}` | jacy-dukang | 交易与权益域 |
+| `server/.../modules/{catalog,settlement,ops}` | jacy-dukang | 开城与结算域 |
+| `server/.../modules/store` | 刘京尧 | 门店域 |
+| `server/.../modules/redeem` | 刘京尧 | 核销域 |
+| `server/.../callbacks`, `jobs`, `common`, `integrations` | jacy-dukang | 回调与任务 |
+| `packages/*` | jacy-dukang 主责；破坏性改动 @刘京尧 | 公共契约 |
+| `server/dukang-api/prisma` | jacy-dukang + 刘京尧（涉及 store/redeem 表时） | 迁移 Review |
 
 ---
 

server/dukang-api/AGENTS.md

@@ -0,0 +1,75 @@
+# 杜康好客 · 后端 AGENTS.md
+
+> 父级：[`../AGENTS.md`](../AGENTS.md) · API 契约：V2 手册 §六 · 表结构：§五
+
+## 范围
+
+本目录 = 唯一后端进程 `dukang-api`（NestJS 10 + Prisma 5）。
+
+## 模块 → 表 OWNER（写权限）
+
+| Module | 主要 Prisma Model | 负责人 |
+|--------|-------------------|--------|
+| **iam** | User, UserAddress, … | jacy-dukang |
+| **catalog** | CommonCity, CommonProductItem, … | jacy-dukang |
+| **store** | Store, Partner | 刘京尧 |
+| **trade** | Order, OrderDelivery | jacy-dukang |
+| **benefit** | BenefitCoupon | jacy-dukang |
+| **redeem** | RedeemRecord, StoreRating | 刘京尧 |
+| **settlement** | StorePayout, PartnerBill | jacy-dukang |
+| **ops** | 只读聚合 | jacy-dukang |
+| **analytics** | LogUserAnalytics | jacy-dukang |
+| **common** | CommonResource, CommonEvent, CommonTicket | jacy-dukang |
+| **integrations** | 无表 | jacy-dukang |
+
+**log_***：`LogThirdParty` 由写入方 Module 负责（支付→trade，短信→iam/notify）。
+
+## 允许依赖（摘要）
+
+```
+trade → catalog, store, benefit, iam, notify, common, domain
+benefit → iam, common, domain（禁止 → trade/redeem）
+redeem → benefit, store, settlement, iam, notify, common, domain
+store → catalog, iam, common, domain（禁止 → trade/benefit）
+settlement → trade, redeem, store, catalog, iam, notify, common, domain
+callbacks → trade, benefit, settlement, common（薄层，无业务表）
+jobs → trade, settlement, notify, common
+```
+
+完整矩阵见 V2 手册 §四 §2.5.2。
+
+## 新接口 checklist
+
+1. 在 **OWNER 模块** 建 `dto/`、`*.controller.ts`、`*.service.ts`
+2. Service 只写本模块表；跨域 inject exported Service
+3. Guard：`JwtAuthGuard` + `actorType` 校验（User/Store/Partner/HQ）
+4. 响应 `{ code: 0, message: 'ok', data }`（`ResponseInterceptor`）
+5. DTO/枚举同步 `packages/shared-types`
+6. preV1 Mock：改 `integrations/*`，不在 Controller 散落 `if (mock)`
+
+## Mock 集成（preV1）
+
+```
+integrations/
+├── sms/sms.mock.provider.ts
+├── pay/pay.mock.provider.ts
+└── delivery/delivery.mock.provider.ts
+```
+
+开关见 `packages/shared-types/src/config.ts`（`MOCK_SMS`, `MOCK_PAY`, `MOCK_DELIVERY_AUTO`）。
+
+## 常用命令
+
+```bash
+pnpm dev:api
+pnpm db:validate
+pnpm db:seed
+cd server/dukang-api && npx prisma studio
+```
+
+## 禁止
+
+- 在 `redeem` 里 `prisma.order.update` → 调 `TradeService`
+- 在 `benefit` 里 inject `TradeService` / `RedeemService`
+- 多个 Module 注册同一 callback 路由
+- 复制起购/核销规则到 Controller → 用 `packages/domain`

skills.md

@@ -14,13 +14,26 @@
 
 ---
 
+## Cursor Skills / Agents（推荐）
+
+| 资源 | 路径 | 用途 |
+|------|------|------|
+| AI 入口 | [`AGENTS.md`](./AGENTS.md) | 自动加载的项目上下文 |
+| 编码 Skill | `.cursor/skills/dukang-coding/` | @dukang-coding |
+| preV1 Skill | `.cursor/skills/dukang-prev1/` | Mock / Flag |
+| 任务卡 Skill | `.cursor/skills/dukang-task-card/` | P1-* / M*-* |
+| OWNER 子 Agent | `.cursor/agents/owner-*.md` | `/owner-a-user-trade` 等 |
+| 边界审查 | `.cursor/agents/boundary-reviewer.md` | PR 前只读审查 |
+| Scoped Rules | `.cursor/rules/*.mdc` | 按文件类型自动附加 |
+
 ## 文档读取顺序
 
 1. [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) — PRD、DB v3.1、API、计划（最高权威）
-2. [`agent.md`](./agent.md) — Agent 流程与 DoD
-3. [`conventions.md`](./conventions.md) — 模块边界、提交规范
-4. `pages/{端}/` — UI 原型（字段、Tab、跳转）
-5. `.cursor/skills/dukang-coding/reference-*.md` — 前后端路径速查（可选）
+2. [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md) — 当前 Mock 联调裁剪
+3. [`AGENTS.md`](./AGENTS.md) + [`agent.md`](./agent.md) — 流程、OWNER、DoD
+4. [`conventions.md`](./conventions.md) — 模块边界、提交规范
+5. `pages/{端}/` — UI 原型（字段、Tab、跳转）
+6. `.cursor/skills/dukang-coding/reference-*.md` — 前后端路径速查（可选）
 
 ---