简介：Hostel-Allocation 是一套面向高校宿舍预订与管理场景的 Web 全栈项目源码，适合计算机专业学生、课程设计开发者及 Node.js 入门者参考。它围绕在线查看房源、远程预订房间与管理员分配管理展开，试图替代线下排队登记，降低人员聚集与沟通成本。项目采用 Node.js 与 Express.js 搭建后端，MySQL 配合 Sequelize 完成学生、房间及预订记录的数据建模，前端由 HTML5、CSS3、Bootstrap4 与 jQuery 构建响应式界面，并引入 JWT 实现登录鉴权与受保护路由。压缩包共 22 个文件，以 11 个 JavaScript 脚本、4 个 HTML 页面和 2 个 JSON 配置为主，另含样式表、说明文档及证书密钥文件，整体约 34KB，便于快速部署与二次修改，现有 117 人学习下载。读者可从中获得前后端分离思路、数据库模型定义、认证中间件、房间增删与预订流程等可运行代码，也能参考目录组织方式完成自己的宿舍管理系统或全栈练手项目。

1. 宿舍分配的真实痛点：把排队选房搬到线上

宿舍分配最怕的不是没房，而是信息不对称：学生在楼下排队，管理员在表格里逐行找人。Hostel-Allocation 这套方案把“谁住在哪个房间”搬到线上，学生远程选房、提交申请，管理员在后台看床位占用和入住人。它适合做课程设计、毕设，也适合小规模宿舍的轻量管理。技术栈不追新：Node.js + Express 做接口，MySQL + Sequelize 管数据，前端 jQuery + Bootstrap4，JWT 做登录态。下面按需求、架构、权限、流程、避坑、验收六段拆开，每段都落到能改的代码和能检查的表结构。

2. 总体架构与数据模型：Express 分层与六张核心表

2.1 选型：Node.js + Express + Sequelize 的轻量组合

这个项目的业务量不大，但涉及角色、床位状态和并发提交，选型重点不是“新技术”，而是“能讲清楚、能跑起来、能查问题”。Node.js 加 Express 的请求链路短，中间件顺序一眼能看懂，适合学生项目答辩时逐层说明；MySQL 支持事务和行锁，床位这种“同一时刻只能一个人占”的资源必须靠数据库兜底；Sequelize 把关联查询和迁移管起来，学生、房间、床位、申请、分配、审计六类数据不用手写大量拼接 SQL。前端用 jQuery 加 Bootstrap4，页面交互不复杂，表格、弹窗、表单校验都能快速搭出来，html5 和 css3 负责页面结构与响应式布局，省掉构建工具带来的额外调试成本。JWT authentication 放在 Express 中间件里做无状态登录，学生端和管理员端共用一套接口，靠角色字段区分权限。这套组合不花哨，但每一层都有明确职责，出问题时能快速定位是路由、事务还是前端取值的问题。

关键词里的 javascript 在这里不是“网页脚本”这么泛，而是贯穿前后端的同一门语言：后端写控制器和模型，前端写表单校验和 ajax 请求，调试时不用在两套语法之间切换。Express-js 的路由文件按资源拆分，sequelize 的模型文件按表拆分，整体结构对课设和毕设都够用。

2.2 目录分层与一次请求的完整链路

我一般把后端按“路由—中间件—控制器—服务—模型”五层拆，避免把所有逻辑塞进一个 app.js。目录可以长这样：

# 后端目录结构，按职责分层 src/ app.js # Express 实例、全局中间件、路由挂载 config/ db.js # Sequelize 连接与连接池配置 routes/ auth.routes.js # 登录、刷新 token room.routes.js # 房间与床位查询 application.routes.js# 学生申请 admin.routes.js # 管理员审核、分配、退宿 middlewares/ auth.js # JWT 校验 role.js # 角色判断 error.js # 统一错误返回 controllers/ room.controller.js application.controller.js services/ allocation.service.js# 事务型分配逻辑 models/ student.js room.js bed.js application.js allocation.js auditLog.js

