feat: multi-module iteration

2026-08-04 21:38:49 +08:00
parent 9d96c73246
commit 71f508e02b
1366 changed files with 202004 additions and 0 deletions
@@ -0,0 +1,122 @@
+---
+name: dukang-coding
+description: >-
+  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
+
+## 何时启用
+
+- 实现/修复 `apps/*`、`server/dukang-api`、`packages/*` 功能
+- 实现任务卡（`M2-BE-TRD-002`、`P1-M2-002` 等）
+- 用户给出任务卡 ID、说「开始 coding」或 @dukang-coding
+- 修复 V1 范围 Bug
+
+**不用于**：写 PRD、评审需求、纯文档问答 → 用 @dukang-project 或直接读手册
+
+## 会话启动（按序）
+
+1. 确认阶段：**V3.0** → 读 `杜康好客-v3-PRD.md` + `@dukang-v3`；preV1 → preV1 手册；V2 蓝图 → V2 手册
+2. 读 [`AGENTS.md`](../../AGENTS.md) OWNER 表 → **只改本 OWNER 路径**
+3. 有任务卡 ID → 配合 `dukang-task-card` skill 或查 preV1 §9 / V2 §七
+4. UI 任务 → `pages/ROUTE_MAP.md` + 对应 `pages/{端}/` 原型
+5. 编码前过一遍下方 Checklist
+
+**需求变更** → V3.0 只改 `杜康好客-v3-PRD.md`，编码时不改业务规则。
+
+## 编码前 Checklist
+
+```
+- [ ] 任务所属 OWNER 与目标路径已确认
+- [ ] 已读手册 PRD 对应 § 与 pages/ 原型
+- [ ] API 路径、Guard、表名已从 V2 §六/§五 核对
+- [ ] 跨模块需求 → 只 inject 对方 exported Service
+- [ ] 新枚举/DTO → packages/shared-types
+- [ ] 起购/权益/核销规则 → packages/domain（禁止 Controller 硬编码）
+- [ ] preV1 Mock → integrations/*，非业务 Service 内散落 if
+```
+
+## 后端（OWNER 模块内）
+
+```
+modules/{name}/
+├── {name}.module.ts    # exports: [XxxService] 唯一出口
+├── {name}.controller.ts
+├── {name}.service.ts   # 仅写本模块 Prisma 表
+└── dto/
+```
+
+Workflow：DTO → Service（本模块表）→ Controller + Guard → 同步 shared-types。
+
+跨模块示例（允许）：
+
+```typescript
+// trade.service.ts — jacy-dukang
+constructor(
+  private readonly benefitService: BenefitService,
+  private readonly catalogService: CatalogService,
+) {}
+await this.benefitService.grantOnOrderPaid(orderId);
+```
+
+跨模块示例（禁止）：
+
+```typescript
+// redeem.service.ts — ❌ 禁止
+await this.prisma.order.update({ ... });
+```
+
+## 前端（单 App 内）
+
+1. 路由对照 `pages/ROUTE_MAP.md`
+2. `src/lib/api.ts` 统一 fetch + `X-Client-App`
+3. 类型从 `@dukang/shared-types` import
+4. preV1 App：`h5-user` / `h5-shop` / `h5-partner` / `admin-web`
+5. C 端订单 Tab（V3.0）：`待付款 | 已付款 | 已完成`
+
+## 数据库变更
+
+1. 改 `server/dukang-api/prisma/schema.prisma` 对齐手册 §五
+2. 迁移需 OWNER Review（store/redeem 表 → 刘景尧）
+3. 初始化 SQL：`server/dukang-api/prisma/init_v3.sql`
+
+## 核心业务（packages/domain）
+
+```typescript
+const benefitAmount = product.benefitAmount ?? product.price;
+// 核销：直接核销按全部 ACTIVE 权益总余额；带单据核销按该单据可用金额
+// 同城 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+）
+
+- Redis `redeem:token:{token}` EX 300
+- 事务 + `user_benefit_coupon.version` 乐观锁
+- 写 `user_redeem_record` + `store_payout`(PENDING) + `common_event(BENEFIT_LEDGER, REDEEM)`
+
+## 资源上传
+
+`POST /common/resources/upload-token` → OSS 直传 → `POST /common/resources`
+
+## 完成定义
+
+- 任务卡验收项全部满足
+- 无跨模块 Prisma 直写
+- `packages/domain` 相关单测通过
+- `pnpm lint` 无新增错误
+- 改了 API/表 → 同步手册与 shared-types
+
+## 延伸阅读
+
+- 模块/表/路由：[reference-backend.md](reference-backend.md)
+- 页面↔API 速查：[reference-frontend.md](reference-frontend.md)
+- preV1 Mock：`dukang-prev1` skill
+- 详细清单：根目录 `skills.md`
@@ -0,0 +1,160 @@
+# 后端速查（杜康好客 v3.1）
+
+> 完整 DDL/API 以 V2 手册 §五/§六 为准。
+
+## API Base
+
+- Prefix: `/api/v1`
+- Response: `{ code: 0, message: 'ok', data }`
+- JWT: `actorType` + `actorId` + `clientApp`
+- 请求头：`Authorization`、`X-Client-App`
+
+## clientApp → actorType → 表
+
+| preV1 clientApp | V2 clientApp | actorType | 账号表 |
+|-----------------|--------------|-----------|--------|
+| USER_H5 | USER_MINI | USER | user_user |
+| SHOP_H5 | SHOP_H5 | STORE | store_account |
+| PARTNER_H5 | PARTNER_MINI | PARTNER | partner_account |
+| HQ_WEB | HQ_MINI | HQ | hq_account |
+
+## Guard 对照
+
+| Guard | 用途 |
+|-------|------|
+| JwtAuthGuard | 需登录 |
+| PhoneVerifiedGuard | （已废弃强制）C 端手机号改为下单页可选绑定 |
+| OptionalJwtAuthGuard | 可选登录（bootstrap） |
+
+Admin 路由在 `modules/ops/` 下，前缀 `/admin/*`。
+
+## Module → API 前缀
+
+| 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
+
+| 前缀 | 示例表 | 负责人 |
+|------|--------|--------|
+| 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/真实支付成功**
+
+```
+PayProvider → TradeService.handlePaySuccess()
+  → BenefitService.grantOnOrderPaid(orderId)
+  → OrderDelivery 预创建
+  → common_event(ORDER_STATUS)
+```
+
+**核销确认**
+
+```
+RedeemService.confirm()
+  → BenefitService.deduct(couponId)
+  → SettlementService.createStorePayout(redeemRecordId)
+```
+
+## 禁止依赖（PR 拒绝）
+
+| # | 禁止 |
+|---|------|
+| F1 | redeem 直写 order |
+| F2 | store → trade/benefit |
+| F3 | benefit → trade/redeem |
+| F4 | trade → redeem |
+| F5 | benefit → redeem |
+| F6 | catalog → trade/settlement |
+| F9 | apps import server 源码 |
+
+## integrations（preV1）
+
+| Flag | Provider | 行为 |
+|------|----------|------|
+| MOCK_SMS=true | sms.mock | 固定码 123456 |
+| MOCK_PAY=true | pay.mock | 同步 PAID + 发券 |
+| MOCK_DELIVERY_AUTO=true | delivery.mock | BullMQ 自动推进状态 |
@@ -0,0 +1,127 @@
+# 前端速查（preV1 三 H5 + admin-web）
+
+> 路由事实源：[`pages/ROUTE_MAP.md`](../../../pages/ROUTE_MAP.md)
+
+## 四 App 概览
+
+| 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`。
+
+## 共享包
+
+```typescript
+import { OrderStatus, ClientApp } from '@dukang/shared-types';
+import { PageHeader } from '@dukang/shared-ui';
+```
+
+H5 三端引用 `@dukang/shared-ui`（`tokens.css`）。admin-web 使用 Ant Design 5，不引用 shared-ui。
+
+## h5-user 路由（jacy-dukang）
+
+| 路由 | 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
+
+```
+待付款 | 已付款 (`paid`) | 已完成
+```
+
+## 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 端订单 **3 Tab**（`pending_pay` / `paid` / `completed`）
+- 个人中心无会员等级（V1 不做会员体系）
+- 清香型 4 SKU 可购；酱香/浓香灰态
+- 门店列表仅 `OPEN` 状态
+- 原型只读：`pages/{端}/*/code.html`，勿改原型目录
+
+## preV1 与 V2 UI 差异
+
+| 项 | preV1 | V2 |
+|----|-------|-----|
+| C/合伙人载体 | H5 | 微信小程序 |
+| 总部 | admin-web 内部 | mini-hq 小程序 |
+| 支付页 | Mock 同步成功 | 微信 JSAPI |