# 宿舍床位分配管理API文档

## 目录

- [1. 接口概述](#1-接口概述)
- [2. 批量分配床位给班级](#2-批量分配床位给班级)
  - [2.1 接口说明](#21-接口说明)
  - [2.2 重要修复记录](#22-重要修复记录)
  - [2.3 请求参数](#23-请求参数)
  - [2.4 返回结果](#24-返回结果)
  - [2.5 业务逻辑](#25-业务逻辑)
- [3. 批量分配床位给学院](#3-批量分配床位给学院)

## 1. 接口概述

宿舍床位分配管理API提供了床位分配的核心功能，包括：
- 批量分配床位给学院
- 批量分配床位给班级（学院分配后的二次分配）
- 床位收回和重新分配

## 2. 批量分配床位给班级

### 2.1 接口说明

该接口用于将已分配给学院的床位进一步分配给具体的班级。支持房间优先分配策略，尽量避免混住。

#### 请求方式

```
POST /dormBedStudent/dormBedStudent/batchAllocateToClass
```

#### 权限要求

```
xgss:dormBedStudent:allocateToClass
```

### 2.2 重要修复记录

**修复日期：2025-01-27**

#### 问题描述
在床位分配过程中，当床位数量小于等于分配的数量时，存在部分床位未能成功分配的问题。具体现象：
- 前端显示34个床位需要分配
- 接口执行后，部分床位没有被分配给班级
- 导致实际分配数量少于预期分配数量

#### 根本原因
1. **分配算法与更新逻辑不匹配**：分配算法使用`roomUsage`数组记录房间使用情况，但更新逻辑依赖`roomClassMap`判断床位归属
2. **混住场景下的床位丢失**：当房间产生混住时，`roomClassMap`只记录最后分配的班级，导致之前分配的床位在更新时被忽略
3. **缺乏精确的床位级别跟踪**：原算法只在房间级别跟踪分配，没有在床位级别进行精确记录

#### 修复方案
1. **新增床位级别映射**：引入`bedClassMap`（Map<Long, Long>）精确记录每个床位分配给哪个班级
2. **四轮分配策略优化**：在每轮分配中同步更新`bedClassMap`，确保床位分配记录准确
3. **更新逻辑重构**：使用`bedClassMap`替代原有的房间级别判断逻辑，确保所有分配的床位都能正确更新
4. **完整性验证**：增加分配结果验证，确保预期分配数量与实际分配数量一致

#### 修复效果
- ✅ 解决了床位分配不完整的问题
- ✅ 确保34个床位全部正确分配
- ✅ 支持混住场景下的精确床位跟踪
- ✅ 增加了详细的日志记录和验证机制

### 2.3 请求参数

#### 请求体参数

```json
{
  "bedIds": ["1947684655866236929", "1947684656965144578", ...],
  "classIds": ["1947944181282590721", "1947943837236416514", ...],
  "classStudentCounts": [0, 6, 7, 7, 3, 11],
  "buildingId": "1947658161827794945",
  "buildingType": "2"
}
```

#### 参数说明

| 参数名 | 类型 | 必须 | 描述 |
|--------|------|------|------|
| bedIds | Long[] | 是 | 需要分配的床位ID列表 |
| classIds | Long[] | 是 | 目标班级ID列表 |
| classStudentCounts | Integer[] | 否 | 各班级分配床位数量，与classIds一一对应 |
| buildingId | Long | 是 | 楼栋ID |
| buildingType | String | 是 | 楼栋类型（1-男生楼，2-女生楼） |

#### 参数校验规则

1. **床位状态校验**：所有床位必须已分配给学院且未分配给班级
2. **数量校验**：classStudentCounts总和不能超过可用床位总数
3. **班级信息校验**：所有classIds必须存在且有效
4. **楼栋信息校验**：buildingId必须存在且与床位楼栋匹配

### 2.4 返回结果

#### 成功响应

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": true
}
```

#### 错误响应

```json
{
  "code": 500,
  "msg": "床位分配失败：具体错误信息",
  "data": null
}
```

#### 常见错误信息

| 错误信息 | 原因 | 解决方案 |
|----------|------|----------|
| 以下床位已分配给班级，无法重复分配 | 床位已被其他班级占用 | 检查床位状态，选择未分配的床位 |
| 选择的床位尚未分配给学院 | 床位未完成学院分配 | 先执行学院分配再进行班级分配 |
| 班级人数总和超过了可用床位总数 | 分配数量超过可用床位 | 调整各班级分配数量 |
| 床位分配不完整，存在未分配的床位 | 分配算法异常 | 联系技术支持检查日志 |

### 2.5 业务逻辑

#### 分配策略

**四轮房间优先分配策略**：

1. **第一轮：完整房间分配**
   - 优先将空闲房间完整分配给单个班级
   - 条件：房间空闲 && 班级人数 >= 房间床位数

2. **第二轮：同班级房间补充**
   - 在已分配给该班级的房间中补充床位
   - 避免不必要的混住

3. **第三轮：空闲房间分配**
   - 将剩余学生分配到完全空闲的房间
   - 保持房间内班级单一性

4. **第四轮：混住分配**
   - 将剩余学生分配到任何有空闲床位的房间
   - 允许混住以确保所有学生都有床位

#### 分配原则

- **房间优先**：尽量保持同一房间内学生来自同一班级
- **顺序分配**：按房间编码顺序进行分配
- **完整性保证**：确保所有指定的床位都被分配
- **日志记录**：详细记录分配过程和结果

#### 数据更新

分配完成后，系统会更新以下信息：
- `xg_dorm_bed_student.class_id`：床位分配的班级ID
- `xg_dorm_bed_student.major_id`：床位分配的专业ID
- `xg_dorm_bed_student.update_time`：更新时间
- `xg_dorm_bed_student.update_by`：更新人员

## 3. 批量分配床位给学院

### 3.1 接口说明

该接口用于将空闲床位批量分配给二级学院，是床位分配的第一步。

#### 请求方式

```
POST /dormBedStudent/dormBedStudent/batchAllocateToCollege
```

#### 权限要求

```
xgss:dormBedStudent:allocateToCollege
```

#### 请求参数

```json
{
  "bedIds": ["床位ID列表"],
  "collegeIds": ["学院ID列表"],
  "collegeStudentCounts": [各学院分配数量],
  "buildingId": "楼栋ID",
  "buildingType": "楼栋类型"
}
```

#### 业务逻辑

1. **床位状态校验**：确保床位处于空闲状态（bed_status = "0"）
2. **学院分配**：采用与班级分配相同的房间优先策略
3. **数据更新**：更新床位的学院归属信息

---

## 技术说明

### 关键数据结构

```java
// 房间使用状态跟踪
int[] roomUsage = new int[sortedRoomIds.size()];

// 房间主要归属班级映射
Map<Integer, Long> roomClassMap = new HashMap<>();

// 床位精确分配映射（修复关键）
Map<Long, Long> bedClassMap = new HashMap<>(); // bedId -> classId
```

### 修复前后对比

**修复前**：
- 依赖房间级别的`roomClassMap`判断床位归属
- 混住场景下床位分配记录丢失
- 更新逻辑与分配算法不匹配

**修复后**：
- 使用床位级别的`bedClassMap`精确跟踪
- 支持混住场景下的完整床位分配
- 分配算法与更新逻辑完全一致

### 性能优化

- 使用批量更新减少数据库操作
- 流式处理大量床位数据
- 详细的日志记录便于问题排查

---

## 修复记录

### 2025-01-27 第二轮修复：完全匹配场景下的床位分配问题

**严重问题**：
用户反馈75个床位完全匹配75个需求时，仍有13个床位未分配。

**新发现的根本原因**：
1. **床位预筛选逻辑错误**：条件 `.isNull(XgDormBedStudent::getClassId)` 导致已分配班级的床位被排除在分配范围之外
2. **数据库更新条件过严**：只更新未分配班级的床位，忽略了需要重新分配的床位
3. **验证逻辑不够严格**：对完全匹配场景缺少强制验证

**第二轮修复方案**：

#### 1. 修复床位预筛选逻辑
```java
// 修复前：只查询未分配班级的床位
.isNull(XgDormBedStudent::getClassId) // 只分配了学院，还没分配班级

// 修复后：查询所有已分配给学院的床位，不论是否已分配班级
// 移除了.isNull(XgDormBedStudent::getClassId)条件
```

#### 2. 增强数据库更新策略
```java
// 分两种情况处理：
// 情况1：更新未分配班级的记录（新分配）
// 情况2：强制更新所有指定床位的班级分配（重新分配）
int totalUpdateCount = updateCount1 + updateCount2;
```

#### 3. 完善验证和诊断机制
```java
// 当床位数量完全匹配需求时，必须全部分配完
if (totalExpectedBeds == totalAvailableBeds && totalAllocatedBeds < totalExpectedBeds) {
    // 详细诊断未分配的床位和房间分布
    throw new RuntimeException("床位分配不完整，存在" + (totalExpectedBeds - totalAllocatedBeds) + "个床位未分配");
}
```

### 2025-01-27 第一轮修复：床位分配不完整问题

**问题描述**：
在床位分配过程中，存在剩余床位未分配的问题。例如：
- 34个床位分配给6个班级时，存在剩余床位未分配
- 分配算法与更新逻辑不匹配，导致混住场景下床位分配记录丢失

**根本原因**：
1. **分配算法使用房间级别跟踪**：`roomUsage`数组 + `roomClassMap`映射
2. **更新逻辑依赖房间归属判断**：只处理`roomClassMap`中记录的房间
3. **混住场景下的数据丢失**：`roomClassMap`被覆盖，之前分配的床位被忽略

**第一轮修复方案**：
- 新增床位级别精确跟踪：`Map<Long, Long> bedClassMap`
- 四轮分配策略优化：同步更新床位分配记录
- 更新逻辑重构：使用`bedClassMap`替代房间级别判断
- 完整性验证：确保所有床位都能正确分配

---

**文档版本**：v1.2  
**最后更新**：2025-01-27  
**修复版本**：重要Bug修复 - 完全匹配场景下床位分配不完整问题（第二轮修复）