# 宿舍楼树形结构API文档

## 接口说明

本文档描述了获取宿舍楼树形结构数据的API接口，该接口返回校区-宿舍区-宿舍楼的三级树形结构，其中校区和宿舍区节点不可选，只有宿舍楼节点可以选择。

## 接口定义

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

**请求URL**：`/sslxx/dormBuilding/buildingTree`

**请求方式**：`GET`

**权限标识**：`sslxx:dormBuilding:list`

**请求参数**：无

**响应示例**：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "label": "东校区",
      "nodeType": "campus",
      "disabled": true,
      "children": [
        {
          "id": 101,
          "label": "东区宿舍区",
          "nodeType": "area",
          "disabled": true,
          "children": [
            {
              "id": 1001,
              "label": "1号楼",
              "nodeType": "building",
              "disabled": false
            },
            {
              "id": 1002,
              "label": "2号楼",
              "nodeType": "building",
              "disabled": false
            }
          ]
        }
      ]
    },
    {
      "id": 2,
      "label": "西校区",
      "nodeType": "campus",
      "disabled": true,
      "children": [
        {
          "id": 201,
          "label": "西区宿舍区",
          "nodeType": "area",
          "disabled": true,
          "children": [
            {
              "id": 2001,
              "label": "3号楼",
              "nodeType": "building",
              "disabled": false
            },
            {
              "id": 2002,
              "label": "4号楼",
              "nodeType": "building",
              "disabled": false
            }
          ]
        }
      ]
    }
  ]
}
```

## 数据结构

### BuildingTreeSelectVo

树形结构节点对象：

| 字段名      | 类型               | 描述                                    |
|------------|-------------------|----------------------------------------|
| id         | Long              | 节点ID                                  |
| label      | String            | 节点名称                                |
| nodeType   | String            | 节点类型：campus(校区)、area(宿舍区)、building(宿舍楼) |
| disabled   | Boolean           | 是否禁用选择                            |
| children   | List<BuildingTreeSelectVo> | 子节点列表                                |
| createBy   | Long              | 创建者                                  |
| createTime | Date              | 创建时间                                |
| updateBy   | Long              | 更新者                                  |
| updateTime | Date              | 更新时间                                |

## 使用方法

### 前端使用示例

在Vue组件中使用该接口获取树形数据：

```typescript
import { getBuildingTree } from '@/api/sslxx/dormBuilding';
import type { BuildingTreeSelectVo } from '@/api/sslxx/dormBuilding/types';

// 在组件的setup函数中
const treeData = ref<BuildingTreeSelectVo[]>([]);

// 加载宿舍楼树形数据
const loadBuildingTree = async () => {
  try {
    const res = await getBuildingTree();
    if (res && res.data) {
      treeData.value = res.data;
    }
  } catch (error) {
    console.error('加载宿舍楼树形数据失败:', error);
  }
};

// 调用加载方法
loadBuildingTree();
```

### 使用el-tree-select组件展示

```html
<el-tree-select
  v-model="selectedBuildings"
  placeholder="请选择宿舍楼"
  style="width: 100%"
  clearable
  filterable
  multiple
  collapse-tags
  collapse-tags-tooltip
  :data="treeData"
  :props="{
    children: 'children',
    label: 'label',
    disabled: 'disabled',
    value: 'id'
  }"
  check-strictly
/>
```

## 特殊说明

1. 接口返回的树形结构中，校区和宿舍区节点已设置 `disabled=true`，前端无需额外处理即可实现只能选择宿舍楼节点的效果
2. 使用 `check-strictly=true` 可以确保树形选择器的选中状态不会级联影响父子节点
3. 该接口已支持管理员分配宿舍楼管理范围的业务需求

## 相关API接口

- [宿舍管理员授权API](./宿舍管理员授权API.md)

## 数据库关系

- `xg_dorm_building` 表通过 `campus_id` 字段关联 `xg_dorm_campus` 表
- `xg_dorm_building` 表通过 `area_id` 字段关联 `xg_dorm_area` 表
- `xg_dorm_area` 表通过 `campus_id` 字段关联 `xg_dorm_campus` 表

## 最后更新时间

2025-07-20