张翔
c1d7660aac
- 修复HLD-系统概要设计.md中所有ASCII图表的右侧边框对齐 - 修复LLD-签到模块详细设计.md中ASCII图表的右侧边框对齐 - 修复LLD-会员模块详细设计.md中ASCII图表的右侧边框对齐 - 修复LLD-预约模块详细设计.md中ASCII图表的右侧边框对齐 - 确保所有ASCII图表的右侧边框纵向靠右对齐
86 KiB
86 KiB
健身房管理系统概要设计文档（HLD）
文档编号: GYM-HLD-001
版本: v1.0
日期: 2026-02-28
作者: 张翔
状态: 初稿
文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|---|---|---|---|
| v1.0 | 2026-02-28 | 张翔 | 初稿 |
一、引言
1.1 编写目的
本文档为健身房管理系统的概要设计文档（High-Level Design），旨在：
- 从总体上描述系统的技术架构、模块划分、接口设计
- 为详细设计提供指导和约束
- 作为开发人员、测试人员、运维人员的技术参考
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 总体架构
采用分层架构 + 微服务思想的模块化设计：
┌─────────────────────────────────────────────────────────────────────────┐
│ 总体架构 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 客户端层 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 会员小程序 (uniapp+Vue3) │ │
│ │ • 教练端App (uniapp+Vue3) │ │
│ │ • 管理后台PC (Vue3+Vite) │ │
│ │ • 硬件设备 (人脸/NFC) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ API Gateway 统一网关 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 路由转发 • 认证鉴权 • 限流熔断 • 日志追踪 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 业务层 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 会员服务 (Member Service) │ │
│ │ • 预约服务 (Booking Service) │ │
│ │ • 数据服务 (Data Service) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 公共服务层 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 认证服务 • 消息服务 • 文件服务 • 缓存服务 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 基础设施层 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • PostgreSQL • R2DBC • Caffeine • Redis(可选) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 外部服务层 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 微信开放平台 • 短信服务 • 支付服务 • OSS存储 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
3.2 技术架构
┌─────────────────────────────────────────────────────────────────────────┐
│ 技术架构 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 表现层 Presentation │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 会员端 uniapp (Vue3 + TS + Pinia + uni-ui) │ │
│ │ • 教练端 uniapp (Vue3 + TS + Pinia + uni-ui) │ │
│ │ • 管理后台 Vue3 (Vue3 + TS + Pinia + Element Plus) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 网关层 Gateway │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ Spring Cloud Gateway (路由转发/认证鉴权/限流熔断/日志追踪/灰度发布) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 业务层 Business │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ Spring Boot 3 + WebFlux + JDK 21 │ │
│ │ • Controller (API) • Service (业务逻辑) │ │
│ │ • Repository (数据访问) • Model (领域模型) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 数据层 Data │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • PostgreSQL (R2DBC + Flyway) │ │
│ │ • Caffeine (本地缓存 + 热点数据) │ │
│ │ • Redis可选 (分布式缓存 + 分布式锁) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
3.3 部署架构
┌─────────────────────────────────────────────────────────────────────────┐
│ 部署架构 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 负载均衡器 (Nginx/ALB) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ API Gateway 集群 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • API Gateway 实例1 • API Gateway 实例2 • API Gateway 实例N │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 应用服务集群 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 应用服务 实例1 • 应用服务 实例2 • 应用服务 实例N │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┴───────────────┐ │
│ ▼ ▼ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ PostgreSQL 数据库层 │ │ Redis 缓存层 │ │
│ ├─────────────────────────┤ ├─────────────────────────┤ │
│ │ • 主库 │ │ • 主节点 │ │
│ │ • 从库1 (主从复制) │ │ • 从节点1 (主从复制) │ │
│ │ • 从库N (主从复制) │ │ • 从节点N (主从复制) │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
四、模块设计
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 模块交互
┌─────────────────────────────────────────────────────────────────────────┐
│ 模块交互流程 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 客户端 (Client) │
│ │ │
│ │ 1. HTTP Request │
│ ▼ │
│ API Layer │
│ │ │
│ │ 2. 调用业务逻辑 │
│ ▼ │
│ Service Layer │
│ │ │
│ │ 3. 处理领域逻辑 │
│ ▼ │
│ Domain Layer │
│ │ │
│ │ 4. 访问数据 │
│ ▼ │
│ Repo Layer │
│ │ │
│ │ 5. 访问基础设施 │
│ ▼ │
│ Infrastructure │
│ │ │
│ │ 6. 返回结果 │
│ ▼ │
│ Repo Layer ──────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 7. 返回数据 │ │
│ ▼ │ │
│ Domain Layer ────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ 8. 返回领域对象 │ │
│ ▼ │ │
│ Service Layer ──────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ 9. 返回业务结果 │ │
│ ▼ │ │
│ API Layer ──────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ 10. HTTP Response │ │
│ ▼ │ │
│ 客户端 (Client) ◀────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
五、接口设计
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 请求响应格式
// 统一响应格式
{
"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 接口分组
┌─────────────────────────────────────────────────────────────────────────┐
│ 接口分组 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 认证接口 /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 | 假设冲突较多，通过锁机制控制并发 |
文档结束