宿舍房间管理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停用)
sort	Integer	否	排序号，精确查询

返回结果

{
  "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",
      "sort": 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",
      "sort": 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停用)
sort	Integer	排序号，数字越小排序越靠前
remark	String	备注
createBy	Long	创建者ID
createTime	Date	创建时间
updateBy	Long	更新者ID
updateTime	Date	更新时间

排序规则

房间列表按照以下优先级顺序排序：

第一优先级：按排序号（sort）升序排列
第二优先级：按楼层号（floorNum）升序排列
第三优先级：按房间名称（roomName）升序排列

排序逻辑说明：

自定义排序：sort 字段允许管理员为房间设置自定义排序，数字越小排序越靠前
默认排序：当 sort 值相同或为0时，按楼层和房间名称的自然顺序排列
灵活管理：支持同一楼层内房间的个性化排序需求

这确保了宿舍管理系统既能保持传统的楼层顺序展示，又能支持管理员根据实际需要进行个性化排序调整。

错误码

错误码	描述
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: [] };
}

4. 宿舍床位管理

4.1 获取房间床位详细信息列表

接口说明

该接口用于获取指定房间的床位详细信息列表，包含床位基本信息和分配的学生详细信息（学院、专业、班级、学号、姓名等）。

请求方式

GET /dormbed/dormBed/details/room/{roomId}

权限要求

dormbed:dormBed:query

请求参数

参数名	类型	必须	描述
roomId	Long	是	房间ID

返回结果

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": "1947459199879495684",
      "bedCode": "bed-101-01",
      "bedName": "101-1号床",
      "roomId": "1947459199879495682",
      "roomName": "101",
      "bedType": "1",
      "bedStatus": "1",
      "bedRemark": "下铺",
      "assignmentId": "1947459199879495685",
      "assignTime": "2025-01-15 09:00:00",
      "assignmentStatus": "0",
      "collegeId": "1001",
      "collegeName": "计算机学院",
      "majorId": "2001",
      "majorName": "计算机科学与技术",
      "classId": "3001",
      "className": "计算机科学与技术1班",
      "classCode": "CS2024-01",
      "grade": "2024",
      "studentId": "4001",
      "studentNo": "2024001001",
      "studentName": "张三",
      "studentGender": "0",
      "studentPhone": "13800138001",
      "studentIdCard": "330101199901011234",
      "createBy": 1,
      "createTime": "2025-07-22 10:00:00",
      "updateBy": 1,
      "updateTime": "2025-07-22 10:00:00"
    },
    {
      "id": "1947459199879495686",
      "bedCode": "bed-101-02",
      "bedName": "101-2号床",
      "roomId": "1947459199879495682",
      "roomName": "101",
      "bedType": "2",
      "bedStatus": "0",
      "bedRemark": "上铺",
      "assignmentId": null,
      "assignTime": null,
      "assignmentStatus": null,
      "collegeId": null,
      "collegeName": null,
      "majorId": null,
      "majorName": null,
      "classId": null,
      "className": null,
      "classCode": null,
      "grade": null,
      "studentId": null,
      "studentNo": null,
      "studentName": null,
      "studentGender": null,
      "studentPhone": null,
      "studentIdCard": null,
      "createBy": 1,
      "createTime": "2025-07-22 10:00:00",
      "updateBy": 1,
      "updateTime": "2025-07-22 10:00:00"
    }
  ]
}

返回参数说明

参数名	类型	描述
床位基本信息
id	Long	床位主键ID
bedCode	String	床位编号
bedName	String	床位名称
roomId	Long	所属房间ID
roomName	String	房间名称
bedType	String	床位类型(1下铺 2上铺 3中铺 4独立床)
bedStatus	String	床位状态(0空闲 1已分配 2维修中)
bedRemark	String	床位备注
分配信息
assignmentId	Long	分配关系ID（空闲床位为null）
assignTime	String	分配时间（空闲床位为null）
assignmentStatus	String	分配状态(0正常 1已退宿)（空闲床位为null）
学院信息
collegeId	Long	学院ID（空闲床位为null）
collegeName	String	学院名称（空闲床位为null）
专业信息
majorId	Long	专业ID（空闲床位为null）
majorName	String	专业名称（空闲床位为null）
班级信息
classId	Long	班级ID（空闲床位为null）
className	String	班级名称（空闲床位为null）
classCode	String	班级代码（空闲床位为null）
grade	String	年级（空闲床位为null）
学生信息
studentId	Long	学生ID（空闲床位为null）
studentNo	String	学号（空闲床位为null）
studentName	String	学生姓名（空闲床位为null）
studentGender	String	学生性别(0男 1女)（空闲床位为null）
studentPhone	String	学生手机号（空闲床位为null）
studentIdCard	String	身份证号（空闲床位为null）
基础字段
createBy	Long	创建者ID
createTime	String	创建时间
updateBy	Long	更新者ID
updateTime	String	更新时间

错误码

错误码	描述
401	未授权，需要登录
403	无权限访问该接口
404	房间ID不存在
500	服务器内部错误

使用示例

// 前端代码示例（使用axios）
import axios from 'axios';

// 获取房间床位详细信息列表
async function getBedDetailsByRoomId(roomId) {
  try {
    const response = await axios.get(`/dormbed/dormBed/details/room/${roomId}`);
    if (response.data.code === 200) {
      return response.data.data;
    }
  } catch (error) {
    console.error('获取房间床位详细信息失败:', error);
  }
  return [];
}

