1. 项目概述与需求分析
1.1 这个系统能解决什么问题
学生宿舍管理系统，听名字就知道是干什么的：管宿舍、管学生、管入住、管报修。但我见过太多学校的宿舍管理还在用Excel表格加微信群的方式，学生报修靠接龙，查个宿舍信息要翻半天聊天记录，月底统计入住率更是噩梦。这套SpringBoot后端+Vue前端+MySQL的系统，说白了就是把宿舍管理的日常操作全部搬到线上，做成一个B/S架构的Web应用。
项目标题里写了【可直接运行】，说明作者的定位很明确——不是让你从头造轮子，而是拿一套完整可跑的代码去学习、去改造、去落地。适合三类人：一是计算机专业的学生，拿来做毕业设计或课程设计，代码结构清晰，方便二次开发；二是刚学完SpringBoot和Vue、想找个全栈项目练手的开发者，可以从这套代码里学到前后端怎么配合、接口怎么设计、权限怎么控制；三是学校或企业的信息化管理人员，想了解一个完整的管理系统该具备哪些模块，用来做需求预研或供应商评估。
1.2 技术栈选型背后的理由
这个项目选了SpringBoot + Vue + MySQL三件套，非常典型，也非常务实。SpringBoot是目前Java后端开发的事实标准，简化了配置，内嵌Tomcat，一键启动，你不用像以前用SSH框架那样写一堆XML。Vue作为前端框架，组件化开发让页面逻辑清晰，配合Element UI这样的组件库，能快速做出像样的管理后台界面。MySQL则是最常用的开源关系型数据库，免费、稳定、资料多，学生和中小企业首选。
我接触过不少类似的毕设项目，有的用JSP + Servlet，有的用PHP，但体验和可维护性确实差一截。SpringBoot + Vue这套组合的生态太成熟了，遇到问题搜一下解决方案基本都是现成的。而且前后端分离的模式也是目前企业开发的标配，学这一套东西，往后找工作面试也能用到。
2. 后端核心设计与业务模块拆解
2.1 SpringBoot工程结构与分层
这套项目的后端采用经典的三层架构：Controller、Service、Mapper（或者叫Repository）。Controller负责接收前端请求、参数校验、返回结果；Service写业务逻辑；Mapper层做数据库操作。三层分开的好处是职责明确、便于维护，如果以后要改业务规则，只需要动Service层，不用动接口。
代码里会看到一些基础包结构：config放配置类，比如跨域配置、MyBatis-Plus分页配置；entity（或pojo/domain）放数据库实体类；dto放数据传输对象，比如登录时接收用户名密码、注册时接收学生信息；vo放返回给前端的视图对象；common（或util）放统一返回结果类、异常处理类、工具类。
这里有个很值得学习的点：统一返回结果。项目里通常会定义一个Result类，里面包含code（状态码）、msg（提示信息）、data（数据）三个字段。前端拿到响应后，先判断code是否为200，再做后续操作。这样做的好处是，前后端接口联调时有统一的规范，不至于一个接口返回一个样。
2.2 核心业务模块梳理
一个完整的宿舍管理系统，通常包含以下模块：
第一是登录认证模块。系统里至少有三种角色：管理员、宿管员、学生。管理员能管所有东西，宿管员管理自己负责的楼栋，学生只能看自己的宿舍和报修记录。所以在设计接口时，需要做权限控制，比如学生角色的请求不能访问管理员接口。
第二是基础信息管理。包括宿舍楼栋管理（楼栋号、楼层数、每层房间数、宿舍类型）、宿舍房间管理（房间号、可住人数、已住人数、是否满员）、学生信息管理（学号、姓名、院系、班级、联系方式、辅导员）。
第三是入住与退宿管理。学生入住时，要选择一个宿舍房间，系统自动更新该房间的已住人数；退宿时，释放床位。这里有一个关键逻辑：一个学生同时只能有一条有效的入住记录。为了避免数据混乱，代码里通常会在业务层查一下该学生是否已有未退宿的记录，如果有则提示“该学生已入住”。
第四是调宿管理。学生从一个房间调到另一个房间，系统需要同时处理原房间和新房间的人数变更。如果两个房间属于同一楼栋还好，如果跨楼栋，还得考虑宿管员权限问题。
第五是报修管理。学生提交报修工单（比如灯坏了、水管漏水），填写位置和描述，管理员或宿管员查看工单，派工处理，完成后标记为“已处理”。这个模块虽然简单，但涉及状态的流转：待处理、处理中、已完成。
第六是考勤/归寝管理。这个是宿舍管理的常见需求，学生晚归或不归的记录。实际项目里有的会用刷卡或人脸识别设备对接，毕设项目通常就是手动记录或学生自助提交。
第七是公告管理。管理员发布宿舍通知，比如停水停电时间、安全检查通知，学生端能看到。
还有一个容易被忽略的是数据统计。管理员首页通常要展示一些统计图表：宿舍总数、入住总人数、入住率、男女占比、各楼栋入住率等。这些数据不需要额外表，通过SQL的group by就能统计出来。
2.3 关键技术点：登录鉴权与权限控制
这个项目的登录鉴权方案，常见的有两种：一种是基于Session + Interceptor（拦截器），另一种是基于JWT + Token。老一点的项目用Session的比较多，新的项目一般用JWT。
JWT方案的流程是：用户登录成功后，后端生成一个Token返回给前端，前端存在localStorage里，每次发请求时通过请求头（通常是Authorization）带上Token，后端在拦截器里校验Token是否合法、是否过期，并取出用户信息放到当前请求上下文中。
权限控制我建议用基于角色的访问控制（RBAC），数据库中设计用户表、角色表、权限表，以及用户-角色、角色-权限关联表。不过对于毕设或中小型项目，做一个简化版就够了：用户表加一个role字段，值为admin、dorm、student三个枚举值之一，后端拦截器判断请求路径前缀和用户角色是否匹配。比如/admin/**开头的路径只能由管理员访问，/student/**只能由学生访问。这样实现简单，也够用。
3. 数据库表结构设计详解
3.1 核心表的设计思路
MySQL部分是这个项目的地基，表结构设计直接决定业务逻辑是否顺畅、SQL是否高效。我的建议是设计时要想清楚表与表之间的关系，千万别做出一堆冗余字段，也别贪多做一些用不上的表。
用户表（t_user）：存储所有登录账号。字段至少要有id、username、password（MD5或BCrypt加密存储）、role（角色）、user_info_id（关联具体用户信息，如学生表）、status（是否启用）、create_time。
学生信息表（t_student）：id、student_no（学号）、name（姓名）、gender（性别）、college（院系）、class_name（班级）、phone（联系方式）、user_id（关联用户表）。
宿舍楼栋表（t_building）：id、building_no（楼栋号，比如"1栋""A栋"）、name、floors（楼层总数）、rooms_per_floor、manager（宿管员姓名）、manager_phone。
宿舍房间表（t_dormitory）：id、building_id（关联楼栋）、room_no（房间号）、type（比如4人间、6人间）、capacity（容纳人数）、current_people（当前已住人数）、status（如启用/停用）。宿舍房间与楼栋是多对一关系。判断一个房间是否可住，就用current_people < capacity。
入住记录表（t_record）：id、student_id、dormitory_id、check_in_time（入住时间）、check_out_time（退宿时间，默认空）、status（在住/已退宿、调宿时原记录调宿状态）。这是最重要的业务表，能查出每个学生的住宿历史，也能统计当前在住人数。
报修表（t_repair）：id、student_id（报修人）、content（报修内容）、location（位置）、status（待处理/处理中/已完成）、create_time、handle_time（处理完成时间）、handler_name。
公告表（t_notice）：id、title、content、create_time、user_id（发布人）、is_top（是否置顶）。
像t_user与t_student为什么要分开建表？因为管理员和宿管员不需要学生信息，他们也有自己的登录账号。如果强行把登录账号和学生信息放在一张表里，会导致大量字段对管理员来说是空着的，不优雅也不好扩展。
3.2 关键SQL与索引设计
宿舍入住统计是最常见的高频查询。比如要统计当前所有楼栋的入住率，可以这样写：
SELECT b.id AS building_id, b.name AS building_name, SUM(d.capacity) AS total_beds, SUM(d.current_people) AS used_beds, ROUND(SUM(d.current_people) / SUM(d.capacity) * 100, 2) AS occupancy_rate FROM t_building b LEFT JOIN t_dormitory d ON d.building_id = b.id GROUP BY b.id, b.name ORDER BY b.id;这里用LEFT JOIN保证了即使某栋楼没有房间，也能在统计结果里以0的形式出现，而不是把该楼栋整行丢弃。ROUND(..., 2)保留两位小数，前端展示时好看一些。
要给高频率查询字段建立索引。比如t_record.student_id用于查询某学生的住宿记录，t_record.status用于筛选在住人员，t_repair.status用于统计各种状态的工单数，这些都是索引的好位置。MySQL主键默认就是聚簇索引，不需要额外处理。对于联合索引，比如t_dormitory(building_id, room_no)，因为查询某个楼栋下的房间很频繁，用联合索引能让过滤条件更精确。
事务在这个项目里也派得上用场。比如调宿这个操作：把学生在原宿舍的记录标记为调出，再插入一条新宿舍的入住记录，同时更新原房间的current_people减1、新房间的current_people加1。这几步必须保证“要么全部成功，要么全部失败”，所以要在Service方法上标注@Transactional(rollbackFor = Exception.class)。如果不加事务，中途某一步抛异常，数据就可能变成“学生两边都没住”或者“两边都显示在住”，非常难排查。
4. 前端核心实现与前后端联调
4.1 Vue工程结构与页面规划
Vue前端用Vue 3 + Vite脚手架更现代，也可以用Vue 2 + Webpack，要看作者怎么选。不管用哪个版本，核心思路是差不多的。Vue项目里面通常有一个核心目录结构：src/views放页面组件，src/router放路由配置，src/store（如果是Pinia或Vuex）放全局状态，src/api放接口请求封装，src/utils放工具函数。
页面规划方面，登录页是第一个要做的；然后是管理员端的首页（仪表盘）、宿舍管理页、学生管理页、入住退宿页、调宿页、报修管理页、公告管理页；学生端的首页和报修提交页。
管理后台的布局，跨时代的那一套：左侧菜单栏加右侧内容区，顶部一个导航栏，展示系统名称、当前用户、退出按钮。左侧菜单根据角色动态渲染，管理员看到完整菜单，学生只看到自己的功能入口。这样权限在功能入口层面就能做到第一道隔离。
4.2 Axios封装与接口对接
前后端分离的项目，前端所有的HTTP请求都要通过Axios发出去。直接在每个页面里写axios调用，代码会很碎、重复率高、不好维护。正确做法是封装一个统一的request工具：
import axios from 'axios'; import { message } from 'ant-design-vue'; import router from '@/router'; const request = axios.create({ baseURL: '/api', timeout: 10000 }); request.interceptors.request.use(config => { const token = localStorage.getItem('token'); if (token) { config.headers.Authorization = token; } return config; }); request.interceptors.response.use( response => { const res = response.data; if (res.code === 200) { return res; } message.error(res.msg || '请求失败'); return Promise.reject(new Error(res.msg || '请求失败')); }, error => { if (error.response && error.response.status === 401) { message.error('登录已过期，请重新登录'); localStorage.removeItem('token'); router.push('/login'); } else { message.error('网络异常，请稍后重试'); } return Promise.reject(error); } ); export default request;这个封装做到了三件事：自动附带Token、统一处理响应体、全局拦截401跳登录页。页面里只用关心拿到的数据，不用每次判断状态码。另一个重要的点是baseURL: '/api'配合Vite的代理配置，避免在开发环境出现跨域问题。
在vite.config.js里这样配：
server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }这样开发时请求/api/login就会代理到后端http://localhost:8080/login，浏览器不直接跨域。生产环境则用Nginx做反向代理，把前端静态文件放到Nginx，同时配置location /api { proxy_pass http://后端地址; }。
4.3 权限路由与动态菜单
前端动态菜单是个常见考题。后端登录接口可以返回当前用户的角色信息和拥有权限的菜单列表，前端拿到后动态注册路由。但这里有个小坑：不要完全依赖前端控制权限，前端只是隐藏入口，真正安全校验还是后端拦截器，不然别人直接拼URL也能访问到接口。
简单做法是：路由表里写静态路由和需要动态注册的路由，登录成功后根据角色过滤出可访问的菜单。Pedestrian的做法是写死三种角色的菜单，比如：
const roleMenus = { admin: [ { path: '/dashboard', title: '首页' }, { path: '/student', title: '学生管理' }, { path: '/dormitory', title: '宿舍管理' }, { path: '/record', title: '入住退宿' }, { path: '/repair', title: '报修管理' } ], student: [ { path: '/student-dashboard', title: '我的宿舍' }, { path: '/student-repair', title: '我要报修' } ] };然后根据当前用户的角色，把对应菜单渲染到侧边栏。后端接口返回的role字段就是这里判断的依据。
5. 本地快速部署与运行指南
5.1 环境准备与配置清单
要让这套系统跑起来，本地环境需要准备以下工具：
- JDK 8或11（SpringBoot 2.x用8最稳，SpringBoot 3.x需要17）
- Maven 3.6+（用来编译打包后端）
- MySQL 5.7或8.0（建议8.0，字段限制更宽松，字符集用utf8mb4）
- Node.js 14+（Vue项目打包和运行需要）
- 一个趁手的IDE，后端用IntelliJ IDEA或Eclipse，前端用VSCode
基础环境装好后，做三步初始化：
第一步，在MySQL里创建数据库，比如叫dormitory_system，执行项目里提供的sql目录下的初始化脚本，导入表结构和基础数据。基础数据里通常包含几个测试账号，比如管理员账号、宿管员账号、学生账号，密码一般是经过MD5或BCrypt加密的。如果导入后发现密码不对，可以用注册接口重新注册再测试，或者用后端的工具类手动生成加密密码更新到数据库里。
第二步，修改后端application.yml或application.properties里的数据库连接信息：url、username、password。注意server.servlet.context-path这个配置，如果设置了前缀（比如/dorm），那前端的代理也要对应修改。
第三步，前端需要修改环境变量文件.env.development里的API地址，还有Vite的代理目标地址要指向后端启动的端口。
5.2 启动步骤与验证清单
后端启动很简单：用IDE打开项目，等待Maven下载依赖（第一次会比较慢），然后运行DormitoryApplication主类。看到控制台输出“Started DormitoryApplication in x.xxx seconds”就代表启动成功。
前端启动需要在项目根目录下执行：
npm install npm run devnpm install安装依赖，如果网速慢或版本冲突，可以换用淘宝镜像源。启动后浏览器访问http://localhost:5173（Vite默认端口），看到登录页就说明一切正常。
验证系统功能时，按这个顺序走一遍：先用管理员账号登录，进学生管理页面添加一个新学生；再到宿舍管理页面确认房间状态；然后给新学生办理入住，看房间的已住人数是否加1；用学生账号登录，提交一条报修工单；再切回管理员账号，处理这条报修。如果每个环节的数据变化都符合预期，说明核心流程是通的。
6. 常见问题与排查技巧实录
6.1 数据库连接与启动类的坑
数据库相关的报错是遇到频率最高的。常见报错之一是Access denied for user 'root'@'localhost'，原因基本是密码配错或指定的账号没有远程访问权限。排查方法很简单：先在Navicat或命令行里用同样的账号密码试着连一下数据库，连不上的话，问题在账号密码本身，跟代码无关。
另一个高频报错是Unknown database 'dormitory_system'，说明数据库没有创建或者名字写错了。执行语句CREATE DATABASE dormitory_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;就能解决。
还有MySQL连接串时区报错也经常出现。SpringBoot连接MySQL 8.x时，url里最好加上这些参数：
url: jdbc:mysql://localhost:3306/dormitory_system?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=trueserverTimezone=Asia/Shanghai解决时区问题，useSSL=false避免SSL握手警告。这条配置我每次都直接复制，印象深刻。
6.2 前端跨域、Token失效与打包部署问题
前端明明通过代理配置了，但还是报跨域请求错误（浏览器控制台提示CORS），这种情况最先看一眼代理是否指向了正确的后端端口。有时后端前端同时改了端口，代理配置忘了同步，请求打到别的地方去了。还有一种可能是后端有自己独立的CORS配置，二者冲突。建议开发时只用后端全局跨域配置，或者只用前端代理，别混着用，不然排查起来头晕。
Token失效的表现症状是“点击某个功能，几秒后跳回登录页”，同时网络面板里能看到某个接口返回401。靠谱的处理方式，就是前面写的响应拦截器里统一捕获401，清除本地Token并跳转登录页。这里提醒一下，不要只在单个页面处理“登录过期”，否则每个接口都要写一遍重复代码。
最后说说打包部署。后端打包用Maven的mvn clean package，生成target目录下的jar包，扔到服务器上执行java -jar dormitory-system.jar即可。前端打包执行npm run build，生成dist静态目录，交给Nginx托管，同时配置代理到后端服务。实际部署时有个细节容易被忽略：后端接口服务要监听外网可达的地址（比如0.0.0.0），前端Nginx代理的目标地址要写后端服务器的内网IP或公网IP。如果只写localhost，部署在远程服务器上就访问不到了。
还有一个小技巧，前端路由用了history模式（路由地址没有#号），生产环境Nginx需要这样配置，否则刷新页面会404：
location / { try_files $uri $uri/ /index.html; }不然每次用户手动刷新浏览器，都会看到"404 Not Found"，这是很多初学者部署后遇到的经典问题。实际使用中我还发现，宿舍管理这类系统的数据字典量不大，但各宿舍的楼栋、房间数量往往需要灵活调整。如果代码里只有基础的表结构，我建议后端的管理员接口里留好楼栋编辑功能，而不是每次数据库里手工改，这个模块做完之后整体系统维护成本会低很多。
