# 杜康好客 · Cursor Agent 指引

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

---

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

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

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

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

---

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

1. 阅读 [`AGENTS.md`](./AGENTS.md) 确认 OWNER 边界与当前阶段（preV1）
2. 阅读 [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)；细节查 V2 手册对应 §
3. 启用 Skill：`@dukang-coding`（通用）或 `@dukang-prev1` / `@dukang-task-card`（按需）
4. 按 OWNER 选择子 Agent：`/owner-a-user-trade` 等（见 AGENTS.md §子 Agent）
5. 阅读 [`conventions.md`](./conventions.md) 模块边界
6. 若用户给出任务卡 ID（如 `P1-M2-002` 或 V2 的 `M2-*`）→ preV1 §9 或 V2 §七
7. 对照 `pages/{user,shop,partner}/` 原型图（preV1 无 hq 小程序；HQ 用 admin-web）
8. 一次只完成一个任务卡；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. 核心业务规则（不可偏离）

```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** 开始，除非用户指定其他任务卡。

---

*编码时 @ [`AGENTS.md`](./AGENTS.md) 或 Skill `dukang-coding`；需求变更只改 `杜康好客-V2编码手册.md`。*