jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions 8 Packages Projects Releases Wiki Activity

fix:更新skill和rules

Browse Source
This commit is contained in:
刘京尧
2026-07-01 15:04:53 +08:00
parent 6fa8ecc714
commit f3ae9e6520
10 changed files with 634 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/skills/dukang-coding/SKILL.md
+98
View File
@@ -0,0 +1,98 @@
---
name: dukang-coding
description: >-
Implements 杜康好客 features following preV1/V2 specs: NestJS API, H5 pages,
Prisma schema, shared-types. Use when implementing task cards, writing API/page
code, fixing bugs, or when the user says start coding or @dukang-coding.
disable-model-invocation: true
---
# 杜康好客 · 编码 Skill
## 何时启用
- 实现任务卡（`M2-BE-TRD-002`、`P1-M2-002` 等）
- 写 API、页面、数据库逻辑
- 用户说「开始 coding」或 @dukang-coding
- 修复 V1 范围 Bug
**不用于**：写 PRD、评审需求（用 @dukang-project）
## 文档读取顺序
1. `杜康好客-preV1编码手册.md` — preV1 联调范围
2. `杜康好客-V2编码手册.md` — PRD、DB v3.1、API（最高权威）
3. `agent.md` — Agent 流程与 DoD
4. `conventions.md` — 模块边界
5. `pages/{端}/` — UI 原型
6. [reference-backend.md](reference-backend.md) / [reference-frontend.md](reference-frontend.md) — 路径速查
**需求变更** → 只改 V2 手册，编码时不改业务规则。
## 编码前检查清单
```
- [ ] 已确认任务卡 ID 与 OWNER 模块
- [ ] 已读手册 PRD 对应 § 与 pages/ 原型
- [ ] 已知 API 路径与 Guard
- [ ] 已知 Prisma model（v3.1 表名）
- [ ] 不跨模块直写他人表
- [ ] 新枚举/DTO → packages/shared-types
- [ ] 纯规则 → packages/domain（无 IO）
```
## 后端工作流
1. OWNER 模块建 `dto/`、`controller`、`service`
2. Service 只写本模块表；跨域 inject exported Service
3. Controller 加 Guard；响应 `{ code, message, data }`
4. 同步 `packages/shared-types`
## 前端工作流
1. 对照 `pages/{端}/` 原型命名页面与 Tab
2. 使用 `shared-types`；请求带 `X-Client-App`
3. preV1 App：`h5-user` / `h5-shop` / `h5-partner` / `admin-web`
4. C 端订单 **5 Tab**（含 `pending_ship`）
## 数据库变更
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;
// 核销上限 ¥500
if (amount <= 0 || amount > coupon.balance || amount > 500) throw ...
// 订单 Tab: all | pending_pay | pending_ship | pending_receive | completed
// 支付成功 → log_third_party + user_order.pay_status=PAID
// → user_benefit_coupon + common_event(BENEFIT_LEDGER, GRANT)
// 埋点 → log_user_analytics；业务审计 → common_event
```
## 核销并发（必须）
- Redis：`redeem:token:{token}` EX 300
- 事务：扣券 balance + version 乐观锁
- 写 `user_redeem_record` + `store_payout`(PENDING) + `common_event(BENEFIT_LEDGER, REDEEM)`
## 完成定义
- 任务卡验收项全部满足
- `packages/domain` 相关单测通过
- 无跨模块 Prisma 直写
- 改了 API/表 → 同步手册与 shared-types
## 延伸阅读
- 后端路径速查：[reference-backend.md](reference-backend.md)
- 前端页面速查：[reference-frontend.md](reference-frontend.md)
- 详细清单：根目录 `skills.md`
.cursor/skills/dukang-coding/reference-backend.md
+113
View File
@@ -0,0 +1,113 @@
# 后端路径速查
> Base: `/api/v1` · 响应: `{ code, message, data }`
## JWT clientApp（preV1 实际值）
| clientApp | actorType | 账号表 |
|-----------|-----------|--------|
| USER_H5 | USER | user_user |
| SHOP_H5 | STORE | store_account |
| PARTNER_H5 | PARTNER | partner_account |
| HQ_WEB | HQ | hq_account |
Token 含 `actorType` + `actorId` + `clientApp`。请求头：`Authorization`、`X-Client-App`。
## 表前缀
| 前缀 | 域 |
|------|-----|
| user_ | C 端用户、订单、权益、核销 |
| store_ | 门店、门店账号、结算 |
| partner_ | 合伙人 |
| hq_ | 总部账号 |
| common_ | 商品、资源、事件、工单 |
| log_ | 第三方、埋点 |
## Guard 对照
| Guard | 用途 |
|-------|------|
| JwtAuthGuard | 需登录 |
| PhoneVerifiedGuard | C 端需绑定手机（下单/支付） |
| OptionalJwtAuthGuard | 可选登录（bootstrap） |
Admin 路由在 `modules/ops/` 下，前缀 `/admin/*`。
## Controller 路由（当前实现）
### iam
| 路径 | Controller |
|------|-----------|
| `POST /auth/session/bootstrap` | UserAuthController |
| `POST /auth/sms/send` | UserAuthController |
| `POST /auth/sms/login` | UserAuthController |
| `GET /user/me` | UserAuthController |
| `GET/POST/PUT/DELETE /user/addresses` | UserAddressController |
| `POST /shop/auth/*` | ShopAuthController |
| `POST /partner/auth/*` | PartnerAuthController |
| `POST /admin/auth/login` | AdminAuthController |
### catalog / trade / benefit / redeem
| 路径 | Module |
|------|--------|
| `GET /catalog/*` | catalog |
| `POST/GET /trade/orders` | trade |
| `GET/POST /benefit/*` | benefit |
| `POST /redeem/*` | redeem（C 端） |
| `POST /shop/redeem/*` | redeem（门店） |
### store / settlement
| 路径 | Module |
|------|--------|
| `GET /stores` | store（C 端门店列表） |
| `GET/POST /partner/stores` | store |
| `GET /partner/dashboard` | store |
| `GET /shop/store` | store |
| `GET /shop/dashboard` | store |
| `GET /partner/settlement/*` | settlement |
| `GET /partner/me` | settlement |
| `GET /partner/orders` | trade |
### ops（admin-web）
| 路径 | 说明 |
|------|------|
| `/admin/dashboard` | 看板 |
| `/admin/users` | C 端用户 |
| `/admin/orders` | 订单 |
| `/admin/stores` | 门店 |
| `/admin/store-accounts` | 门店账号 |
| `/admin/store-media` | 门店媒体 |
| `/admin/partners` | 合伙人 |
| `/admin/partner-accounts` | 合伙人账号 |
| `/admin/cities` | 开城 |
| `/admin/hq-accounts` | 总部账号 |
| `/admin/benefit/coupons` | 权益券 |
| `/admin/benefit/ledgers` | 权益流水 |
| `/admin/redeem-records` | 核销记录 |
| `/admin/deliveries` | 配送 |
### analytics / health
| 路径 | Module |
|------|--------|
| `POST /analytics/*` | analytics |
| `GET /health` | health |
## 模块 → OWNER
| Module | Owner | 主责 |
|--------|-------|------|
| iam, trade, benefit, analytics | A | 交易与权益 |
| store | B | 门店域 |
| catalog, settlement, ops | C | 开城与结算 |
| redeem | D | 核销域 |
## 禁止
- Module A 直写 Module B 的 Prisma 表
- apps import server 源码
.cursor/skills/dukang-coding/reference-frontend.md
+100
View File
@@ -0,0 +1,100 @@
# 前端页面速查
## 四 App 概览
| App | 目录 | 端口 | CLIENT_APP | 原型 |
|-----|------|------|------------|------|
| h5-user | apps/h5-user | 5173 | USER_H5 | pages/user/ |
| h5-shop | apps/h5-shop | 5174 | SHOP_H5 | pages/shop/ |
| h5-partner | apps/h5-partner | 5175 | PARTNER_H5 | pages/partner/ |
| admin-web | apps/admin-web | 5175 | HQ_WEB | pages/hq/ |
> h5-partner 与 admin-web 端口同为 5175，勿同时 dev。
Vite 代理：`/api` → `localhost:3000`。
## h5-user 路由（C 端）
| 路由 | Page | 主要 API |
|------|------|----------|
| /login | LoginPage | /auth/* |
| / | HomePage | /catalog |
| /product/:id | ProductDetailPage | /catalog |
| /order/confirm | OrderConfirmPage | /trade/orders/preview |
| /pay | PayPage | /trade/orders/:id/pay |
| /orders | OrderListPage | /trade/orders?tab= |
| /orders/:id | OrderDetailPage | /trade/orders/:id |
| /stores | StoreListPage | /stores |
| /stores/:id | StoreDetailPage | /stores/:id |
| /benefit | BenefitPage | /benefit |
| /benefit/:id | BenefitDetailPage | /benefit/:id |
| /redeem | RedeemPage | /redeem |
| /redeem/code | RedeemCodePage | /redeem |
| /redeem/success | RedeemSuccessPage | — |
| /addresses | AddressListPage | /user/addresses |
| /mine | MinePage | /user/me |
### 订单 5 Tab
```
all | pending_pay | pending_ship | pending_receive | completed
```
## h5-shop 路由（门店）
| 路由 | Page | 主要 API |
|------|------|----------|
| /login | LoginPage | /shop/auth/* |
| / | HomePage | /shop/dashboard |
| /redeem | RedeemConfirmPage | /shop/redeem/* |
| /redeem/success | RedeemSuccessPage | — |
| /records | RecordsPage | /shop/redeem/records |
| /status | StatusPage | /shop/store |
| /mine | MinePage | /shop/store |
## h5-partner 路由（合伙人）
| 路由 | Page | 主要 API |
|------|------|----------|
| /login | LoginPage | /partner/auth/* |
| / | HomePage | /partner/dashboard |
| /stores | StoreListPage | /partner/stores |
| /stores/new | StoreCreatePage | /partner/stores |
| /stores/:id | StoreDetailPage | /partner/stores/:id |
| /orders | OrderListPage | /partner/orders |
| /orders/:id | OrderDetailPage | /partner/orders/:id |
| /center | CenterPage | /partner/me |
| /center/bills | BillsPage | /partner/settlement/* |
## admin-web 路由（总部）
| 路由 | Page | 主要 API |
|------|------|----------|
| /login | LoginPage | /admin/auth/login |
| / | DashboardPage | /admin/dashboard |
| /users | UsersPage | /admin/users |
| /orders | OrdersPage | /admin/orders |
| /stores | StoresPage | /admin/stores |
| /store-accounts | StoreAccountsPage | /admin/store-accounts |
| /store-media | StoreMediaPage | /admin/store-media |
| /partners | PartnersPage | /admin/partners |
| /partner-accounts | PartnerAccountsPage | /admin/partner-accounts |
| /cities | CitiesPage | /admin/cities |
| /hq-accounts | HqAccountsPage | /admin/hq-accounts |
| /benefit/coupons | BenefitCouponsPage | /admin/benefit/coupons |
| /benefit/ledgers | BenefitLedgersPage | /admin/benefit/ledgers |
| /redeem-records | RedeemRecordsPage | /admin/redeem-records |
| /deliveries | DeliveriesPage | /admin/deliveries |
## 端 → API 前缀（V2 附录 B）
| 端 | API 前缀 | NestJS Module |
|----|----------|---------------|
| C 端 | /auth, /user, /catalog, /trade, /benefit, /redeem, /stores | iam, catalog, trade, benefit, redeem, store |
| 门店 | /shop/auth, /shop/redeem, /shop/store | iam, redeem, store |
| 合伙人 | /partner/* | iam, store, trade, settlement |
| 总部 | /admin/* | iam, catalog, store, trade, settlement, ops |
## 共享 UI
H5 三端引用 `@dukang/shared-ui`（设计令牌 `tokens.css`）。admin-web 使用 Ant Design 5，不引用 shared-ui。