88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文档为 Claude Code (claude.ai/code) 在本项目中工作时提供指导。
|
||
|
||
## 项目概述
|
||
|
||
这是一个普拉提预约微信小程序项目，后端采用 NestJS 框架。项目使用 pnpm monorepo 结构，包含 3 个包：
|
||
|
||
- **packages/app** - Vue 3 + uni-app（微信小程序前端）
|
||
- **packages/server** - NestJS（后端 API 服务）
|
||
- **packages/shared** - TypeScript 类型定义、枚举、常量（前后端共用）
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 开发
|
||
pnpm dev:server # 启动 NestJS 后端（热重载）
|
||
pnpm dev:app # 构建 uni-app 为微信小程序
|
||
|
||
# 构建
|
||
pnpm build:shared # 编译共享类型
|
||
pnpm build:server # 构建 NestJS 后端
|
||
pnpm build:app # 构建微信小程序
|
||
|
||
# 测试与代码检查
|
||
pnpm test # 运行所有测试（仅 server）
|
||
pnpm lint # 运行 ESLint（仅 server）
|
||
|
||
# 数据库相关（位于 packages/server 目录）
|
||
cd packages/server
|
||
pnpm prisma:generate # 生成 Prisma 客户端
|
||
pnpm prisma:migrate # 执行数据库迁移
|
||
pnpm prisma:seed # 填充测试数据
|
||
pnpm test:watch # 监听模式运行测试
|
||
|
||
# 部署
|
||
pnpm deploy:server # 部署后端到生产环境
|
||
```
|
||
|
||
## 架构说明
|
||
|
||
### 前端 (packages/app)
|
||
- 基于 Vue 3 + uni-app 框架，主攻微信小程序平台
|
||
- 页面目录：`src/pages/`（包含 home、booking、card、profile、admin 等模块）
|
||
- 组件目录：`src/components/`
|
||
- 状态管理：Pinia
|
||
- 样式：SCSS
|
||
|
||
### 后端 (packages/server)
|
||
- 框架：NestJS + Prisma ORM
|
||
- 核心模块：auth（认证）、user（用户）、booking（预约）、membership（会员卡）、payment（支付）、studio（场馆）、time-slot（时段）、scheduler（定时任务）、admin（管理）
|
||
- 认证：JWT + 微信登录
|
||
- 定时任务：@nestjs/schedule
|
||
- 数据库：SQLite（开发）/ MySQL（生产）
|
||
|
||
### 共享包 (packages/shared)
|
||
- TypeScript 接口和类型定义
|
||
- 枚举值定义
|
||
- 前后端共用的 DTO 类型
|
||
|
||
### API 结构
|
||
- 所有接口统一前缀：`/api`
|
||
- RESTful 风格接口
|
||
- 全局拦截器：日志记录、响应包装
|
||
- 全局过滤器：异常处理
|
||
|
||
### 数据库
|
||
- Prisma schema 位于 `packages/server/prisma/schema.prisma`
|
||
- 核心数据模型：User、Studio、TimeSlot、Booking、Membership、CardType、Order
|
||
- 注意：查询会员列表时，booking 统计通过 `groupBy` 批量获取，避免 N+1 查询
|
||
|
||
### 卡类型枚举
|
||
- `CardTypeCategory` (TIMES/DURATION/TRIAL) 定义在 `packages/shared/src/enums.ts`
|
||
- 会员管理筛选使用特殊值 `NONE` 表示无卡/无有效会员（不在枚举中）
|
||
- 前端选项硬编码在 `src/pages/admin/members.vue` 的 `cardTypeOptions`，需与枚举保持同步
|
||
|
||
### 管理后台 API 模式
|
||
- `/admin/members` 支持 `page`, `limit`, `search`, `cardType` 参数
|
||
- `cardType=NONE` → 无有效会员的用户；其他值对应 `CardTypeCategory`
|
||
- 预约统计（total/completed/cancelled）通过 `groupBy` 批量查询
|
||
|
||
### 筛选组件模式
|
||
- picker 筛选使用 300ms debounce 再触发加载，避免频繁请求
|
||
- 列表分页使用 `onReachBottom` + `hasMore` 标志位实现无限滚动
|
||
|
||
### Admin Store (`src/stores/admin.ts`)
|
||
- 聚合所有管理端 API 调用：weekTemplates、cardTypes、studioConfig、members、bookings、orders、stats 等
|
||
- 遵循不可变更新原则：`data` 赋值使用展开运算符 `[...newData]` |