# 宿舍楼树形结构API文档

## 接口说明

本文档描述了获取宿舍楼树形结构数据的API接口。**重要变更**：根据业务需求调整，主要接口已从 "校区-宿舍区-宿舍楼" 三级结构改为 "校区-宿舍楼" 二级结构，隐藏宿舍区层级，简化用户操作。

## 接口定义

### 🔄 主要接口（二级结构）

#### 1. 获取宿舍楼树形结构（推荐使用）

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

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

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

**结构说明**：校区-宿舍楼二级结构，校区不可选，只有宿舍楼可以选择

**请求参数**：无

**响应示例**：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "label": "东校区",
      "nodeType": "campus",
      "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": 2001,
          "label": "3号楼",
          "nodeType": "building",
          "disabled": false
        },
        {
          "id": 2002,
          "label": "4号楼",
          "nodeType": "building",
          "disabled": false
        }
      ]
    }
  ]
}
```

#### 2. 获取宿舍楼树形结构（基于权限）

**请求URL**：`/xgss/dormBuildingTree/list`

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

**权限标识**：`xgss:dormBuildingTree:list`

**结构说明**：校区-宿舍楼二级结构，根据当前用户权限过滤

**请求参数**：

| 参数名     | 类型   | 必填 | 描述           |
|-----------|--------|------|----------------|
| campusId  | Long   | 否   | 校区ID过滤条件 |
| buildingName | String | 否 | 宿舍楼名称过滤条件 |

**响应格式**：与上述接口相同

#### 3. 获取所有宿舍楼树形结构（不考虑权限）

**请求URL**：`/xgss/dormBuildingTree/listAll`

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

**权限标识**：`xgss:dormBuildingTree:list`

**结构说明**：校区-宿舍楼二级结构，返回所有数据，不进行权限过滤

**响应格式**：与上述接口相同

### 📋 特殊用途接口（三级结构）

#### 4. 获取完整宿舍楼树形结构（包含宿舍区）

**请求URL**：`/xgss/dormBuildingTree/fullList`

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

**权限标识**：`xgss:dormBuildingTree:list`

**结构说明**：校区-宿舍区-宿舍楼三级结构，仅用于特殊需求

**响应示例**：

```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,
              "buildingType": "1"
            }
          ]
        }
      ]
    }
  ]
}
```

## 数据结构

### BuildingTreeSelectVo（二级结构）

树形结构节点对象：

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

### DormBuildingTreeVo（完整结构）

完整三级结构节点对象：

| 字段名           | 类型               | 描述                                    |
|-----------------|-------------------|----------------------------------------|
| id              | Long              | 节点ID                                  |
| label           | String            | 节点名称                                |
| type            | String            | 节点类型：campus(校区)、area(宿舍区)、building(宿舍楼) |
| disabled        | Boolean           | 是否禁用选择                            |
| children        | List<DormBuildingTreeVo> | 子节点列表                                |
| buildingFloors  | Integer           | 宿舍楼层数（仅宿舍楼节点）              |
| buildingType    | String            | 宿舍楼类型（仅宿舍楼节点）              |

## 使用方法

### 前端使用示例

在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. **主要接口结构调整**：为简化用户操作，去除宿舍区概念，主要接口已改为二级结构
2. **向后兼容**：保留了 `fullList` 接口供需要完整三级结构的特殊场景使用
3. **业务影响**：前端界面将不再显示宿舍区层级，用户直接在校区下选择宿舍楼

### 📋 使用建议

1. **推荐使用二级结构接口**：适用于绝大多数业务场景
2. **校区节点设置为不可选**：确保用户只能选择宿舍楼
3. **使用权限过滤接口**：根据用户权限显示相应的宿舍楼范围

## 相关API接口

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

## 数据库关系

- `xg_dorm_building` 表通过 `campus_id` 字段关联 `xg_dorm_campus` 表
- `xg_dorm_building` 表通过 `area_id` 字段关联 `xg_dorm_area` 表（数据库保留，UI隐藏）
- `xg_dorm_area` 表通过 `campus_id` 字段关联 `xg_dorm_campus` 表

## 版本历史

- **2025-01-29**: 接口结构重大调整，主要接口从三级改为二级结构
- **2025-07-20**: 初始版本，三级结构

## 最后更新时间

2025-01-29