杜康好客 · 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`	按文件类型自动附加

文档读取顺序

杜康好客-V2编码手册.md — PRD、DB v3.1、API、计划（最高权威）
杜康好客-preV1编码手册.md — 当前 Mock 联调裁剪
AGENTS.md + agent.md — 流程、OWNER、DoD
conventions.md — 模块边界、提交规范
pages/{端}/ — UI 原型（字段、Tab、跳转）
.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）。

后端新接口工作流

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

前端新页面工作流

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

数据库变更

改 server/dukang-api/prisma/schema.prisma 对齐手册 §五
迁移需对应模块 OWNER Review
可执行 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）

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

提交规范

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

完成定义

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

5.4 KiB Raw Blame History Unescape Escape

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

何时使用

Cursor Skills / Agents（推荐）

文档读取顺序

编码前检查清单

仓库与模块映射

JWT 与账号表（v3.1）

后端新接口工作流

前端新页面工作流

数据库变更

核心业务实现（勿偏离）

核销并发（必须）

资源上传（common_resource）

提交规范

完成定义

延伸阅读

5.4 KiB

Raw Blame History