# SmartDorm

**Repository Path**: gitBVBV/smart-dorm

## Basic Information

- **Project Name**: SmartDorm
- **Description**: No description available
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SmartDorm — 智慧宿舍管理系统

## 1. 项目概述

SmartDorm 是一套面向高校的**智慧宿舍管理系统**，提供宿舍楼栋管理、学生入住/退宿/调宿、归寝考勤、报修管理、巡查记录、违规用电管理、水电用量管理、公告通知等核心功能。

系统采用 **前后端分离** 架构：
- **后端 (api/)**：Spring Boot 3.2.5 + MyBatis Plus + JWT 认证
- **前端 (app/)**：Android 原生应用（Java），Material Design 3 风格

**三种用户角色**：

| 角色 | userType | 说明 |
|------|----------|------|
| 管理员 (Admin) | 1 | 全局管理：楼栋/宿舍/床位/学生/宿管 CRUD、宿舍分配、公告发布、数据统计 |
| 宿管 (Keeper) | 2 | 辖区管理：归寝考勤、报修处理、巡查记录、违规用电记录 |
| 学生 (Student) | 3 | 个人服务：查看宿舍信息、每日打卡、报修/调宿/退宿申请、查看公告 |

---

## 2. 项目目录结构

```
smart-dorm/
├── api/                          # 后端 Spring Boot 工程
│   ├── pom.xml                   # Maven 构建配置
│   └── src/main/
│       ├── java/com/ys/smart/dorm/
│       │   ├── SmartDormApplication.java      # Spring Boot 启动类
│       │   ├── common/           # 公共类（统一响应、异常处理）
│       │   ├── config/           # 配置类（Web、MyBatis、密码加密等）
│       │   ├── controller/       # 控制器层（12 个 Controller）
│       │   ├── entity/           # 实体类（28 个 Entity，对应 28 张数据表）
│       │   ├── mapper/           # MyBatis Mapper 接口（28 个 Mapper）
│       │   ├── security/         # 安全模块（JWT Token、登录拦截器、ThreadLocal 用户上下文）
│       │   └── service/          # 业务服务层（目前仅 SysUserService）
│       └── resources/
│           └── application.yml   # Spring Boot 配置文件
│
├── app/                          # Android 前端工程
│   ├── build.gradle.kts          # App 模块构建配置
│   └── src/main/
│       ├── AndroidManifest.xml
│       ├── java/com/ys/smartdorm/
│       │   ├── SmartDormApp.java          # Application 类
│       │   ├── api/ApiClient.java         # Retrofit 网络客户端
│       │   ├── api/ApiService.java        # API 接口定义（Retrofit 接口）
│       │   ├── model/                     # 数据模型（与后端 entity 对应）
│       │   ├── ui/                        # UI 层
│       │   │   ├── login/LoginActivity.java       # 登录页
│       │   │   ├── MainActivity.java              # 主页面（底部导航）
│       │   │   ├── admin/                         # 管理员页面
│       │   │   │   ├── AdminHomeFragment.java     #   管理后台首页
│       │   │   │   ├── BuildingManageFragment.java #   楼栋/宿舍管理
│       │   │   │   └── UserManageFragment.java    #   学生/宿管管理
│       │   │   ├── keeper/                        # 宿管页面
│       │   │   │   ├── KeeperHomeFragment.java    #   宿管工作台
│       │   │   │   ├── NightCheckFragment.java    #   归寝考勤
│       │   │   │   └── InspectionFragment.java    #   巡查与报修
│       │   │   ├── student/                       # 学生页面
│       │   │   │   ├── StudentHomeFragment.java   #   学生首页（宿舍信息+公告）
│       │   │   │   ├── CheckinFragment.java       #   每日打卡
│       │   │   │   └── ServiceFragment.java       #   服务申请（报修/调宿/退宿）
│       │   │   └── profile/ProfileFragment.java   # 个人中心（修改密码/退出）
│       │   └── utils/                            # 工具类
│       │       ├── ApiCallback.java               #   API 回调封装
│       │       ├── MaterialUtils.java             #   Material UI 动态构建工具
│       │       └── TokenManager.java              #   Token 本地存储管理
│       └── res/                                   # 资源文件
│           ├── layout/              # XML 布局文件（4 个）
│           ├── menu/                # 底部导航菜单（3 套，按角色）
│           ├── drawable/            # 矢量图标
│           ├── anim/                # Fragment 切换动画
│           ├── color/               # 颜色选择器
│           ├── values/              # 颜色/字符串/主题定义
│           └── mipmap-*/            # 应用图标
│
├── .init/init.sql                 # 数据库初始化脚本（9 大模块，28 张表）
├── build.gradle.kts               # 根项目构建配置
├── settings.gradle.kts            # Gradle 项目设置
├── gradle/libs.versions.toml      # 版本目录（统一依赖管理）
└── gradle/wrapper/                # Gradle Wrapper
```

