cykj/hzdyjs
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
1e6dcb164c76b6ac029d8bed1074d91591662f3b
hzdyjs/docs/开发文档/API/宿舍房间管理API.md
T
zlwu 99b771bb51 提交代码
2025-09-03 11:45:24 +08:00

25 KiB
Raw Blame History

宿舍房间管理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 子节点列表

数据权限说明

接口会根据当前登录用户的权限进行数据过滤：

  1. 全校管理员(manager_type=1)：可以查看所有校区、宿舍区和宿舍楼数据
  2. 校区管理员(manager_type=2)：只能查看其管理的校区下的宿舍区和宿舍楼数据
  3. 宿舍区管理员(manager_type=3)：只能查看其管理的宿舍区下的宿舍楼数据
  4. 宿舍楼管理员(manager_type=4)：只能查看其管理的宿舍楼数据
  5. 多角色支持：如果用户同时拥有多种管理员角色（如既是校区管理员又是宿舍楼管理员），将会合并所有权限范围内的数据。例如，一个用户同时是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 更新时间

排序规则

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

  1. 第一优先级：按排序号（sort）升序排列
  2. 第二优先级：按楼层号（floorNum）升序排列
  3. 第三优先级：按房间名称（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 获取房间床位详细信息列表 相同。

排序规则

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

  1. 优先按房间名称（roomName）升序排列
  2. 其次按床位编号（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} 状态：空闲`);
    }
  });
}

接口特点

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

应用场景

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

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": "操作成功"
}
Reference in new issue View Git Blame Copy Permalink