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

Merge commit 'a0ee3a21cd01229a555384ad5e1f4b3ccdcdd620' into dev_jacy

Browse Source
This commit is contained in:
jacy-dukang
2026-07-01 19:38:05 +08:00
parent 9cbd65f8d7 a0ee3a21cd
commit a1cbfc7241
23 changed files with 1080 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/skills/dukang-coding/SKILL.md
+32 -11
View File
@@ -1,9 +1,10 @@
---
name: dukang-coding
description: >-
Implements Dukang Haoke (杜康好客) features following V2/preV1 coding manuals,
module OWNER boundaries, and shared-types contracts. Use when coding APIs,
pages, Prisma logic, task cards, or fixing bugs in this monorepo.
Implements 杜康好客 features following V2/preV1 coding manuals, module OWNER
boundaries, and shared-types contracts. Use when coding APIs, pages, Prisma logic,
task cards, or fixing bugs — not for PRD/requirements review (use @dukang-project).
disable-model-invocation: true
---
# 杜康好客 · 编码 Skill
@@ -11,8 +12,11 @@ description: >-
## 何时启用
- 实现/修复 `apps/*`、`server/dukang-api`、`packages/*` 功能
- 用户给出任务卡 ID 或 @ 本 skill
- **不要**用于纯文档问答（直接读手册即可）
- 实现任务卡（`M2-BE-TRD-002`、`P1-M2-002` 等）
- 用户给出任务卡 ID、说「开始 coding」或 @dukang-coding
- 修复 V1 范围 Bug
**不用于**：写 PRD、评审需求、纯文档问答 → 用 @dukang-project 或直接读手册
## 会话启动（按序）
@@ -22,10 +26,13 @@ description: >-
4. UI 任务 → `pages/ROUTE_MAP.md` + 对应 `pages/{端}/` 原型
5. 编码前过一遍下方 Checklist
**需求变更** → 只改 V2 手册，编码时不改业务规则。
## 编码前 Checklist
```
- [ ] 任务所属 OWNER 与目标路径已确认
- [ ] 已读手册 PRD 对应 § 与 pages/ 原型
- [ ] API 路径、Guard、表名已从 V2 §六/§五 核对
- [ ] 跨模块需求 → 只 inject 对方 exported Service
- [ ] 新枚举/DTO → packages/shared-types
@@ -48,9 +55,9 @@ Workflow：DTO → Service（本模块表）→ Controller + Guard → 同步 sh
跨模块示例（允许）：
```typescript
// trade.service.ts — OWNER A
// trade.service.ts — jacy-dukang
constructor(
private readonly benefitService: BenefitService, // from BenefitModule
private readonly benefitService: BenefitService,
private readonly catalogService: CatalogService,
) {}
await this.benefitService.grantOnOrderPaid(orderId);
@@ -68,7 +75,14 @@ await this.prisma.order.update({ ... });
1. 路由对照 `pages/ROUTE_MAP.md`
2. `src/lib/api.ts` 统一 fetch + `X-Client-App`
3. 类型从 `@dukang/shared-types` import
4. C 端订单 Tab：`all | pending_pay | pending_ship | pending_receive | completed`
4. preV1 App：`h5-user` / `h5-shop` / `h5-partner` / `admin-web`
5. C 端订单 Tab：`all | pending_pay | pending_ship | pending_receive | completed`
## 数据库变更
1. 改 `server/dukang-api/prisma/schema.prisma` 对齐手册 §五
2. 迁移需 OWNER Review（store/redeem 表 → @刘京尧）
3. 初始化 SQL：`server/dukang-api/prisma/init_v3.sql`
## 核心业务（packages/domain）
@@ -76,6 +90,10 @@ await this.prisma.order.update({ ... });
const benefitAmount = product.benefitAmount ?? product.price;
// 核销：0 < amount ≤ min(balance, 500)
// 同城 min 2 瓶 / 跨城 min 6 瓶
// 支付成功 → log_third_party + user_order.pay_status=PAID
// → user_benefit_coupon + common_event(BENEFIT_LEDGER, GRANT)
// 埋点 → log_user_analytics；业务审计 → common_event
```
## 核销并发（M3+）
@@ -92,10 +110,13 @@ const benefitAmount = product.benefitAmount ?? product.price;
- 任务卡验收项全部满足
- 无跨模块 Prisma 直写
- `pnpm lint` 无新增错误；domain 相关单测通过
- `packages/domain` 相关单测通过
- `pnpm lint` 无新增错误
- 改了 API/表 → 同步手册与 shared-types
## 延伸阅读
- 模块/表/依赖矩阵：[reference-backend.md](reference-backend.md)
- 模块/表/路由：[reference-backend.md](reference-backend.md)
- 页面↔API 速查：[reference-frontend.md](reference-frontend.md)
- preV1 Mock 细节：`dukang-prev1` skill
- preV1 Mock：`dukang-prev1` skill
- 详细清单：根目录 `skills.md`
.cursor/skills/dukang-coding/reference-backend.md
+95 -20
View File
@@ -7,6 +7,7 @@
- Prefix: `/api/v1`
- Response: `{ code: 0, message: 'ok', data }`
- JWT: `actorType` + `actorId` + `clientApp`
- 请求头：`Authorization`、`X-Client-App`
## clientApp → actorType → 表
@@ -15,36 +16,110 @@
| USER_H5 | USER_MINI | USER | user_user |
| SHOP_H5 | SHOP_H5 | STORE | store_account |
| PARTNER_H5 | PARTNER_MINI | PARTNER | partner_account |
| — | HQ_MINI | HQ | hq_account |
| HQ_WEB | HQ_MINI | HQ | hq_account |
## Guard 对照
| Guard | 用途 |
|-------|------|
| JwtAuthGuard | 需登录 |
| PhoneVerifiedGuard | C 端需绑定手机（下单/支付） |
| OptionalJwtAuthGuard | 可选登录（bootstrap） |
Admin 路由在 `modules/ops/` 下，前缀 `/admin/*`。
## Module → API 前缀
| Module | 前缀示例 | OWNER |
|--------|----------|-------|
| iam | `/auth`, `/user` | A |
| catalog | `/catalog`, `/admin/cities`, `/admin/products` | C |
| trade | `/trade`, `/partner/orders`, `/admin/orders` | A |
| benefit | `/benefit` | A |
| store | `/stores`, `/partner/stores`, `/admin/store-audits` | B |
| redeem | `/redeem`, `/shop/redeem` | D |
| settlement | `/settlement`, `/partner/settlement`, `/admin/settlement` | C |
| ops | `/admin/dashboard`, `/admin/reports` | C |
| analytics | `/analytics`, `/promo/touch` | A |
| callbacks | `/callbacks/wechat/pay`, `/callbacks/xfx/delivery` | Lead |
| Module | 前缀示例 | 负责人 |
|--------|----------|--------|
| iam | `/auth`, `/user` | jacy-dukang |
| catalog | `/catalog`, `/admin/cities`, `/admin/products` | jacy-dukang |
| trade | `/trade`, `/partner/orders`, `/admin/orders` | jacy-dukang |
| benefit | `/benefit` | jacy-dukang |
| store | `/stores`, `/partner/stores`, `/admin/store-audits` | 刘京尧 |
| redeem | `/redeem`, `/shop/redeem` | 刘京尧 |
| settlement | `/settlement`, `/partner/settlement`, `/admin/settlement` | jacy-dukang |
| ops | `/admin/dashboard`, `/admin/reports` | jacy-dukang |
| analytics | `/analytics`, `/promo/touch` | jacy-dukang |
| callbacks | `/callbacks/wechat/pay`, `/callbacks/xfx/delivery` | jacy-dukang |
## 表前缀 → Module 写 OWNER
| 前缀 | 示例表 | OWNER Module |
|------|--------|--------------|
| user_ | user_user, user_order, user_benefit_coupon | iam / trade / benefit |
| store_ | store_store, store_account, store_payout | store / iam / settlement |
| partner_ | partner_partner, partner_bill | store(B) / settlement(C) |
| hq_ | hq_account | iam |
| common_ | common_product_item, common_event, common_city | catalog / common |
| 前缀 | 示例表 | 负责人 |
|------|--------|--------|
| user_ | user_user, user_order, user_benefit_coupon | jacy-dukang |
| store_ | store_store, store_account, store_payout | 刘京尧 / jacy-dukang（settlement） |
| partner_ | partner_partner, partner_bill | 刘京尧 / jacy-dukang（settlement） |
| hq_ | hq_account | jacy-dukang |
| common_ | common_product_item, common_event, common_city | jacy-dukang |
| log_ | log_third_party, log_user_analytics | 写入方 Module |
**无以下 V1 表**：payments、user_order_item、redeem_tokens（DB）。
## 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 |
## 关键跨模块调用链
**Mock/真实支付成功**
.cursor/skills/dukang-coding/reference-frontend.md
+93 -31
View File
@@ -2,14 +2,18 @@
> 路由事实源：[`pages/ROUTE_MAP.md`](../../../pages/ROUTE_MAP.md)
## App 配置
## 四 App 概览
| App | Filter | Dev | X-Client-App |
|-----|--------|-----|--------------|
| h5-user | @dukang/h5-user | pnpm dev:user | USER_H5 |
| h5-shop | @dukang/h5-shop | pnpm dev:shop | SHOP_H5 |
| h5-partner | @dukang/h5-partner | pnpm dev:partner | PARTNER_H5 |
| admin-web | @dukang/admin-web | pnpm dev:admin | AdminAuth（内部） |
| App | 目录 | 端口 | 负责人 | X-Client-App | 原型 |
|-----|------|------|--------|--------------|------|
| h5-user | apps/h5-user | 5173 | jacy-dukang | 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 | jacy-dukang | HQ_WEB | pages/hq/ |
> **h5-partner 与 admin-web 端口同为 5175**，勿同时 `dev:partner` + `dev:admin`。
Vite 代理：`/api` → `localhost:3000`。
## 共享包
@@ -18,42 +22,100 @@ import { OrderStatus, ClientApp } from '@dukang/shared-types';
import { PageHeader } from '@dukang/shared-ui';
```
## h5-user 主路由（OWNER A）
H5 三端引用 `@dukang/shared-ui`（`tokens.css`）。admin-web 使用 Ant Design 5，不引用 shared-ui。
| Route | 页面 | 关键 API |
|-------|------|----------|
| `/login` | 登录 | POST /auth/sms/send, /auth/login/sms |
| `/` | 首页 | GET /catalog/products |
| `/product/:id` | 详情 | GET /catalog/products/:id |
| `/order/confirm` | 确认订单 | POST /trade/orders/preview, /trade/orders |
| `/pay` | Mock 支付 | POST /trade/orders/:id/pay |
| `/orders` | 5 Taber | GET /trade/orders?tab= |
| `/benefit` | 权益 | GET /benefit/coupons |
| `/redeem` | 出码 | POST /redeem/token |
| `/stores` | 门店 | GET /stores（仅 OPEN） |
## h5-user 路由（jacy-dukang）
## h5-shop 主路由（OWNER D）
| 路由 | 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 |
| Route | 页面 | 关键 API |
|-------|------|----------|
| `/login` | 登录 | POST /shop/auth/login/sms |
| `/redeem` | 核销确认 | POST /shop/redeem/confirm |
| `/records` | 核销记录 | GET /shop/redeem/records |
### 订单 5 Tab
## h5-partner 主路由（OWNER B）
```
all | pending_pay | pending_ship | pending_receive | completed
```
| Route | 页面 | 关键 API |
|-------|------|----------|
| `/stores/new` | 录店 | POST /partner/stores |
| `/stores` | 门店管理 | GET /partner/stores |
| `/orders` | 辖区订单 | GET /partner/orders |
## 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/* |
| /reshipments | ReshipPage | /partner/after-sales/reshipments |
| /reports/weekly | WeeklyReportPage | /partner/reports/weekly |
| /leaderboard | LeaderboardPage | /partner/dashboard/leaderboard |
| — | Mock 推进配送 | POST /partner/orders/:id/mock-advance-delivery |
## admin-web 路由（jacy-dukang）
| 路由 | 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 前缀
| 端 | 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 硬约束
- C 端订单 **5 Tab**（含 pending_ship）
- 个人中心无会员等级（V1 不做会员体系）
- 清香型 4 SKU 可购；酱香/浓香灰态
- 门店列表仅 `OPEN` 状态
- 原型只读：`pages/{端}/*/code.html`，勿改原型目录
## preV1 与 V2 UI 差异