宿舍房间管理API文档
目录
1. 宿舍楼树形结构
1.1 获取宿舍楼树形结构
接口说明
该接口用于获取宿舍楼的树形结构数据,按照校区-宿舍区-宿舍楼三级结构组织。校区和宿舍区节点不可点击,只有宿舍楼节点可以点击。
请求方式
GET /xgss/dormBuildingTree/list
权限要求
xgss:dormBuildingTree:list
请求参数
| 参数名 |
类型 |
必须 |
描述 |
| campusId |
Long |
否 |
校区ID,用于筛选 |
| areaId |
Long |
否 |
宿舍区ID,用于筛选 |
| buildingName |
String |
否 |
宿舍楼名称,模糊查询 |
| status |
String |
否 |
宿舍楼状态 |
返回结果
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"label": "主校区",
"type": "campus",
"disabled": true,
"children": [
{
"id": 101,
"label": "东区宿舍",
"type": "area",
"disabled": true,
"children": [
{
"id": 1001,
"label": "1号楼",
"type": "building",
"disabled": false,
"buildingFloors": 6,
"gender": "male"
},
{
"id": 1002,
"label": "2号楼",
"type": "building",
"disabled": false,
"buildingFloors": 5,
"gender": "female"
}
]
},
{
"id": 102,
"label": "西区宿舍",
"type": "area",
"disabled": true,
"children": [
{
"id": 1003,
"label": "3号楼",
"type": "building",
"disabled": false,
"buildingFloors": 7
}
]
}
]
}
]
}
返回参数说明
| 参数名 |
类型 |
描述 |
| id |
Long |
节点ID |
| label |
String |
节点显示名称 |
| type |
String |
节点类型(campus:校区、area:宿舍区、building:宿舍楼) |
| disabled |
Boolean |
是否禁用点击(校区和宿舍区为true,宿舍楼为false) |
| buildingFloors |
Integer |
宿舍楼层数(只有宿舍楼节点有此字段) |
| gender |
String |
宿舍楼性别(只有宿舍楼节点有此字段) |
| children |
Array |
子节点列表 |
数据权限说明
接口会根据当前登录用户的权限进行数据过滤:
- 全校管理员(manager_type=1):可以查看所有校区、宿舍区和宿舍楼数据
- 校区管理员(manager_type=2):只能查看其管理的校区下的宿舍区和宿舍楼数据
- 宿舍区管理员(manager_type=3):只能查看其管理的宿舍区下的宿舍楼数据
- 宿舍楼管理员(manager_type=4):只能查看其管理的宿舍楼数据
- 多角色支持:如果用户同时拥有多种管理员角色(如既是校区管理员又是宿舍楼管理员),将会合并所有权限范围内的数据。例如,一个用户同时是A校区管理员和B宿舍楼管理员,则可以看到A校区下的所有宿舍楼以及B宿舍楼。
权限判断逻辑:
- 通过 xg_dorm_manager 表的 user_id 与当前登录用户匹配,获取用户管理员类型
- 根据 manager_type 确定权限级别
- 通过 xg_dorm_manager_source 表的 auth_source 确定具体权限范围
- 多角色权限合并:合并不同角色对应的宿舍楼数据,确保不重复
错误码
| 错误码 |
描述 |
| 401 |
未授权,需要登录 |
| 403 |
无权限访问该接口 |
| 500 |
服务器内部错误 |
使用示例
// 前端代码示例(使用axios)
import axios from 'axios';
// 获取宿舍楼树形结构
async function getDormBuildingTree() {
try {
const response = await axios.get('/xgss/dormBuildingTree/list');
if (response.data.code === 200) {
return response.data.data;
}
} catch (error) {
console.error('获取宿舍楼树失败:', error);
}
return [];
}
2. 宿舍楼信息管理
2.1 获取宿舍楼列表
接口说明
该接口用于获取宿舍楼信息的分页列表,包含宿舍楼基本信息以及关联的校区和宿舍区信息。
请求方式
GET /sslxx/dormBuilding/list
权限要求
sslxx:dormBuilding:list
请求参数
| 参数名 |
类型 |
必须 |
描述 |
| pageNum |
Integer |
是 |
当前页码,从1开始 |
| pageSize |
Integer |
是 |
每页记录数 |
| buildingCode |
String |
否 |
宿舍楼编码,模糊查询 |
| buildingName |
String |
否 |
宿舍楼名称,模糊查询 |
| areaId |
Long |
否 |
宿舍区ID,精确查询 |
| campusId |
Long |
否 |
校区ID,精确查询 |
| buildingType |
String |
否 |
宿舍楼类型(1男生楼 2女生楼 3混合楼) |
返回结果
{
"total": 1,
"rows": [
{
"id": "1947459199879495681",
"buildingCode": "xixi-ssq01-ssl01",
"buildingName": "西溪校区-宿舍区01-宿舍楼01",
"areaId": "1946829650430935041",
"areaName": "西溪校区-宿舍区01",
"campusId": "1946815553291304962",
"campusName": "西溪校区",
"buildingType": "1",
"buildingDescription": "12312",
"sortOrder": 1,
"floors": 6,
"createBy": 1,
"createTime": "2025-07-22 08:50:30",
"updateBy": 1,
"updateTime": "2025-07-22 08:51:06"
}
],
"code": 200,
"msg": "查询成功"
}
返回参数说明
| 参数名 |
类型 |
描述 |
| id |
Long |
宿舍楼主键ID |
| buildingCode |
String |
宿舍楼编码 |
| buildingName |
String |
宿舍楼名称 |
| areaId |
Long |
所属宿舍区ID |
| areaName |
String |
所属宿舍区名称 |
| campusId |
Long |
所属校区ID |
| campusName |
String |
所属校区名称 |
| buildingType |
String |
宿舍楼类型(1男生楼 2女生楼 3混合楼) |
| buildingDescription |
String |
宿舍楼描述 |
| sortOrder |
Integer |
排序号 |
| floors |
Integer |
总楼层数 |
| createBy |
Long |
创建者ID |
| createTime |
Date |
创建时间 |
| updateBy |
Long |
更新者ID |
| updateTime |
Date |
更新时间 |
错误码
| 错误码 |
描述 |
| 401 |
未授权,需要登录 |
| 403 |
无权限访问该接口 |
| 500 |
服务器内部错误 |
使用示例
// 前端代码示例(使用axios)
import axios from 'axios';
// 获取宿舍楼列表
async function getDormBuildingList(params) {
try {
const response = await axios.get('/sslxx/dormBuilding/list', {
params: {
pageNum: 1,
pageSize: 10,
...params
}
});
if (response.data.code === 200) {
return response.data;
}
} catch (error) {
console.error('获取宿舍楼列表失败:', error);
}
return { total: 0, rows: [] };
}
3. 宿舍房间管理
3.1 获取宿舍房间列表
接口说明
该接口用于获取宿舍房间信息的列表,包含房间基本信息。列表按照楼层升序、房间名称升序排列。
请求方式
GET /xgss/dormRoom/list
权限要求
xgss:dormRoom:list
请求参数
| 参数名 |
类型 |
必须 |
描述 |
| pageNum |
Integer |
是 |
当前页码,从1开始 |
| pageSize |
Integer |
是 |
每页记录数 |
| buildingId |
Long |
否 |
宿舍楼ID,精确查询 |
| roomName |
String |
否 |
房间名称,模糊查询 |
| floorNum |
Integer |
否 |
楼层号,精确查询 |
| roomType |
String |
否 |
房间类型(1标准间 2单人间 3套间) |
| roomStatus |
String |
否 |
房间状态(0正常 1维修中 2停用) |
返回结果
{
"total": 2,
"rows": [
{
"id": "1947459199879495682",
"roomCode": "room-101",
"roomName": "101",
"buildingId": "1947459199879495681",
"floorNum": 1,
"roomType": "1",
"standardBeds": 4,
"actualBeds": 4,
"roomArea": 20.5,
"roomStatus": "0",
"remark": "标准四人间",
"createBy": 1,
"createTime": "2025-07-22 09:15:30",
"updateBy": 1,
"updateTime": "2025-07-22 09:15:30"
},
{
"id": "1947459199879495683",
"roomCode": "room-201",
"roomName": "201",
"buildingId": "1947459199879495681",
"floorNum": 2,
"roomType": "1",
"standardBeds": 4,
"actualBeds": 4,
"roomArea": 20.5,
"roomStatus": "0",
"remark": "标准四人间",
"createBy": 1,
"createTime": "2025-07-22 09:15:30",
"updateBy": 1,
"updateTime": "2025-07-22 09:15:30"
}
],
"code": 200,
"msg": "查询成功"
}
返回参数说明
| 参数名 |
类型 |
描述 |
| id |
Long |
房间主键ID |
| roomCode |
String |
房间编码 |
| roomName |
String |
房间名称 |
| buildingId |
Long |
所属宿舍楼ID |
| floorNum |
Integer |
楼层号 |
| roomType |
String |
房间类型(1标准间 2单人间 3套间) |
| standardBeds |
Integer |
标准床位数 |
| actualBeds |
Integer |
实际床位数 |
| roomArea |
Double |
房间面积(平方米) |
| roomStatus |
String |
房间状态(0正常 1维修中 2停用) |
| remark |
String |
备注 |
| createBy |
Long |
创建者ID |
| createTime |
Date |
创建时间 |
| updateBy |
Long |
更新者ID |
| updateTime |
Date |
更新时间 |
排序规则
房间列表按照以下顺序排序:
- 优先按楼层号(floorNum)升序排列
- 其次按房间名称(roomName)升序排列
这确保了在宿舍管理系统中房间按照从低楼层到高楼层的顺序展示,相同楼层的房间按照名称顺序排列,提供更直观的浏览体验。
错误码
| 错误码 |
描述 |
| 401 |
未授权,需要登录 |
| 403 |
无权限访问该接口 |
| 500 |
服务器内部错误 |
使用示例
// 前端代码示例(使用axios)
import axios from 'axios';
// 获取宿舍房间列表
async function getDormRoomList(params) {
try {
const response = await axios.get('/xgss/dormRoom/list', {
params: {
pageNum: 1,
pageSize: 100,
buildingId: buildingId,
...params
}
});
if (response.data.code === 200) {
return response.data;
}
} catch (error) {
console.error('获取宿舍房间列表失败:', error);
}
return { total: 0, rows: [] };
}