dukang/.cursor/skills/dukang-coding/SKILL.md

name, description

name	description
dukang-coding	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 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。

跨模块示例（允许）：

// trade.service.ts — OWNER A
constructor(
  private readonly benefitService: BenefitService, // from BenefitModule
  private readonly catalogService: CatalogService,
) {}
await this.benefitService.grantOnOrderPaid(orderId);

跨模块示例（禁止）：

// 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）

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
• 页面↔API 速查：reference-frontend.md
• preV1 Mock 细节：dukang-prev1 skill