一次“学生查可预订床位”的请求会经过：Express 路由匹配/api/rooms/available，auth中间件解析 Authorization 头里的 JWT，把用户信息挂到req.user；role中间件确认是学生角色；控制器读取查询参数（楼栋、性别、入住日期），调用服务层；服务层用 Sequelize 查询房间和床位，只返回状态为 available 的床位；最后统一响应格式返回。链路短，但每一层都有落点，答辩时被问到“请求怎么走”不会卡住。

// app.js 关键挂载顺序，顺序错了权限会失效 const express = require('express'); const app = express(); app.use(express.json()); // 解析 JSON 请求体 app.use('/api/auth', require('./routes/auth.routes')); // 登录接口不需要 token app.use('/api/rooms', require('./middlewares/auth'), require('./routes/room.routes')); app.use('/api/applications', require('./middlewares/auth'), require('./routes/application.routes')); app.use('/api/admin', require('./middlewares/auth'), require('./middlewares/role')('admin'), require('./routes/admin.routes')); app.use(require('./middlewares/error')); // 统一错误处理放最后 module.exports = app;

这段挂载顺序里，express.json()必须放在路由前，否则req.body是 undefined；登录路由不挂auth，因为此时还没有 token；管理员路由在auth之后再加role('admin')，先确认“你是谁”，再确认“你能不能进”。参数说明：require('./middlewares/role')('admin')返回一个中间件函数，角色名从路由层传入，避免在中间件里写死多个判断分支。

2.3 数据模型：学生、房间、床位、申请、分配、审计

宿舍分配的核心不是“房间表”一张表，而是把“房间—床位—人—申请—分配”拆开。房间是物理空间，床位是库存单位，申请是学生意愿，分配是管理员确认，审计是后悔药。六张表的关系如下：

床位状态用枚举控制：available、locked、allocated、checked_in、checked_out。学生提交申请时床位从 available 变 locked，管理员确认后变 allocated，学生入住变 checked_in，退宿变 checked_out 并释放为 available。状态流转写进服务层，不让控制器直接改字段。

// models/bed.js：床位模型，状态枚举和关联 module.exports = (sequelize, DataTypes) => { const Bed = sequelize.define('Bed', { id: { type: DataTypes.INTEGER, primaryKey: true, autoIncrement: true }, roomId: { type: DataTypes.INTEGER, allowNull: false, field: 'room_id' }, bedNo: { type: DataTypes.STRING(10), allowNull: false, field: 'bed_no' }, status: { type: DataTypes.ENUM('available', 'locked', 'allocated', 'checked_in', 'checked_out'), allowNull: false, defaultValue: 'available' } }, { tableName: 'beds', indexes: [{ unique: true, fields: ['room_id', 'bed_no'] }] // 防止同一房间重复床位号 }); Bed.associate = (models) => { Bed.belongsTo(models.Room, { foreignKey: 'roomId', as: 'room' }); Bed.hasMany(models.Application, { foreignKey: 'bedId', as: 'applications' }); }; return Bed; };

这段模型代码只做三件事：字段映射、状态枚举、唯一索引。field把驼峰命名映射到数据库下划线字段，避免 Sequelize 默认命名和建表脚本对不上；indexes里的唯一索引是防重复床位的最后一道闸，前端校验只能算提示，数据库约束才算数。关联写在associate里，查询房间时可以用include一次带出床位，减少后面说的 N+1 问题。

建表时再补一个关键约束：同一张床位在“有效分配”状态下只能有一条记录。MySQL 不能用部分唯一索引，通常的做法是给allocations加一个active_key字段，有效分配写bed_id，退宿后写bed_id + '_released_' + id，再对active_key建唯一索引。这样既保留历史记录，又避免两个人同时占一张床。

3. 认证与权限：JWT 双角色与路由守卫的落地

3.1 登录流程与 token 载荷设计

