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,42 @@
+---
+description: NestJS 模块依赖与 Prisma 写权限 — 后端 OWNER 边界
+globs: server/dukang-api/src/**/*.ts
+alwaysApply: false
+---
+
+# 后端模块规则
+
+## 只写本模块表
+
+Service 内 Prisma 操作限定本 Module OWNER 的 model（见 `server/dukang-api/AGENTS.md`）。
+
+## 禁止依赖（示例）
+
+```typescript
+// ❌ redeem.service.ts
+await this.prisma.order.update(...)
+
+// ✅ redeem.service.ts
+await this.benefitService.deduct(dto)
+await this.settlementService.createStorePayout(recordId)
+```
+
+```typescript
+// ❌ benefit.module.ts imports TradeModule
+// ❌ store.service.ts imports TradeService
+```
+
+## 模块结构
+
+- `exports: [XxxService]` — 唯一对外能力
+- 禁止 export Repository / 裸 Prisma 访问
+- Controller 不可被其他 Module import
+
+## 回调与任务
+
+- 微信/配送回调 **仅** `callbacks/` 入口
+- BullMQ 消费者在 `jobs/`，调用 OWNER Service
+
+## 响应格式
+
+`{ code: 0, message: 'ok', data }` + 对应 Guard（User/Store/Partner/HQ）
@@ -0,0 +1,51 @@
+---
+description: 杜康好客 NestJS 后端编码规范
+globs: server/**/*.ts
+alwaysApply: false
+---
+
+# 后端规范
+
+## 模块目录
+
+```
+server/dukang-api/src/
+├── modules/{iam,trade,benefit,catalog,store,redeem,settlement,ops,analytics,health}/
+├── common/{guards,decorators,interceptors,filters,prisma,redis}/
+├── integrations/{pay,sms,delivery}/
+└── jobs/
+```
+
+## 新接口流程
+
+1. 在 **OWNER 模块** 建 `dto/`、`*.service.ts`、`*.controller.ts`
+2. Service 只写本模块 Prisma 表
+3. 跨域 inject 其他 Module 的 exported Service
+4. Controller 加对应 Guard（`JwtAuthGuard`、`PhoneVerifiedGuard` 等）
+5. 响应 `{ code: 0, message: 'ok', data }`
+6. 同步 `packages/shared-types`
+
+## Controller 示例
+
+```typescript
+@Controller('trade/orders')
+@UseGuards(JwtAuthGuard)
+export class TradeController {
+  constructor(private readonly tradeService: TradeService) {}
+}
+```
+
+## 鉴权路由前缀
+
+| 端 | 前缀 |
+|----|------|
+| C 端 | `/auth`, `/user`, `/catalog`, `/trade`, `/benefit`, `/redeem`, `/stores` |
+| 门店 | `/shop/auth`, `/shop/redeem`, `/shop/store` |
+| 合伙人 | `/partner/*` |
+| 总部 | `/admin/*` |
+
+## 数据约定
+
+- 埋点 → `log_user_analytics`；业务审计 → `common_event`
+- 支付 → `log_third_party` + `user_order.pay_*`（无 payments 表）
+- 核销码 → Redis 3min（`REDEEM_TOKEN_TTL_SECONDS`）
@@ -0,0 +1,55 @@
+---
+description: 杜康好客全局约束 — Monorepo 布局、文档优先级、2 人 OWNER 边界
+alwaysApply: true
+---
+
+# 杜康好客 · 核心规则
+
+## Monorepo 布局
+
+- `apps/` — preV1：`h5-user`、`h5-shop`、`h5-partner`、`admin-web`
+- `packages/` — `shared-types`、`domain`、`shared-ui`
+- `server/dukang-api/` — NestJS 单体 API
+- `pages/` — UI 原型（**只读参照**）
+
+> V2 目标为 Taro 四端（`mini-user` 等），编码以 **当前实际目录** 为准。
+
+## 文档
+
+- **V3.0 业务事实源**：`杜康好客-v3-PRD.md`
+- V3 实现验收：`杜康好客-v3编码手册.md`
+- V2 蓝图：`杜康好客-V2编码手册.md`（与 V3 冲突时 V3 PRD 优先）
+- preV1 裁剪：`杜康好客-preV1编码手册.md`
+- 协作：`conventions.md` · AI 入口：`AGENTS.md`
+
+**禁止**：编码时修改业务规则；需求变更只改 `杜康好客-v3-PRD.md`。
+
+## 边界（2 人团队）
+
+> **临时（2026-07）**：刘京尧任务由 `jacy-dukang` 代管，B+D 路径可改。
+
+| 负责人 | 路径 |
+|--------|------|
+| jacy-dukang | `apps/*`, `packages/`, `callbacks/`, `jobs/`, `common/`, `integrations/`, 全部 `modules/*` |
+| ~~刘京尧~~ | ~~`apps/h5-partner/`, `apps/h5-shop/`, `modules/{store,redeem}/`~~（暂代管） |
+
+- 跨模块只 inject **exported Service**，禁止 `prisma` 写他人表
+- `apps/*` 禁止 import `server/*` 或其他 app
+- Mock 只在 `integrations/*`，不在业务 Service 散落
+
+## 共享契约
+
+- 枚举/DTO → `packages/shared-types`
+- 纯规则 → `packages/domain`（无 IO）
+
+## 核心业务常量
+
+- 权益额 = `benefit_amount ?? price`
+- 核销：直接核销 `0 < amount ≤ 全部 ACTIVE 权益总余额`；带单据核销 `0 < amount ≤ 该单据可用金额`；Redis 码 3 分钟
+- 订单 Tab（V3.0）：`待付款 | 已付款 | 已完成`
+- API：`/api/v1`，响应 `{ code, message, data }`
+
+## 提交
+
+- Conventional Commits：`feat(trade):` 等
+- 不提交 `.env`
@@ -0,0 +1,53 @@
+---
+description: 杜康好客前端 H5 / Admin 编码规范与 OWNER 边界
+globs: apps/**/*.{tsx,ts}
+alwaysApply: false
+---
+
+# 前端规范
+
+## 目录约定
+
+```
+src/
+├── components/   # PascalCase（AppToast.tsx）
+├── pages/        # *Page.tsx
+├── layouts/      # *Layout.tsx
+├── contexts/     # *Context.tsx
+├── lib/          # kebab-case（api.ts, client-location.ts）
+├── App.tsx
+└── main.tsx
+```
+
+## 四 App
+
+| App | 端口 | 负责人 | 样式 | X-Client-App |
+|-----|------|--------|------|--------------|
+| h5-user | 5173 | jacy-dukang | shared-ui tokens | USER_H5 |
+| h5-shop | 5174 | jacy-dukang | shared-ui tokens | SHOP_H5 |
+| h5-partner | 5175 | 刘京尧 | shared-ui tokens | PARTNER_H5 |
+| admin-web | 5175 | jacy-dukang | Ant Design 5 | HQ_WEB |
+
+> h5-partner 与 admin-web 勿同时 dev。H5 三端用 `@dukang/shared-ui`；admin-web 独立 Ant Design。
+
+## 隔离与请求
+
+- 禁止 import 其他 `apps/*` 或 `server/*`
+- 类型从 `@dukang/shared-types` import
+- Base: `/api/v1`；Headers: `Authorization` + `X-Client-App`
+- Vite dev 代理 `/api` → `localhost:3000`
+
+## UI 约束
+
+- C 端订单 **5 Tab**（含 pending_ship）
+- 门店列表仅 `OPEN` 状态
+- 原型 `pages/` 只读；路由对照 `pages/ROUTE_MAP.md`
+
+## App 归属（勿改他端）
+
+| App | 勿改 |
+|-----|------|
+| h5-user | shop 核销、partner 录店 |
+| h5-shop | user 出码、admin 报表 |
+| h5-partner | user 下单、admin 开城 |
+| admin-web | 非 V2 小程序规格 |
@@ -0,0 +1,33 @@
+---
+description: Git 提交与 PR 协作规范
+alwaysApply: true
+---
+
+# Git 规范
+
+## 提交格式
+
+Conventional Commits，scope = 端或模块名：
+
+```
+feat(trade): add order preview API
+fix(redeem): validate redeem amount against balance
+chore(shared-types): add OrderStatus enum
+```
+
+## 禁止提交
+
+- `.env`、`.env.local` 等敏感配置
+- `node_modules/`、`dist/`（已在 .gitignore）
+
+## PR 与 Review
+
+- feature 分支 + 小步 PR
+- 跨模块改动需相关双 Owner Review
+- Prisma 迁移必须多 Owner Review
+
+## Agent 行为
+
+- **仅用户明确要求时** 才执行 git commit / push
+- 不 amend 已推送的 commit，不 force push main/master/dev
+- 发版：`dev`→测试(staging)，`main`→生产；用户只说「发布/发版」默认发**生产**（见 dukang-release skill）；明确说「发测试」才发 staging
@@ -0,0 +1,43 @@
+---
+description: 杜康好客共享包（shared-types / domain / shared-ui）规范
+globs: packages/**/*.{ts,tsx}
+alwaysApply: false
+---
+
+# 共享包规范
+
+## 包职责
+
+| 包 | 用途 | 约束 |
+|----|------|------|
+| `@dukang/shared-types` | DTO、枚举、错误码、JWT Payload | 前后端唯一契约 |
+| `@dukang/domain` | 纯函数业务规则 | **禁止 IO**，含 Vitest 单测 |
+| `@dukang/shared-ui` | H5 共享组件 + `tokens.css` | 仅 H5 三端使用 |
+
+## shared-types
+
+- 枚举用 `SCREAMING_SNAKE_CASE`（如 `OrderStatus.PENDING_PAY`）
+- API Tab 查询用 snake_case（`pending_pay`）
+- **加法优先**：新字段 optional；删除/改名先 deprecated
+- 改 API 必须同步 V2 手册 §六 与 shared-types
+
+## domain
+
+- 纯函数，无 IO（无 Prisma/Redis/HTTP）
+- 起购 2/6 瓶、权益 `benefitAmount ?? price`、V3 两路径核销规则在此实现
+- 变更必须有单元测试
+
+```typescript
+const benefitAmount = product.benefitAmount ?? product.price;
+// 同城起购 2 瓶 / 跨城 6 瓶
+// 直接核销按全部 ACTIVE 权益总余额；带单据核销按该单据可用金额
+```
+
+## shared-ui
+
+- 跨 App 组件；禁止 import 特定 App 代码
+- admin-web 使用 Ant Design，不引用 shared-ui
+
+## 破坏性改动
+
+需通知 **jacy-dukang** 与 **刘京尧**（若影响 partner/shop API）并在 PR 说明影响面。Prisma 迁移需双方 Review（涉及 store/redeem 表时）。
@@ -0,0 +1,29 @@
+---
+description: Prisma schema 变更需对齐 V2 手册 §五 并经表 OWNER Review
+globs: server/dukang-api/prisma/**
+alwaysApply: false
+---
+
+# Prisma / 数据库规则
+
+## 事实源
+
+V2 手册 §五（v3.1，28 表）。schema 与手册保持一致。
+
+## 变更流程
+
+1. 确认受影响 Module OWNER（见 `server/dukang-api/AGENTS.md` 表映射）
+2. 修改 `schema.prisma`
+3. `pnpm db:validate`
+4. PR 需对应 OWNER + Lead Review
+
+## 关键约定
+
+- 无 `payments` / `user_order_item` / `redeem_tokens` 表
+- 核销码仅 Redis **3 分钟**（`REDEEM_TOKEN_TTL_SECONDS=180`）
+- 支付流水 → `log_third_party` + `user_order.pay_*`
+- 业务事件 → `common_event`；埋点 → `log_user_analytics`
+
+## preV1
+
+不删表、不改 V2 字段语义。Seed：`prisma/seed-v31.ts`