一个功能完善的学习空间预约管理系统，支持多类型空间分类、灵活预约模式、自动签退/缺席检测和实时通知
本系统是一个基于 Spring Boot + Vue 3 的现代化学习空间预约管理平台，专为高校、图书馆、自习室等场景设计。系统支持三种角色（管理员、工作人员、学生），提供完整的空间分类管理、预约与审批、签到签退、评价反馈、违约管控、数据统计分析、消息通知等功能。
- 🗂️ 空间分类体系 - 支持自定义空间分类（静音自习区、研讨室、小组活动室等），每种分类可独立配置是否需要座位、是否需要审批、容量限制及时间模式
- 🪑 可视化座位布局 - 提供可视化座位编辑器，支持自定义行列布局、拖拽式操作，实时展示座位占用状态
- ⏰ 双重时间模式 - 支持固定时段模式（上午/下午/晚上）与自由时间模式，按分类灵活切换
- 🔄 完整预约生命周期 - 待审批 → 已批准/待签到 → 已签到 → 已完成/缺席/违规，支持自动签退与缺席检测
- 🐇 RabbitMQ 延迟队列 - 基于延迟消息交换机实现预约到期自动签退、超时未签到自动标记缺席，配有死信队列保障消息可靠性
- 🔔 实时消息通知 - 基于 WebSocket 实时推送，支持预约状态变更、签到提醒、违约警告、公告发布、反馈回复等多种通知类型
- ⚖️ 预约规则引擎 - 可配置每日最大预约次数、单次最大时长、提前预约天数、签到时间窗口、月度违约上限等规则
- ⭐ 评价系统 - 支持多维度评分（环境/设施/服务）、图片上传、匿名评价、工作人员回复
- 💬 反馈工单 - 分类反馈（建议/投诉/设施问题/环境问题/服务建议），支持图片附件、工单状态跟踪
- 📊 可视化数据看板 - ECharts 图表展示空间使用率、热门时段、用户排行榜、预约趋势等统计数据
- 📤 Excel 数据导出 - 支持预约记录、用户数据、统计报表等 Excel 导出
- 🛡️ 安全体系 - JWT 无状态鉴权 + 自定义
@RequireRole角色注解 +@Sensitive敏感信息自动脱敏 + 图形验证码 - 📱 响应式设计 - 完美适配桌面端和移动端，随时随地预约
（在此处添加项目运行截图，例如首页、预约界面、后台管理界面等）
| 技术 | 版本 | 说明 |
|---|---|---|
| Java | 17 | 核心开发语言 |
| Spring Boot | 2.7.18 | 核心应用框架 |
| MyBatis Plus | 3.5.15 | ORM 框架，简化 CRUD 操作 |
| MySQL | 8.0+ | 关系型数据库 |
| Druid | 1.2.23 | 高性能数据库连接池，内置 SQL 防火墙 |
| JWT (jjwt) | 0.9.1 | 用户认证与无状态授权 |
| WebSocket | - | 实时双向通信（消息通知推送） |
| RabbitMQ | - | 延迟消息队列（自动签退/缺席检测） |
| Apache POI | 5.4.0 | Excel 数据导出 |
| SpringDoc OpenAPI | 1.7.0 | Swagger API 文档自动生成 |
| Hutool | 5.8.26 | Java 工具类库 |
| Fastjson | 2.0.25 | JSON 序列化/反序列化 |
| Commons Lang3 | 3.18.0 | Apache 通用工具库 |
| Lombok | - | 简化 Java 代码 |
| Jackson JSR310 | - | Java 8+ 时间类型序列化支持 |
| 技术 | 版本 | 说明 |
|---|---|---|
| Vue | 3.5.27 | 渐进式 JavaScript 框架 |
| Vue Router | 5.0.2 | 路由管理 |
| Pinia | 3.0.4 | 下一代状态管理库 |
| Element Plus | 2.13.2 | 基于 Vue 3 的 UI 组件库 |
| Axios | 1.6.0 | HTTP 客户端 |
| ECharts | 6.0.0 | 强大的数据可视化库 |
| Vite | 7.3.1 | 极速构建工具 |
| Sass | 1.97.3 | CSS 预处理器 |
| heic2any | 0.0.4 | HEIC/HEIF 图片格式转换 |
| 模块 | 说明 |
|---|---|
| 数据看板 | 系统概览、空间使用率、预约趋势、用户排行等可视化统计 |
| 空间分类管理 | 创建/编辑空间分类，配置是否需要座位、审批、容量限制及时间模式 |
| 学习空间管理 | 空间 CRUD、设施配置、时段设置、图片管理 |
| 座位布局编辑 | 可视化座位编辑器，自定义行列布局 |
| 用户管理 | 用户列表、批量启用/禁用、密码重置、角色管理 |
| 预约管理 | 查看所有预约记录 |
| 公告管理 | 发布/编辑/删除公告，支持图片附件和置顶 |
| 反馈管理 | 查看/处理用户反馈工单 |
| 评价管理 | 查看/管理用户评价，隐藏不当评价 |
| 预约规则管理 | 配置预约规则（次数限制、时长限制、签到窗口、违约上限等） |
| 通知消息 | 查看系统通知 |
| 模块 | 说明 |
|---|---|
| 工作首页 | 待办事项、今日预约概览 |
| 空间列表 | 查看负责的学习空间信息 |
| 预约审批 | 审批学生预约申请（通过/拒绝） |
| 统计分析 | 空间使用统计、预约数据分析 |
| 公告管理 | 发布/管理公告 |
| 评价查看 | 查看空间评价、回复评价 |
| 意见反馈 | 处理用户反馈工单 |
| 通知消息 | 查看通知（含新预约待审批提醒） |
| 模块 | 说明 |
|---|---|
| 学生首页 | 今日预约、快捷入口、公告展示 |
| 学习空间列表 | 浏览空间、筛选分类、查看评分和实时占用情况 |
| 座位选座 | 可视化座位布局，实时查看座位状态，选座预约 |
| 我的预约 | 预约列表、签到、签退、取消预约 |
| 我的评价 | 对已完成的预约进行多维度评价，支持图片和匿名 |
| 公告通知 | 查看系统公告 |
| 意见反馈 | 提交反馈（建议/投诉/设施问题等），查看处理进度 |
| 通知消息 | 实时接收预约状态变更、签到提醒、违约警告等通知 |
| 个人中心 | 个人信息管理、头像上传、密码修改 |
| 模块 | 说明 |
|---|---|
| 登录 | 用户名密码 + 图形验证码登录 |
| 注册 | 学生自助注册 |
| 404 页面 | 友好的未找到页面提示 |
确保您的开发环境已安装以下软件：
- JDK: 17 或更高版本
- Maven: 3.6+
- MySQL: 8.0+
- Node.js: 16+ (推荐 LTS 版本)
- RabbitMQ: 3.8+（需安装
rabbitmq_delayed_message_exchange插件）
- 创建数据库:
CREATE DATABASE str_reservation DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
- 导入脚本:
按顺序执行
src/main/resources/database/目录下的 SQL 脚本：str_reservation.sql- 核心表结构与基础数据study_room.sql- 学习空间数据sys_user.sql- 用户数据reservation.sql- 预约数据evaluation.sql- 评价数据
- 配置连接:
修改
src/main/resources/application-dev.yml中的数据库配置：spring: datasource: url: jdbc:mysql://localhost:3306/str_reservation?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true username: root # 替换为您的数据库账号 password: 123456 # 替换为您的数据库密码
系统使用 RabbitMQ 延迟消息交换机实现预约自动签退和缺席检测。
- 安装并启动 RabbitMQ 服务
- 安装延迟消息插件：
rabbitmq-plugins enable rabbitmq_delayed_message_exchange - 默认连接配置（
application-dev.yml）：spring: rabbitmq: host: localhost port: 5672 username: guest password: guest
- 使用 IDE: 用 IntelliJ IDEA 打开项目，等待依赖下载完成，运行
StrReservationApplication主类。 - 使用命令行:
mvn clean package -DskipTests java -jar target/str-reservation-0.0.1-SNAPSHOT.jar
- 服务检查:
- API 服务端口:
8080，上下文路径:/api - Swagger 文档:
http://localhost:8080/api/swagger-ui/index.html
- API 服务端口:
cd frontend
npm install # 安装依赖
npm run dev # 启动开发服务器- 访问地址:
http://localhost:3000
初始化 SQL 脚本中包含以下默认账号（默认密码均为 123456）：
| 角色 | 用户名 | 密码 | 权限说明 |
|---|---|---|---|
| 管理员 | admin |
123456 |
系统拥有者，具备所有权限 |
| 工作人员 | staff1 |
123456 |
负责审核预约、管理现场 |
| 学生 | student1 |
123456 |
进行空间预约、签到等操作 |
新增用户和密码重置后的默认密码也是
123456。
str-reservation/
├── frontend/ # Vue 3 前端工程
│ ├── src/
│ │ ├── api/ # 13 个接口模块：按业务域封装 HTTP 请求
│ │ ├── views/
│ │ │ ├── admin/ # 管理端页面（14）
│ │ │ ├── staff/ # 工作人员页面（10）
│ │ │ ├── student/ # 学生端页面（11）
│ │ │ └── common/ # 公共页面（3，登录/注册/404）
│ │ ├── components/ # 通用组件（弹窗、通知、卡片、动画数字等）
│ │ ├── composables/ # 组合式逻辑复用（通知订阅等）
│ │ ├── router/ # 路由入口与鉴权治理
│ │ │ ├── index.js # 路由实例入口（仅装配）
│ │ │ ├── routes/ # 分角色路由表（admin/staff/student/common）
│ │ │ └── guards/ # 路由守卫（登录态/角色权限/标题）
│ │ ├── store/ # Pinia 状态管理
│ │ ├── utils/ # 工具层（按职责拆分）
│ │ │ ├── request.js # HTTP 实例与拦截器（不承载下载）
│ │ │ ├── download.js # 文件下载能力（含鉴权与异常提示）
│ │ │ ├── echarts.js # ECharts 按需注册入口
│ │ │ ├── websocket.js # WebSocket 单例与重连策略
│ │ │ ├── auth.js # 认证信息读写（token/userInfo）
│ │ │ ├── upload.js # 上传与格式转换（含 HEIC）
│ │ │ ├── date.js # 日期格式与时间计算
│ │ │ ├── textFormatter.js # 展示文本格式化
│ │ │ └── constants.js # 业务枚举与映射常量
│ │ ├── styles/ # 全局样式与设计系统样式
│ │ └── assets/ # 静态资源（图片、局部样式）
│ ├── public/
│ ├── index.html
│ ├── vite.config.js
│ └── package.json
│
├── src/main/java/com/strreservation/ # Spring Boot 后端主代码
│ ├── StrReservationApplication.java # 应用启动入口
│ ├── controller/ # 接口层（15 个 Controller）：参数接收/鉴权注解/响应包装
│ ├── service/ # 业务接口层：定义业务能力边界
│ │ ├── impl/ # 业务实现层：事务、编排、规则执行
│ │ └── statistics/ # 统计子域接口与实现（排行榜、空间利用率等）
│ ├── dao/ # 数据访问层
│ │ ├── entity/ # 15 个实体：仅映射表结构与持久化字段
│ │ └── mapper/ # 15 个 Mapper：SQL 访问与联表查询映射
│ ├── dto/ # 数据传输模型
│ │ ├── req/ # 12 个请求 DTO：入参模型与校验承载
│ │ ├── resp/ # 14 个响应 VO：出参模型与聚合视图
│ │ └── mq/ # 3 个消息 DTO：RabbitMQ 生产/消费载荷
│ ├── common/ # 跨模块公共能力
│ │ ├── constant/ # 全局常量定义
│ │ ├── convention/ # 通用规范能力
│ │ │ ├── annotation/ # 约定注解（如角色校验注解）
│ │ │ ├── enums/ # 通用枚举（结果码等）
│ │ │ ├── exception/ # 业务异常与全局异常处理
│ │ │ ├── filter/ # 请求过滤器（如 XSS 过滤）
│ │ │ ├── result/ # 统一返回模型（Result/PageResult）
│ │ │ ├── serialize/ # 脱敏序列化注解与序列化器
│ │ │ └── web/ # Web 拦截器（JWT/权限/脱敏）
│ │ ├── database/ # 数据库框架扩展（自动填充处理等）
│ │ └── store/ # 进程内共享存储（如导出任务状态）
│ ├── config/ # 基础设施配置（MyBatis、RabbitMQ、WebSocket、OpenAPI 等）
│ ├── task/ # 定时任务与后台清理任务
│ ├── toolkit/ # 业务无关工具类（JWT、Excel、上传、上下文、加密）
│ └── websocket/ # WebSocket 服务端与握手配置
│
├── src/main/resources/
│ ├── application.yml # 公共配置
│ ├── application-dev.yml # 开发环境配置
│ ├── application-prod.yml # 生产环境配置
│ ├── database/ # 数据库初始化 SQL
│ └── mapper/ # MyBatis XML（与 dao/mapper 一一对应）
│
├── frontend/README.md # 前端开发说明
├── HELP.md # 部署/排障补充文档
├── upload/ # 上传文件目录（头像、评价图、反馈图、导出文件等）
├── logs/ # 运行日志目录
└── pom.xml # Maven 依赖与构建配置
controller：只做请求接入、鉴权注解、参数转换、统一响应包装，不直接写 SQL、不承载复杂业务。service：定义业务语义与能力边界；impl中完成事务控制、规则判断、流程编排。dao/entity：只维护数据库字段映射，避免依赖dto.resp这类上层表示模型。dao/mapper：负责数据访问；可直接返回联表查询需要的 VO，减少服务层重复装配与 N+1 查询。dto/req：面向输入；dto/resp：面向输出；dto/mq：面向异步消息，不与 HTTP 请求 DTO 混用。common/convention：沉淀可复用技术规范能力（异常、结果、过滤、拦截、序列化），避免散落到业务目录。toolkit：存放无业务状态、可复用工具函数；若涉及业务语义应进入 service 或 common 子域。task：仅放定时/后台作业；任务中的业务逻辑优先下沉到 service，任务只做触发与调度。
router/index：只做路由装配，不放具体路由明细与守卫实现。router/routes：按角色拆分路由定义，新增页面时仅改对应角色文件，降低冲突。router/guards：统一鉴权、角色跳转、页面标题规则，避免散落在页面组件中。utils/request：仅处理请求实例与拦截器；下载等特殊 IO 逻辑下沉到独立工具。utils/download：封装文件下载和下载态异常处理，避免在页面重复实现。utils/echarts：集中维护图表按需注册清单，避免页面直接全量引入 ECharts。store：聚焦状态管理；本地持久化读写优先复用utils/auth，避免双写。
- 后端：Controller 15，Entity 15，Mapper 15，DTO(req/resp/mq) = 12/14/3。
- 前端：API 模块 13，管理端页面 14，工作人员页面 10，学生端页面 11，公共页面 3。
系统采用 Spring Profiles 多环境配置方案：
application.yml- 通用配置（Tomcat 线程池优化、Druid 连接池、MyBatis Plus、JWT 等）application-dev.yml- 开发环境（本地数据库、调试日志、热重启）application-prod.yml- 生产环境（生产数据库、文件路径、日志级别）
切换环境：
java -jar str-reservation-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod延迟交换机 (x-delayed-message)
├── 签退队列 (reservation.checkout.queue) → 预约到期自动签退
│ └── 签退死信队列 (reservation.checkout.dlq) → 消费失败兜底
└── 缺席队列 (reservation.absence.queue) → 超时未签到标记缺席
└── 缺席死信队列 (reservation.absence.dlq) → 消费失败兜底
系统内置丰富的通知模板，覆盖以下场景：
- 预约通知 - 审批通过/拒绝、开始提醒、签到提醒、完成通知、缺席通知
- 违约警告 - 违约次数提醒、月度上限警告、当日违约提醒
- 公告通知 - 新公告发布、紧急公告
- 反馈通知 - 反馈回复、反馈处理完成
- 系统通知 - 维护通知、版本更新、欢迎消息、账号安全提醒
详细开发指南与问题排查请参阅 HELP.md。
Q: 启动前端时提示 'vite' 不是内部或外部命令？
A: 请确保在 frontend 目录下执行 npm install，或者全局安装 vite (npm install -g vite)。
Q: 登录时提示"网络错误"？
A: 请检查后端服务是否已在 8080 端口启动。如果是跨域问题，请检查前端 vite.config.js 的 proxy 配置。
Q: 验证码显示红叉？
A: 这通常是由于服务器缺少字体库导致的。请参考 HELP.md 中的解决方案安装 fontconfig。
Q: RabbitMQ 连接失败？
A: 请确保 RabbitMQ 服务已启动，并已安装 rabbitmq_delayed_message_exchange 插件。检查 application-dev.yml 中的连接配置是否正确。
Q: 文件上传失败（413 Payload Too Large）？
A: 系统默认限制单文件 15MB、请求总大小 80MB。如需调整，修改 application.yml 中的 spring.servlet.multipart 配置，生产环境还需调整 Nginx 的 client_max_body_size。
Happy Coding! 🚀