提交代码

2025-08-22 22:24:06 +08:00
1 parent eb51f1645c
commit c164d1feb4
@@ -9,10 +9,12 @@
 ## API模块列表
 - [学生信息管理API](./学生信息管理API.md)
 - [学生信息收集批次管理API](./学生信息收集批次管理API.md)
+- [学生信息收集批次API](./学生信息收集批次API.md) - **重要更新**：修改列表排序方式为按创建时间倒序（2025-01-03）
 - [班级信息管理API](./班级信息管理API.md)
 - [班级干部信息管理API](./班级干部信息管理API.md)
 - [宿舍管理API](./宿舍管理API.md)
 - [宿舍房间管理API](./宿舍房间管理API.md) - **新增床位详细信息查询接口**（2025-01-27）
+- [宿舍床位分配管理API](./宿舍床位分配管理API.md) - **重要修复：床位分配不完整问题**（2025-01-27）
 - [宿舍管理员信息API](./宿舍管理员信息API.md)
 - [宿舍管理员授权API](./宿舍管理员授权API.md)
 - [学生管理员授权关系API](./学生管理员授权关系API.md)
@@ -82,6 +84,8 @@
 | 处理预约申请 | POST | /api/xljk/consultation/appointment/process | 预约管理 | xljk:consultation:appointment:process |
 | **获取房间床位详细信息** | GET | /dormbed/dormBed/details/room/{roomId} | 宿舍管理 | dormbed:dormBed:query |
 | **获取宿舍楼床位详细信息** | GET | /dormbed/dormBed/details/building/{buildingId} | 宿舍管理 | dormbed:dormBed:query |
+| **批量分配床位给班级** | POST | /dormBedStudent/dormBedStudent/batchAllocateToClass | 床位分配 | xgss:dormBedStudent:allocateToClass |
+| **批量分配床位给学院** | POST | /dormBedStudent/dormBedStudent/batchAllocateToCollege | 床位分配 | xgss:dormBedStudent:allocateToCollege |
 | 记录咨询结果 | POST | /api/xljk/consultation/appointment/record | 预约管理 | xljk:consultation:appointment:record |
 | 查询未到访记录列表 | GET | /api/xljk/consultation/no-show/list | 预约限制 | xljk:consultation:noshow:list |
 | 获取未到访记录详情 | GET | /api/xljk/consultation/no-show/{id} | 预约限制 | xljk:consultation:noshow:query |
@@ -96,6 +100,7 @@
 | 2025-07-01 | 1.0 | 初始版本 | 系统管理员 |
 | 2025-07-15 | 1.1 | 添加心理健康测评API | 张工 |
 | 2025-07-30 | 1.2 | 添加预约限制功能API | Cursor |
+| 2025-01-27 | 1.3 | 添加宿舍床位分配管理API，修复床位分配不完整问题 | Cursor |

 **详细文档**: [企业信息管理API.md](./企业信息管理API.md)

