学生宿舍管理系统 —— 项目介绍文档

项目信息概览

属性	说明
项目名称	学生宿舍管理系统（Student Dormitory Management System）
架构模式	B/S 前后端分离
后端技术	Node.js + Express 5 / MySQL2 / JWT / MySQL 8.0
前端技术	Vue 3 / Element Plus / Pinia / Vue Router / Axios / ECharts / Vite
开发语言	JavaScript（ES6+）
适用场景	计算机毕设、课程设计、源码学习与二次开发

一、项目简介

学生宿舍管理系统 是一套面向高校、高职及寄宿制学校的一站式宿舍信息化管理平台。系统采用前后端分离架构，围绕"宿舍楼 → 房间 → 入住 → 报修"全业务链路，为宿管部门提供学生信息、宿舍资源、入住退宿、故障报修等日常事务的数字化管理能力，帮助管理者从繁琐的纸质台账中解放出来，实现宿舍管理标准化、流程化、可视化。

系统内置系统管理员、宿管员、学生三类角色，各角色拥有独立的操作界面与数据权限，权限控制覆盖前后端双重校验，开箱即用。项目附带完整的数据库初始化脚本与演示数据，部署后即可体验全部功能。

核心价值

维度	价值说明
效率提升	入住 / 退宿 / 报修等流程线上化，替代手工台账，数据实时可查
规范管理	床位容量、楼栋性别、楼层等约束由系统强校验，杜绝超员、错配
数据可视化	入住率、入住趋势等指标以图表形式直观呈现，辅助管理决策
安全可控	三角色权限隔离 + 宿管管理范围隔离，数据操作全程留痕可追溯
成本低廉	轻量级技术栈，单机即可部署运行，无需昂贵授权费用

二、技术架构

系统采用主流的前后端分离技术方案，所有组件均为开源免费技术，生态成熟、易于维护与二次开发。

2.1 后端技术栈

类别	技术选型	版本	说明
核心框架	Express	5.2.1	轻量高性能 Web 服务框架
数据访问	MySQL2	3.23.3	连接池 + 预编译语句 + 事务支持
数据库	MySQL	8.0+	关系型数据库，utf8mb4 全字符集支持
安全认证	jsonwebtoken（JWT）	9.0.3	无状态 Token 认证，天然支持多端
密码加密	bcryptjs	3.0.3	密码加盐哈希存储，不可逆
跨域处理	cors	2.8.6	跨域资源共享配置
环境配置	dotenv	17.4.2	环境变量加载与管理
开发热重载	nodemon	3.1.14	开发模式代码改动自动重启

2.2 前端技术栈

类别	技术选型	版本	说明
核心框架	Vue 3（Composition API）	3.5.41	渐进式前端框架
UI 组件库	Element Plus	2.14.4	企业级桌面端组件库
路由	Vue Router	5.2.0	单页应用路由与权限守卫
状态管理	Pinia	4.0.2	Vue 官方推荐的状态管理方案
HTTP 客户端	Axios	1.19.0	统一封装请求拦截、错误处理与登录态管理
图表	ECharts	6.1.0	入住率饼图、入住趋势柱状图等可视化
构建工具	Vite	8.2.1	下一代前端构建工具
图标库	@element-plus/icons-vue	2.3.2	Element Plus 配套图标库

2.3 架构图

