# 杜康好客 · Cursor Agent 指引

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

---

## 1. 你是谁、要做什么

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

**当前编码手册（preV1）**：[`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)  
**V2 完整规格（预留对齐）**：[`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md)

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

---

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

1. 阅读 [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)；细节查 V2 手册对应 §
2. 阅读 [`skills.md`](./skills.md) 中的编码检查清单
3. 阅读 [`conventions.md`](./conventions.md) 模块边界
4. 若用户给出任务卡 ID（如 `P1-M2-002` 或 V2 的 `M2-*`）→ 在 preV1 §9 或 V2 §七 查验收标准
5. 对照 `pages/{user,shop,partner}/` 原型图（preV1 无 hq）
6. 一次只完成一个任务卡；完成后自验 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. 核心业务规则（不可偏离）

```text
权益发放额 = 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`。*