登录接口只做三件事：按学号或管理员账号查用户、比对密码哈希、签发 JWT。JWT 载荷不要放密码、手机号、宿舍号这类敏感信息，放sub（用户 id）、role（student/admin）、name（页面显示用）和过期时间即可。学生端和管理员端共用一套登录接口，前端登录后根据role跳不同首页。token 有效期不宜太长，课设环境设 2 小时足够，过期后前端统一跳登录页重新认证。

// routes/auth.routes.js：登录签发 token const jwt = require('jsonwebtoken'); const bcrypt = require('bcryptjs'); const { Student } = require('../models'); router.post('/login', async (req, res, next) => { try { const { account, password } = req.body; const user = await Student.findOne({ where: { studentNo: account } }); if (!user || user.status !== 'active') { return res.status(401).json({ code: 401, message: '账号或密码错误' }); } const ok = await bcrypt.compare(password, user.passwordHash); // 比对哈希 if (!ok) return res.status(401).json({ code: 401, message: '账号或密码错误' }); const token = jwt.sign( { sub: user.id, role: user.role, name: user.name }, process.env.JWT_SECRET, { expiresIn: '2h' } // 课设环境够用，生产按需缩短 ); res.json({ code: 0, data: { token, role: user.role, name: user.name } }); } catch (err) { next(err); } });

参数说明：account兼容学号和管理员账号，password是明文只在传输层出现，落库前必须哈希；JWT_SECRET从环境变量读，不写进代码仓库；expiresIn控制过期时间，前端拦截 401 时统一处理。注意登录失败不要区分“账号不存在”和“密码错误”，统一返回同一句提示，减少账号枚举风险。

3.2 角色中间件与接口权限矩阵

权限不要写在前端隐藏按钮上，按钮隐藏只是体验，后端必须再判一次。学生能查可用床位、提交申请、看自己的申请状态、取消未确认的申请；管理员能查全部申请、分配床位、退宿、看审计日志。接口权限矩阵如下：

中间件先解 token，再判角色。401 表示“没登录或 token 失效”，403 表示“登录了但没权限”，前端根据状态码做不同提示，不要一律弹“网络错误”。

// middlewares/auth.js：解析并校验 JWT const jwt = require('jsonwebtoken'); module.exports = (req, res, next) => { const header = req.headers.authorization || ''; const token = header.startsWith('Bearer ') ? header.slice(7) : null; if (!token) return res.status(401).json({ code: 401, message: '请先登录' }); try { req.user = jwt.verify(token, process.env.JWT_SECRET); // 挂到请求上下文 next(); } catch (err) { return res.status(401).json({ code: 401, message: '登录已过期' }); } }; // middlewares/role.js：角色守卫，返回中间件函数 module.exports = (role) => (req, res, next) => { if (req.user.role !== role) { return res.status(403).json({ code: 403, message: '无权访问' }); } next(); };

auth中间件只负责“你是谁”，role中间件只负责“你能不能进”，两个中间件组合使用，管理员路由写成auth在前、role('admin')在后。这样学生 token 调管理员接口会返回 403，而不是 401，前端提示更准确。

3.3 密码哈希与 token 失效处理

密码用 bcryptjs 哈希，salt rounds 设 10 左右，登录时用compare，不要自己写加密函数。JWT 是无状态的，签发后服务端不保存，所以“管理员禁用账号”后旧 token 在过期前仍然有效。解决方式有两种：一是在 token 里加tokenVersion，用户表也存一个版本号，每次请求比对；二是auth中间件里查一次用户状态，确认status === 'active'。课设环境用第二种更直观，代价是多一次数据库查询，但能讲清楚“禁用即失效”。

// 登录时写入哈希，注册或初始化管理员账号时使用 const hash = await bcrypt.hash(password, 10); await Student.create({ studentNo, name, passwordHash: hash, role: 'student', status: 'active' });

