# 宿舍管理系统

**Repository Path**: icb/dormitory-management-system

## Basic Information

- **Project Name**: 宿舍管理系统
- **Description**: 一个基于 Spring Boot 3 + Vue 3 的现代化学生宿舍管理系统，提供管理员端、维修人员端和学生端三端功能，支持宿舍分配、报修管理、公告通知等核心业务。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏠 学生宿舍管理系统

一个基于 Spring Boot 3 + Vue 3 的现代化学生宿舍管理系统，提供管理员端、维修人员端和学生端三端功能，支持宿舍分配、报修管理、公告通知等核心业务。

## ✨ 项目特点

- 🎯 **前后端分离架构**：Spring Boot 3 后端 + Vue 3 前端，职责清晰，易于维护
- 🔐 **完善的权限控制**：基于 Sa-Token 的权限管理，支持管理员、维修人员、学生三种角色
- 💾 **高效的数据持久化**：使用 MyBatis Flex 轻量级 ORM 框架，支持逻辑删除
- 🚀 **异步消息处理**：RabbitMQ 实现报修、公告等异步通知，提升用户体验
- ⚡ **缓存加速**：Redis 缓存用户登录状态和热点数据，提高系统性能
- 📱 **现代化 UI**：基于 Naive UI 组件库，界面美观易用，响应式设计
- 🎨 **优雅的代码结构**：分层清晰，遵循 RESTful 设计规范

## 🎨 功能模块

### 👨‍💼 管理员端
- ✅ **学生信息管理**：学生信息的增删改查、批量导入导出
- ✅ **宿舍管理**：宿舍楼管理、宿舍分配与调整、床位管理
- ✅ **报修管理**：报修申请审核、指定维修人员、查看处理进度
- ✅ **公告管理**：公告发布、编辑、删除，支持分类和置顶
- ✅ **数据统计**：系统数据统计、报修趋势分析、宿舍入住率统计

### 🔧 维修人员端
- ✅ **报修处理**：查看分配的报修任务、开始处理、完成报修
- ✅ **任务管理**：查看待处理、处理中、已完成的报修任务

### 👨‍🎓 学生端
- ✅ **个人信息**：查看个人信息、修改密码
- ✅ **宿舍信息**：查看宿舍信息、室友信息
- ✅ **报修申请**：提交报修申请、上传图片、查看处理进度
- ✅ **公告通知**：查看公告列表、公告详情、消息通知

## 🛠️ 技术栈

### 后端技术
- **核心框架**：Spring Boot 3.1.11
- **ORM 框架**：MyBatis Flex 1.7.8
- **权限认证**：Sa-Token 1.37.0
- **缓存**：Spring Data Redis
- **消息队列**：RabbitMQ (Spring AMQP)
- **数据库**：MySQL 8.0+
- **连接池**：Druid 1.2.20
- **API 文档**：Knife4j 4.4.0 (基于 OpenAPI 3)
- **工具类库**：
  - Hutool 5.8.24
  - Apache Commons Lang3 3.14.0
  - FastJson2 2.0.43
- **构建工具**：Maven 3.6+

### 前端技术
- **核心框架**：Vue 3.3.11 (Composition API)
- **构建工具**：Vite 5.0.8
- **状态管理**：Pinia 2.1.7
- **路由管理**：Vue Router 4.2.5
- **UI 组件库**：Naive UI 2.36.0
- **HTTP 客户端**：Axios 1.6.2
- **图表库**：ECharts 6.0.0 + Vue-ECharts 8.0.1
- **图标库**：@vicons/ionicons5 0.12.0
- **CSS 框架**：Tailwind CSS 3.4.18

## 📁 项目结构

