重构HLD和LLD文档，明确业务概要设计与详细设计的职责分工
主要变更： - 重构HLD-系统概要设计.md为业务概要设计文档 * 聚焦于业务范围、业务流程、业务规则、业务场景 * 移除技术架构、模块设计、接口设计等技术内容 * 新增核心业务流程图（会员注册、课程预约、签到、会员卡购买） * 新增详细业务规则（会员管理、预约管理、签到管理、财务管理、数据分析） * 新增典型业务场景和特殊业务场景描述 * 新增业务约束和业务指标 - 新增LLD-系统详细设计.md作为系统技术详细设计文档 * 整合从HLD移出的技术架构设计（总体架构、技术架构、部署架构） * 整合模块设计（模块划分、模块职责、模块交互） * 整合接口设计（接口规范、接口分组、接口版本管理） * 整合安全设计（认证机制、权限控制、数据安全、接口安全） * 整合性能设计（性能目标、性能优化策略、高并发场景处理） * 整合可扩展性设计（水平扩展、功能扩展） * 整合监控与运维（监控体系、日志规范） - 更新所有LLD模块文档的参考文档 * 更新HLD文档引用为业务概要设计文档 * 新增LLD-系统详细设计.md作为参考文档 - 删除docs/api/API接口文档.md（接口设计已整合到LLD-系统详细设计.md） 文档职责分工： - PRD：产品需求文档，描述产品需求和功能 - HLD：业务概要设计文档，描述业务范围、流程、规则、场景 - LLD：详细设计文档，描述技术架构、模块设计、接口设计等实现细节~
This commit is contained in:
张翔
-1390
File diff suppressed because it is too large
Load Diff
+466
-777
File diff suppressed because it is too large
Load Diff
@@ -19,7 +19,8 @@
|
||||
## 参考文档
|
||||
|
||||
- 《健身房管理系统产品设计文档》 GYM-PRD-001
|
||||
- 《健身房管理系统概要设计文档》 GYM-HLD-001
|
||||
- 《健身房管理系统业务概要设计文档》 GYM-HLD-001
|
||||
- 《健身房管理系统详细设计文档》 GYM-LLD-000
|
||||
- Spring Boot 3 官方文档
|
||||
- R2DBC 规范文档
|
||||
- PostgreSQL 官方文档
|
||||
|
||||
@@ -19,7 +19,8 @@
|
||||
## 参考文档
|
||||
|
||||
- 《健身房管理系统产品设计文档》 GYM-PRD-001
|
||||
- 《健身房管理系统概要设计文档》 GYM-HLD-001
|
||||
- 《健身房管理系统业务概要设计文档》 GYM-HLD-001
|
||||
- 《健身房管理系统详细设计文档》 GYM-LLD-000
|
||||
- Spring Boot 3 官方文档
|
||||
- R2DBC 规范文档
|
||||
- PostgreSQL 官方文档
|
||||
|
||||
@@ -0,0 +1,796 @@
|
||||
# 健身房管理系统详细设计文档（LLD）
|
||||
|
||||
> 文档编号: GYM-LLD-000
|
||||
> 版本: v1.0
|
||||
> 日期: 2026-03-04
|
||||
> 作者: 张翔
|
||||
> 状态: 初稿
|
||||
|
||||
---
|
||||
|
||||
## 文档修订历史
|
||||
|
||||
| 版本 | 日期 | 作者 | 修订内容 |
|
||||
| ---- | ---------- | ---- | -------- |
|
||||
| v1.0 | 2026-03-04 | 张翔 | 创建系统详细设计文档 |
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
- 《健身房管理系统产品设计文档》 GYM-PRD-001
|
||||
- 《健身房管理系统业务概要设计文档》 GYM-HLD-001
|
||||
- Spring Boot 3 官方文档
|
||||
- R2DBC 规范文档
|
||||
- PostgreSQL 官方文档
|
||||
|
||||
---
|
||||
|
||||
## 一、系统架构设计
|
||||
|
||||
### 1.1 总体架构
|
||||
|
||||
采用分层架构 + 微服务思想的模块化设计：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 总体架构 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 客户端层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 会员小程序 (uniapp+Vue3) │ │
|
||||
│ │ • 教练端App (uniapp+Vue3) │ │
|
||||
│ │ • 管理后台PC (Vue3+Vite) │ │
|
||||
│ │ • 硬件设备 (人脸/NFC) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ API Gateway 统一网关 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 路由转发 • 认证鉴权 • 限流熔断 • 日志追踪 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 业务层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 会员服务 (Member Service) │ │
|
||||
│ │ • 预约服务 (Booking Service) │ │
|
||||
│ │ • 数据服务 (Data Service) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 公共服务层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 认证服务 • 消息服务 • 文件服务 • 缓存服务 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 基础设施层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • PostgreSQL • R2DBC • Caffeine • Redis(可选) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 外部服务层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 微信开放平台 • 短信服务 • 支付服务 • OSS存储 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 1.2 技术架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 技术架构 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 前端技术栈 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • uniapp (跨平台小程序) • Vue3 (前端框架) │ │
|
||||
│ │ • Vite (构建工具) • TypeScript (类型安全) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 后端技术栈 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • Spring Boot 3 (应用框架) • WebFlux (响应式编程) │ │
|
||||
│ │ • JDK 21+ (运行环境) • R2DBC (响应式数据库访问) │ │
|
||||
│ │ • Spring Security (安全框架) • Caffeine (本地缓存) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 数据库技术栈 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • PostgreSQL 15+ (主数据库) • Redis (可选缓存) │ │
|
||||
│ │ • Flyway (数据库版本管理) • R2DBC PostgreSQL Driver │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 开发工具栈 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • Maven (依赖管理) • Git (版本控制) • Docker (容器化) │ │
|
||||
│ │ • IDEA (开发IDE) • Postman (接口测试) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 1.3 部署架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 部署架构 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 客户端层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 微信小程序 • 教练端App • 管理后台PC • 硬件设备 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ CDN层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 静态资源加速 • 图片优化 • 视频加速 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 负载均衡层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • Nginx (反向代理) • 负载均衡策略 • SSL/TLS │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 应用服务器层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • Spring Boot应用 (多实例部署) • Docker容器化 │ │
|
||||
│ │ • 健康检查 • 自动扩缩容 • 滚动更新 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 数据库层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • PostgreSQL主从复制 • Redis集群 (可选) • 备份策略 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 监控运维层 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────────┤ │
|
||||
│ │ • 日志收集 • 性能监控 • 告警通知 • 自动化运维 │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、模块设计
|
||||
|
||||
### 2.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 (管理后台启动器) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 模块职责
|
||||
|
||||
| 模块 | 职责 | 依赖 |
|
||||
| ------------------- | ---------------------------------- | ------------------------------ |
|
||||
| gym-common-core | 提供通用工具类、常量定义、异常处理 | 无 |
|
||||
| gym-common-security | 提供JWT认证、权限校验 | gym-common-core |
|
||||
| gym-common-redis | 提供Redis缓存支持（可选） | gym-common-core |
|
||||
| gym-common-log | 提供统一日志记录 | gym-common-core |
|
||||
| gym-api | 提供HTTP接口、路由转发 | gym-service-* |
|
||||
| gym-service-member | 会员管理业务逻辑 | gym-domain, gym-infrastructure |
|
||||
| gym-service-booking | 预约管理业务逻辑 | gym-domain, gym-infrastructure |
|
||||
| gym-service-checkin | 签到管理业务逻辑 | gym-domain, gym-infrastructure |
|
||||
| gym-service-course | 课程管理业务逻辑 | gym-domain, gym-infrastructure |
|
||||
| gym-service-coach | 教练管理业务逻辑 | gym-domain, gym-infrastructure |
|
||||
| gym-service-finance | 财务管理业务逻辑 | gym-domain, gym-infrastructure |
|
||||
| gym-service-data | 数据分析业务逻辑 | gym-domain, gym-infrastructure |
|
||||
| gym-domain | 领域模型、领域事件、领域服务 | 无 |
|
||||
| gym-infrastructure | 数据仓储、缓存、外部服务集成 | gym-domain |
|
||||
| gym-starter | 应用启动器 | 所有业务模块 |
|
||||
|
||||
### 2.3 模块交互
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 模块交互 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────┐ │
|
||||
│ │ 客户端 │ │
|
||||
│ └─────┬────┘ │
|
||||
│ │ HTTP/HTTPS │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ gym-api (API网关) │ │
|
||||
│ └─────────────┬───────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌─────────┼─────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||||
│ │member │ │booking │ │checkin │ │
|
||||
│ │service │ │service │ │service │ │
|
||||
│ └───┬────┘ └───┬────┘ └───┬────┘ │
|
||||
│ │ │ │ │
|
||||
│ └───────────┼───────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────┐ │
|
||||
│ │ gym-domain │ │
|
||||
│ └───────┬───────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌───────────────┐ │
|
||||
│ │ gym-infra │ │
|
||||
│ └───────┬───────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────┼───────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||||
│ │ PG │ │Redis │ │External│ │
|
||||
│ └────────┘ └────────┘ └────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、接口设计
|
||||
|
||||
### 3.1 接口规范
|
||||
|
||||
#### 3.1.1 RESTful API设计原则
|
||||
|
||||
- 使用HTTP标准方法：GET（查询）、POST（创建）、PUT（更新）、DELETE（删除）
|
||||
- 使用HTTP状态码表示请求结果：200（成功）、400（请求错误）、401（未认证）、403（无权限）、404（资源不存在）、500（服务器错误）
|
||||
- 使用JSON格式进行数据交换
|
||||
- 使用统一的响应结构
|
||||
|
||||
#### 3.1.2 统一响应结构
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.1.3 错误响应结构
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "参数错误",
|
||||
"data": null,
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.1.4 分页响应结构
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"list": [],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"pageSize": 10
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 接口分组
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 接口分组 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 认证接口 /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 (排行数据) │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.3 接口版本管理
|
||||
|
||||
#### 3.3.1 版本策略
|
||||
|
||||
- 采用URL路径版本控制：/v1/、/v2/
|
||||
- 主版本号变更表示不兼容的API变更
|
||||
- 次版本号变更表示向后兼容的功能新增
|
||||
- 修订版本号变更表示向后兼容的问题修复
|
||||
|
||||
#### 3.3.2 版本兼容性
|
||||
|
||||
- 新版本API发布后，旧版本API至少维护6个月
|
||||
- 废弃API在响应头中添加Warning字段
|
||||
- 提供API版本迁移指南
|
||||
|
||||
---
|
||||
|
||||
## 四、安全设计
|
||||
|
||||
### 4.1 认证机制
|
||||
|
||||
#### 4.1.1 JWT认证
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ JWT认证流程 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 用户 │────▶│ 登录 │────▶│ 验证 │────▶│ 生成 │ │
|
||||
│ │ 登录 │ │ 请求 │ │ 凭证 │ │ Token │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────┐ │
|
||||
│ │ 返回 │ │
|
||||
│ │ Token │ │
|
||||
│ └──────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────┐ │
|
||||
│ │ 后续 │ │
|
||||
│ │ 请求 │ │
|
||||
│ └──────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────┐ │
|
||||
│ │ 携带 │ │
|
||||
│ │ Token │ │
|
||||
│ └──────────┘ │
|
||||
│ │
|
||||
│ Token结构: │
|
||||
│ • Header: 算法、类型 │
|
||||
│ • Payload: 用户ID、角色、过期时间 │
|
||||
│ • Signature: 签名 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### 4.1.2 Token刷新机制
|
||||
|
||||
- Access Token有效期：2小时
|
||||
- Refresh Token有效期：7天
|
||||
- Access Token过期时使用Refresh Token刷新
|
||||
- Refresh Token过期时需要重新登录
|
||||
|
||||
### 4.2 权限控制
|
||||
|
||||
#### 4.2.1 RBAC权限模型
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ RBAC权限模型 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 用户 │──▶│ 角色 │──▶│ 权限 │──▶│ 资源 │ │
|
||||
│ │ User │ │ Role │ │Permission│ │ Resource │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ │
|
||||
│ 权限示例: │
|
||||
│ • member:view (查看会员) │
|
||||
│ • member:edit (编辑会员) │
|
||||
│ • member:delete (删除会员) │
|
||||
│ • booking:create (创建预约) │
|
||||
│ • booking:cancel (取消预约) │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### 4.2.2 权限校验流程
|
||||
|
||||
1. 用户登录后获取角色和权限
|
||||
2. 每次请求时校验权限
|
||||
3. 无权限时返回403错误
|
||||
4. 支持权限继承和组合
|
||||
|
||||
### 4.3 数据安全
|
||||
|
||||
#### 4.3.1 数据加密
|
||||
|
||||
- 敏感数据（手机号、身份证）使用AES-256加密存储
|
||||
- 密码使用BCrypt加密
|
||||
- 传输数据使用HTTPS加密
|
||||
- 数据库连接使用SSL/TLS
|
||||
|
||||
#### 4.3.2 数据脱敏
|
||||
|
||||
- 手机号脱敏：138****5678
|
||||
- 身份证脱敏：110101********1234
|
||||
- 银行卡脱敏：6222************1234
|
||||
|
||||
#### 4.3.3 数据备份
|
||||
|
||||
- 每日全量备份
|
||||
- 每小时增量备份
|
||||
- 备份数据加密存储
|
||||
- 备份数据异地容灾
|
||||
|
||||
### 4.4 接口安全
|
||||
|
||||
#### 4.4.1 防重放攻击
|
||||
|
||||
- 每个请求携带时间戳
|
||||
- 时间戳有效期：5分钟
|
||||
- 请求签名验证
|
||||
|
||||
#### 4.4.2 防SQL注入
|
||||
|
||||
- 使用参数化查询
|
||||
- 使用R2DBC响应式数据库访问
|
||||
- 输入参数校验和过滤
|
||||
|
||||
#### 4.4.3 防XSS攻击
|
||||
|
||||
- 输入内容过滤和转义
|
||||
- 响应头设置Content-Security-Policy
|
||||
- 使用白名单过滤
|
||||
|
||||
---
|
||||
|
||||
## 五、性能设计
|
||||
|
||||
### 5.1 性能目标
|
||||
|
||||
| 指标 | 目标值 | 测量方法 |
|
||||
| -------------- | ---------- | ---------------------- |
|
||||
| 响应时间 | ≤ 2秒 | 请求响应时间 |
|
||||
| 并发处理能力 | ≥ 1000 QPS | 每秒处理请求数 |
|
||||
| 数据库查询时间 | ≤ 100ms | SQL执行时间 |
|
||||
| 缓存命中率 | ≥ 80% | 缓存命中次数/总请求次数 |
|
||||
| 系统可用性 | ≥ 99.9% | (总时间-故障时间)/总时间 |
|
||||
|
||||
### 5.2 性能优化策略
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 性能优化策略 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 缓存策略 │
|
||||
│ ├── Caffeine本地缓存 (热点数据) │
|
||||
│ ├── Redis分布式缓存 (可选) │
|
||||
│ ├── 数据库查询结果缓存 │
|
||||
│ └── 缓存预热和失效策略 │
|
||||
│ │
|
||||
│ 2. 数据库优化 │
|
||||
│ ├── 索引优化 │
|
||||
│ ├── 查询优化 │
|
||||
│ ├── 分页查询 │
|
||||
│ └── 读写分离 (后期) │
|
||||
│ │
|
||||
│ 3. 响应式编程 │
|
||||
│ ├── WebFlux非阻塞IO │
|
||||
│ ├── R2DBC响应式数据库访问 │
|
||||
│ └── 异步处理 │
|
||||
│ │
|
||||
│ 4. 前端优化 │
|
||||
│ ├── 资源压缩 │
|
||||
│ ├── CDN加速 │
|
||||
│ ├── 懒加载 │
|
||||
│ └── 防抖节流 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.3 高并发场景处理
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 高并发场景处理 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 限流保护 │
|
||||
│ └── 令牌桶限流，防止系统过载 │
|
||||
│ │
|
||||
│ 2. 熔断降级 │
|
||||
│ └── 服务异常时快速失败，防止雪崩 │
|
||||
│ │
|
||||
│ 3. 分布式锁 │
|
||||
│ └── Redis分布式锁，保证数据一致性 │
|
||||
│ │
|
||||
│ 4. 乐观锁 │
|
||||
│ └── 版本号控制，冲突时重试 │
|
||||
│ │
|
||||
│ 5. 排队机制 │
|
||||
│ └── 请求进入队列，异步处理结果 │
|
||||
│ │
|
||||
│ 6. 候补机制 │
|
||||
│ └── 满员后自动进入候补队列，有人取消时自动补位 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、可扩展性设计
|
||||
|
||||
### 6.1 水平扩展
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 水平扩展方案 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 无状态设计 │
|
||||
│ ├── Session外置到Redis │
|
||||
│ ├── 本地不存储用户状态 │
|
||||
│ └── 任意实例可处理任意请求 │
|
||||
│ │
|
||||
│ 2. 负载均衡 │
|
||||
│ ├── 轮询: 默认策略 │
|
||||
│ ├── 加权轮询: 根据服务器性能分配权重 │
|
||||
│ └── 最少连接: 请求分配给连接数最少的服务器 │
|
||||
│ │
|
||||
│ 3. 服务拆分（后期） │
|
||||
│ ├── 会员服务独立部署 │
|
||||
│ ├── 预约服务独立部署 │
|
||||
│ └── 数据服务独立部署 │
|
||||
│ │
|
||||
│ 4. 数据库扩展（后期） │
|
||||
│ ├── 读写分离 │
|
||||
│ ├── 分库分表 │
|
||||
│ └── 多活架构 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.2 功能扩展
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 功能扩展点 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 支付扩展 │
|
||||
│ ├── 预留支付接口抽象 │
|
||||
│ ├── 支持微信支付、支付宝、银联等 │
|
||||
│ └── 可扩展其他支付渠道 │
|
||||
│ │
|
||||
│ 2. 硬件扩展 │
|
||||
│ ├── 签到网关抽象设计 │
|
||||
│ ├── 支持多种签到设备 │
|
||||
│ └── 可扩展智能硬件 │
|
||||
│ │
|
||||
│ 3. 消息扩展 │
|
||||
│ ├── 消息模板可配置 │
|
||||
│ ├── 支持多渠道推送 │
|
||||
│ └── 可扩展新的消息渠道 │
|
||||
│ │
|
||||
│ 4. 报表扩展 │
|
||||
│ ├── 报表模板可配置 │
|
||||
│ ├── 支持自定义报表 │
|
||||
│ └── 可扩展BI工具对接 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、监控与运维
|
||||
|
||||
### 7.1 监控体系
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ 监控体系 │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. 基础监控 │
|
||||
│ ├── CPU使用率 │
|
||||
│ ├── 内存使用率 │
|
||||
│ ├── 磁盘使用率 │
|
||||
│ ├── 网络IO │
|
||||
│ └── 进程状态 │
|
||||
│ │
|
||||
│ 2. 应用监控 │
|
||||
│ ├── JVM监控(GC、堆内存、线程) │
|
||||
│ ├── HTTP请求监控(QPS、响应时间、错误率) │
|
||||
│ ├── 数据库连接池监控 │
|
||||
│ └── 缓存命中率监控 │
|
||||
│ │
|
||||
│ 3. 业务监控 │
|
||||
│ ├── 会员注册数 │
|
||||
│ ├── 预约成功率 │
|
||||
│ ├── 签到成功率 │
|
||||
│ └── 支付成功率 │
|
||||
│ │
|
||||
│ 4. 告警机制 │
|
||||
│ ├── 告警规则配置 │
|
||||
│ ├── 告警通知方式(邮件、短信、钉钉) │
|
||||
│ └── 告警升级策略 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 7.2 日志规范
|
||||
|
||||
#### 7.2.1 日志级别
|
||||
|
||||
- ERROR：错误日志，系统异常
|
||||
- WARN：警告日志，潜在问题
|
||||
- INFO：信息日志，关键业务操作
|
||||
- DEBUG：调试日志，开发调试使用
|
||||
|
||||
#### 7.2.2 日志格式
|
||||
|
||||
```
|
||||
[时间] [级别] [线程] [类名] - 日志内容
|
||||
[2026-03-04 10:00:00] [INFO] [http-nio-8080-exec-1] [com.gym.controller.MemberController] - 会员登录成功, memberId=12345
|
||||
```
|
||||
|
||||
#### 7.2.3 日志存储
|
||||
|
||||
- 日志文件按日期滚动
|
||||
- 日志文件保留30天
|
||||
- 错误日志单独存储
|
||||
- 支持日志查询和导出
|
||||
|
||||
---
|
||||
|
||||
## 八、附录
|
||||
|
||||
### 8.1 技术选型清单
|
||||
|
||||
| 技术类别 | 技术选型 | 版本 | 用途 |
|
||||
| -------------- | --------------------------- | -------- | ------------------ |
|
||||
| 前端框架 | Vue3 | 3.x | 前端开发 |
|
||||
| 前端构建 | Vite | 5.x | 前端构建 |
|
||||
| 跨平台框架 | uniapp | 3.x | 小程序开发 |
|
||||
| 后端框架 | Spring Boot | 3.x | 应用框架 |
|
||||
| 响应式编程 | Spring WebFlux | 3.x | 响应式Web开发 |
|
||||
| 数据库 | PostgreSQL | 15+ | 主数据库 |
|
||||
| 数据库访问 | R2DBC | 1.x | 响应式数据库访问 |
|
||||
| 缓存 | Caffeine | 3.x | 本地缓存 |
|
||||
| 缓存（可选） | Redis | 7.x | 分布式缓存 |
|
||||
| 安全框架 | Spring Security | 6.x | 安全认证授权 |
|
||||
| 数据库版本管理 | Flyway | 9.x | 数据库版本管理 |
|
||||
| 容器化 | Docker | 24+ | 容器化部署 |
|
||||
| 负载均衡 | Nginx | 1.24+ | 反向代理负载均衡 |
|
||||
|
||||
### 8.2 术语表
|
||||
|
||||
| 术语 | 定义 |
|
||||
| ----------------------------- | ------------------------------------------------ |
|
||||
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
|
||||
| 门店(Store) | 租户下的具体经营场所 |
|
||||
| 会员(Member) | 在门店注册的用户 |
|
||||
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
|
||||
| 可预约资源(Bookable Resource) | 团课、私教、场地、线上课程等可被预约的对象 |
|
||||
| 时段(Slot) | 资源的可预约时间窗口 |
|
||||
| JWT | JSON Web Token，用于身份认证 |
|
||||
| RBAC | Role-Based Access Control，基于角色的访问控制 |
|
||||
| QPS | Queries Per Second，每秒查询数 |
|
||||
| SLA | Service Level Agreement，服务等级协议 |
|
||||
|
||||
---
|
||||
|
||||
**文档结束**
|
||||
@@ -19,7 +19,8 @@
|
||||
## 参考文档
|
||||
|
||||
- 《健身房管理系统产品设计文档》 GYM-PRD-001
|
||||
- 《健身房管理系统概要设计文档》 GYM-HLD-001
|
||||
- 《健身房管理系统业务概要设计文档》 GYM-HLD-001
|
||||
- 《健身房管理系统详细设计文档》 GYM-LLD-000
|
||||
- Spring Boot 3 官方文档
|
||||
- R2DBC 规范文档
|
||||
- PostgreSQL 官方文档
|
||||
|
||||
Reference in New Issue
Block a user