Python + FastAPI+ uniapp 健身房预约系统

1. 概述健身房预约系统是一个基于现代Web技术栈构建的高效在线预约管理平台旨在解决传统健身房电话/前台预约的痛点。2. 技术架构2.1 整体架构┌─────────────────────────────────────────────────────────────────┐│ 客户端层 │├─────────────────────────────────────────────────────────────────┤│ ┌────────────────┐ ┌────────────────┐ ┌─────────────────┐ ││ │ 管理员Web端 │ │ 会员小程序 │ │ 教练小程序 │ ││ │ (Vue3/Element)│ │ (微信小程序) │ │ (微信小程序) │ ││ └────────────────┘ └────────────────┘ └─────────────────┘ │└─────────────────────────────────────────────────────────────────┘│ HTTPS▼┌─────────────────────────────────────────────────────────────────┐│ API网关层 ││ (Nginx/Traefik) │└─────────────────────────────────────────────────────────────────┘│▼┌─────────────────────────────────────────────────────────────────┐│ 应用服务层 ││ FastAPI - Python ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ 用户服务 │ │ 课程服务 │ │ 预约服务 │ │ 签到服务 │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │└─────────────────────────────────────────────────────────────────┘│┌─────────┴─────────┐▼ ▼┌───────────────────────────┐ ┌───────────────────────┐│ 数据存储层 │ │ 缓存层 (Redis) ││ SQLite/PostgreSQL │ │ 会话管理/限流 │└───────────────────────────┘ └───────────────────────┘2.2 后端技术栈| 组件 | 技术选型 | 版本要求 | 用途 ||-----|---------|---------|-----|| Web框架 | FastAPI | 0.104.0 | 高性能异步Web框架 || ASGI服务器 | Uvicorn | 0.24.0 | 异步服务运行时 || ORM | SQLAlchemy | 2.0.0 | 对象关系映射 || 数据验证 | Pydantic | 2.0.0 | 数据模型验证 || 数据库 | SQLite/PostgreSQL | - | 数据持久化存储 || 缓存 | Redis | 5.0.0 | 缓存和会话管理 || 认证 | JWT (python-jose) | 3.3.0 | Token认证 || 密码加密 | Passlib (bcrypt) | 1.7.4 | 密码安全哈希 || 二维码 | QRCode | 7.4.0 | 签到二维码生成 |2.3 前端技术栈| 组件 | 技术选型 | 版本要求 | 用途 ||-----|---------|---------|-----|| 前端框架 | Vue.js | 3.x | 响应式前端框架 || UI组件库 | Element Plus | 最新 | 企业级UI组件 || 路由管理 | Vue Router | 4.x | 前端路由 || 状态管理 | Pinia | 最新 | 状态管理 || HTTP客户端 | Axios | 最新 | API请求 || 构建工具 | Vite | 最新 | 现代化构建工具 |3. 系统模块架构3.1 核心模块划分3.1.1 用户与认证模块用户与认证模块├── 用户注册/登录│ ├── 手机号密码登录│ ├── JWT Token生成与验证│ └── Token刷新机制├── 用户信息管理│ ├── 用户基本信息│ ├── 用户状态管理│ └── 密码修改└── 权限管理├── 角色权限验证├── 管理员权限├── 教练权限└── 会员权限3.1.2 会员管理模块会员管理模块├── 会员档案│ ├── 会员基本信息│ ├── 会员编号生成│ └── 会籍状态管理├── 会员统计│ ├── 预约次数│ ├── 签到次数│ └── 活动记录└── 会员关系├── 用户-会员一对一关联└── 黑名单管理3.1.3 教练管理模块教练管理模块├── 教练档案│ ├── 教练基本信息│ ├── 教练编号生成│ ├── 擅长领域│ └── 个人简介├── 课程管理│ └── 教练课程关联└── 签到权限└── 课程签到授权3.1.4 课程管理模块课程管理模块├── 课程类型│ ├── 课程类型定义│ └── 课程类型状态├── 教室管理│ ├── 教室信息│ ├── 教室容量│ └── 教室位置└── 课程管理├── 课程创建与编辑├── 课程状态管理├── 周期性课程├── 预约配置└── 容量管理3.1.5 预约管理模块预约管理模块├── 预约创建│ ├── 可用性检查│ ├── 会员资格验证│ ├── 容量检查│ └── 预约记录├── 预约取消│ ├── 取消时间限制│ ├── 取消原因记录│ └── 容量回滚├── 签到管理│ ├── 签到二维码生成│ ├── 二维码验证│ ├── 签到记录│ └── 签到统计└── 预约查询├── 会员预约列表├── 课程预约列表└── 历史预约记录3.1.6 会籍管理模块会籍管理模块├── 会籍类型│ ├── 无限期会籍│ ├── 有限期会籍│ └── 次卡会籍├── 会籍管理│ ├── 会籍创建│ ├── 会籍激活│ └── 会籍更新└── 次卡扣减└── 使用记录3.2 API架构3.2.1 API路径结构/api├── /auth # 认证模块│ ├── /register # 用户注册│ ├── /login # 用户登录│ └── /me # 获取当前用户├── /users # 用户管理│ ├── /list # 用户列表│ ├── /{id} # 用户详情│ └── /{id}/status # 用户状态├── /courses # 课程与预约│ ├── / # 课程列表│ ├── /{id} # 课程详情│ ├── /book # 创建预约│ ├── /coach/my # 教练课程│ ├── /bookings/my # 我的预约│ ├── /bookings/{id}/cancel # 取消预约│ ├── /bookings/{id}/qr # 获取签到二维码│ ├── /bookings/{id}/checkin # 学员签到│ └── /memberships # 会籍管理├── /admins # 管理员功能│ └── ...├── /members # 会员管理└── /coaches # 教练管理4. 数据架构4.1 ER图┌──────────────┐ ┌──────────────┐ ┌──────────────┐│ Users │ │ Members │ │ Coaches │├──────────────┤ ├──────────────┤ ├──────────────┤│ id (PK) │◄────►│ id (PK) │ │ id (PK) ││ phone │ │ user_id (FK) │◄────►│ user_id (FK) ││ password │ │ member_code │ │ coach_code ││ nickname │ │ ... │ │ ... ││ role │ └──────────────┘ └──────────────┘│ is_active │└──────────────┘││▼┌──────────────────────────────┐│ Bookings │├──────────────────────────────┤│ id (PK) ││ booking_code ││ user_id (FK)──────────────────┐│ member_id (FK) ││ course_id (FK)──────────────┐││ status │││ checkin_time │││ ... ││└──────────────────────────────┘││┌──────────────────────────────┐││ Courses ││├──────────────────────────────┤││ id (PK) │││ course_code │││ name │││ course_type_id (FK)─────────┐│││ coach_id (FK)───────────────┼┼┘│ classroom_id (FK)──────────┐│││ start_time ││││ end_time ││││ capacity ││││ booked_count ││││ ... │││└────────────────────────────┘││││││┌─────────────────────┘││▼ ││┌──────────────┐ ┌────────┴┐ ┌──────────────┐│ CourseTypes │ │Classrooms│ │ Memberships │├──────────────┤ ├─────────┤ ├──────────────┤│ id (PK) │ │ id (PK) │ │ id (PK) ││ name │ │ name │ │ member_id(FK)││ is_active │ │ capacity│ │ type │└──────────────┘ └─────────┘ └──────────────┘4.2 数据表说明4.2.1 用户表 (users)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 用户ID || phone | String(20) | Unique, Not Null | 手机号 || password_hash | String(255) | Not Null | 密码哈希 || nickname | String(50) | Not Null | 昵称 || gender | String(10) | Nullable | 性别 || avatar | String(255) | Nullable | 头像URL || role | String(20) | Not Null | 用户角色 || is_active | Boolean | Default True | 是否激活 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |4.2.2 会员表 (members)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 会员ID || user_id | Integer | FK to users | 用户ID || member_code | String(20) | Unique | 会员编号 || real_name | String(50) | Nullable | 真实姓名 || phone | String(20) | - | 手机号 || birthday | Date | Nullable | 生日 || join_date | Date | - | 入会日期 || total_bookings | Integer | Default 0 | 总预约次数 || total_attended | Integer | Default 0 | 总签到次数 || is_blacklist | Boolean | Default False | 是否黑名单 || is_active | Boolean | Default True | 是否激活 || notes | Text | Nullable | 备注 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |4.2.3 教练表 (coaches)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 教练ID || user_id | Integer | FK to users | 用户ID || coach_code | String(20) | Unique | 教练编号 || real_name | String(50) | Not Null | 真实姓名 || phone | String(20) | - | 手机号 || avatar | String(255) | Nullable | 头像 || specialty | String(200) | Nullable | 擅长领域 || bio | Text | Nullable | 个人简介 || is_active | Boolean | Default True | 是否激活 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |4.2.4 课程类型表 (course_types)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 课程类型ID || name | String(100) | Not Null | 课程类型名称 || description | Text | Nullable | 描述 || icon | String(255) | Nullable | 图标 || is_active | Boolean | Default True | 是否激活 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |4.2.5 教室表 (classrooms)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 教室ID || name | String(100) | Not Null | 教室名称 || capacity | Integer | Default 20 | 容量 || location | String(200) | Nullable | 位置 || equipment | Text | Nullable | 设备描述 || is_active | Boolean | Default True | 是否激活 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |4.2.6 课程表 (courses)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 课程ID || course_code | String(50) | Unique | 课程编号 || name | String(200) | Not Null | 课程名称 || description | Text | Nullable | 课程描述 || course_type_id | Integer | FK | 课程类型ID || coach_id | Integer | FK | 教练ID || classroom_id | Integer | FK | 教室ID || start_time | DateTime | Not Null | 开始时间 || end_time | DateTime | Not Null | 结束时间 || capacity | Integer | Default 20 | 课程容量 || booked_count | Integer | Default 0 | 已预约人数 || booking_start_time | DateTime | Nullable | 预约开始时间 || booking_end_time | DateTime | Nullable | 预约结束时间 || cancel_deadline_minutes | Integer | Default 120 | 取消截止时间分钟 || status | String(20) | Default available | 课程状态 || is_recurring | Boolean | Default False | 是否周期性课程 || recurring_rule | String(200) | Nullable | 周期规则 || notes | Text | Nullable | 备注 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |4.2.7 预约表 (bookings)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 预约ID || booking_code | String(50) | Unique | 预约编号 || user_id | Integer | FK | 用户ID || member_id | Integer | FK | 会员ID || course_id | Integer | FK | 课程ID || status | String(20) | Default booked | 预约状态 || checkin_time | DateTime | Nullable | 签到时间 || canceled_by | String(20) | Nullable | 取消者 || canceled_at | DateTime | Nullable | 取消时间 || canceled_reason | Text | Nullable | 取消原因 || notes | Text | Nullable | 备注 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |4.2.8 会籍表 (memberships)| 字段 | 类型 | 约束 | 说明 ||-----|------|------|-----|| id | Integer | PK | 会籍ID || member_id | Integer | FK | 会员ID || type | String(20) | Default unlimited | 会籍类型 || start_date | Date | Nullable | 开始日期 || end_date | Date | Nullable | 结束日期 || total_count | Integer | Default 0 | 总次数 || used_count | Integer | Default 0 | 已用次数 || is_active | Boolean | Default True | 是否激活 || notes | Text | Nullable | 备注 || created_at | DateTime | - | 创建时间 || updated_at | DateTime | - | 更新时间 |5. 安全架构5.1 认证机制- **JWT (JSON Web Token)** - 无状态认证- 算法HS256- 过期时间默认 1440分钟 (24小时)- 可配置过期时间5.2 权限控制权限矩阵┌─────────────┬──────────┬──────────┬──────────┐│ 功能 │ 管理员 │ 教练 │ 会员 │├─────────────┼──────────┼──────────┼──────────┤│ 用户管理 │ ✅ │ ❌ │ ❌ ││ 会员管理 │ ✅ │ ❌ │ ❌ ││ 教练管理 │ ✅ │ ❌ │ ❌ ││ 课程管理 │ ✅ │ ❌ │ ❌ ││ 查看课程 │ ✅ │ ✅ │ ✅ ││ 创建预约 │ ✅ │ ❌ │ ✅ ││ 查看自己预约│ ✅ │ ❌ │ ✅ ││ 取消预约 │ ✅ │ ❌ │ ✅ ││ 查看课程预约│ ✅ │ ✅ │ ❌ ││ 学员签到 │ ✅ │ ✅ │ ❌ ││ 教室管理 │ ✅ │ ❌ │ ❌ ││ 课程类型 │ ✅ │ ❌ │ ❌ ││ 数据统计 │ ✅ │ ❌ │ ❌ │└─────────────┴──────────┴──────────┴──────────┘5.3 数据安全5.3.1 密码安全- 使用 bcrypt 哈希算法- 哈希成本因子可配置- 密码在传输过程中使用 HTTPS 加密5.3.2 输入验证- Pydantic 模型验证所有输入数据- 防止 SQL 注入使用参数化查询- XSS防护前端对用户输入进行转义5.3.3 签到二维码安全- 二维码包含课程ID、会员ID和时间戳- 二维码具有时效性仅限课程前后30分钟内有效- 动态生成防止复用5.4 并发安全- 数据库事务保证数据一致性- 乐观锁机制防止超售- 预约操作原子化处理6. 部署架构6.1 单机部署架构┌──────────────────────────────────────────────────┐│ 应用服务器 ││ ┌───────────────────────────────────────────┐ ││ │ Docker容器 │ ││ │ ┌──────────┐ ┌───────────────────┐ │ ││ │ │ Nginx │◄──►│ FastAPI App │ │ ││ │ │ (反向代理)│ │ (8002端口) │ │ ││ │ └──────────┘ └───────────────────┘ │ ││ │ │ │ ││ │ ▼ │ ││ │ ┌───────────────────┐ │ ││ │ │ SQLite/PG │ │ ││ │ └───────────────────┘ │ ││ └───────────────────────────────────────────┘ │└──────────────────────────────────────────────────┘6.2 生产环境推荐架构┌───────────────┐│ CDN/负载均衡 │└───────┬───────┘│┌────▼────┐│ Nginx │└────┬────┘│┌────┴────┐│ 应用集群 │ (多个FastAPI实例)└────┬────┘│┌────▼────┐│ Redis │└────┬────┘│┌────▼────┐│ PostgreSQL│└─────────┘7. 性能指标| 指标 | 要求值 | 说明 ||-----|--------|-----|| 系统可用性 | ≥99.9% | 系统在线时间百分比 || API响应时间 | 200ms | 普通API响应时间 || 预约操作响应时间 | 1000ms | 预约/取消操作时间 || 课表加载时间 | 2000ms | 未来7天课表加载 || 并发用户支持 | ≥500 | 同时在线用户数 || 数据库查询优化 | 使用索引 | 关键查询优化 |8. 系统扩展8.1 功能扩展方向1. **会员小程序** - 完整的微信小程序版本2. **教练小程序** - 教练专用小程序3. **数据分析** - 更丰富的数据分析与报表4. **消息推送** - 课程提醒、预约确认等通知5. **支付集成** - 会员卡购买、次卡购买6. **评价系统** - 课程评价与教练评价7. **视频课程** - 线上课程功能8. **多门店支持** - 连锁健身房门店管理8.2 技术扩展方向1. **微服务架构** - 拆分服务模块2. **消息队列** - 异步处理3. **搜索引擎** - Elasticsearch 全文搜索4. **CDN** - 静态资源加速5. **日志系统** - ELK 日志收集6. **监控系统** - Prometheus Grafana7. **CI/CD** - 自动化部署流程9. 总结本系统采用现代化的技术架构具备以下特点- ✅ 高可用性 - 异步架构高性能- ✅ 高安全性 - JWT认证、权限控制、数据加密- ✅ 易扩展性 - 模块化设计易于功能扩展- ✅ 易部署 - Docker容器化支持多种部署方式- ✅ 易维护 - 代码结构清晰文档完善