```
dormitory/
├── dormitory-backend/                    # 后端项目
│   ├── src/main/java/
│   │   └── com/dormitory/management/
│   │       ├── controller/               # 控制器层（RESTful API）
│   │       │   ├── AuthController.java          # 认证控制器
│   │       │   ├── StudentController.java        # 学生管理
│   │       │   ├── DormitoryController.java      # 宿舍管理
│   │       │   ├── RepairRequestController.java  # 报修管理
│   │       │   ├── NoticeController.java         # 公告管理
│   │       │   ├── MaintenanceStaffController.java # 维修人员管理
│   │       │   └── DashboardController.java     # 数据统计
│   │       ├── service/                  # 服务层（业务逻辑）
│   │       │   └── impl/                 # 服务实现
│   │       ├── mapper/                   # 数据访问层（MyBatis Flex）
│   │       ├── entity/                   # 实体类（数据库映射）
│   │       ├── dto/                      # 数据传输对象（请求参数）
│   │       ├── vo/                       # 视图对象（响应数据）
│   │       ├── config/                   # 配置类
│   │       │   ├── MyBatisFlexConfiguration.java
│   │       │   ├── RabbitMQConfig.java
│   │       │   ├── WebMvcConfig.java
│   │       │   └── Knife4jConfig.java
│   │       ├── common/                   # 公共类
│   │       │   ├── Result.java           # 统一响应结果
│   │       │   ├── ResultCode.java      # 响应码枚举
│   │       │   └── Constants.java       # 常量定义
│   │       ├── exception/                # 异常处理
│   │       │   ├── BusinessException.java
│   │       │   └── GlobalExceptionHandler.java
│   │       ├── interceptor/              # 拦截器
│   │       └── mq/                       # 消息队列
│   │           ├── MessageProducer.java  # 消息生产者
│   │           └── MessageConsumer.java # 消息消费者
│   └── src/main/resources/
│       ├── application.yml               # 应用配置文件
│       └── sql/
│           └── schema.sql                # 数据库建表脚本
│
└── dormitory-frontend/                   # 前端项目
    ├── src/
    │   ├── api/                          # API 接口定义
    │   │   ├── auth.js                   # 认证接口
    │   │   ├── student.js                # 学生接口
    │   │   ├── dormitory.js              # 宿舍接口
    │   │   ├── repair.js                 # 报修接口
    │   │   ├── notice.js                 # 公告接口
    │   │   └── dashboard.js             # 数据统计接口
    │   ├── assets/                       # 静态资源
    │   │   └── style.css                # 全局样式
    │   ├── components/                   # 公共组件
    │   ├── router/                       # 路由配置
    │   │   └── index.js                 # 路由定义和守卫
    │   ├── stores/                       # Pinia 状态管理
    │   │   └── user.js                   # 用户状态
    │   ├── utils/                        # 工具类
    │   │   └── request.js                # Axios 请求封装
    │   └── views/                        # 页面视图
    │       ├── admin/                    # 管理员端页面
    │       │   ├── Layout.vue            # 布局组件
    │       │   ├── Dashboard.vue        # 仪表盘
    │       │   ├── StudentManage.vue     # 学生管理
    │       │   ├── DormitoryManage.vue   # 宿舍管理
    │       │   ├── RepairManage.vue      # 报修管理
    │       │   └── NoticeManage.vue      # 公告管理
    │       ├── student/                  # 学生端页面
    │       │   ├── Layout.vue            # 布局组件
    │       │   ├── Home.vue              # 首页
    │       │   ├── Dormitory.vue         # 宿舍信息
    │       │   ├── Repair.vue            # 报修申请
    │       │   ├── Notice.vue            # 公告通知
    │       │   └── Profile.vue           # 个人信息
    │       └── common/                   # 公共页面
    │           ├── Login.vue             # 登录页
    │           └── Register.vue           # 注册页（如需要）
    ├── package.json                      # 依赖配置
    ├── vite.config.js                    # Vite 配置
    └── tailwind.config.cjs               # Tailwind CSS 配置
```

## 🚀 快速开始

### 环境要求

- **JDK**: 17+
- **Node.js**: 16+
- **MySQL**: 8.0+
- **Redis**: 5.0+
- **RabbitMQ**: 3.11+ (可选，如不需要消息队列功能可关闭)
- **Maven**: 3.6+

