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