docs: 添加预约模块和签到模块详细设计文档及API接口文档
- 添加预约模块详细设计文档（LLD-预约模块详细设计.md） - 添加签到模块详细设计文档（LLD-签到模块详细设计.md） - 添加API接口文档（API接口文档.md） 文档包含： - 模块概述与边界定义 - 数据模型设计（含SQL建表语句） - 领域模型设计 - 业务流程设计 - 接口设计 - 核心代码设计 - 高并发处理方案 - 缓存设计 - 定时任务设计 - 异常处理 - 附录（枚举定义、错误码）~
This commit is contained in:
张翔
@@ -0,0 +1,925 @@
|
||||
# 健身房管理系统概要设计文档（HLD）
|
||||
|
||||
> 文档编号: GYM-HLD-001
|
||||
> 版本: v1.0
|
||||
> 日期: 2026-02-28
|
||||
> 作者: 张翔
|
||||
> 状态: 初稿
|
||||
|
||||
---
|
||||
|
||||
## 文档修订历史
|
||||
|
||||
| 版本 | 日期 | 作者 | 修订内容 |
|
||||
| ---- | ---------- | ---- | -------- |
|
||||
| v1.0 | 2026-02-28 | 张翔 | 初稿 |
|
||||
|
||||
---
|
||||
|
||||
## 一、引言
|
||||
|
||||
### 1.1 编写目的
|
||||
|
||||
本文档为健身房管理系统的概要设计文档（High-Level Design），旨在：
|
||||
|
||||
1. 从总体上描述系统的技术架构、模块划分、接口设计
|
||||
2. 为详细设计提供指导和约束
|
||||
3. 作为开发人员、测试人员、运维人员的技术参考
|
||||
|
||||
### 1.2 项目背景
|
||||
|
||||
健身房管理系统是一款面向综合型健身俱乐部、精品工作室、连锁品牌的全场景管理平台，核心解决：
|
||||
|
||||
- 会员端：一站式查看个人所有信息，便捷预约签到
|
||||
- 管理后台：全维度数据整理与分析，支撑运营决策
|
||||
- 多业态支持：灵活适配不同规模和类型的健身场所
|
||||
|
||||
### 1.3 术语定义
|
||||
|
||||
| 术语 | 定义 |
|
||||
| ----------------------------- | ------------------------------------------------ |
|
||||
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
|
||||
| 门店(Store) | 租户下的具体经营场所 |
|
||||
| 会员(Member) | 在门店注册的用户 |
|
||||
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
|
||||
| 可预约资源(Bookable Resource) | 团课、私教、场地、线上课程等可被预约的对象 |
|
||||
| 时段(Slot) | 资源的可预约时间窗口 |
|
||||
|
||||
### 1.4 参考文档
|
||||
|
||||
- 《健身房管理系统产品设计文档》 GYM-PRD-001
|
||||
- Spring Boot 3 官方文档
|
||||
- R2DBC 规范文档
|
||||
- PostgreSQL 官方文档
|
||||
|
||||
---
|
||||
|
||||
## 二、系统概述
|
||||
|
||||
### 2.1 系统目标
|
||||
|
||||
| 目标 | 描述 | 度量标准 |
|
||||
| ------ | -------------------------- | ---------------- |
|
||||
| 高可用 | 系统稳定运行，故障快速恢复 | SLA ≥ 99.9% |
|
||||
| 高并发 | 支撑热门课程抢课场景 | QPS ≥ 1000 |
|
||||
| 可扩展 | 支持功能模块渐进式扩展 | 模块化设计 |
|
||||
| 易维护 | 代码规范，文档完善 | 代码覆盖率 ≥ 80% |
|
||||
|
||||
### 2.2 用户角色
|
||||
|
||||
| 角色 | 描述 | 主要功能 |
|
||||
| ---------- | -------------- | ---------------------------- |
|
||||
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息 |
|
||||
| 教练 | 健身房教练 | 排课、私教预约确认、学员签到 |
|
||||
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
|
||||
| 店长 | 门店管理者 | 单店全功能管理、数据查看 |
|
||||
| 运营管理员 | 平台运营人员 | 营销活动配置、数据分析 |
|
||||
| 财务专员 | 财务人员 | 账单管理、财务报表 |
|
||||
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
|
||||
|
||||
### 2.3 业务范围
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 业务范围 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 会员管理 │ │ 预约管理 │ │ 签到管理 │ │
|
||||
│ │ 会员注册 │ │ 团课预约 │ │ 扫码签到 │ │
|
||||
│ │ 会员卡管理 │ │ 私教预约 │ │ 刷脸签到 │ │
|
||||
│ │ 权益管理 │ │ 场地预约 │ │ NFC签到 │ │
|
||||
│ │ 等级管理 │ │ 线上课程 │ │ 教练代签 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 课程管理 │ │ 教练管理 │ │ 财务管理 │ │
|
||||
│ │ 课程类型 │ │ 教练信息 │ │ 营收统计 │ │
|
||||
│ │ 课程排期 │ │ 排班管理 │ │ 账单管理 │ │
|
||||
│ │ 场地管理 │ │ 课时统计 │ │ 退款管理 │ │
|
||||
│ │ 价格配置 │ │ 评价管理 │ │ 对账管理 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ 计划中心 │ │ 数据分析 │ │ 系统管理 │ │
|
||||
│ │ 训练计划 │ │ 会员分析 │ │ 租户管理 │ │
|
||||
│ │ 课程排期 │ │ 课程分析 │ │ 门店管理 │ │
|
||||
│ │ 会员目标 │ │ 财务分析 │ │ 权限管理 │ │
|
||||
│ │ 教练排班 │ │ 运营分析 │ │ 系统配置 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、系统架构设计
|
||||
|
||||
### 3.1 总体架构
|
||||
|
||||
采用分层架构 + 微服务思想的模块化设计：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 客户端层 │
|
||||
├──────────────────┬──────────────────┬──────────────────┬───────────────┤
|
||||
│ 会员小程序 │ 教练端App │ 管理后台PC │ 硬件设备 │
|
||||
│ (uniapp+Vue3) │ (uniapp+Vue3) │ (Vue3+Vite) │ (人脸/NFC) │
|
||||
└────────┬─────────┴────────┬─────────┴────────┬─────────┴───────┬───────┘
|
||||
│ │ │ │
|
||||
└──────────────────┴────────┬─────────┴─────────────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ API Gateway │
|
||||
│ (统一网关) │
|
||||
│ - 路由转发 │
|
||||
│ - 认证鉴权 │
|
||||
│ - 限流熔断 │
|
||||
│ - 日志追踪 │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌───────────────────────────┼───────────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ 会员服务 │ │ 预约服务 │ │ 数据服务 │
|
||||
│ Member Service │ │ Booking Service │ │ Data Service │
|
||||
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
|
||||
│ - 会员管理 │ │ - 课程管理 │ │ - 数据统计 │
|
||||
│ - 会员卡管理 │ │ - 预约管理 │ │ - 报表生成 │
|
||||
│ - 权益管理 │ │ - 签到管理 │ │ - 数据导出 │
|
||||
│ - 等级管理 │ │ - 库存管理 │ │ - 数据分析 │
|
||||
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
|
||||
│ │ │
|
||||
└──────────────────────────┼──────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────┼───────────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ 公共服务层 │ │ 基础设施层 │ │ 外部服务 │
|
||||
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
|
||||
│ - 认证服务 │ │ - PostgreSQL │ │ - 微信开放平台 │
|
||||
│ - 消息服务 │ │ - R2DBC │ │ - 短信服务 │
|
||||
│ - 文件服务 │ │ - Caffeine │ │ - 支付服务 │
|
||||
│ - 缓存服务 │ │ - Redis(可选) │ │ - OSS存储 │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### 3.2 技术架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 技术架构分层 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 表现层 (Presentation) │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
|
||||
│ │ │ 会员端 uniapp │ │ 教练端 uniapp │ │ 管理后台 Vue3 │ │ │
|
||||
│ │ │ - Vue3 + TS │ │ - Vue3 + TS │ │ - Vue3 + TS │ │ │
|
||||
│ │ │ - Pinia │ │ - Pinia │ │ - Pinia │ │ │
|
||||
│ │ │ - uni-ui │ │ - uni-ui │ │ - Element Plus│ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 网关层 (Gateway) │ │
|
||||
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Spring Cloud Gateway │ │ │
|
||||
│ │ │ - 路由转发 - 认证鉴权 - 限流熔断 - 日志追踪 - 灰度发布 │ │ │
|
||||
│ │ └─────────────────────────────────────────────────────────────┘ │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 业务层 (Business) │ │
|
||||
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ Spring Boot 3 + WebFlux + JDK 21 │ │ │
|
||||
│ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │
|
||||
│ │ │ │ Controller│ │ Service │ │ Repository│ │ Model │ │ │ │
|
||||
│ │ │ │ (API) │ │ (业务逻辑) │ │ (数据访问) │ │ (领域模型) │ │ │ │
|
||||
│ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │
|
||||
│ │ └─────────────────────────────────────────────────────────────┘ │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 数据层 (Data) │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
|
||||
│ │ │ PostgreSQL │ │ Caffeine │ │ Redis(可选) │ │ │
|
||||
│ │ │ - R2DBC │ │ - 本地缓存 │ │ - 分布式缓存 │ │ │
|
||||
│ │ │ - Flyway │ │ - 热点数据 │ │ - 分布式锁 │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
|
||||
│ └───────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.3 部署架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 部署架构 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────┐ │
|
||||
│ │ 负载均衡器 │ │
|
||||
│ │ (Nginx/ALB) │ │
|
||||
│ └────────┬────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────┼───────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
||||
│ │ API Gateway │ │ API Gateway │ │ API Gateway │ │
|
||||
│ │ (实例1) │ │ (实例2) │ │ (实例N) │ │
|
||||
│ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └───────────────────┼───────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────────┼──────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
||||
│ │ Application │ │ Application │ │ Application │ │
|
||||
│ │ Server (Pod1) │ │ Server (Pod2) │ │ Server (PodN) │ │
|
||||
│ └───────┬────────┘ └───────┬────────┘ └
|
||||
```
|
||||
───────┬────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └───────────────────┼───────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────────┼───────────────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ PostgreSQL │ │ Redis │ │ OSS │ │
|
||||
│ │ (主从复制) │ │ (哨兵模式) │ │ (对象存储) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、模块设计
|
||||
|
||||
### 4.1 模块划分
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 模块划分 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ gym-manage-server (父工程) │
|
||||
│ │ │
|
||||
│ ├── gym-common (公共模块) │
|
||||
│ │ ├── gym-common-core # 核心工具类、常量、枚举 │
|
||||
│ │ ├── gym-common-redis # Redis配置（可选） │
|
||||
│ │ ├── gym-common-security # 安全认证公共组件 │
|
||||
│ │ └── gym-common-log # 日志公共组件 │
|
||||
│ │ │
|
||||
│ ├── gym-api (API网关模块) │
|
||||
│ │ ├── controller # HTTP接口 │
|
||||
│ │ ├── dto # 数据传输对象 │
|
||||
│ │ ├── vo # 视图对象 │
|
||||
│ │ └── config # API配置 │
|
||||
│ │ │
|
||||
│ ├── gym-service (业务服务模块) │
|
||||
│ │ ├── gym-service-member # 会员服务 │
|
||||
│ │ ├── gym-service-booking # 预约服务 │
|
||||
│ │ ├── gym-service-checkin # 签到服务 │
|
||||
│ │ ├── gym-service-course # 课程服务 │
|
||||
│ │ ├── gym-service-coach # 教练服务 │
|
||||
│ │ ├── gym-service-finance # 财务服务 │
|
||||
│ │ └── gym-service-data # 数据服务 │
|
||||
│ │ │
|
||||
│ ├── gym-domain (领域模型模块) │
|
||||
│ │ ├── model # 领域模型 │
|
||||
│ │ ├── event # 领域事件 │
|
||||
│ │ └── service # 领域服务 │
|
||||
│ │ │
|
||||
│ ├── gym-infrastructure (基础设施模块) │
|
||||
│ │ ├── repository # 数据仓储 │
|
||||
│ │ ├── cache # 缓存配置 │
|
||||
│ │ ├── external # 外部服务集成 │
|
||||
│ │ └── config # 基础配置 │
|
||||
│ │ │
|
||||
│ └── gym-starter (启动模块) │
|
||||
│ └── gym-admin # 管理后台启动器 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.2 模块职责
|
||||
|
||||
| 模块 | 职责 | 依赖 |
|
||||
|------|------|------|
|
||||
| gym-common-core | 提供通用工具类、常量定义、异常处理 | 无 |
|
||||
| gym-common-security | 提供JWT认证、权限校验 | gym-common-core |
|
||||
| gym-common-log | 提供统一日志处理 | gym-common-core |
|
||||
| gym-domain | 定义领域模型、领域事件、领域服务 | gym-common-core |
|
||||
| gym-infrastructure | 提供数据访问、缓存、外部服务集成 | gym-domain |
|
||||
| gym-service-member | 会员、会员卡、权益管理 | gym-domain, gym-infrastructure |
|
||||
| gym-service-booking | 课程预约、库存管理 | gym-domain, gym-infrastructure |
|
||||
| gym-service-checkin | 签到处理、权益扣减 | gym-domain, gym-infrastructure |
|
||||
| gym-api | HTTP接口定义、参数校验 | gym-service-* |
|
||||
| gym-starter | 应用启动、配置加载 | gym-api |
|
||||
|
||||
### 4.3 模块交互
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 模块交互流程 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ HTTP Request │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ API │───▶│ Service │───▶│ Domain │───▶│ Repo │ │
|
||||
│ │ Layer │ │ Layer │ │ Layer │ │ Layer │ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ▼ ▼ ▼ │
|
||||
│ │ ┌─────────────────────────────────────┐ │
|
||||
│ │ │ Infrastructure │ │
|
||||
│ │ │ ┌─────────┐ ┌─────────┐ ┌─────┐ │ │
|
||||
│ │ │ │ Cache │ │ MQ │ │ DB │ │ │
|
||||
│ │ │ └─────────┘ └─────────┘ └─────┘ │ │
|
||||
│ │ └─────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ HTTP Response │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、接口设计
|
||||
|
||||
### 5.1 接口规范
|
||||
|
||||
#### 5.1.1 RESTful API 规范
|
||||
|
||||
```
|
||||
基础URL: https://api.gym-manage.com/v1
|
||||
|
||||
资源命名规范:
|
||||
- 使用名词复数形式: /members, /bookings, /courses
|
||||
- 使用小写字母和连字符: /member-cards, /booking-slots
|
||||
- 避免动词: /members (正确) vs /getMembers (错误)
|
||||
|
||||
HTTP方法语义:
|
||||
- GET: 查询资源
|
||||
- POST: 创建资源
|
||||
- PUT: 全量更新资源
|
||||
- PATCH: 部分更新资源
|
||||
- DELETE: 删除资源
|
||||
```
|
||||
|
||||
#### 5.1.2 请求响应格式
|
||||
|
||||
```json
|
||||
// 统一响应格式
|
||||
{
|
||||
"code": 0, // 业务状态码，0表示成功
|
||||
"message": "success", // 响应消息
|
||||
"data": {}, // 响应数据
|
||||
"timestamp": 1709123456789 // 时间戳
|
||||
}
|
||||
|
||||
// 分页响应格式
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"list": [], // 数据列表
|
||||
"total": 100, // 总记录数
|
||||
"page": 1, // 当前页码
|
||||
"pageSize": 20 // 每页大小
|
||||
},
|
||||
"timestamp": 1709123456789
|
||||
}
|
||||
|
||||
// 错误响应格式
|
||||
{
|
||||
"code": 40001, // 错误码
|
||||
"message": "参数校验失败", // 错误消息
|
||||
"data": {
|
||||
"errors": [ // 详细错误信息
|
||||
{"field": "phone", "message": "手机号格式不正确"}
|
||||
]
|
||||
},
|
||||
"timestamp": 1709123456789
|
||||
}
|
||||
```
|
||||
|
||||
#### 5.1.3 状态码定义
|
||||
|
||||
| 状态码 | 含义 | 说明 |
|
||||
|--------|------|------|
|
||||
| 0 | 成功 | 请求处理成功 |
|
||||
| 40001 | 参数错误 | 请求参数校验失败 |
|
||||
| 40002 | 资源不存在 | 请求的资源不存在 |
|
||||
| 40003 | 资源已存在 | 创建的资源已存在 |
|
||||
| 40101 | 未登录 | 用户未登录或Token过期 |
|
||||
| 40102 | 无权限 | 用户无访问权限 |
|
||||
| 40301 | 业务异常 | 业务逻辑校验失败 |
|
||||
| 50001 | 系统异常 | 系统内部错误 |
|
||||
|
||||
### 5.2 接口分组
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ API 接口分组 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ /v1/auth # 认证接口 │
|
||||
│ ├── POST /login # 登录 │
|
||||
│ ├── POST /logout # 登出 │
|
||||
│ ├── POST /refresh # 刷新Token │
|
||||
│ └── POST /wechat-login # 微信登录 │
|
||||
│ │
|
||||
│ /v1/members # 会员接口 │
|
||||
│ ├── GET / # 会员列表 │
|
||||
│ ├── GET /{id} # 会员详情 │
|
||||
│ ├── POST / # 创建会员 │
|
||||
│ ├── PUT /{id} # 更新会员 │
|
||||
│ ├── GET /{id}/cards # 会员卡列表 │
|
||||
│ ├── GET /{id}/benefits # 权益列表 │
|
||||
│ └── GET /{id}/bookings # 预约记录 │
|
||||
│ │
|
||||
│ /v1/courses # 课程接口 │
|
||||
│ ├── GET / # 课程列表 │
|
||||
│ ├── GET /{id} # 课程详情 │
|
||||
│ ├── POST / # 创建课程 │
|
||||
│ ├── PUT /{id} # 更新课程 │
|
||||
│ └── GET /{id}/slots # 可预约时段 │
|
||||
│ │
|
||||
│ /v1/bookings # 预约接口 │
|
||||
│ ├── GET / # 预约列表 │
|
||||
│ ├── GET /{id} # 预约详情 │
|
||||
│ ├── POST / # 创建预约 │
|
||||
│ ├── POST /{id}/cancel # 取消预约 │
|
||||
│ └── GET /my # 我的预约 │
|
||||
│ │
|
||||
│ /v1/checkins # 签到接口 │
|
||||
│ ├── GET / # 签到列表 │
|
||||
│ ├── POST /scan # 扫码签到 │
|
||||
│ ├── POST /manual # 手动签到(教练代签) │
|
||||
│ └── GET /my # 我的签到 │
|
||||
│ │
|
||||
│ /v1/coaches # 教练接口 │
|
||||
│ ├── GET / # 教练列表 │
|
||||
│ ├── GET /{id} # 教练详情 │
|
||||
│ ├── GET /{id}/schedule # 教练排班 │
|
||||
│ └── GET /{id}/slots # 可预约时段 │
|
||||
│ │
|
||||
│ /v1/dashboard # 数据看板 │
|
||||
│ ├── GET /overview # 今日概览 │
|
||||
│ ├── GET /trends # 趋势数据 │
|
||||
│ └── GET /rankings # 排行数据 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.3 接口版本管理
|
||||
|
||||
```
|
||||
版本策略:
|
||||
1. URL路径版本: /v1/members, /v2/members
|
||||
2. 向后兼容原则: 新版本接口保留旧版本功能
|
||||
3. 废弃通知: 旧版本接口返回 Warning 头，提前3个月通知
|
||||
|
||||
版本生命周期:
|
||||
- 开发中: 内部测试，不对外发布
|
||||
- 当前版本: 正式发布，完全支持
|
||||
- 已废弃: 仍可使用，但建议迁移
|
||||
- 已下线: 不再可用
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、安全设计
|
||||
|
||||
### 6.1 认证机制
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 认证机制 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ JWT Token 认证流程 │ │
|
||||
│ │ │ │
|
||||
│ │ 1. 用户登录 │ │
|
||||
│ │ POST /v1/auth/login │ │
|
||||
│ │ { phone, code } │ │
|
||||
│ │ │ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ 2. 服务端验证 │ │
|
||||
│ │ - 验证手机号和验证码 │ │
|
||||
│ │ - 查询用户信息 │ │
|
||||
│ │ - 生成 JWT Token │ │
|
||||
│ │ │ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ 3. 返回 Token │ │
|
||||
│ │ { accessToken, refreshToken, expiresIn } │ │
|
||||
│ │ │ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ 4. 后续请求携带 Token │ │
|
||||
│ │ Authorization: Bearer {accessToken} │ │
|
||||
│ │ │ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ 5. 服务端验证 Token │ │
|
||||
│ │ - 解析 Token │ │
|
||||
│ │ - 验证签名和有效期 │ │
|
||||
│ │ - 提取用户信息 │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Token 结构: │
|
||||
│ { │
|
||||
│ "sub": "member:12345", // 用户标识 │
|
||||
│ "tenant": "tenant:001", // 租户标识 │
|
||||
│ "store": "store:001", // 门店标识 │
|
||||
│ "roles": ["MEMBER"], // 角色列表 │
|
||||
│ "exp": 1709123456, // 过期时间 │
|
||||
│ "iat": 1709120000 // 签发时间 │
|
||||
│ } │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.2 权限控制
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ RBAC 权限模型 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────┐ M:N ┌─────────┐ M:N ┌─────────┐ │
|
||||
│ │ 用户 │─────────────▶│ 角色 │─────────────▶│ 权限 │ │
|
||||
│ │ User │ │ Role │ │Permission│ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ │
|
||||
│ │
|
||||
│ 角色定义: │
|
||||
│ ┌────────────────┬────────────────────────────────────────────────┐ │
|
||||
│ │ 角色 │ 权限范围 │ │
|
||||
│ ├────────────────┼────────────────────────────────────────────────┤ │
|
||||
│ │ ROLE_MEMBER │ 会员端功能：预约、签到、个人信息 │ │
|
||||
│ │ ROLE_COACH │ 教练端功能：排课、签到、学员管理 │ │
|
||||
│ │ ROLE_RECEPTION │ 前台功能：接待、签到、会员查询 │ │
|
||||
│ │ ROLE_STORE_MGR │ 店长功能：单店全功能管理 │ │
|
||||
│ │ ROLE_OPERATOR │ 运营功能：营销活动、数据分析 │ │
|
||||
│ │ ROLE_FINANCE │ 财务功能：账单、报表 │ │
|
||||
│ │ ROLE_ADMIN │ 超管功能：全平台管理 │ │
|
||||
│ └────────────────┴────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 权限标识: │
|
||||
│ 格式: {模块}:{资源}:{操作} │
|
||||
│ 示例: │
|
||||
│ - member:user:read # 查看会员信息 │
|
||||
│ - member:user:write # 编辑会员信息 │
|
||||
│ - booking:course:create # 创建课程预约 │
|
||||
│ - booking:course:cancel # 取消课程预约 │
|
||||
│ - checkin:scan:execute # 执行扫码签到 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.3 数据安全
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 数据安全措施 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 敏感数据加密 │
|
||||
│ ├── 手机号: 存储时AES加密，展示时脱敏(138****1234) │
|
||||
│ ├── 身份证: 存储时AES加密，不对外展示 │
|
||||
│ ├── 密码: 使用BCrypt加密存储 │
|
||||
│ └── 支付信息: 不存储，仅保留支付渠道token │
|
||||
│ │
|
||||
│ 2. 传输安全 │
|
||||
│ ├── 全站HTTPS │
|
||||
│ ├── 敏感接口签名验证 │
|
||||
│ └── 防重放攻击(timestamp + nonce) │
|
||||
│ │
|
||||
│ 3. SQL注入防护 │
|
||||
│ ├── 使用R2DBC参数化查询 │
|
||||
│ ├── 禁止拼接SQL │
|
||||
│ └── 输入参数校验 │
|
||||
│ │
|
||||
│ 4. XSS防护 │
|
||||
│ ├── 输入过滤 │
|
||||
│ ├── 输出编码 │
|
||||
│ └── Content-Security-Policy头 │
|
||||
│ │
|
||||
│ 5. CSRF防护 │
|
||||
│ ├── CSRF Token验证 │
|
||||
│ └── SameSite Cookie │
|
||||
│ │
|
||||
│ 6. 多租户数据隔离 │
|
||||
│ ├── tenant_id 强制过滤 │
|
||||
│ ├── 数据库行级安全策略(RLS) │
|
||||
│ └── API层租户上下文自动注入 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.4 接口安全
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 接口安全措施 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 限流策略 │
|
||||
│ ├── 全局限流: 10000 QPS │
|
||||
│ ├── 单IP限流: 100 QPS │
|
||||
│ ├── 单用户限流: 50 QPS │
|
||||
│ └── 敏感接口限流: 登录10次/分钟，短信1次/分钟 │
|
||||
│ │
|
||||
│ 2. 熔断降级 │
|
||||
│ ├── 错误率阈值: 50% │
|
||||
│ ├── 熔断时间窗口: 30秒 │
|
||||
│ └── 降级策略: 返回默认值或友好提示 │
|
||||
│ │
|
||||
│ 3. 黑白名单 │
|
||||
│ ├── IP白名单: 管理后台接口 │
|
||||
│ ├── IP黑名单: 恶意攻击IP │
|
||||
│ └── 用户黑名单: 违规用户 │
|
||||
│ │
|
||||
│ 4. 日志审计 │
|
||||
│ ├── 操作日志: 记录所有写操作 │
|
||||
│ ├── 访问日志: 记录所有API请求 │
|
||||
│ └── 异常日志: 记录系统异常 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、性能设计
|
||||
|
||||
### 7.1 性能目标
|
||||
|
||||
| 指标 | 目标值 | 说明 |
|
||||
|------|--------|------|
|
||||
| 响应时间 | P99 < 200ms | 99%的请求响应时间小于200ms |
|
||||
| 吞吐量 | QPS ≥ 1000 | 系统每秒处理请求数 |
|
||||
| 并发用户 | ≥ 5000 | 同时在线用户数 |
|
||||
| 可用性 | SLA ≥ 99.9% | 年度可用性 |
|
||||
|
||||
### 7.2 性能优化策略
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 性能优化策略 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 数据库优化 │
|
||||
│ ├── 索引优化: 合理创建索引，避免全表扫描 │
|
||||
│ ├── 连接池: R2DBC连接池，max-size=20 │
|
||||
│ ├── 读写分离: 主库写入，从库读取（后期扩展） │
|
||||
│ └── 分库分表: 按租户分库（后期扩展） │
|
||||
│ │
|
||||
│ 2. 缓存优化 │
|
||||
│ ├── L1缓存: Caffeine本地缓存，热点数据 │
|
||||
│ ├── L2缓存: Redis分布式缓存（可选扩展） │
|
||||
│ ├── 缓存策略: 写穿透 + 延迟双删 │
|
||||
│ └── 缓存预热: 系统启动时预加载热点数据 │
|
||||
│ │
|
||||
│ 3. 代码优化 │
|
||||
│ ├── 响应式编程: WebFlux非阻塞IO │
|
||||
│ ├── 异步处理: 非核心流程异步化 │
|
||||
│ ├── 批量操作: 减少数据库往返 │
|
||||
│ └── 虚拟线程: JDK 21虚拟线程优化阻塞操作 │
|
||||
│ │
|
||||
│ 4. 网络优化 │
|
||||
│ ├── CDN加速: 静态资源CDN分发 │
|
||||
│ ├── GZIP压缩: 响应数据压缩 │
|
||||
│ ├── HTTP/2: 多路复用 │
|
||||
│ └── Keep-Alive: 连接复用 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 7.3 高并发场景处理
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 高并发预约场景处理 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 场景: 热门课程开抢，大量用户同时预约 │
|
||||
│ │
|
||||
│ 解决方案: │
|
||||
│ │
|
||||
│ 1. 库存预热 │
|
||||
│ └── 开抢前将课程库存加载到Caffeine缓存 │
|
||||
│ │
|
||||
│ 2. 原子操作 │
|
||||
│ └── 使用PostgreSQL原子更新: │
|
||||
│ UPDATE booking_slot │
|
||||
│ SET booked_count = booked_count + 1 │
|
||||
│ WHERE id = ? AND booked_count < capacity │
|
||||
│ │
|
||||
│ 3. 乐观锁 │
|
||||
│ └── 版本号控制，冲突时重试 │
|
||||
│ │
|
||||
│ 4. 排队机制 │
|
||||
│ └── 请求进入队列，异步处理结果 │
|
||||
│ │
|
||||
│ 5. 限流保护 │
|
||||
│ └── 令牌桶限流，防止系统过载 │
|
||||
│ │
|
||||
│ 6. 候补机制 │
|
||||
│ └── 满员后自动进入候补队列，有人取消时自动补位 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、可扩展性设计
|
||||
|
||||
### 8.1 水平扩展
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 水平扩展方案 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 无状态设计 │
|
||||
│ ├── Session外置到Redis │
|
||||
│ ├── 本地不存储用户状态 │
|
||||
│ └── 任意实例可处理任意请求 │
|
||||
│ │
|
||||
│ 2. 负载均衡 │
|
||||
│ ├── 轮询: 默认策略 │
|
||||
│ ├── 加权轮询: 根据服务器性能分配权重 │
|
||||
│ └── 最少连接: 请求分配给连接数最少的服务器 │
|
||||
│ │
|
||||
│ 3. 服务拆分（后期） │
|
||||
│ ├── 会员服务独立部署 │
|
||||
│ ├── 预约服务独立部署 │
|
||||
│ └── 数据服务独立部署 │
|
||||
│ │
|
||||
│ 4. 数据库扩展（后期） │
|
||||
│ ├── 读写分离 │
|
||||
│ ├── 分库分表 │
|
||||
│ └── 多活架构 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 8.2 功能扩展
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 功能扩展点 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 支付扩展 │
|
||||
│ ├── 预留支付接口抽象 │
|
||||
│ ├── 支持微信支付、支付宝、银联等 │
|
||||
│ └── 可扩展其他支付渠道 │
|
||||
│ │
|
||||
│ 2. 硬件扩展 │
|
||||
│ ├── 签到网关抽象设计 │
|
||||
│ ├── 支持多种签到设备 │
|
||||
│ └── 可扩展智能硬件 │
|
||||
│ │
|
||||
│ 3. 消息扩展 │
|
||||
│ ├── 消息模板可配置 │
|
||||
│ ├── 支持多渠道推送 │
|
||||
│ └── 可扩展新的消息渠道 │
|
||||
│ │
|
||||
│ 4. 报表扩展 │
|
||||
│ ├── 报表模板可配置 │
|
||||
│ ├── 支持自定义报表 │
|
||||
│ └── 可扩展BI工具对接 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、监控与运维
|
||||
|
||||
### 9.1 监控体系
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 监控体系 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 基础监控 │
|
||||
│ ├── CPU使用率 │
|
||||
│ ├── 内存使用率 │
|
||||
│ ├── 磁盘使用率 │
|
||||
│ ├── 网络IO │
|
||||
│ └── 进程状态 │
|
||||
│ │
|
||||
│ 2. 应用监控 │
|
||||
│ ├── JVM监控(GC、堆内存、线程) │
|
||||
│ ├── 请求QPS/响应时间 │
|
||||
│ ├── 错误率/异常数 │
|
||||
│ └── 数据库连接池状态 │
|
||||
│ │
|
||||
│ 3. 业务监控 │
|
||||
│ ├── 登录数/在线用户数 │
|
||||
│ ├── 预约成功率 │
|
||||
│ ├── 签到成功率 │
|
||||
│ └── 支付成功率 │
|
||||
│ │
|
||||
│ 4. 告警策略 │
|
||||
│ ├── CPU > 80% 告警 │
|
||||
│ ├── 内存 > 85% 告警 │
|
||||
│ ├── 错误率 > 1% 告警 │
|
||||
│ └── 响应时间 P99 > 500ms 告警 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 9.2 日志规范
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 日志规范 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 日志级别 │
|
||||
│ ├── ERROR: 错误日志，需要立即处理 │
|
||||
│ ├── WARN: 警告日志，需要关注 │
|
||||
│ ├── INFO: 重要业务日志 │
|
||||
│ └── DEBUG: 调试日志（生产环境关闭） │
|
||||
│ │
|
||||
│ 2. 日志格式 │
|
||||
│ { │
|
||||
│ "timestamp": "2024-02-28T10:00:00.000+08:00", │
|
||||
│ "level": "INFO", │
|
||||
│ "traceId": "abc123", │
|
||||
│ "spanId": "def456", │
|
||||
│ "tenantId": "tenant:001", │
|
||||
│ "userId": "member:12345", │
|
||||
│ "class": "MemberService", │
|
||||
│ "method": "createMember", │
|
||||
│ "message": "创建会员成功", │
|
||||
│ "args": {"phone": "138****1234"}, │
|
||||
│ "result": {"memberId": 12345}, │
|
||||
│ "duration": 50 │
|
||||
│ } │
|
||||
│ │
|
||||
│ 3. 日志存储 │
|
||||
│ ├── 本地文件: 保留7天 │
|
||||
│ ├── ELK: 集中存储和分析 │
|
||||
│ └── 归档: 超过30天归档到OSS │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、附录
|
||||
|
||||
### 10.1 技术选型清单
|
||||
|
||||
| 分类 | 技术 | 版本 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 后端框架 | Spring Boot | 3.x | 主框架 |
|
||||
| 响应式 | Spring WebFlux | 3.x | 响应式Web框架 |
|
||||
| JDK | OpenJDK | 21+ | 虚拟线程支持 |
|
||||
| 数据库 | PostgreSQL | 15+ | 主数据库 |
|
||||
| 数据访问 | R2DBC | 1.x | 响应式数据库访问 |
|
||||
| 数据库迁移 | Flyway | 9.x | 数据库版本管理 |
|
||||
| 缓存 | Caffeine | 3.x | 本地缓存 |
|
||||
| 缓存(可选) | Redis | 7.x | 分布式缓存 |
|
||||
| 前端框架 | Vue | 3.x | 前端框架 |
|
||||
| 跨端框架 | uniapp | 3.x | 跨端开发框架 |
|
||||
| 状态管理 | Pinia | 2.x | 状态管理 |
|
||||
| UI组件 | Element Plus | 2.x | 管理后台UI |
|
||||
| 构建工具 | Vite | 5.x | 前端构建工具 |
|
||||
| 容器 | Docker | 24.x | 容器化部署 |
|
||||
|
||||
### 10.2 术语表
|
||||
|
||||
| 术语 | 英文 | 定义 |
|
||||
|------|------|------|
|
||||
| 高可用 | High Availability | 系统持续提供服务的能力 |
|
||||
| 响应式编程 | Reactive Programming | 基于数据流和变化传播的编程范式 |
|
||||
| 多租户 | Multi-tenancy | 单个实例服务多个租户的架构 |
|
||||
| 软删除 | Soft Delete | 通过标记删除时间而非物理删除数据 |
|
||||
| 乐观锁 | Optimistic Lock | 假设冲突较少，通过版本号控制并发 |
|
||||
| 悲观锁 | Pessimistic Lock | 假设冲突较多，通过锁机制控制并发 |
|
||||
|
||||
---
|
||||
|
||||
*文档结束*
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user