# 健身房管理系统概要设计文档（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 总体架构 采用分层架构 + 微服务思想的模块化设计： ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 总体架构 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ 客户端层 │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ • 会员小程序 (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 请求响应格式 ```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 接口分组 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 接口分组 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ 认证接口 /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 | 假设冲突较多，通过锁机制控制并发 | --- _文档结束_