mp-pilates/CLAUDE.md

CLAUDE.md

本文档为 Claude Code (claude.ai/code) 在本项目中工作时提供指导。

项目概述

这是一个普拉提预约微信小程序项目，后端采用 NestJS 框架。项目使用 pnpm monorepo 结构，包含 3 个包：

• packages/app - Vue 3 + uni-app（微信小程序前端）
• packages/server - NestJS（后端 API 服务）
• packages/shared - TypeScript 类型定义、枚举、常量（前后端共用）

常用命令

# 开发
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]