dukang/skills.md

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

preV1 联调：见 杜康好客-preV1编码手册.md

---

何时使用

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

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

---

Cursor Skills / Agents（推荐）

资源	路径	用途
AI 入口	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 — PRD、DB v3.1、API、计划（最高权威）
2. 杜康好客-preV1编码手册.md — 当前 Mock 联调裁剪
3. AGENTS.md + agent.md — 流程、OWNER、DoD
4. 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（从手册 §五 导出）

---

核心业务实现（勿偏离）

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