# 杜康好客 · Cursor Skills（编码技能）

> **preV1 联调**：见 [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)

---

## 何时使用

- 初始化 Monorepo、实现 API、页面、数据库逻辑
- 用户给出任务卡 ID（`M2-BE-TRD-002` 等）或说「开始 coding」
- 修复与 V1 范围相关的 Bug

**需求/PRD 变更** → 只改 `杜康好客-V2编码手册.md`，不要边写代码边改业务规则。

---

## 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. [`杜康好客-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` — 前后端路径速查（可选）

---

## 编码前检查清单

```
- [ ] 已确认任务卡 ID 与 OWNER 模块
- [ ] 已读手册 PRD 对应 § 与 pages/ 原型文件名
- [ ] 已知 API 路径与 Guard（UserAuth/StoreAuth/PartnerAuth/AdminAuth）
- [ ] 已知 Prisma model（v3.1 表名，见手册 §五）
- [ ] 不跨模块直写他人表（只 inject exported Service）
- [ ] 新枚举/DTO → packages/shared-types
- [ ] 纯规则 → packages/domain（无 IO）
```

---

## 仓库与模块映射

| 路径 | 用途 |
|------|------|
| `apps/mini-user` | C端 Taro |
| `apps/mini-partner` | 合伙人 |
| `apps/mini-hq` | 总部 |
| `apps/h5-shop` | 门店 H5 |
| `server/dukang-api/src/modules/iam` | 四端登录、JWT |
| `modules/catalog` | 开城、商品、推广码 |
| `modules/trade` | 订单、支付、改址 |
| `modules/benefit` | 权益券 |
| `modules/store` | 门店、审核 |
| `modules/redeem` | 核销 |
| `modules/settlement` | T+1/T+30 结算 |
| `modules/ops` | 看板、预警、报表 |
| `modules/analytics` | 埋点、归因 |
| `modules/notify` | 短信（内部 Service） |
| `callbacks/` | 微信/配送回调（薄层） |
| `jobs/` | BullMQ、定时任务 |

---

## JWT 与账号表（v3.1）

| clientApp | actorType | 表 |
|-----------|-----------|-----|
| USER_MINI | USER | user_user |
| SHOP_H5 | STORE | store_account |
| PARTNER_MINI | PARTNER | partner_account |
| HQ_MINI | HQ | hq_account |

Token 必须含 `actorType` + `actorId`（手册 §六 §1.5）。

---

## 后端新接口工作流

1. 在 **OWNER 模块** 建 `dto/`、`controller`、`service`
2. Service 只写本模块表；跨域 inject 其他 Module 的 exported Service
3. Controller 加对应 Guard
4. 响应 `{ code: 0, message: 'ok', data }`
5. 同步 `packages/shared-types`

---

## 前端新页面工作流

1. 对照 `pages/{端}/` 原型命名页面与 Tab
2. 使用 `shared-types`；请求带 `X-Client-App`
3. C 端订单列表 **5 Tab**（含 `pending_ship`）
4. 个人中心/订单列表 Tab 命名与 PRD 一致

---

## 数据库变更

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;

// V3 核销：直接核销按全部 ACTIVE 权益总余额；带单据核销按该单据可用金额
if (amount <= 0 || amount > allowedBalance) throw ...

// 订单 Tab
// all | pending_pay | pending_ship | pending_receive | completed

// C 端门店：仅 store_store.status === 'OPEN'

// 支付成功（callbacks → TradeService）
// log_third_party(WECHAT_PAY) + user_order.pay_status=PAID
// user_benefit_coupon + common_event(BENEFIT_LEDGER, GRANT)

// 埋点 → log_user_analytics（非 common_event）
// 业务审计 → common_event
```

---

## 核销并发（必须）

- Redis：`redeem:token:{token}` EX 300
- 事务：扣 `user_benefit_coupon.balance` + `version` 乐观锁
- 写 `user_redeem_record` + `store_payout`(PENDING) + `common_event(BENEFIT_LEDGER, REDEEM)`

---

## 资源上传（common_resource）

1. `POST /common/resources/upload-token` → OSS 直传
2. `POST /common/resources` 登记 owner_type/owner_id/biz_type
3. 商品主图、门店门头、合同、签收照均走此流程

---

## 提交规范

- Conventional Commits：`feat(trade): ...`、`fix(redeem): ...`
- scope = 端或模块名
- 不提交 `.env`

---

## 完成定义

- 任务卡「验收」列全部满足
- `packages/domain` 相关单测通过
- `pnpm lint` 无新增错误（M0 后）
- 无跨模块 Prisma 直写

---

## 延伸阅读

- 后端细节：`.cursor/skills/dukang-coding/reference-backend.md`
- 前端页面↔API：`.cursor/skills/dukang-coding/reference-frontend.md`
- 任务卡全集：手册 §七 附录 A