### 1. 克隆项目

```bash
git clone <repository-url>
cd dormitory
```

### 2. 数据库初始化

```bash
# 执行 SQL 脚本创建数据库和表
mysql -u root -p < dormitory-backend/src/main/resources/sql/schema.sql
```

或者手动执行：
1. 打开 MySQL 客户端
2. 执行 `dormitory-backend/src/main/resources/sql/schema.sql` 文件

### 3. 后端配置

编辑 `dormitory-backend/src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/dormitory_management?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 你的数据库密码
  
  data:
    redis:
      host: localhost
      port: 6379
      password: 你的Redis密码（如果有）
      database: 8
  
  rabbitmq:
    enabled: true  # 如果不需要消息队列，设置为 false
    host: localhost
    port: 5672
    username: guest
    password: guest
```

### 4. 启动后端服务

```bash
cd dormitory-backend

# 方式一：使用 Maven 直接运行
mvn clean install
mvn spring-boot:run

# 方式二：打包后运行
mvn clean package
java -jar target/dormitory-management-1.0.0.jar
```

后端服务启动后：
- 服务地址：`http://localhost:8080`
- API 基础路径：`http://localhost:8080/api`
- 接口文档：`http://localhost:8080/api/doc.html`
- Druid 监控：`http://localhost:8080/api/druid` (用户名/密码：admin/admin)

### 5. 前端配置

编辑 `dormitory-frontend/vite.config.js`（如需要修改代理地址）：

```javascript
server: {
  port: 3000,
  proxy: {
    '/api': {
      target: 'http://localhost:8080',  // 后端服务地址
      changeOrigin: true
    }
  }
}
```

### 6. 启动前端服务

```bash
cd dormitory-frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端服务启动后：
- 访问地址：`http://localhost:3000`

### 7. 构建生产版本

```bash
# 前端构建
cd dormitory-frontend
npm run build

# 构建产物在 dist/ 目录
```

## 👤 默认账号

系统初始化后，可以通过数据库脚本或注册功能创建账号。以下是测试账号示例：

### 管理员账号
- **用户名**：`admin`
- **密码**：123456
- **角色**：管理员 (ADMIN)

### 维修人员账号
- **用户名**：`staff001`
- **密码**：123456
- **角色**：维修人员 (STAFF)

### 学生账号
- **学号**：`2025001`
- **密码**：123456
- **角色**：学生 (STUDENT)

> ⚠️ **注意**：生产环境请务必修改默认密码！

## 📊 数据库设计

系统包含以下核心数据表：

1. **admin_user** - 管理员表
2. **maintenance_staff** - 维修人员表
3. **student** - 学生表
4. **building** - 宿舍楼表
5. **dormitory** - 宿舍表
6. **dorm_assign** - 宿舍分配表
7. **repair_request** - 报修申请表
8. **notice** - 通知公告表
9. **operation_log** - 操作日志表
10. **message_notification** - 消息通知表

详细表结构请查看 `dormitory-backend/src/main/resources/sql/schema.sql`

### 核心业务状态说明

#### 报修状态
- `0` - 待审核
- `1` - 已接受（已分配维修人员）
- `2` - 处理中
- `3` - 已完成
- `4` - 已拒绝

#### 公告类型
- `1` - 系统公告
- `2` - 宿舍公告
- `3` - 报修公告
- `4` - 其他公告

## 🔔 消息队列场景

系统使用 RabbitMQ 实现异步消息通知，提升用户体验：

### 报修提交流程
1. 学生提交报修申请
2. 系统发送消息到报修队列 (`repair.submit.queue`)
3. 消费者异步通知所有在线管理员

### 报修处理流程
1. 管理员/维修人员处理报修申请
2. 系统发送消息到处理队列 (`repair.handle.queue`)
3. 消费者异步通知对应学生

### 公告发布流程
1. 管理员发布公告
2. 系统发送消息到公告队列 (`notice.publish.queue`)
3. 消费者根据目标角色异步通知用户

