139 lines
5.4 KiB
Markdown
139 lines
5.4 KiB
Markdown
# 杜康好客 · 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 ≤ 全部 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`](./AGENTS.md) 或 Skill `dukang-coding`；需求变更只改 `杜康好客-V2编码手册.md`。*
|