参数说明：10是 salt rounds，数值越大越慢，课设环境 10 足够；passwordHash字段长度要留够，bcrypt 输出通常在 60 字符左右，建表时用VARCHAR(100)更稳妥。不要在日志里打印明文密码或完整 token，调试时只打印用户 id 和角色。

提示：JWT_SECRET 不要用默认值，也不要提交到代码仓库，部署时通过环境变量注入。

4. 预订与分配流程：从选房到入住的可回滚状态机

4.1 房间检索与床位锁定

学生进入首页先看到可用房间列表，筛选条件包括楼栋、性别类型、剩余床位数。查询不要先查房间再循环查床位，直接以床位为主表关联房间，过滤beds.status = 'available'，按房间分组返回剩余数量。分页参数page、pageSize从 query 读，默认第一页、每页 20 条，避免一次返回全部数据。

// services/room.service.js：按床位查可用房间，减少循环查询 async function listAvailableRooms({ building, genderType, page = 1, pageSize = 20 }) { const where = { status: 'available' }; const roomWhere = {}; if (building) roomWhere.building = building; if (genderType) roomWhere.genderType = genderType; const { rows, count } = await Bed.findAndCountAll({ where, include: [{ model: Room, as: 'room', where: roomWhere, required: true // 房间条件不满足时床位不返回 }], order: [['roomId', 'ASC'], ['bedNo', 'ASC']], offset: (page - 1) * pageSize, limit: pageSize }); return { total: count, page, pageSize, list: rows }; }

这段查询用required: true把关联变成内连接，房间筛选条件直接落到 SQL 的WHERE里；findAndCountAll一次返回分页数据和总数，前端分页条不用再发一次请求。参数说明：building和genderType为空时不拼条件；offset和limit控制分页，pageSize最好限制上限，防止前端传 10000 把数据库拖慢。床位的status字段建索引，房间的building、gender_type建联合索引，列表页数据量上来后不会全表扫。

学生点“申请”时，前端只传bedId和入住日期，不要传studentId，学生 id 从 token 里取，避免越权替别人申请。提交后床位进入locked，申请进入pending，管理员还没确认，其他人不能再选这张床。

4.2 事务与并发：避免两个人抢到同一张床

床位是典型的“库存”资源，两个学生同时点提交，如果代码先查状态再更新，中间没有锁，就会翻车：两个请求都查到available，都更新成功，最后一张床出现两条申请。解决靠三件事：事务、行锁、唯一约束。事务保证申请和床位状态一起成功或一起失败；行锁用SELECT ... FOR UPDATE锁住床位行；唯一约束兜底，防止代码漏判。

// services/application.service.js：事务内锁定床位再创建申请 async function createApplication(studentId, bedId, checkInDate) { return sequelize.transaction(async (t) => { // 锁定床位行，其他事务等待 const bed = await Bed.findOne({ where: { id: bedId }, lock: t.LOCK.UPDATE, transaction: t }); if (!bed || bed.status !== 'available') { throw new Error('该床位已被占用，请重新选择'); } // 同一学生不能重复提交有效申请 const exists = await Application.findOne({ where: { studentId, status: ['pending', 'approved'] }, transaction: t }); if (exists) throw new Error('你已有待处理的申请'); const application = await Application.create({ studentId, bedId, checkInDate, status: 'pending' }, { transaction: t }); await bed.update({ status: 'locked' }, { transaction: t }); return application; }); }

逻辑说明：sequelize.transaction开启事务，lock: t.LOCK.UPDATE生成FOR UPDATE，锁住床位行直到事务提交；床位状态不是available直接抛错，事务回滚；同一学生重复申请在事务内查一次，避免连点两次生成两条记录；Application.create和bed.update都带transaction: t，任何一步失败都回滚。参数说明：checkInDate只存日期，不存时分秒；status初始为pending，管理员确认后才变approved。

MySQL 的 InnoDB 支持行锁，但要注意查询条件必须命中索引，否则可能锁表。beds.id是主键，按 id 查会走主键索引，锁范围可控。唯一约束再补一层：applications表对(student_id, active_flag)建唯一索引，active_flag在有效申请时为 1，取消或完成后改为 0，防止同一学生刷出多条有效申请。

