DormMaster - 一款基于 PHP + MySQL 的现代化智能宿舍管理系统
为宿舍管理而生，让管理更简单、更智能、更高效
一个功能完整的宿舍公寓楼管理系统，支持多角色权限管理、批量操作、数据可视化和 CSV 编码自动转换功能。
- 楼栋管理：添加、编辑、删除宿舍楼
- 房间管理：批量添加房间，支持楼层范围设置
- 床位管理：实时显示房间占用情况
- 学生信息：完整的学生档案管理
- CSV导入：支持 GBK/UTF-8 编码自动转换
- 批量操作：快速导入大量学生数据
- 管理员：系统配置、用户管理、数据统计
- 教师：查看分配情况、申请调整
- 宿管：管理所负责楼栋、查看入住情况
- 学生：查看个人宿舍信息
- ECharts 集成：饼图、柱状图、折线图
- 实时统计：入住率、空床位、分配率
- 多维分析：按楼栋、楼层、性别统计
- 智能搜索：按学号、姓名、学院、专业搜索
- 双栏布局：左侧可选学生，右侧已选列表
- 实时容量：自动计算剩余床位，超限警告
- 便捷操作：全选、清空、单独移除
| 语言 | 名称 | 英文名 | 缩写 |
|---|---|---|---|
| 中文 | 宿舍大师 | DormMaster | DM |
| 英文 | Dormitory Master System | DormMaster | DM |
- PHP >= 7.4
- MySQL >= 5.7
- Apache/Nginx
- PDO 扩展
- GD 扩展（用于图表）
- 下载项目
# 方式一：Git 克隆（推荐）
git clone https://github.com/chu0119/DormMaster.git
cd DormMaster
# 方式二：下载压缩包
# 访问 https://github.com/chu0119/DormMaster/releases
# 下载并解压- 配置数据库
# 复制配置文件模板
cp config/config.example.php config/config.php
# 编辑配置文件
vim config/config.php修改数据库连接信息：
define('DB_HOST', 'localhost');
define('DB_NAME', 'dormitory');
define('DB_USER', 'root');
define('DB_PASS', 'password');- 初始化数据库
# 访问安装页面
http://your-domain/install.php或手动导入：
mysql -u root -p dormitory < database.sql- 设置权限
# 确保 logs 目录可写
chmod 755 logs/
chmod 644 logs/*.log- 访问系统
# 首页（自动跳转到登录页）
http://your-domain/
# 登录页面
http://your-domain/login.php
# 管理后台
http://your-domain/admin/
- 管理员：admin / admin123
DormMaster/
├── config/
│ ├── config.example.php # 配置文件模板
│ └── config.php # 实际配置（需创建）
├── app/
│ ├── Database.php # 数据库操作类
│ ├── Auth.php # 认证与权限管理
│ ├── helpers.php # 辅助函数（含编码转换）
│ └── Models/
│ ├── DormitoryBuilding.php
│ ├── Room.php
│ └── Student.php
├── admin/ # 管理后台
│ ├── index.php # 管理首页
│ ├── buildings.php # 楼栋管理
│ ├── rooms.php # 房间管理
│ ├── students.php # 学生管理
│ ├── users.php # 用户管理
│ ├── assignments.php # 宿舍分配（批量）
│ ├── import.php # CSV导入
│ ├── statistics.php # 统计图表
│ └── logout.php # 登出
├── teacher/ # 教师角色
│ └── index.php
├── housekeeper/ # 宿管角色
│ └── index.php
├── student/ # 学生角色
│ └── index.php
├── logs/ # 日志目录（需创建）
│ ├── operation.log
│ ├── error.log
│ └── import.log
├── database.sql # 数据库结构
├── install.php # 安装向导
├── login.php # 登录页面
├── index.php # 主入口
├── README.md # 本文件
├── INSTALL.md # 详细安装指南
├── USAGE.md # 使用手册
├── CHANGELOG.md # 更新日志
└── LICENSE # 许可证
首次使用请访问 install.php 按向导完成安装。
- 访问
login.php - 输入用户名和密码
- 根据角色自动跳转到对应首页
- 准备 CSV 文件（10列，UTF-8 或 GBK 编码）
- 进入管理后台 → 学生管理 → 批量导入
- 上传文件，系统自动检测编码并转换
- 查看导入结果
- 进入管理后台 → 宿舍分配
- 点击"批量分配"
- 选择目标房间
- 搜索并选择学生
- 确认分配
- 进入管理后台 → 数据统计
- 查看各类图表
- 导出数据（可选）
系统支持 GBK、GB2312、UTF-8 编码的 CSV 文件自动转换：
// 自动检测并转换编码
importCsv($filePath, $callback, 'auto');- 实时搜索：输入即搜索，无需点击
- 双栏布局：一目了然，操作便捷
- 容量检查：实时计算，超限警告
- 已选管理：右侧列表，单独移除
$auth->requireRole([1]); // 仅管理员
$auth->requireRole([1, 2]); // 管理员和教师- 操作日志：记录所有关键操作
- 错误日志：记录系统异常
- 导入日志：记录 CSV 导入详情
- 使用 PSR-12 编码风格
- 所有 SQL 查询使用预处理语句
- 所有用户输入必须验证和过滤
- 所有输出必须转义
- 在
app/Models/创建模型类 - 在
admin/或对应角色目录创建页面 - 更新权限配置
- 添加日志记录
- CSRF 保护所有 POST 请求
- 密码使用
password_hash()加密 - SQL 使用预处理防止注入
- XSS 防护：所有输出使用
h()函数转义
A: 系统会自动检测编码，如果失败请：
- 使用 UTF-8 编码保存 CSV
- 或使用 GBK 编码，系统会自动转换
- 查看
logs/import.log获取详细错误
A:
- 确保有未分配的学生
- 检查
students表中status = 1 - 查看
room_assignments表，确认学生未被分配
A:
- 确保安装了 GD 扩展
- 检查浏览器是否支持 Canvas
- 查看浏览器控制台错误
A: 执行以下 SQL：
UPDATE users SET password = '$2y$10$...' WHERE username = 'admin';使用 password_hash('新密码', PASSWORD_DEFAULT) 生成新密码的哈希值。
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
如有问题或建议，请通过以下方式联系：
- 提交 Issue
版本: v1.1.0 最后更新: 2026-01-05 状态: ✅ 生产环境就绪