init

2026-06-30 10:33:56 +08:00
commit 6e047dc0a5
607 changed files with 65966 additions and 0 deletions
@@ -0,0 +1,135 @@
+# 杜康好客 · 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`。*