杜康好客 · Cursor Agent 指引

本文件供 下一个 Cursor Agent 在编码前阅读。与 skills.md、杜康好客-V2编码手册.md 配合使用。

1. 你是谁、要做什么

你是杜康好客 preV1 的实现 Agent（Mock 联调阶段）。目标：三端 H5 + NestJS 跑通购酒→发券→核销；架构与表结构对齐 V2。

当前编码手册（preV1）：杜康好客-preV1编码手册.md
V2 完整规格（预留对齐）：杜康好客-V2编码手册.md

不要依赖 doc/ 下分散旧文档（可能过时）；不要臆造 PRD 未定义的业务规则。

2. 启动流程（每次会话）

阅读 杜康好客-preV1编码手册.md；细节查 V2 手册对应 §
阅读 skills.md 中的编码检查清单
阅读 conventions.md 模块边界
若用户给出任务卡 ID（如 P1-M2-002 或 V2 的 M2-*）→ 在 preV1 §9 或 V2 §七查验收标准
对照 pages/{user,shop,partner}/ 原型图（preV1 无 hq）
一次只完成一个任务卡；完成后自验 DoD

3. 技术栈（锁定）

层	选型
前端	Taro 3 + React + TypeScript，Monorepo 四 App
后端	Node 20 + NestJS 10 + Prisma 5
数据	MySQL 8 + Redis 7 + BullMQ
存储	阿里云 OSS → `common_resource`
协作	一个 `server/dukang-api`，模块 OWNER，禁止跨模块直写表

4. 数据库 v3.1 要点（必记）

28 张表，前缀：user_ / partner_ / store_ / hq_ / common_ / log_
公共抽象：common_resource（OSS）、common_event（业务事件）、common_ticket（工单）、log_third_party（第三方）、log_user_analytics（埋点）
C 端用户：user_user，phone 唯一必填
B 端三表：store_account / partner_account / hq_account
订单：user_order 含商品快照（V1 单 SKU，无 user_order_item）
配送：user_order_delivery 与 user_order 1:1
支付：无 payments 表 → log_third_party + user_order.pay_*
核销码：仅 Redis 5 分钟，无 DB 表
权益流水：common_event(BENEFIT_LEDGER)，amount1/amount2 仅此类使用

完整 DDL 见手册 §五。

5. API 与鉴权

Base：/api/v1
JWT Payload：actorType（USER|STORE|PARTNER|HQ）+ actorId + clientApp
请求头：Authorization、X-Client-App
响应：{ code, message, data }
完整路径见手册 §六

clientApp	actorType	账号表
USER_MINI	USER	user_user
SHOP_H5	STORE	store_account
PARTNER_MINI	PARTNER	partner_account
HQ_MINI	HQ	hq_account

6. 模块 OWNER（写代码时只改自己的目录）

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

禁止：Module A 直写 Module B 的 Prisma 表；apps import server 源码。

7. 核心业务规则（不可偏离）

权益发放额 = common_product_item.benefit_amount ?? price
同城起购 2 瓶 / 跨城 6 瓶
核销：0 < amount ≤ min(balance, 500)
C 端门店列表仅 status=OPEN
订单 Tab：all | pending_pay | pending_ship | pending_receive | completed
支付回调幂等 → 发券 → common_event(BENEFIT_LEDGER, GRANT)
门店核销结算 60%，T+1；合伙人 T+30 账单

8. 仓库目标结构（M0 优先）

dukang/
├── apps/{mini-user,mini-partner,mini-hq,h5-shop}/
├── packages/{shared-types,domain,shared-ui,shared-utils}/
├── server/dukang-api/{prisma,src/modules,callbacks,jobs}/
├── pages/{user,shop,partner,hq}/     # 原型图（只读参照）
├── 杜康好客-V2编码手册.md
├── agent.md / skills.md / conventions.md
└── deploy/docker-compose.yml

9. 完成定义（DoD）

任务卡验收项全部满足
枚举/DTO 在 packages/shared-types
纯规则在 packages/domain（含单测）
未跨模块直写 Prisma 表
改了 API/表结构则同步手册相关章节（或提 PR 说明）

10. 里程碑顺序

M0 Monorepo 骨架 → M1 四端登录+开城+商品 → M2 下单支付+5 Tab 订单 → M3 权益核销 → M4 拓店审核+售后 → M5 结算 → M6 推广码+埋点 → 上线

从 M0-INFRA-001 开始，除非用户指定其他任务卡。

编码时 @ 本文件或阅读 skills.md；需求变更只改 杜康好客-V2编码手册.md。

4.7 KiB Raw Blame History Unescape Escape