---

## 3. 技术栈

### 3.1 后端 (api/)

| 技术 | 版本 | 用途 |
|------|------|------|
| Java | 17 | 运行语言 |
| Spring Boot | 3.2.5 | Web 框架 |
| MyBatis Plus | 3.5.6 | ORM 框架（简化 CRUD） |
| MySQL Connector/J | (runtime) | 数据库驱动 |
| jjwt | 0.12.5 | JSON Web Token 认证 |
| spring-security-crypto | (Spring Boot 3.2.5 管理) | BCrypt 密码加密 |
| Lombok | (optional) | 简化实体类 Getter/Setter |
| Spring Boot Validation | (Spring Boot 3.2.5 管理) | 参数校验 |

### 3.2 Android 前端 (app/)

| 技术 | 版本 | 用途 |
|------|------|------|
| Java | 11 | 运行语言 |
| Android SDK | min 24 / target 36 | Android 平台 |
| Retrofit 2 | 2.9.0 | HTTP 网络请求 |
| OkHttp | 4.12.0 | HTTP 客户端（拦截器/日志） |
| Gson | 2.10.1 | JSON 序列化/反序列化 |
| Material Components | 1.10.0 | Material Design 3 UI |
| Navigation Fragment | 2.7.6 | Fragment 导航 |
| Lifecycle ViewModel | 2.7.0 | 生命周期管理 |
| AGP | 9.0.0 | Android 构建插件 |

---

## 4. 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                     Android 客户端 (app/)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Admin UI │  │Keeper UI │  │Student UI│  │ Profile  │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
│       └──────────────┴──────────────┴────────────┘             │
│                          │                                      │
│              ┌───────────▼───────────┐                          │
│              │  Retrofit + OkHttp    │   (header: token)        │
│              └───────────┬───────────┘                          │
└──────────────────────────┼──────────────────────────────────────┘
                           │  HTTP REST (JSON)
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│                    Spring Boot 后端 (api/)                       │
│                                                                  │
│  ┌────────┐   ┌────────────────┐   ┌──────────────────────┐    │
│  │ Filter │──▶│LoginInterceptor│──▶│   Controller 层      │    │
│  │ (CORS) │   │  (JWT 验证)    │   │  (12 个 Controller)   │    │
│  └────────┘   └───────┬────────┘   └──────────┬───────────┘    │
│                       │                        │                 │
│              ┌────────▼────────┐    ┌──────────▼──────────┐     │
│              │   TokenUtil     │    │  Service 层          │     │
│              │ (JWT 生成/解析)  │    │ (SysUserService)     │     │
│              └─────────────────┘    └──────────┬──────────┘     │
│                                                │                 │
│                                    ┌───────────▼──────────┐     │
│                                    │  Mapper 层            │     │
│                                    │ (MyBatis Plus, 28个)  │     │
│                                    └───────────┬──────────┘     │
│                                                │                 │
└────────────────────────────────────────────────┼─────────────────┘
                                                 │
                                                 ▼
                                    ┌───────────────────────┐
                                    │   MySQL (smart_dorm)   │
                                    │      28 张数据表       │
                                    └───────────────────────┘
