179 lines
5.4 KiB
Markdown
179 lines
5.4 KiB
Markdown
# 杜康好客 · Cursor Skills（编码技能）
|
||
|
||
> **preV1 联调**：见 [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md)
|
||
|
||
---
|
||
|
||
## 何时使用
|
||
|
||
- 初始化 Monorepo、实现 API、页面、数据库逻辑
|
||
- 用户给出任务卡 ID（`M2-BE-TRD-002` 等）或说「开始 coding」
|
||
- 修复与 V1 范围相关的 Bug
|
||
|
||
**需求/PRD 变更** → 只改 `杜康好客-V2编码手册.md`，不要边写代码边改业务规则。
|
||
|
||
---
|
||
|
||
## Cursor Skills / Agents（推荐）
|
||
|
||
| 资源 | 路径 | 用途 |
|
||
|------|------|------|
|
||
| AI 入口 | [`AGENTS.md`](./AGENTS.md) | 自动加载的项目上下文 |
|
||
| 编码 Skill | `.cursor/skills/dukang-coding/` | @dukang-coding |
|
||
| preV1 Skill | `.cursor/skills/dukang-prev1/` | Mock / Flag |
|
||
| 任务卡 Skill | `.cursor/skills/dukang-task-card/` | P1-* / M*-* |
|
||
| OWNER 子 Agent | `.cursor/agents/owner-*.md` | `/owner-a-user-trade` 等 |
|
||
| 边界审查 | `.cursor/agents/boundary-reviewer.md` | PR 前只读审查 |
|
||
| Scoped Rules | `.cursor/rules/*.mdc` | 按文件类型自动附加 |
|
||
|
||
## 文档读取顺序
|
||
|
||
1. [`杜康好客-V2编码手册.md`](./杜康好客-V2编码手册.md) — PRD、DB v3.1、API、计划（最高权威）
|
||
2. [`杜康好客-preV1编码手册.md`](./杜康好客-preV1编码手册.md) — 当前 Mock 联调裁剪
|
||
3. [`AGENTS.md`](./AGENTS.md) + [`agent.md`](./agent.md) — 流程、OWNER、DoD
|
||
4. [`conventions.md`](./conventions.md) — 模块边界、提交规范
|
||
5. `pages/{端}/` — UI 原型（字段、Tab、跳转）
|
||
6. `.cursor/skills/dukang-coding/reference-*.md` — 前后端路径速查（可选）
|
||
|
||
---
|
||
|
||
## 编码前检查清单
|
||
|
||
```
|
||
- [ ] 已确认任务卡 ID 与 OWNER 模块
|
||
- [ ] 已读手册 PRD 对应 § 与 pages/ 原型文件名
|
||
- [ ] 已知 API 路径与 Guard（UserAuth/StoreAuth/PartnerAuth/AdminAuth）
|
||
- [ ] 已知 Prisma model（v3.1 表名，见手册 §五）
|
||
- [ ] 不跨模块直写他人表（只 inject exported Service）
|
||
- [ ] 新枚举/DTO → packages/shared-types
|
||
- [ ] 纯规则 → packages/domain（无 IO）
|
||
```
|
||
|
||
---
|
||
|
||
## 仓库与模块映射
|
||
|
||
| 路径 | 用途 |
|
||
|------|------|
|
||
| `apps/mini-user` | C端 Taro |
|
||
| `apps/mini-partner` | 合伙人 |
|
||
| `apps/mini-hq` | 总部 |
|
||
| `apps/h5-shop` | 门店 H5 |
|
||
| `server/dukang-api/src/modules/iam` | 四端登录、JWT |
|
||
| `modules/catalog` | 开城、商品、推广码 |
|
||
| `modules/trade` | 订单、支付、改址 |
|
||
| `modules/benefit` | 权益券 |
|
||
| `modules/store` | 门店、审核 |
|
||
| `modules/redeem` | 核销 |
|
||
| `modules/settlement` | T+1/T+30 结算 |
|
||
| `modules/ops` | 看板、预警、报表 |
|
||
| `modules/analytics` | 埋点、归因 |
|
||
| `modules/notify` | 短信（内部 Service） |
|
||
| `callbacks/` | 微信/配送回调（薄层） |
|
||
| `jobs/` | BullMQ、定时任务 |
|
||
|
||
---
|
||
|
||
## JWT 与账号表（v3.1）
|
||
|
||
| clientApp | actorType | 表 |
|
||
|-----------|-----------|-----|
|
||
| USER_MINI | USER | user_user |
|
||
| SHOP_H5 | STORE | store_account |
|
||
| PARTNER_MINI | PARTNER | partner_account |
|
||
| HQ_MINI | HQ | hq_account |
|
||
|
||
Token 必须含 `actorType` + `actorId`（手册 §六 §1.5）。
|
||
|
||
---
|
||
|
||
## 后端新接口工作流
|
||
|
||
1. 在 **OWNER 模块** 建 `dto/`、`controller`、`service`
|
||
2. Service 只写本模块表；跨域 inject 其他 Module 的 exported Service
|
||
3. Controller 加对应 Guard
|
||
4. 响应 `{ code: 0, message: 'ok', data }`
|
||
5. 同步 `packages/shared-types`
|
||
|
||
---
|
||
|
||
## 前端新页面工作流
|
||
|
||
1. 对照 `pages/{端}/` 原型命名页面与 Tab
|
||
2. 使用 `shared-types`；请求带 `X-Client-App`
|
||
3. C 端订单列表 **5 Tab**（含 `pending_ship`）
|
||
4. 个人中心/订单列表 Tab 命名与 PRD 一致
|
||
|
||
---
|
||
|
||
## 数据库变更
|
||
|
||
1. 改 `server/dukang-api/prisma/schema.prisma` 对齐手册 §五
|
||
2. 迁移需对应模块 OWNER Review
|
||
3. 可执行 SQL：`server/dukang-api/prisma/init_v3.sql`（从手册 §五 导出）
|
||
|
||
---
|
||
|
||
## 核心业务实现（勿偏离）
|
||
|
||
```typescript
|
||
// packages/domain
|
||
const benefitAmount = product.benefitAmount ?? product.price;
|
||
|
||
// V3 核销：直接核销按全部 ACTIVE 权益总余额；带单据核销按该单据可用金额
|
||
if (amount <= 0 || amount > allowedBalance) throw ...
|
||
|
||
// 订单 Tab
|
||
// all | pending_pay | pending_ship | pending_receive | completed
|
||
|
||
// C 端门店：仅 store_store.status === 'OPEN'
|
||
|
||
// 支付成功（callbacks → TradeService）
|
||
// log_third_party(WECHAT_PAY) + user_order.pay_status=PAID
|
||
// user_benefit_coupon + common_event(BENEFIT_LEDGER, GRANT)
|
||
|
||
// 埋点 → log_user_analytics（非 common_event）
|
||
// 业务审计 → common_event
|
||
```
|
||
|
||
---
|
||
|
||
## 核销并发（必须）
|
||
|
||
- Redis：`redeem:token:{token}` EX 300
|
||
- 事务：扣 `user_benefit_coupon.balance` + `version` 乐观锁
|
||
- 写 `user_redeem_record` + `store_payout`(PENDING) + `common_event(BENEFIT_LEDGER, REDEEM)`
|
||
|
||
---
|
||
|
||
## 资源上传（common_resource）
|
||
|
||
1. `POST /common/resources/upload-token` → OSS 直传
|
||
2. `POST /common/resources` 登记 owner_type/owner_id/biz_type
|
||
3. 商品主图、门店门头、合同、签收照均走此流程
|
||
|
||
---
|
||
|
||
## 提交规范
|
||
|
||
- Conventional Commits：`feat(trade): ...`、`fix(redeem): ...`
|
||
- scope = 端或模块名
|
||
- 不提交 `.env`
|
||
|
||
---
|
||
|
||
## 完成定义
|
||
|
||
- 任务卡「验收」列全部满足
|
||
- `packages/domain` 相关单测通过
|
||
- `pnpm lint` 无新增错误（M0 后）
|
||
- 无跨模块 Prisma 直写
|
||
|
||
---
|
||
|
||
## 延伸阅读
|
||
|
||
- 后端细节：`.cursor/skills/dukang-coding/reference-backend.md`
|
||
- 前端页面↔API：`.cursor/skills/dukang-coding/reference-frontend.md`
|
||
- 任务卡全集：手册 §七 附录 A
|