# 健身房管理系统概要设计文档（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[会员小程序
uniapp+Vue3]
A2[教练端App
uniapp+Vue3]
A3[管理后台PC
Vue3+Vite]
A4[硬件设备
人脸/NFC]
end
subgraph Gateway[API Gateway
统一网关]
B1[路由转发]
B2[认证鉴权]
B3[限流熔断]
B4[日志追踪]
end
subgraph BusinessLayer[业务层]
C1[会员服务
Member Service]
C2[预约服务
Booking Service]
C3[数据服务
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
Vue3 + TS
Pinia
uni-ui]
A2[教练端 uniapp
Vue3 + TS
Pinia
uni-ui]
A3[管理后台 Vue3
Vue3 + TS
Pinia
Element Plus]
end
subgraph Gateway[网关层 Gateway]
B[Spring Cloud Gateway
路由转发
认证鉴权
限流熔断
日志追踪
灰度发布]
end
subgraph Business[业务层 Business]
C[Spring Boot 3 + WebFlux + JDK 21]
C1[Controller
API]
C2[Service
业务逻辑]
C3[Repository
数据访问]
C4[Model
领域模型]
end
subgraph Data[数据层 Data]
D1[PostgreSQL
R2DBC
Flyway]
D2[Caffeine
本地缓存
热点数据]
D3[Redis可选
分布式缓存
分布式锁]
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[负载均衡器
Nginx/ALB]
subgraph GatewayInstances[API Gateway集群]
GW1[API Gateway
实例1]
GW2[API Gateway
实例2]
GW3[API Gateway
实例N]
end
subgraph AppInstances[应用服务集群]
APP1[应用服务
实例1]
APP2[应用服务
实例2]
APP3[应用服务
实例N]
end
subgraph DBLayer[数据库层]
PG1[PostgreSQL
主库]
PG2[PostgreSQL
从库1]
PG3[PostgreSQL
从库N]
end
subgraph CacheLayer[缓存层]
REDIS1[Redis
主节点]
REDIS2[Redis
从节点1]
REDIS3[Redis
从节点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
核心工具类、常量、枚举]
C2[gym-common-redis
Redis配置可选]
C3[gym-common-security
安全认证公共组件]
C4[gym-common-log
日志公共组件]
end
subgraph API[gym-api API网关模块]
A1[controller
HTTP接口]
A2[dto
数据传输对象]
A3[vo
视图对象]
A4[config
API配置]
end
subgraph Service[gym-service 业务服务模块]
S1[gym-service-member
会员服务]
S2[gym-service-booking
预约服务]
S3[gym-service-checkin
签到服务]
S4[gym-service-course
课程服务]
S5[gym-service-coach
教练服务]
S6[gym-service-finance
财务服务]
S7[gym-service-data
数据服务]
end
subgraph Domain[gym-domain 领域模型模块]
D1[model
领域模型]
D2[event
领域事件]
D3[service
领域服务]
end
subgraph Infra[gym-infrastructure 基础设施模块]
I1[repository
数据仓储]
I2[cache
缓存配置]
I3[external
外部服务集成]
I4[config
基础配置]
end
subgraph Starter[gym-starter 启动模块]
ST[gym-admin
管理后台启动器]
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
登录]
A2[POST /logout
登出]
A3[POST /refresh
刷新Token]
A4[POST /wechat-login
微信登录]
end
subgraph Members[会员接口 /v1/members]
M1[GET /
会员列表]
M2[GET /{id}
会员详情]
M3[POST /
创建会员]
M4[PUT /{id}
更新会员]
M5[GET /{id}/cards
会员卡列表]
M6[GET /{id}/benefits
权益列表]
M7[GET /{id}/bookings
预约记录]
end
subgraph Courses[课程接口 /v1/courses]
C1[GET /
课程列表]
C2[GET /{id}
课程详情]
C3[POST /
创建课程]
C4[PUT /{id}
更新课程]
C5[GET /{id}/slots
可预约时段]
end
subgraph Bookings[预约接口 /v1/bookings]
B1[GET /
预约列表]
B2[GET /{id}
预约详情]
B3[POST /
创建预约]
B4[POST /{id}/cancel
取消预约]
B5[GET /my
我的预约]
end
subgraph Checkins[签到接口 /v1/checkins]
CH1[GET /
签到列表]
CH2[POST /scan
扫码签到]
CH3[POST /manual
手动签到]
CH4[GET /my
我的签到]
end
subgraph Coaches[教练接口 /v1/coaches]
CO1[GET /
教练列表]
CO2[GET /{id}
教练详情]
CO3[GET /{id}/schedule
教练排班]
CO4[GET /{id}/slots
可预约时段]
end
subgraph Dashboard[数据看板 /v1/dashboard]
D1[GET /overview
今日概览]
D2[GET /trends
趋势数据]
D3[GET /rankings
排行数据]
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 | 假设冲突较多，通过锁机制控制并发 |
---
_文档结束_