┌─────────────────────────────────────────────────────────┐
│                      浏览器（Browser）                    │
├───────────────────────┬─────────────────────────────────┤
│    管理端（Admin）      │     学生端（Student）             │
│    localhost:5173      │     localhost:5173              │
│   · 数据看板/数据统计    │     · 我的信息（住宿/床位）         │
│   · 学生管理            │     · 我的报修（提交/跟踪）         │
│   · 宿舍楼/房间管理      │                                 │
│   · 入住/退宿管理        │                                 │
│   · 报修管理            │                                 │
│   · 系统用户管理         │                                 │
└───────────────────────┴─────────────────────────────────┘
                          │  HTTP /api/*
                          ▼
┌─────────────────────────────────────────────────────────┐
│             Express 后端服务（localhost:3000）            │
├─────────────┬──────────────┬──────────────┬──────────────┤
│  Middleware │  Controller  │    Model     │    Route     │
│  JWT 认证    │  业务控制器   │  数据访问层   │  路由定义     │
│  角色鉴权     │  参数校验     │  MySQL2 查询  │  模块化分发    │
│  异常处理     │  事务管理     │  预编译 SQL   │              │
└─────────────┴──────────────┴──────────────┴──────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│             MySQL 8.0（dormitory_management）            │
└─────────────────────────────────────────────────────────┘

三、项目目录结构

student-dormitory-management
├── db/
│   └── init.sql              # 数据库初始化脚本（建库、建表、演示数据）
├── server/                   # 后端服务（Express）
│   ├── src/
│   │   ├── app.js            # 应用入口
│   │   ├── config/           # 配置（端口、数据库、JWT）
│   │   ├── controllers/      # 业务控制器
│   │   ├── middlewares/      # 认证 / 角色校验 / 异常处理
│   │   ├── models/           # 数据访问层
│   │   ├── routes/           # 路由定义
│   │   └── utils/            # 工具（JWT、响应封装、参数校验）
│   ├── test/
│   │   └── api.test.js       # API 集成测试脚本
│   ├── .env.example          # 环境变量模板
│   └── package.json
└── web/                      # 前端应用（Vue 3 + Vite）
    ├── src/
    │   ├── api/              # 接口请求封装
    │   ├── router/           # 前端路由与权限守卫
    │   ├── stores/           # Pinia 状态管理
    │   ├── utils/            # 请求封装、格式化工具
    │   └── views/            # 页面组件
    ├── index.html
    └── package.json

四、系统功能

1. 数据看板（仪表盘）

面向管理员与宿管员，一屏掌握宿舍管理全局数据：

核心统计指标：学生总数、在住人数、宿舍楼数量、房间总数、入住率等
宿舍楼入住率饼图：各楼栋已入住 / 空余床位占比一目了然
近 30 天入住趋势柱状图：直观反映入住办理量的时间分布

2. 学生管理

学生信息增删改查，支持学号、姓名、学院、专业、班级等字段
关键字模糊搜索，快速定位目标学生
学生账号与学号联动，登录即绑定本人数据
住宿状态（未入住 / 在住 / 已退宿）自动维护

3. 宿舍楼管理

宿舍楼信息维护（楼栋名称、楼层数、楼栋类型、备注）
楼栋类型（男 / 女）约束入住分配，避免性别混住
楼栋与宿管员绑定，实现"一栋一管"的责任制管理
删除保护：含房间的楼栋禁止删除，防止数据错乱

4. 房间管理

房间增删改查，支持按楼栋筛选与房间号检索
床位容量 / 已入住人数实时同步，入住自动累加、退宿自动扣减
楼层合法性校验：楼层不得超出楼栋总层数
容量保护：容量不得小于已入住人数，有在住学生的房间禁止删除

5. 入住管理

入住登记：选择未入住学生、可入住房间与空余床号，一键办理
退宿办理：登记退宿日期，自动释放床位与房间容量
多种业务校验：重复入住拦截、床号占用拦截、满员房间拦截
入住记录按状态（在住 / 已退宿）与关键字筛选，全程可追溯

6. 报修管理

学生自主提交报修（强制绑定本人），无需线下跑腿
报修状态流转：待处理 → 处理中 → 已完成，全程留痕
处理人登记与完成时间记录，责任清晰
报修内容长度、状态值合法性等严格校验

7. 系统用户管理（仅管理员）

管理员 / 宿管员账号的创建、修改、禁用与删除
禁止创建学生账号（学生账号随学号联动），从源头保证数据一致性
自我保护：禁止修改、禁用或删除当前登录账号
所有用户支持自助修改密码，原密码验证后才可更换

8. 学生端

我的信息：查看本人学籍、住宿房间、床位与入住信息
我的报修：提交报修、实时跟踪本人报修处理进度

角色权限一览

功能模块	系统管理员	宿管员	学生
数据看板	✅	✅	——
学生管理	✅	✅	——
宿舍楼管理	✅	✅（仅本人负责楼栋）	——
房间管理	✅	✅（仅本人负责楼栋）	——
入住管理	✅	✅（仅本人负责楼栋）	——
报修管理	✅	✅	✅（本人）
系统用户管理	✅	——	——
我的信息 / 我的报修	——	——	✅

五、项目亮点 / 特色

1. 三角色权限体系，前后端双重鉴权

系统内置 admin（系统管理员）、manager（宿管员）、student（学生） 三种角色。前端通过路由守卫控制菜单与页面可见性，后端通过 JWT + 角色中间件对每个接口二次校验，即便绕过前端直接调用接口也会被拒绝，权限安全不留死角。

2. 宿管员管理范围隔离

宿管员只能看到并操作自己负责的宿舍楼及其下属房间、入住记录，对非本人管理的楼栋执行修改、删除等操作一律返回 403。实现"谁负责、谁管理"的精细化授权，多栋宿舍楼并行管理互不干扰。

3. 业务层数据关联保护，杜绝脏数据

系统不依赖数据库外键，而是由业务层统一校验表间关联关系：在住学生禁止删除、有在住学生的房间禁止删除、含房间的楼栋禁止删除，配合满员拦截、床位占用拦截、重复入住拦截，从入口处保证数据完整性与业务合法性。

4. 核心流程事务化，数据原子一致

入住登记、退宿办理等涉及学生状态、房间容量、入住记录多表联动的操作，全部包裹在数据库事务中执行，任一步骤失败即整体回滚，杜绝"房间住满了但学生没登记上"之类的数据不一致问题。

5. 数据可视化辅助决策

内置 ECharts 数据看板，宿舍楼入住率饼图、近 30 天入住趋势柱状图等图表实时联动数据库，让管理者对宿舍资源使用情况"看得见、算得清"。

6. 全方位安全防护

密码安全：bcrypt 加盐哈希存储，数据库泄露也无法还原明文
防 SQL 注入：全部 SQL 采用预编译参数占位
JWT 无状态认证：Token 自动续期机制（7 天有效期），请求拦截器统一携带
统一异常处理：404、参数校验、业务异常、系统异常分级响应，接口行为规范一致

7. 完整 API 集成测试，交付质量有保障

项目附带覆盖 90 项断言的后端集成测试脚本，涵盖健康检查、认证鉴权、三角色权限隔离、各模块 CRUD、入住退宿流程、报修流程、统计接口、业务校验与异常处理，一条命令即可回归验证全部接口。

8. 开箱即用，立即可体验

内置完整初始化脚本与演示数据（2 栋宿舍楼、48 间房间、20 名学生、入住与报修记录），三套角色账号全部就绪，数据库初始化后 5 分钟内即可完整体验系统全流程。

文档整理人：MakeXu
文档修订人：MakeXu