杜康好客 · Cursor Agent 指引

本文件供 人类与 Agent 在编码前阅读。
AI 自动加载入口：AGENTS.md（跨工具通用）
Skills / 子 Agent：.cursor/skills/、.cursor/agents/（Cursor 2.4+）
与 skills.md、杜康好客-V2编码手册.md 配合使用。

1. 你是谁、要做什么

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

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

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

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

阅读 AGENTS.md 确认 OWNER 边界与当前阶段（preV1）
阅读 杜康好客-preV1编码手册.md；细节查 V2 手册对应 §
启用 Skill：@dukang-coding（通用）或 @dukang-prev1 / @dukang-task-card（按需）
按 OWNER 选择子 Agent：/owner-a-user-trade 等（见 AGENTS.md §子 Agent）
阅读 conventions.md 模块边界
若用户给出任务卡 ID（如 P1-M2-002 或 V2 的 M2-*）→ preV1 §9 或 V2 §七
对照 pages/{user,shop,partner}/ 原型图（preV1 无 hq 小程序；HQ 用 admin-web）
一次只完成一个任务卡；PR 前可用 /boundary-reviewer 审查跨模块违规

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（2 人团队）

负责人	Git 账号	App（preV1 → V2）	Module
Jacy	jacy-dukang	h5-user、admin-web → mini-user/mini-hq	iam, trade, benefit, analytics, catalog, settlement, ops
刘景尧	刘景尧	h5-partner、h5-shop → mini-partner	store, redeem
Jacy（横切）	jacy-dukang	packages/*, callbacks/, jobs/, integrations/	基础设施

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

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

权益发放额 = common_product_item.benefit_amount ?? price
同城起购 2 瓶 / 跨城 6 瓶
核销：直接核销 0 < amount ≤ 全部 ACTIVE 权益总余额；带单据核销 0 < amount ≤ 该单据可用金额
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 开始，除非用户指定其他任务卡。

编码时 @ AGENTS.md 或 Skill dukang-coding；需求变更只改 杜康好客-V2编码手册.md。

5.4 KiB Raw Permalink Blame History Unescape Escape