@@ -0,0 +1,233 @@
+# 学生信息收集批次API文档
+
+## 📋 文档信息
+
+| 项目 | 信息 |
+|------|------|
+| **项目名称** | 校园管理系统 - 学生信息收集批次 |
+| **API模块** | 学生信息收集批次管理 |
+| **文档版本** | V1.1.0 |
+| **创建时间** | 2025-01-03 |
+| **基础路径** | `/XgStuColBatch/stuColBatch` |
+
+## 🎯 API概述
+
+### 模块说明
+学生信息收集批次管理系统提供完整的批次创建、查询、修改、删除等API接口，支持学生信息收集的批次化管理。
+
+### 技术规范
+- **认证方式**: Bearer Token (Sa-Token)
+- **数据格式**: JSON
+- **响应格式**: 统一使用R类型或TableDataInfo分页格式
+- **权限控制**: 基于角色的权限管理(RBAC)
+
+### 权限角色
+- **学生管理员**: 查看权限范围内的批次信息
+- **班主任**: 查看相关班级的批次信息
+- **全校学生管理员**: 查看全校范围的批次信息
+- **系统管理员**: 完整的批次管理权限
+
+## 📊 数据模型
+
+### 学生信息收集批次VO (XgStuColBatchVo)
+
+```java
+{
+  "id": 1,                           // 批次ID
+  "batchName": "2025年春季学期信息收集", // 批次名称
+  "description": "收集学生基本信息",    // 批次描述
+  "startTime": "2025-02-01 00:00:00", // 开始时间
+  "endTime": "2025-02-28 23:59:59",   // 结束时间
+  "status": "0",                      // 状态（0正常 1停用）
+  "collectionType": "1",              // 收集类型（1-新学期收集 2-其他）
+  "remark": "备注信息",                // 备注
+  "createBy": 1,                      // 创建者
+  "createTime": "2025-01-27 10:00:00", // 创建时间
+  "updateBy": 1,                      // 更新者
+  "updateTime": "2025-01-27 10:00:00"  // 更新时间
+}
+```
+
+## 🔧 API接口列表
+
+### 1. 基础管理接口
+
+#### 1.1 查询学生信息收集批次列表
+- **接口路径**: GET `/XgStuColBatch/stuColBatch/list`
+- **权限标识**: `XgStuColBatch:stuColBatch:list`
+- **功能描述**: 分页查询学生信息收集批次列表
+- **排序方式**: 按创建时间倒序排列（最新创建的批次在前）
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| pageNum | integer | 否 | 页码，默认1 |
+| pageSize | integer | 否 | 每页大小，默认10 |
+| batchName | string | 否 | 批次名称（模糊查询） |
+| status | string | 否 | 状态（0正常 1停用） |
+| collectionType | string | 否 | 收集类型（1-新学期收集 2-其他） |
+
+**响应数据**:
+```json
+{
+  "code": 200,
+  "msg": "查询成功",
+  "rows": [
+    {
+      "id": 2,
+      "batchName": "2025年春季学期信息收集",
+      "description": "收集学生基本信息",
+      "startTime": "2025-02-01 00:00:00",
+      "endTime": "2025-02-28 23:59:59",
+      "status": "0",
+      "collectionType": "1",
+      "createTime": "2025-01-27 15:30:00"
+    },
+    {
+      "id": 1,
+      "batchName": "2024年秋季学期信息收集",
+      "description": "收集学生基本信息",
+      "startTime": "2024-09-01 00:00:00",
+      "endTime": "2024-09-30 23:59:59",
+      "status": "1",
+      "collectionType": "1",
+      "createTime": "2024-08-15 10:00:00"
+    }
+  ],
+  "total": 2
+}
+```
+
+#### 1.2 获取学生信息收集批次详细信息
+- **接口路径**: GET `/XgStuColBatch/stuColBatch/{id}`
+- **权限标识**: `XgStuColBatch:stuColBatch:query`
+- **功能描述**: 根据主键获取学生信息收集批次详细信息
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | long | 是 | 批次主键ID |
+
+**响应数据**:
+```json
+{
+  "code": 200,
+  "msg": "查询成功",
+  "data": {
+    "id": 1,
+    "batchName": "2025年春季学期信息收集",
+    "description": "收集学生基本信息",
+    "startTime": "2025-02-01 00:00:00",
+    "endTime": "2025-02-28 23:59:59",
+    "status": "0",
+    "collectionType": "1",
+    "remark": "备注信息",
+    "createBy": 1,
+    "createTime": "2025-01-27 10:00:00",
+    "updateBy": 1,
+    "updateTime": "2025-01-27 10:00:00"
+  }
+}
+```
+
+#### 1.3 新增学生信息收集批次
+- **接口路径**: POST `/XgStuColBatch/stuColBatch`
+- **权限标识**: `XgStuColBatch:stuColBatch:add`
+- **功能描述**: 新增学生信息收集批次
+
+**请求参数**:
+```json
+{
+  "batchName": "2025年春季学期信息收集",
+  "description": "收集学生基本信息",
+  "startTime": "2025-02-01 00:00:00",
+  "endTime": "2025-02-28 23:59:59",
+  "status": "0",
+  "collectionType": "1",
+  "remark": "备注信息"
+}
+```
+
+**响应数据**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+#### 1.4 修改学生信息收集批次
+- **接口路径**: PUT `/XgStuColBatch/stuColBatch`
+- **权限标识**: `XgStuColBatch:stuColBatch:edit`
+- **功能描述**: 修改学生信息收集批次信息
+
+**请求参数**:
+```json
+{
+  "id": 1,
+  "batchName": "2025年春季学期信息收集",
+  "description": "收集学生基本信息",
+  "startTime": "2025-02-01 00:00:00",
+  "endTime": "2025-02-28 23:59:59",
+  "status": "0",
+  "collectionType": "1",
+  "remark": "备注信息"
+}
+```
+
+**响应数据**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+#### 1.5 删除学生信息收集批次
+- **接口路径**: DELETE `/XgStuColBatch/stuColBatch/{ids}`
+- **权限标识**: `XgStuColBatch:stuColBatch:remove`
+- **功能描述**: 批量删除学生信息收集批次
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| ids | string | 是 | 批次ID集合，多个ID用逗号分隔 |
+
+**响应数据**:
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+#### 1.6 导出学生信息收集批次
+- **接口路径**: POST `/XgStuColBatch/stuColBatch/export`
+- **权限标识**: `XgStuColBatch:stuColBatch:export`
+- **功能描述**: 导出学生信息收集批次列表到Excel
+
+**请求参数**:
+同查询列表接口，用于筛选导出数据。
+
+**响应数据**:
+返回Excel文件流。
+
+## 📝 更新历史
+
+| 日期 | 版本 | 更新内容 | 更新人 |
+|------|------|---------|-------|
+| 2025-01-03 | V1.1.0 | **重要更新**：修改列表接口排序方式，从按ID升序改为按创建时间倒序，确保最新创建的批次显示在前面 | 系统管理员 |
+| 2025-01-27 | V1.0.0 | 初始版本，创建学生信息收集批次管理API文档 | 系统管理员 |
+
+## 🚨 重要说明
+
+### 排序变更说明
+- **变更时间**: 2025-01-03
+- **变更内容**: 列表查询接口的排序方式从按ID升序(`orderByAsc(XgStuColBatch::getId)`)改为按创建时间倒序(`orderByDesc(XgStuColBatch::getCreateTime)`)
+- **变更原因**: 提升用户体验，确保最新创建的批次显示在列表前面，便于用户快速找到最近的批次
+- **影响范围**: 仅影响列表查询接口的数据排序，不影响其他功能
+
+### 技术实现
+- **后端实现**: 修改`XgStuColBatchServiceImpl.buildQueryWrapper()`方法中的排序逻辑
+- **数据库字段**: 使用`create_time`字段进行排序
+- **继承关系**: `XgStuColBatch` → `TenantEntity` → `BaseEntity`（`createTime`字段在BaseEntity中定义） 
@@ -0,0 +1,300 @@
+# 宿舍床位分配管理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修复 - 完全匹配场景下床位分配不完整问题（第二轮修复）