# 宿舍房间管理API文档

## 目录

- [1. 宿舍楼树形结构](#1-宿舍楼树形结构)
  - [1.1 获取宿舍楼树形结构](#11-获取宿舍楼树形结构)
- [2. 宿舍楼信息管理](#2-宿舍楼信息管理)
  - [2.1 获取宿舍楼列表](#21-获取宿舍楼列表)
- [3. 宿舍房间管理](#3-宿舍房间管理)
  - [3.1 获取宿舍房间列表](#31-获取宿舍房间列表)
- [4. 宿舍床位管理](#4-宿舍床位管理)
  - [4.1 获取房间床位详细信息列表](#41-获取房间床位详细信息列表)
  - [4.2 获取宿舍楼床位详细信息列表](#42-获取宿舍楼床位详细信息列表)
  - [4.3 批量收回宿舍床位](#43-批量收回宿舍床位)

## 1. 宿舍楼树形结构

### 1.1 获取宿舍楼树形结构

#### 接口说明

该接口用于获取宿舍楼的树形结构数据，按照校区-宿舍区-宿舍楼三级结构组织。校区和宿舍区节点不可点击，只有宿舍楼节点可以点击。

#### 请求方式

```
GET /xgss/dormBuildingTree/list
```

#### 权限要求

```
xgss:dormBuildingTree:list
```

#### 请求参数

| 参数名        | 类型    | 必须 | 描述                 |
| ------------- | ------- | ---- | -------------------- |
| campusId      | Long    | 否   | 校区ID，用于筛选     |
| areaId        | Long    | 否   | 宿舍区ID，用于筛选   |
| buildingName  | String  | 否   | 宿舍楼名称，模糊查询 |
| status        | String  | 否   | 宿舍楼状态           |

#### 返回结果

```json
{
  "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    | 服务器内部错误       |

#### 使用示例

```javascript
// 前端代码示例（使用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混合楼) |

#### 返回结果

```json
{
  "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    | 服务器内部错误       |

#### 使用示例

```javascript
// 前端代码示例（使用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 | 否   | 排序号，精确查询       |

#### 返回结果

```json
{
  "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    | 服务器内部错误       |

#### 使用示例

```javascript
// 前端代码示例（使用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 |

#### 返回结果

```json
{
  "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    | 服务器内部错误       |

#### 使用示例

```javascript
// 前端代码示例（使用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 获取房间床位详细信息列表](#41-获取房间床位详细信息列表) 相同，但包含指定宿舍楼下所有房间的床位信息，按房间名称、床位编号排序。

#### 返回参数说明

参数说明与 [4.1 获取房间床位详细信息列表](#41-获取房间床位详细信息列表) 相同。

#### 排序规则

床位详细信息列表按照以下顺序排序：
1. 优先按房间名称（roomName）升序排列
2. 其次按床位编号（bedCode）升序排列

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

#### 错误码

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

#### 使用示例

```javascript
// 前端代码示例（使用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列表 |

示例：
```json
{ "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`。

#### 返回结果
```json
{
  "code": 200,
  "msg": "操作成功"
}
```