```

### 请求认证流程

```
1. 客户端 POST /api/login {username, password}
2. 服务端验证密码(BCrypt) → 生成 JWT Token → 存入 sys_user.token 字段
3. 客户端保存 Token 到 SharedPreferences
4. 后续请求 OkHttp 拦截器自动附加 header: token
5. LoginInterceptor 拦截 /api/** 请求（排除 login/register/file）
   → 解析 Token → 验证有效性 → 将 userId/username/userType 写入 CurrentUser (ThreadLocal)
6. 请求结束后 afterCompletion 清除 ThreadLocal
```

---

## 5. 后端文件详解

### 5.1 启动类与配置

| 文件 | 说明 |
|------|------|
| `SmartDormApplication.java` | Spring Boot 启动入口，声明 `@MapperScan` 扫描 mapper 包 |
| `application.yml` | 核心配置：端口 5566，MySQL 数据源，JWT secret/过期时间(7天)，文件上传 10MB 限制，MyBatis-Plus 逻辑删除/驼峰命名/控制台 SQL 日志 |
| `pom.xml` | Maven 构建文件，声明 Spring Boot 3.2.5、MyBatis-Plus 3.5.6、jjwt 0.12.5、MySQL Connector、BCrypt、Lombok 等依赖 |

#### 配置类 (`config/`)

| 文件 | 说明 |
|------|------|
| `WebConfig.java` | 实现 `WebMvcConfigurer`：① 全局 CORS 跨域放行 ② 注册 `LoginInterceptor` 拦截 `/api/**`（排除 login/register/file） ③ 映射 `/uploads/**` 到本地 `./uploads/` 目录静态资源 |
| `MybatisPlusConfig.java` | 注册 MyBatis-Plus 分页插件（`PaginationInnerInterceptor`），数据库类型指定 MySQL |
| `PasswordConfig.java` | 注册 `BCryptPasswordEncoder` Bean，用于密码加密和验证 |
| `MetaObjectHandlerConfig.java` | MyBatis-Plus 自动填充处理器：插入时自动填充 `createTime` 和 `updateTime`，更新时自动填充 `updateTime` |

### 5.2 安全模块 (`security/`)

| 文件 | 说明 |
|------|------|
| `TokenUtil.java` | JWT 工具类：`generateToken(userId, username, userType)` 生成 Token；`parseToken(token)` 解析 Claims；`validateToken(token)` 验证有效性；从 `application.yml` 读取 `jwt.secret` 和 `jwt.expiration`（7天） |
| `LoginInterceptor.java` | 拦截器 `HandlerInterceptor`：preHandle 中从 header 取 `token` → 验证有效性 → 将 userId/username/userType 写入 `CurrentUser` (ThreadLocal)；OPTIONS 预检请求直接放行；afterCompletion 中清除 ThreadLocal |
| `CurrentUser.java` | 基于 ThreadLocal 的用户上下文工具：`getUserId()`/`getUsername()`/`getUserType()` 供业务代码获取当前登录用户信息 |

### 5.3 公共类 (`common/`)

| 文件 | 说明 |
|------|------|
| `Result.java` | 统一响应体：`code`(int)、`msg`(String)、`data`(泛型 T)；静态工厂方法 `ok(data)`、`ok()`、`error(code, msg)`、`error(msg)` |
| `PageResult.java` | 分页响应体：`total`、`page`、`size`、`list`(泛型 List)；用于分页查询的统一返回格式 |
| `AppException.java` | 自定义业务异常，继承 `RuntimeException`，携带 `code` 状态码；业务层出现预期错误时抛出 |
| `GlobalExceptionHandler.java` | `@RestControllerAdvice` 全局异常处理：捕获 `AppException` → 返回对应 code/msg；捕获 `Exception` → 打日志并返回 500 "服务器内部错误" |

### 5.4 控制器层 (`controller/`)

每个 Controller 对应一个业务模块，路径以 `/api` 为前缀。

| 文件 | 映射路径 | 主要功能 |
|------|----------|----------|
| `AuthController.java` | `/api/login`, `/api/logout`, `/api/user/info`, `/api/user/password` | 登录认证、登出、获取当前用户信息、修改密码 |
| `BuildingController.java` | `/api/building/**`, `/api/dormitory/**`, `/api/bed/**` | 楼栋 CRUD、宿舍 CRUD（添加时自动创建床位）、床位查询/更新/删除 |
| `StudentDormController.java` | `/api/student/**`, `/api/keeper/**`, `/api/allocation/**` | 学生信息 CRUD（联动创建 sys_user）、宿管信息 CRUD（联动创建 sys_user）、宿舍分配（分配床位→更新床位状态→更新宿舍已用床位→更新学生住宿信息）/取消分配 |
| `AnnouncementController.java` | `/api/announcement/**` | 公告 CRUD、按用户范围推送公告（全局/按楼栋/按宿舍/按学生）、公告已读标记 |
| `RepairController.java` | `/api/repair/**` | 报修申请提交、宿管接单、完成报修、取消报修 |
| `StudentServiceController.java` | `/api/student-service/**`, `/api/checkin/**`, `/api/change-dorm/**`, `/api/leave-dorm/**` | 学生综合服务：通用服务申请、每日打卡（防重复）、调宿申请及审批（更新床位/宿舍状态）、退宿申请及审批（释放床位/清除住宿信息） |
| `InspectionController.java` | `/api/inspection/**` | 巡查记录 CRUD |
| `NightCheckController.java` | `/api/night-check/**` | 归寝考勤：单条录入、批量录入（List<Map>） |
| `IllegalElectricController.java` | `/api/illegal-electric/**` | 违规用电记录 CRUD 和已处理标记 |
| `WaterElectricController.java` | `/api/water-electric/usage/**`, `/api/water-electric/param/**` | 水电用量记录 CRUD、水电参数配置（如单价）CRUD |
| `FileController.java` | `/api/file/**` | 文件上传（UUID 重命名存 `./uploads/`）、文件查询、文件删除（同时删除物理文件和数据库记录） |
| `SysVersionController.java` | `/api/version/**` | 系统版本管理 CRUD |

### 5.5 实体类 (`entity/`)

共 28 个 Entity，每个使用 Lombok `@Data` 注解，通过 `@TableName` 映射数据库表，`@TableId(type = IdType.AUTO)` 声明自增主键，`@TableField(fill = ...)` 声明自动填充字段。

#### 系统权限模块 (5 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `SysUser` | sys_user | username, password(BCrypt加密), token, phone, email, userType(1/2/3), status, lastLoginTime |
| `SysRole` | sys_role | roleName, roleCode(ADMIN/DORM_KEEPER/STUDENT), description, status |
| `SysPermission` | sys_permission | parentId, name, code, type(1菜单/2按钮), path, method, url, sort |
| `SysUserRole` | sys_user_role | userId, roleId |
| `SysRolePermission` | sys_role_permission | roleId, permissionId |

#### 系统管理模块 (3 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `SysFile` | sys_file | fileName, filePath, fileType, fileSize, uploadUserId |
| `SysOperationLog` | sys_operation_log | userId, username, module, operation, method, params, ip, status, errorMsg |
| `SysVersion` | sys_version | versionNo, content, publishTime, publisherId, status |

#### 基础信息管理模块 (5 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `Building` | building | buildingName, buildingCode, description, status |
| `Dormitory` | dormitory | buildingId, dormitoryNo, capacity, usedBeds, floor, status |
| `Bed` | bed | dormitoryId, bedNo, status(0空闲/1占用/2维修) |
| `StudentInfo` | student_info | userId, studentNo, name, gender, major, grade, className, bedId, dormitoryId, buildingId, checkinDate, leaveDate, status, emergencyContact |
| `DormKeeperInfo` | dorm_keeper_info | userId, name, phone, responsibleBuildingIds(逗号分隔) |

#### 住宿管理模块 (5 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `RoomAllocation` | room_allocation | dormitoryId, bedId, studentId, operatorId, allocationDate, status(1已分配/2已变更) |
| `ChangeDormApply` | change_dorm_apply | studentId, oldDormitoryId, oldBedId, newDormitoryId, newBedId, reason, status(0待审/1通过/2拒绝), approveTime, approveUserId |
| `LeaveDormApply` | leave_dorm_apply | studentId, dormitoryId, bedId, reason, status(0待审/1通过/2拒绝) |
| `AccommodationStat` | accommodation_stat | statDate, buildingId, dormCount, usedDormCount, bedCount, usedBedCount, studentCount |
| `StudentCheckinRecord` | student_checkin_record | studentId, dormitoryId, checkinDate, checkinTime, checkinType(2手动), status, remark |

#### 公告管理模块 (3 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `Announcement` | announcement | title, content, publishUserId, publishTime, isGlobal(0/1), status |
| `AnnouncementScope` | announcement_scope | announcementId, scopeType(1楼栋/2宿舍/3学生), scopeId |
| `AnnouncementReadRecord` | announcement_read_record | announcementId, userId, readTime |

#### 宿管业务模块 (3 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `RepairApply` | repair_apply | dormitoryId, studentId, repairType, description, fileId, status(0待接单/1处理中/2已完成/3已关闭), handlerId, handleTime, finishTime |
| `InspectionRecord` | inspection_record | dormitoryId, keeperId, inspectionTime, result, violationStatus(0/1), fileId |
| `NightCheckRecord` | night_check_record | dormitoryId, checkDate, keeperId, studentId, status(0未归寝/1已归寝/2请假), remark |

#### 水电模块 (3 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `WaterElectricUsage` | water_electric_usage | dormitoryId, usageMonth, waterUsage(吨), electricUsage(度) |
| `WaterElectricParam` | water_electric_param | paramKey, paramValue, description |
| `IllegalElectricRecord` | illegal_electric_record | dormitoryId, studentId, violationType, description, recordTime, fileId, operatorId, status(0未处理/1已处理) |

#### 学生服务模块 (1 个)
| Entity | 表名 | 核心字段 |
|--------|------|----------|
| `StudentServiceApply` | student_service_apply | studentId, applyType(1报修/2调宿/3退宿), description, status(0待审/1审核中/2通过/3拒绝), processTime, processUserId |

### 5.6 Mapper 层 (`mapper/`)

共 28 个 Mapper 接口，与 Entity 一一对应。每个 Mapper 继承 MyBatis-Plus 的 `BaseMapper<T>`，自动拥有基本的 CRUD 能力（insert/update/deleteById/selectById/selectList/selectPage 等），无需编写 XML。

### 5.7 服务层 (`service/`)

| 文件 | 说明 |
|------|------|
| `SysUserService.java` | 用户服务接口：login（密码验证+JWT生成+角色/个人信息查询）、logout（清除 token）、updatePassword（BCrypt 验证旧密码后更新）、pageUsers（模糊搜索分页）、addUser（创建用户+分配角色）、updateUser、deleteUser（级联删除角色关联）、updateUserStatus（启用/禁用） |
| `SysUserServiceImpl.java` | 以上接口的实现，注入 `PasswordEncoder`、`TokenUtil`、`SysUserRoleMapper`、`SysRoleMapper`、`StudentInfoMapper`、`DormKeeperInfoMapper` |

> 注：当前大部分 Controller 直接调用 Mapper，未经过 Service 层封装。这是项目初期常见的简化写法。

---

## 6. Android 前端文件详解

### 6.1 核心类

| 文件 | 说明 |
|------|------|
| `SmartDormApp.java` | Application 入口，初始化 `TokenManager` (SharedPreferences) |
| `ApiClient.java` | Retrofit 单例：baseUrl 指向 `http://192.168.0.64:5566/`；配置 OkHttp 拦截器（自动注入 Token header + HTTP 日志）；30 秒超时；Gson 转换器 |
| `ApiService.java` | Retrofit 接口定义，声明所有 API 端点（约 35 个方法），涵盖认证、楼栋、宿舍、床位、学生、宿管、分配、考勤、巡查、报修、违规用电、公告、打卡、服务申请、文件上传等 |

### 6.2 数据模型 (`model/`)

与后端 Entity 结构对应的 POJO 类，部分增加了 UI 辅助方法（如 `getStatusText()`）：

| 文件 | 对应后端 Entity |
|------|----------------|
| `Building.java` | Building |
| `Dormitory.java` | Dormitory |
| `Bed.java` | Bed |
| `StudentInfo.java` | StudentInfo |
| `DormKeeperInfo.java` | DormKeeperInfo |
| `RepairApply.java` | RepairApply |
| `InspectionRecord.java` | InspectionRecord |
| `NightCheckRecord.java` | NightCheckRecord |
| `IllegalElectricRecord.java` | IllegalElectricRecord |
| `Announcement.java` | Announcement |
| `StudentCheckinRecord.java` | StudentCheckinRecord |
| `StudentServiceApply.java` | StudentServiceApply |
| `Result.java` | 通用响应体包装 |
| `PageResult.java` | 分页响应体包装 |

### 6.3 UI 层 (`ui/`)

#### 6.3.1 登录
| 文件 | 说明 |
|------|------|
| `LoginActivity.java` | 登录页面：已登录则跳过进主页；输入账号密码 → 调用 `/api/login` → 保存 token 到 SharedPreferences → 跳转 MainActivity |

#### 6.3.2 主框架
| 文件 | 说明 |
|------|------|
| `MainActivity.java` | 主页面：根据 userType 加载不同底部导航菜单（3 套 menu 资源），Fragment 切换带左右滑动动画；edge-to-edge 沉浸式适配 |

#### 6.3.3 管理端 (Admin)
| 文件 | 说明 |
|------|------|
| `AdminHomeFragment.java` | 管理后台首页仪表盘：四张统计卡片（学生总数/楼栋总数/宿舍总数/待处理报修），分别调用列表接口取 total |
| `BuildingManageFragment.java` | 楼栋/宿舍管理：顶部横向滚动芯片选择楼栋 → 展示该楼栋下的宿舍列表（宿舍号+床位占用+楼层）→ 点击宿舍弹出床位详情 BottomSheet；支持添加楼栋、添加宿舍（自动生成床位） |
| `UserManageFragment.java` | 人员管理：Tab 切换学生/宿管列表 → 长按弹出删除确认 → FAB 按钮添加学生（用户名/学号/姓名/性别/专业/年级/班级/手机号）或宿管（用户名/姓名/手机号/负责楼栋ID） |

#### 6.3.4 宿管端 (Keeper)
| 文件 | 说明 |
|------|------|
| `KeeperHomeFragment.java` | 宿管工作台：三张统计卡片（待处理报修/今日查寝记录数/待巡查间数）+ 近期报修申请列表 |
| `NightCheckFragment.java` | 归寝考勤：选择日期 → 选择楼栋 → 选择宿舍 → 加载该宿舍学生列表 → 每人单选框（未归寝/已归寝/请假）→ 批量提交（逐条调用 API，递归提交直到全部完成） |
| `InspectionFragment.java` | 巡查与报修（双 Tab）：Tab1 巡查记录（列表+新增）→ Tab2 报修处理（待接单可点击接单，处理中可点击完成）；底部违章用电独立区域（列表+新增） |

#### 6.3.5 学生端 (Student)
| 文件 | 说明 |
|------|------|
| `StudentHomeFragment.java` | 学生首页：显示"我的宿舍"卡片（楼栋+宿舍号+床位号，链式查询 building→dormitory→bed）+ 公告通知列表（按用户范围推送）+ 快捷操作按钮（报修/调宿/退宿） |
| `CheckinFragment.java` | 每日打卡：显示当日打卡状态（已打卡/未打卡）+ 打卡按钮（防重复提交）+ 近期打卡记录列表 |
| `ServiceFragment.java` | 服务申请：三个操作按钮（报修弹窗含类型下拉选择、调宿弹窗含目标宿舍/床位/原因、退宿弹窗含原因）+ "我的申请"列表（显示申请类型+状态+时间） |

#### 6.3.6 个人中心
| 文件 | 说明 |
|------|------|
| `ProfileFragment.java` | 个人中心：显示账号和角色；修改密码（BottomSheet 含新旧密码输入+确认）；退出登录（调用 logout API + 清除本地 token → 跳回登录页） |

### 6.4 工具类 (`utils/`)

| 文件 | 说明 |
|------|------|
| `TokenManager.java` | 单例，基于 SharedPreferences 的本地存储：保存/读取 token/userId/username/userType/roleCode；`isLoggedIn()` 判断登录状态；`clear()` 清除所有缓存 |
| `ApiCallback.java` | Retrofit Callback 抽象封装：自动处理 `Result<T>` 响应，成功调用 `onSuccess(data)`，失败调用 `onError(msg)`（默认 Toast 提示）；增加 Fragment `isAdded()` 检查防止内存泄漏 |
| `MaterialUtils.java` | Material Design 动态 UI 工具：`dp()` 像素转换、`card()` 创建卡片、`btn()` 创建按钮、`input()` 创建输入框、`bottomSheet()` 创建底部弹窗（标题+可滚动内容+确认/取消按钮+自适应高度）、`bottomSheetItems()` 创建选项列表弹窗 |

### 6.5 资源文件 (`res/`)

| 路径 | 说明 |
|------|------|
| `layout/activity_login.xml` | 登录页布局：渐变装饰条 + 应用图标 + "智慧宿舍"标题 + 账号/密码输入框 + 登录按钮 |
| `layout/activity_main.xml` | 主页面布局：Fragment 容器 + 底部导航栏 |
| `layout/fragment_profile.xml` | 个人中心布局：头像 + 用户名 + 角色 + 修改密码/退出登录按钮 |
| `layout/dialog_change_password.xml` | 修改密码弹窗布局：旧密码/新密码/确认密码三个输入框 |
| `menu/bottom_nav_admin.xml` | 管理员底部导航：首页、人员管理、楼栋管理、我的 |
| `menu/bottom_nav_keeper.xml` | 宿管底部导航：首页、归寝考勤、巡查报修、我的 |
| `menu/bottom_nav_student.xml` | 学生底部导航：首页、打卡、服务、我的 |
| `drawable/ic_*.xml` | 矢量图标（首页/人员/建筑/锁/打卡/服务/清单/巡查/添加） |
| `anim/slide_in_*.xml` | Fragment 切换动画（左滑入/右滑入/左滑出/右滑出） |
| `color/bottom_nav_selector.xml` | 底部导航图标/文字选中状态颜色 |
| `color/box_stroke_selector.xml` | 输入框边框获得焦点颜色 |
| `color/icon_tint_selector.xml` | 图标颜色选择器 |
| `values/colors.xml` | 颜色定义：Primary(深海军蓝 #1A1A2E)、Success(绿 #00B894)、Error(橙红 #E17055)、背景灰 #F0F2F5 等 |
| `values/themes.xml` | Material 3 主题：NoActionBar、透明状态栏、自定义主色/辅色/错误色 |
| `values/strings.xml` | 应用名 "SmartDorm" |

---

## 7. 数据库设计

数据库脚本位于 `.init/init.sql`，包含 **9 大模块、28 张数据表**，全部使用 InnoDB 引擎 + utf8mb4 字符集。

### 7.1 模块总览

| 模块 | 表数量 | 包含表 |
|------|--------|--------|
| 1. 权限基础模块 | 5 | sys_user, sys_role, sys_permission, sys_user_role, sys_role_permission |
| 2. 文件管理模块 | 1 | sys_file |
| 3. 基础信息管理 | 5 | building, dormitory, bed, student_info, dorm_keeper_info |
| 4. 住宿管理模块 | 4 | room_allocation, change_dorm_apply, leave_dorm_apply, accommodation_stat |
| 5. 水电安全管理 | 3 | water_electric_usage, water_electric_param, illegal_electric_record |
| 6. 系统管理模块 | 2 | sys_operation_log, sys_version |
| 7. 公告管理模块 | 3 | announcement, announcement_scope, announcement_read_record |
| 8. 宿管端业务 | 3 | night_check_record, repair_apply, inspection_record |
| 9. 学生端业务 | 2 | student_service_apply, student_checkin_record |

### 7.2 核心表关系

```
sys_user ──┬── sys_user_role ──── sys_role ──── sys_role_permission ──── sys_permission
           │
           ├── student_info ──── bed / dormitory / building
           │
           ├── dorm_keeper_info
           │
           └── announcement ──── announcement_scope / announcement_read_record

building ──── dormitory ──── bed

dormitory ──── room_allocation ──── student_info
           │
           ├── repair_apply (student_id)
           ├── night_check_record
           ├── inspection_record
           ├── illegal_electric_record
           └── water_electric_usage

student_info ──── student_checkin_record
              │
              ├── change_dorm_apply
              ├── leave_dorm_apply
              └── student_service_apply
```

### 7.3 初始化数据

- 3 个默认角色：ADMIN（管理员）、DORM_KEEPER（宿管）、STUDENT（学生）
- 1 个默认管理员账号：`admin` / `admin123`（BCrypt 加密），关联 ADMIN 角色

---

## 8. API 路由总览

### 认证相关
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/login` | 登录 |
| POST | `/api/logout` | 登出 |
| GET | `/api/user/info` | 获取当前用户信息 |
| PUT | `/api/user/password` | 修改密码 |

### 楼栋 / 宿舍 / 床位
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/building/list` | 楼栋列表 |
| GET | `/api/building/{id}` | 楼栋详情 |
| POST | `/api/building` | 新增楼栋 |
| PUT | `/api/building` | 更新楼栋 |
| DELETE | `/api/building/{id}` | 删除楼栋 |
| GET | `/api/dormitory/list?buildingId=&page=&size=` | 宿舍分页列表 |
| GET | `/api/dormitory/{id}` | 宿舍详情 |
| POST | `/api/dormitory` | 新增宿舍（自动创建床位） |
| PUT | `/api/dormitory` | 更新宿舍 |
| DELETE | `/api/dormitory/{id}` | 删除宿舍（连带床位） |
| GET | `/api/bed/list?dormitoryId=` | 床位列表 |
| GET | `/api/bed/{id}` | 床位详情 |
| PUT | `/api/bed` | 更新床位 |
| DELETE | `/api/bed/{id}` | 删除床位 |

### 学生 / 宿管 / 分配
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/student/list?keyword=&page=&size=` | 学生列表 |
| GET | `/api/student/{id}` | 学生详情 |
| POST | `/api/student` | 新增学生（创建账号+学生信息+分配角色） |
| PUT | `/api/student` | 更新学生 |
| DELETE | `/api/student/{id}` | 删除学生（级联删除关联账号） |
| GET | `/api/keeper/list?keyword=&page=&size=` | 宿管列表 |
| GET | `/api/keeper/{id}` | 宿管详情 |
| POST | `/api/keeper` | 新增宿管（创建账号+宿管信息+分配角色） |
| PUT | `/api/keeper` | 更新宿管 |
| DELETE | `/api/keeper/{id}` | 删除宿管 |
| GET | `/api/allocation/list?dormitoryId=&page=&size=` | 分配记录 |
| POST | `/api/allocation` | 分配宿舍（占用床位→更新计数→更新学生信息） |
| PUT | `/api/allocation/{id}/cancel` | 取消分配 |

### 公告
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/announcement/list?page=&size=` | 全量公告列表 |
| GET | `/api/announcement/user` | 按用户范围获取公告（多级匹配） |
| GET | `/api/announcement/{id}` | 公告详情（自动标记已读） |
| POST | `/api/announcement` | 发布公告 |
| PUT | `/api/announcement` | 更新公告 |
| DELETE | `/api/announcement/{id}` | 删除公告 |
| PUT | `/api/announcement/{id}/status` | 修改公告状态 |

### 报修
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/repair/list?status=&dormitoryId=&page=&size=` | 报修列表 |
| GET | `/api/repair/{id}` | 报修详情 |
| POST | `/api/repair` | 提交报修 |
| PUT | `/api/repair/handle` | 接单 |
| PUT | `/api/repair/finish` | 完成报修 |
| PUT | `/api/repair/cancel` | 取消报修 |

### 学生服务 / 打卡 / 调宿 / 退宿
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/student-service/list?status=&applyType=&page=&size=` | 服务申请列表 |
| GET | `/api/student-service/{id}` | 服务申请详情 |
| POST | `/api/student-service` | 提交服务申请 |
| PUT | `/api/student-service/process` | 处理服务申请 |
| DELETE | `/api/student-service/{id}` | 删除服务申请 |
| GET | `/api/checkin/list?studentId=&checkinDate=&page=&size=` | 打卡记录 |
| POST | `/api/checkin` | 打卡（防重复） |
| GET | `/api/checkin/today?studentId=` | 查询今日打卡状态 |
| GET | `/api/change-dorm/list?status=&page=&size=` | 调宿申请列表 |
| POST | `/api/change-dorm` | 提交调宿申请 |
| PUT | `/api/change-dorm/approve` | 审批调宿（更新床位/宿舍/学生） |
| GET | `/api/change-dorm/{id}` | 调宿详情 |
| GET | `/api/leave-dorm/list?status=&page=&size=` | 退宿申请列表 |
| POST | `/api/leave-dorm` | 提交退宿申请 |
| PUT | `/api/leave-dorm/approve` | 审批退宿（释放床位/清除住宿信息） |

### 巡查 / 归寝考勤 / 违规用电 / 水电
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST/PUT/DELETE | `/api/inspection/**` | 巡查记录 CRUD |
| GET/POST/PUT/DELETE | `/api/night-check/**` | 归寝考勤 CRUD + 批量录入 |
| GET/POST/PUT/DELETE | `/api/illegal-electric/**` | 违规用电 CRUD + 处理 |
| GET/POST/PUT/DELETE | `/api/water-electric/usage/**` | 水电用量 CRUD |
| GET/POST/PUT/DELETE | `/api/water-electric/param/**` | 水电参数 CRUD |

### 文件上传
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/file/upload` | 上传文件 (Multipart) |
| GET | `/api/file/{id}` | 文件信息 |
| DELETE | `/api/file/{id}` | 删除文件 |

### 系统版本
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/version/list?page=&size=` | 版本列表 |
| GET | `/api/version/{id}` | 版本详情 |
| POST | `/api/version` | 新增版本 |
| PUT | `/api/version` | 更新版本 |
| DELETE | `/api/version/{id}` | 删除版本 |

---

## 9. 用户角色与权限体系

```
用户类型体系：
┌─────────────┐
│ userType: 1 │ 管理员 (ADMIN)
│   全局权限   │  - 楼栋/宿舍/床位 CRUD
│             │  - 学生/宿管信息管理
│             │  - 宿舍分配/取消
│             │  - 公告发布/管理
│             │  - 数据仪表盘
│             │  - 所有宿管功能
└─────────────┘
┌─────────────┐
│ userType: 2 │ 宿管 (DORM_KEEPER)
│   辖区权限   │  - 归寝考勤记录
│             │  - 巡查记录管理
│             │  - 报修接单/处理
│             │  - 违规用电记录
│             │  - 工作台仪表盘
└─────────────┘
┌─────────────┐
│ userType: 3 │ 学生 (STUDENT)
│   个人权限   │  - 查看宿舍/床位信息
│             │  - 每日打卡
│             │  - 报修申请
│             │  - 调宿/退宿申请
│             │  - 查看公告通知
└─────────────┘
```

**认证流程**：
1. 登录时 BCrypt 验证密码 + 生成 JWT Token 存入 `sys_user.token`
2. Token 包含 claims：`sub`(userId)、`username`、`userType`
3. 客户端所有请求通过 OkHttp 拦截器自动附加 `header: token`
4. 服务端 `LoginInterceptor` 拦截 `/api/**` 请求验证 Token，用户信息写入 ThreadLocal
5. 前端 `MainActivity` 根据 `userType` 加载不同的底部导航菜单（3 套 menu xml）和首页 Fragment

---

## 10. 项目配置文件说明

### 后端 `application.yml`
```yaml
server.port: 5566                                     # 服务端口
spring.datasource: MySQL 连接                          # 数据库 smart_dorm
spring.servlet.multipart: 10MB/20MB                   # 文件上传限制
mybatis-plus:                                          # ORM 配置
  - 逻辑删除: deleted 字段, 1=删除 0=正常
  - 主键策略: auto (自增)
  - SQL 日志: stdout 控制台输出
jwt.secret: smart-dorm-jwt-secret-key-2025-...         # JWT 签名密钥
jwt.expiration: 604800000                              # Token 过期 (7天)
file.upload-path: ./uploads                            # 文件上传目录
```

### Android
- `ApiClient.java` 中 `BASE_URL = "http://192.168.0.64:5566/"`（局域网地址，需根据部署环境修改）
- `TokenManager` 使用 SharedPreferences 本地持久化登录状态
- 主题使用 Material 3 DayNight，主色为深海军蓝 `#1A1A2E`

---

## 11. 构建与运行

### 后端
```bash
cd api
mvn clean package -DskipTests
java -jar target/api-1.0-SNAPSHOT.jar
```
服务启动后监听 `http://localhost:5566`

### 数据库初始化
```bash
mysql -u root -p < .init/init.sql
```

### Android 前端
用 Android Studio 打开项目根目录，Sync Gradle，选择 `app` 模块运行到设备或模拟器。需要确保手机与后端在同一局域网，且 `ApiClient.java` 中的 `BASE_URL` 指向正确的后端 IP。