all-project/docs/开发文档/API/宿舍床位分配管理API.md

宿舍床位分配管理API文档

目录

• 1. 接口概述
• 2. 批量分配床位给班级
  • 2.1 接口说明
  • 2.2 重要修复记录
  • 2.3 请求参数
  • 2.4 返回结果
  • 2.5 业务逻辑
• 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）精确记录每个床位分配给哪个班级
2. 四轮分配策略优化：在每轮分配中同步更新bedClassMap，确保床位分配记录准确
3. 更新逻辑重构：使用bedClassMap替代原有的房间级别判断逻辑，确保所有分配的床位都能正确更新
4. 完整性验证：增加分配结果验证，确保预期分配数量与实际分配数量一致

修复效果

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

2.3 请求参数

请求体参数

{
  "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 返回结果

成功响应

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

错误响应

{
  "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

请求参数

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

业务逻辑

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

---

技术说明

关键数据结构

// 房间使用状态跟踪
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. 修复床位预筛选逻辑

// 修复前：只查询未分配班级的床位
.isNull(XgDormBedStudent::getClassId) // 只分配了学院，还没分配班级

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

2. 增强数据库更新策略

// 分两种情况处理：
// 情况1：更新未分配班级的记录（新分配）
// 情况2：强制更新所有指定床位的班级分配（重新分配）
int totalUpdateCount = updateCount1 + updateCount2;

3. 完善验证和诊断机制

// 当床位数量完全匹配需求时，必须全部分配完
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修复 - 完全匹配场景下床位分配不完整问题（第二轮修复）