4.3 管理员分配、退宿与审计日志

管理员在后台看到pending申请，确认前先查床位状态，确认时写allocations记录、把申请改为approved、床位改为allocated，三步在同一事务里。退宿时把分配记录改为checked_out，床位释放为available，申请改为completed，同时写一条audit_logs，记录操作人、操作前后状态。审计日志只增不改，管理员误操作后能查到“谁在什么时候把哪张床释放了”。

// services/allocation.service.js：管理员确认分配 async function allocate(applicationId, adminId) { return sequelize.transaction(async (t) => { const app = await Application.findByPk(applicationId, { transaction: t, lock: t.LOCK.UPDATE }); if (!app || app.status !== 'pending') throw new Error('申请状态不允许分配'); const bed = await Bed.findByPk(app.bedId, { transaction: t, lock: t.LOCK.UPDATE }); if (!bed || bed.status !== 'locked') throw new Error('床位状态异常'); await Allocation.create({ applicationId: app.id, studentId: app.studentId, bedId: app.bedId, status: 'allocated', allocatedBy: adminId }, { transaction: t }); await app.update({ status: 'approved' }, { transaction: t }); await bed.update({ status: 'allocated' }, { transaction: t }); await AuditLog.create({ actorId: adminId, action: 'allocate', targetType: 'application', targetId: app.id, beforeJson: { status: 'pending', bedStatus: 'locked' }, afterJson: { status: 'approved', bedStatus: 'allocated' } }, { transaction: t }); }); }

参数说明：adminId从 token 取，不从前端传；lock锁申请和床位两行，避免管理员重复点确认；beforeJson和afterJson存关键状态，不存全表字段，查询时更轻。退宿逻辑类似，把allocated改为checked_out，床位改回available，并写审计日志。状态机如下：

状态流转只在服务层写，控制器只做参数校验和响应组装。这样答辩时画一张状态图就能讲清楚，也方便写测试用例。

5. 避坑与排查：宿舍预订系统最容易翻车的五个点

5.1 并发重复预订：库存扣减写在事务外

现象：两个学生几乎同时提交同一张床，数据库里出现两条pending申请，床位表却只有一条locked，管理员审核时不知道给谁。原因：代码先findOne查床位，再在事务外update，两个请求都查到available，更新时没有条件判断。解决：把“查状态”和“改状态”放进同一个事务，用FOR UPDATE锁行，更新时再加where status = 'available'条件，影响行数为 0 就抛错回滚；同时给有效申请加唯一索引兜底。血泪经验是，前端按钮加 disabled 只能防手快，防不了两个浏览器同时提交。

5.2 JWT 过期后页面白屏：前端只处理 200

现象：学生登录后放着页面不动，两小时后再点“提交申请”，页面没反应，控制台也没有明显报错。原因：jQuery 的$.ajax只写了success，接口返回 401 时走error，但没有全局处理，页面既不跳登录也不提示。解决：用$.ajaxSetup统一拦截 401，清掉本地 token，跳登录页并带上当前地址，登录后跳回来。代码片段如下：

// 前端统一处理 401，避免每个请求都写一遍 $.ajaxSetup({ error: function (xhr) { if (xhr.status === 401) { localStorage.removeItem('token'); location.href = '/login.html?redirect=' + encodeURIComponent(location.pathname); } else if (xhr.status === 403) { alert('没有权限执行该操作'); } else { alert('请求失败，请稍后重试'); } } });

xhr.status是 HTTP 状态码，401 和 403 要分开提示；redirect参数让用户登录后回到原页面，体验更顺。注意不要在error里再发一次需要 token 的请求，否则会循环跳转。

5.3 Sequelize 关联查询 N+1：房间列表越查越慢