4.2 获取宿舍楼床位详细信息列表

接口说明

该接口用于获取指定宿舍楼的所有床位详细信息列表，包含床位基本信息和分配的学生详细信息（学院、专业、班级、学号、姓名等）。

请求方式

GET /dormbed/dormBed/details/building/{buildingId}

权限要求

dormbed:dormBed:query

请求参数

参数名	类型	必须	描述
buildingId	Long	是	宿舍楼ID

返回结果

返回结果格式与 4.1 获取房间床位详细信息列表相同，但包含指定宿舍楼下所有房间的床位信息，按房间名称、床位编号排序。

返回参数说明

参数说明与 4.1 获取房间床位详细信息列表相同。

排序规则

床位详细信息列表按照以下顺序排序：

优先按房间名称（roomName）升序排列
其次按床位编号（bedCode）升序排列

这确保了在宿舍管理系统中床位按照房间顺序展示，方便管理员查看和管理。

错误码

错误码	描述
401	未授权，需要登录
403	无权限访问该接口
404	宿舍楼ID不存在
500	服务器内部错误

使用示例

// 前端代码示例（使用axios）
import axios from 'axios';

// 获取宿舍楼床位详细信息列表
async function getBedDetailsByBuildingId(buildingId) {
  try {
    const response = await axios.get(`/dormbed/dormBed/details/building/${buildingId}`);
    if (response.data.code === 200) {
      return response.data.data;
    }
  } catch (error) {
    console.error('获取宿舍楼床位详细信息失败:', error);
  }
  return [];
}

// 在前端界面中使用示例
async function loadBedDetailsByBuilding(buildingId) {
  const bedDetails = await getBedDetailsByBuildingId(buildingId);
  
  // 处理床位详细信息数据
  bedDetails.forEach(bed => {
    if (bed.bedStatus === '1' && bed.studentName) {
      // 已分配床位，显示学生信息
      console.log(`床位 ${bed.bedName} 已分配给：${bed.studentName}(${bed.studentNo}) - ${bed.collegeName} ${bed.majorName} ${bed.className}`);
    } else {
      // 空闲床位
      console.log(`床位 ${bed.bedName} 状态：空闲`);
    }
  });
}

接口特点

完整信息查询：一次接口调用获取床位基本信息和学生详细信息
多表关联：关联床位表、床位分配表、学生信息表、班级信息表等
状态区分：清晰区分已分配和空闲床位，空闲床位的学生相关字段为null
权限控制：需要相应权限才能访问接口
数据完整性：包含学院、专业、班级、学生等完整层级信息

应用场景

宿舍管理：管理员查看房间或宿舍楼的床位分配情况
学生信息核查：快速查看入住学生的基本信息
统计分析：进行床位利用率、学院分布等数据分析
报表生成：生成宿舍入住情况报表

4.3 批量收回宿舍床位

接口说明

将选中的床位从当前分配状态恢复为空闲状态，并记录退宿时间等信息。

请求方式

POST /dormBedStudent/dormBedStudent/batchRecall

权限要求

dormBedStudent:dormBedStudent:edit

请求参数

参数名	类型	必须	说明
bedIds	Long[]	是	要收回的床位ID列表

示例：

{ "bedIds": [1001, 1002, 1003] }

处理逻辑

更新 xg_dorm_bed_student：按 bed_id、status=0、deleted=0 命中记录，设置 status=1(已退宿)、checkout_time=当前时间、update_time=当前时间、update_by=当前用户。
更新 xg_dorm_bed：按 id in bedIds 且 deleted=0，设置 bed_status=0(空闲)、update_time=当前时间、update_by=当前用户。
更新 xg_student_msg：根据上述分配记录中的 student_id 汇总（过滤空），且 deleted=0，设置 student_status=1，并将 ext_field1、dormitory_room、dormitory_building 置空，同时更新 update_time、update_by。

返回结果

{
  "code": 200,
  "msg": "操作成功"
}

宿舍房间管理API.md 25 KB Cronologia Originale

宿舍房间管理API文档

目录

1. 宿舍楼树形结构

1.1 获取宿舍楼树形结构

接口说明

请求方式

权限要求

请求参数

返回结果

返回参数说明

数据权限说明

错误码

使用示例

2. 宿舍楼信息管理

2.1 获取宿舍楼列表

接口说明

请求方式

权限要求

请求参数

返回结果

返回参数说明

错误码

使用示例

3. 宿舍房间管理

3.1 获取宿舍房间列表

接口说明

请求方式

权限要求

请求参数

返回结果

返回参数说明

排序规则

错误码

使用示例

4. 宿舍床位管理

4.1 获取房间床位详细信息列表

接口说明

请求方式

权限要求

请求参数

返回结果

返回参数说明

错误码

使用示例

4.2 获取宿舍楼床位详细信息列表

接口说明

请求方式

权限要求

请求参数

返回结果

返回参数说明

排序规则

错误码

使用示例

接口特点

应用场景

4.3 批量收回宿舍床位

接口说明

请求方式

权限要求

请求参数

处理逻辑

返回结果

宿舍房间管理API.md 25 KB

Cronologia Originale