张翔
e89f5f1f7f
- HLD-系统概要设计.md: 转换业务范围、总体架构、技术架构、部署架构、模块划分、模块交互、API接口分组等图 - LLD-会员模块详细设计.md: 转换模块边界、实体关系图 - LLD-预约模块详细设计.md: 转换模块边界、实体关系图 - LLD-签到模块详细设计.md: 转换模块边界、实体关系图 Mermaid格式优势: - 更好的可维护性和可读性 - 支持在Markdown编辑器中实时预览 - 更容易进行版本对比和修改 - 支持多种图表类型(mindmap, graph, erDiagram, sequenceDiagram)~
993 lines
51 KiB
Markdown
993 lines
51 KiB
Markdown
# 健身房管理系统概要设计文档（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 业务范围
|
|
|
|
```mermaid
|
|
mindmap
|
|
root((业务范围))
|
|
会员管理
|
|
会员注册
|
|
会员卡管理
|
|
权益管理
|
|
等级管理
|
|
预约管理
|
|
团课预约
|
|
私教预约
|
|
场地预约
|
|
线上课程
|
|
签到管理
|
|
扫码签到
|
|
刷脸签到
|
|
NFC签到
|
|
教练代签
|
|
课程管理
|
|
课程类型
|
|
课程排期
|
|
场地管理
|
|
价格配置
|
|
教练管理
|
|
教练信息
|
|
排班管理
|
|
课时统计
|
|
评价管理
|
|
财务管理
|
|
营收统计
|
|
账单管理
|
|
退款管理
|
|
对账管理
|
|
计划中心
|
|
训练计划
|
|
课程排期
|
|
会员目标
|
|
教练排班
|
|
数据分析
|
|
会员分析
|
|
课程分析
|
|
财务分析
|
|
运营分析
|
|
系统管理
|
|
租户管理
|
|
门店管理
|
|
权限管理
|
|
系统配置
|
|
```
|
|
|
|
---
|
|
|
|
## 三、系统架构设计
|
|
|
|
### 3.1 总体架构
|
|
|
|
采用分层架构 + 微服务思想的模块化设计：
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph ClientLayer[客户端层]
|
|
A1[会员小程序<br/>uniapp+Vue3]
|
|
A2[教练端App<br/>uniapp+Vue3]
|
|
A3[管理后台PC<br/>Vue3+Vite]
|
|
A4[硬件设备<br/>人脸/NFC]
|
|
end
|
|
|
|
subgraph Gateway[API Gateway<br/>统一网关]
|
|
B1[路由转发]
|
|
B2[认证鉴权]
|
|
B3[限流熔断]
|
|
B4[日志追踪]
|
|
end
|
|
|
|
subgraph BusinessLayer[业务层]
|
|
C1[会员服务<br/>Member Service]
|
|
C2[预约服务<br/>Booking Service]
|
|
C3[数据服务<br/>Data Service]
|
|
end
|
|
|
|
subgraph CommonLayer[公共服务层]
|
|
D1[认证服务]
|
|
D2[消息服务]
|
|
D3[文件服务]
|
|
D4[缓存服务]
|
|
end
|
|
|
|
subgraph InfraLayer[基础设施层]
|
|
E1[PostgreSQL]
|
|
E2[R2DBC]
|
|
E3[Caffeine]
|
|
E4[Redis可选]
|
|
end
|
|
|
|
subgraph ExternalLayer[外部服务]
|
|
F1[微信开放平台]
|
|
F2[短信服务]
|
|
F3[支付服务]
|
|
F4[OSS存储]
|
|
end
|
|
|
|
A1 --> Gateway
|
|
A2 --> Gateway
|
|
A3 --> Gateway
|
|
A4 --> Gateway
|
|
|
|
Gateway --> C1
|
|
Gateway --> C2
|
|
Gateway --> C3
|
|
|
|
C1 --> CommonLayer
|
|
C2 --> CommonLayer
|
|
C3 --> CommonLayer
|
|
|
|
CommonLayer --> InfraLayer
|
|
CommonLayer --> ExternalLayer
|
|
```
|
|
|
|
### 3.2 技术架构
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph Presentation[表现层 Presentation]
|
|
A1[会员端 uniapp<br/>Vue3 + TS<br/>Pinia<br/>uni-ui]
|
|
A2[教练端 uniapp<br/>Vue3 + TS<br/>Pinia<br/>uni-ui]
|
|
A3[管理后台 Vue3<br/>Vue3 + TS<br/>Pinia<br/>Element Plus]
|
|
end
|
|
|
|
subgraph Gateway[网关层 Gateway]
|
|
B[Spring Cloud Gateway<br/>路由转发<br/>认证鉴权<br/>限流熔断<br/>日志追踪<br/>灰度发布]
|
|
end
|
|
|
|
subgraph Business[业务层 Business]
|
|
C[Spring Boot 3 + WebFlux + JDK 21]
|
|
C1[Controller<br/>API]
|
|
C2[Service<br/>业务逻辑]
|
|
C3[Repository<br/>数据访问]
|
|
C4[Model<br/>领域模型]
|
|
end
|
|
|
|
subgraph Data[数据层 Data]
|
|
D1[PostgreSQL<br/>R2DBC<br/>Flyway]
|
|
D2[Caffeine<br/>本地缓存<br/>热点数据]
|
|
D3[Redis可选<br/>分布式缓存<br/>分布式锁]
|
|
end
|
|
|
|
A1 --> B
|
|
A2 --> B
|
|
A3 --> B
|
|
B --> C
|
|
C --> C1
|
|
C1 --> C2
|
|
C2 --> C3
|
|
C3 --> C4
|
|
C4 --> D1
|
|
C4 --> D2
|
|
C4 --> D3
|
|
```
|
|
|
|
### 3.3 部署架构
|
|
|
|
```mermaid
|
|
graph TB
|
|
LB[负载均衡器<br/>Nginx/ALB]
|
|
|
|
subgraph GatewayInstances[API Gateway集群]
|
|
GW1[API Gateway<br/>实例1]
|
|
GW2[API Gateway<br/>实例2]
|
|
GW3[API Gateway<br/>实例N]
|
|
end
|
|
|
|
subgraph AppInstances[应用服务集群]
|
|
APP1[应用服务<br/>实例1]
|
|
APP2[应用服务<br/>实例2]
|
|
APP3[应用服务<br/>实例N]
|
|
end
|
|
|
|
subgraph DBLayer[数据库层]
|
|
PG1[PostgreSQL<br/>主库]
|
|
PG2[PostgreSQL<br/>从库1]
|
|
PG3[PostgreSQL<br/>从库N]
|
|
end
|
|
|
|
subgraph CacheLayer[缓存层]
|
|
REDIS1[Redis<br/>主节点]
|
|
REDIS2[Redis<br/>从节点1]
|
|
REDIS3[Redis<br/>从节点N]
|
|
end
|
|
|
|
LB --> GW1
|
|
LB --> GW2
|
|
LB --> GW3
|
|
|
|
GW1 --> APP1
|
|
GW2 --> APP2
|
|
GW3 --> APP3
|
|
|
|
APP1 --> PG1
|
|
APP2 --> PG1
|
|
APP3 --> PG1
|
|
|
|
PG1 -.->|主从复制| PG2
|
|
PG1 -.->|主从复制| PG3
|
|
|
|
APP1 --> REDIS1
|
|
APP2 --> REDIS1
|
|
APP3 --> REDIS1
|
|
|
|
REDIS1 -.->|主从复制| REDIS2
|
|
REDIS1 -.->|主从复制| REDIS3
|
|
```
|
|
|
|
│ └───────────────────┼───────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────┼──────────────────┐ │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
|
│ │ Application │ │ Application │ │ Application │ │
|
|
│ │ Server (Pod1) │ │ Server (Pod2) │ │ Server (PodN) │ │
|
|
│ └───────┬────────┘ └───────┬────────┘ └
|
|
|
|
```
|
|
|
|
───────┬────────┘ │
|
|
│ │ │ │ │
|
|
│ └───────────────────┼───────────────────┘ │
|
|
│ │ │
|
|
│ ┌───────────────────────────┼───────────────────────────┐ │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ PostgreSQL │ │ Redis │ │ OSS │ │
|
|
│ │ (主从复制) │ │ (哨兵模式) │ │ (对象存储) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 四、模块设计
|
|
|
|
### 4.1 模块划分
|
|
|
|
````
|
|
|
|
---
|
|
|
|
## 四、模块设计
|
|
|
|
### 4.1 模块划分
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph Parent[gym-manage-server 父工程]
|
|
subgraph Common[gym-common 公共模块]
|
|
C1[gym-common-core<br/>核心工具类、常量、枚举]
|
|
C2[gym-common-redis<br/>Redis配置可选]
|
|
C3[gym-common-security<br/>安全认证公共组件]
|
|
C4[gym-common-log<br/>日志公共组件]
|
|
end
|
|
|
|
subgraph API[gym-api API网关模块]
|
|
A1[controller<br/>HTTP接口]
|
|
A2[dto<br/>数据传输对象]
|
|
A3[vo<br/>视图对象]
|
|
A4[config<br/>API配置]
|
|
end
|
|
|
|
subgraph Service[gym-service 业务服务模块]
|
|
S1[gym-service-member<br/>会员服务]
|
|
S2[gym-service-booking<br/>预约服务]
|
|
S3[gym-service-checkin<br/>签到服务]
|
|
S4[gym-service-course<br/>课程服务]
|
|
S5[gym-service-coach<br/>教练服务]
|
|
S6[gym-service-finance<br/>财务服务]
|
|
S7[gym-service-data<br/>数据服务]
|
|
end
|
|
|
|
subgraph Domain[gym-domain 领域模型模块]
|
|
D1[model<br/>领域模型]
|
|
D2[event<br/>领域事件]
|
|
D3[service<br/>领域服务]
|
|
end
|
|
|
|
subgraph Infra[gym-infrastructure 基础设施模块]
|
|
I1[repository<br/>数据仓储]
|
|
I2[cache<br/>缓存配置]
|
|
I3[external<br/>外部服务集成]
|
|
I4[config<br/>基础配置]
|
|
end
|
|
|
|
subgraph Starter[gym-starter 启动模块]
|
|
ST[gym-admin<br/>管理后台启动器]
|
|
end
|
|
end
|
|
````
|
|
|
|
### 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 模块交互
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as 客户端
|
|
participant API as API Layer
|
|
participant Service as Service Layer
|
|
participant Domain as Domain Layer
|
|
participant Repo as Repo Layer
|
|
participant Infra as Infrastructure
|
|
|
|
Client->>API: HTTP Request
|
|
API->>Service: 调用业务逻辑
|
|
Service->>Domain: 处理领域逻辑
|
|
Domain->>Repo: 访问数据
|
|
Repo->>Infra: 访问基础设施
|
|
Infra-->>Repo: 返回结果
|
|
Repo-->>Domain: 返回数据
|
|
Domain-->>Service: 返回领域对象
|
|
Service-->>API: 返回业务结果
|
|
API-->>Client: 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 接口分组
|
|
|
|
### 5.2 接口分组
|
|
|
|
```mermaid
|
|
graph LR
|
|
subgraph Auth[认证接口 /v1/auth]
|
|
A1[POST /login<br/>登录]
|
|
A2[POST /logout<br/>登出]
|
|
A3[POST /refresh<br/>刷新Token]
|
|
A4[POST /wechat-login<br/>微信登录]
|
|
end
|
|
|
|
subgraph Members[会员接口 /v1/members]
|
|
M1[GET /<br/>会员列表]
|
|
M2[GET /{id}<br/>会员详情]
|
|
M3[POST /<br/>创建会员]
|
|
M4[PUT /{id}<br/>更新会员]
|
|
M5[GET /{id}/cards<br/>会员卡列表]
|
|
M6[GET /{id}/benefits<br/>权益列表]
|
|
M7[GET /{id}/bookings<br/>预约记录]
|
|
end
|
|
|
|
subgraph Courses[课程接口 /v1/courses]
|
|
C1[GET /<br/>课程列表]
|
|
C2[GET /{id}<br/>课程详情]
|
|
C3[POST /<br/>创建课程]
|
|
C4[PUT /{id}<br/>更新课程]
|
|
C5[GET /{id}/slots<br/>可预约时段]
|
|
end
|
|
|
|
subgraph Bookings[预约接口 /v1/bookings]
|
|
B1[GET /<br/>预约列表]
|
|
B2[GET /{id}<br/>预约详情]
|
|
B3[POST /<br/>创建预约]
|
|
B4[POST /{id}/cancel<br/>取消预约]
|
|
B5[GET /my<br/>我的预约]
|
|
end
|
|
|
|
subgraph Checkins[签到接口 /v1/checkins]
|
|
CH1[GET /<br/>签到列表]
|
|
CH2[POST /scan<br/>扫码签到]
|
|
CH3[POST /manual<br/>手动签到]
|
|
CH4[GET /my<br/>我的签到]
|
|
end
|
|
|
|
subgraph Coaches[教练接口 /v1/coaches]
|
|
CO1[GET /<br/>教练列表]
|
|
CO2[GET /{id}<br/>教练详情]
|
|
CO3[GET /{id}/schedule<br/>教练排班]
|
|
CO4[GET /{id}/slots<br/>可预约时段]
|
|
end
|
|
|
|
subgraph Dashboard[数据看板 /v1/dashboard]
|
|
D1[GET /overview<br/>今日概览]
|
|
D2[GET /trends<br/>趋势数据]
|
|
D3[GET /rankings<br/>排行数据]
|
|
end
|
|
```
|
|
|
|
### 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 | 假设冲突较多，通过锁机制控制并发 |
|
|
|
|
---
|
|
|
|
_文档结束_
|