现象：房间列表只有 30 条，SQL 日志却出现 60 多条查询，页面加载从几百毫秒涨到几秒。原因：先查房间列表，再在循环里await Bed.findAll({ where: { roomId: room.id } })，每条房间一次查询。解决：用include预加载床位，或者一次查全部床位再按roomId分组。列表页用findAndCountAll加include，详情页再按需查。代码示例如下：

// 一次带出房间和床位，避免循环查询 const rooms = await Room.findAll({ include: [{ model: Bed, as: 'beds', where: { status: 'available' }, required: false }], order: [['building', 'ASC'], ['roomNo', 'ASC']] });

required: false是左连接，没有可用床位的房间也会返回，前端显示“已满”；如果只想看有空床的房间，改成required: true。include里的where条件会落到关联表的 SQL 里，不会把全部床位拉到内存再过滤。

5.4 时间字段时区错乱：入住日期差一天

现象：前端选 9 月 1 日入住，后端存成 8 月 31 日 16:00:00，管理员后台显示 8 月 31 日。原因：入住日期用了DATE或DATETIME，Sequelize 默认按 UTC 处理，前端又传了带时区的 ISO 字符串。解决：入住日期用DataTypes.DATEONLY，只存YYYY-MM-DD；创建时间、更新时间用DATETIME并存 UTC；前端日期控件只传YYYY-MM-DD，不传new Date().toISOString()。数据库连接配置里明确时区，避免 MySQL 服务端时区和 Node 进程时区不一致。

// 入住日期只存日期，不存时间 checkInDate: { type: DataTypes.DATEONLY, allowNull: false, field: 'check_in_date' }

参数说明：DATEONLY在 MySQL 里对应DATE，Sequelize 读写时按日期字符串处理，不会自动做时区偏移；如果业务需要“几点入住”，再用DATETIME并统一用 UTC 存储、前端按本地时区展示。验收时专门查一条跨月日期的申请，看列表和详情是否一致。

5.5 管理员误操作无后悔药：缺少审计与软删除

现象：管理员点错“退宿”，床位立刻释放，学生还没搬走，原分配记录也被覆盖，查不到是谁操作的。原因：退宿直接destroy或覆盖状态，没有保留历史，也没有操作日志。解决：分配表用软删除或状态字段保留记录，退宿只改状态不物理删除；关键操作写audit_logs，记录操作人、操作前后状态；前端二次确认，但确认框只是体验，后端仍要校验状态。审计表只增不改，查询按时间倒序分页。这样出问题能回放操作链，答辩时也能讲清楚“可追溯”不是一句空话。

注意：审计日志不要存密码、token 和完整身份证号，只存业务状态和操作人 id。

6. 验收与答辩：三条链路和一张检查表把方案讲圆

6.1 演示脚本：学生预订、管理员分配、异常回滚

答辩演示不要从登录页开始逐个点菜单，按三条链路走更稳。第一条正常链路：学生登录，筛选楼栋，选一张可用床位，提交申请，页面显示“待审核”；管理员登录，看到这条申请，确认分配，床位变“已分配”，学生端刷新看到“已通过”。第二条异常链路：再开一个学生账号，选同一张床，提交时提示“已被占用”，证明并发控制生效；管理员驳回一条申请，床位回到“可用”。第三条审计链路：管理员退宿，查审计日志，能看到操作人、操作前后状态。三条链路走完，功能、权限、异常处理都覆盖到了。

6.2 答辩问答与验收标准

常见问题提前准备三句：为什么用 JWT 不用 session？答：接口无状态，学生端和管理员端共用一套认证，部署不用考虑会话共享；并发怎么保证？答：事务加行锁加唯一索引三层，不靠前端按钮；权限怎么测？答：用学生 token 直接调管理员接口，看是否返回 403。验收时别只看页面能不能点，按表里的检查项逐条过，尤其是床位状态和分配记录是否一致。从那以后我每次做涉及床位、库存的系统，都先把并发用例写进验收清单，再谈页面好不好看。希望帮到你。

本文还有配套的精品资源，点击获取