> 💡 **提示**：如果不需要消息队列功能，可以在 `application.yml` 中设置 `spring.rabbitmq.enabled: false`

## 🔐 权限控制

系统基于 Sa-Token 实现权限认证，支持三种角色：

### 角色说明

| 角色 | 标识 | 权限说明 |
|------|------|----------|
| 管理员 | ADMIN | 拥有所有管理权限，可以管理学生、宿舍、报修、公告等 |
| 维修人员 | STAFF | 可以查看和处理分配给自己的报修任务 |
| 学生 | STUDENT | 可以查看个人信息、提交报修、查看公告等 |

### Token 配置
- **Token 名称**：`Authorization`
- **Token 前缀**：`Bearer`
- **Token 有效期**：30天
- **临时有效期**：30分钟无操作过期
- **存储方式**：Redis

### 接口权限
- 所有接口（除登录、注册外）都需要携带 Token
- Token 格式：`Authorization: Bearer {token}`
- 前端会自动在请求头中添加 Token

## 📝 API 接口规范

### 统一响应格式

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1234567890
}
```

### 响应码说明

| 响应码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 400 | 请求参数错误 |
| 401 | 未登录或 Token 失效 |
| 403 | 无权限访问 |
| 500 | 服务器内部错误 |

### 主要 API 接口

#### 认证相关
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/logout` - 用户登出
- `GET /api/auth/current` - 获取当前用户信息

#### 学生管理
- `GET /api/student/page` - 分页查询学生
- `GET /api/student/{id}` - 查询学生详情
- `POST /api/student` - 新增学生
- `PUT /api/student` - 更新学生信息
- `DELETE /api/student/{id}` - 删除学生

#### 宿舍管理
- `GET /api/dormitory/page` - 分页查询宿舍
- `GET /api/dormitory/{id}` - 查询宿舍详情
- `POST /api/dormitory/assign` - 分配宿舍
- `PUT /api/dormitory/assign` - 调整宿舍

#### 报修管理
- `GET /api/repair/page` - 分页查询报修
- `POST /api/repair/submit` - 提交报修申请
- `POST /api/repair/audit` - 审核报修申请（管理员）
- `PUT /api/repair/start/{id}` - 开始处理（维修人员）
- `PUT /api/repair/complete` - 完成报修（维修人员）

#### 公告管理
- `GET /api/notice/page` - 分页查询公告
- `POST /api/notice/publish` - 发布公告
- `PUT /api/notice` - 更新公告
- `DELETE /api/notice/{id}` - 删除公告

> 📖 完整的 API 文档请访问：`http://localhost:8080/api/doc.html`

## 🎯 开发指南

### 后端开发

#### 代码分层规范
1. **Controller 层**：接收请求，参数校验，调用 Service
2. **Service 层**：业务逻辑处理
3. **Mapper 层**：数据库操作（MyBatis Flex）
4. **DTO**：接收前端参数（请求对象）
5. **VO**：返回给前端的数据（响应对象）
6. **Entity**：数据库实体映射

#### 统一异常处理
- 业务异常：抛出 `BusinessException`
- 全局异常处理：`GlobalExceptionHandler` 统一处理

#### 日志记录
- 使用 `@Slf4j` 注解
- 日志级别：DEBUG（开发）、INFO（生产）
- 日志文件：`logs/dormitory-management.log`

### 前端开发

#### 组件开发规范
- 使用 Vue 3 Composition API
- 组件命名使用 PascalCase
- 文件名和组件名保持一致

#### API 调用规范
- 统一在 `api/` 目录定义接口
- 按模块分文件管理
- 使用封装的 `request` 工具

#### 状态管理
- 需要跨组件共享的状态使用 Pinia
- 组件内部状态使用 `ref`/`reactive`

#### 路由配置
- 使用懒加载：`() => import('@/views/xxx.vue')`
- 配置正确的 `meta` 信息（角色权限）