提交

2025-12-25 18:01:27 +08:00
1 parent fb6d0aa63c
commit ff1228873c
@@ -0,0 +1,175 @@
+# 学生退宿逻辑详细说明
+
+## 概述
+
+本文档详细描述了学生宿舍管理系统中退宿操作的具体实现逻辑，包括前端界面、后端服务调用、数据库操作等各个层面的详细说明。
+
+## 业务流程
+
+### 1. 前端界面操作
+
+**文件位置**: `web/src/views/xg/xsjcxx/xssssq/index.vue`
+
+学生可以通过前端界面提交退宿申请：
+
+- **申请类型**: `applicationType = "2"` (退宿申请)
+- **申请状态**: 初始状态为 `draft` (草稿)
+- **关键字段**:
+  - `currentBedId`: 当前床位ID
+  - `studentId`: 学生ID
+  - `classId`: 班级ID
+
+### 2. 审批流程
+
+退宿申请需要通过工作流审批，流程代码：`hzdyjs-tsts`
+
+审批完成后，当 `applicationStatus = "finish"` 时，触发实际的退宿操作。
+
+## 核心退宿逻辑
+
+### 方法调用链
+
+```java
+// 1. 工作流监听器触发
+@EventListener(condition = "#processEvent.flowCode=='hzdyjs-tsts'")
+public void processHandler(ProcessEvent processEvent) {
+    // 当审批完成时，执行调宿/退宿操作
+    if ("finish".equals(processEvent.getStatus())) {
+        executeApplicationOperation(xgDormApplication);
+    }
+}
+
+// 2. 执行申请操作
+private void executeApplicationOperation(XgDormApplication application) {
+    if ("2".equals(application.getApplicationType())) {
+        // 退宿申请 - 调用退宿接口
+        List<Long> bedIds = List.of(application.getCurrentBedId());
+        Boolean stayawayResult = xgDormBedStudentService.classTeacherStayawaySelectedBeds(
+                bedIds, // 床位ID列表
+                application.getClassId() // 班级ID
+        );
+    }
+}
+
+// 3. 实际退宿实现
+@Override
+@Transactional(rollbackFor = Exception.class)
+public Boolean classTeacherStayawaySelectedBeds(List<Long> bedIds, Long classId)
+```
+
+### 详细SQL操作
+
+**文件位置**: `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/service/impl/XgDormBedStudentServiceImpl.java`
+
+退宿操作涉及三个表的更新，按顺序执行：
+
+#### 1. 更新学生基本信息表 (`xg_student_msg`)
+
+```sql
+-- 清理学生宿舍信息
+UPDATE xg_student_msg
+SET
+    dormitory_building = NULL,    -- 清空宿舍楼信息
+    dormitory_room = NULL,        -- 清空宿舍房间信息
+    ext_field1 = NULL,            -- 清空床位ID（存储在扩展字段1中）
+    update_time = NOW(),          -- 更新时间
+    update_by = ?                 -- 操作人ID
+WHERE
+    ext_field1 IN (?)              -- 床位ID列表（字符串形式）
+    AND deleted = 0                -- 未删除
+    AND student_status = '1';      -- 在校生状态
+```
+
+**说明**:
+- `ext_field1` 字段存储床位ID
+- 只处理在校生 (`student_status = '1'`)
+- 将宿舍相关信息全部清空
+
+#### 2. 更新床位学生分配表 (`xg_dorm_bed_student`)
+
+```sql
+-- 标记床位为退宿状态
+UPDATE xg_dorm_bed_student
+SET
+    status = '1',                  -- 状态：1-退宿
+    checkout_time = NOW(),         -- 退宿时间
+    update_time = NOW(),           -- 更新时间
+    update_by = ?                  -- 操作人ID
+WHERE
+    bed_id IN (?)                  -- 床位ID列表
+    AND deleted = '0'              -- 未删除
+    AND status = '0';              -- 当前状态：0-正常入住
+```
+
+**说明**:
+- 状态变更：`0`(正常入住) → `1`(退宿)
+- 记录退宿时间 `checkout_time`
+- 只处理当前正常入住的床位
+
+#### 3. 更新床位状态表 (`xg_dorm_bed`)
+
+```sql
+-- 将床位状态改为闲置
+UPDATE xg_dorm_bed
+SET
+    bed_status = '0'               -- 床位状态：0-闲置
+WHERE
+    id IN (?)                      -- 床位ID列表
+    AND deleted = '0';             -- 未删除
+```
+
+**说明**:
+- 床位状态变更为闲置，供其他学生使用
+- 不更新时间字段，只修改状态
+
+## 数据状态说明
+
+### 床位状态 (`bed_status`)
+- `0`: 闲置 - 可分配给新学生
+- `1`: 已分配 - 已有学生入住
+
+### 床位学生分配状态 (`status`)
+- `0`: 正常入住 - 学生正在使用该床位
+- `1`: 退宿 - 学生已退宿，床位释放
+
+### 学生状态 (`student_status`)
+- `1`: 在校生 - 正常在校学生
+- `2`: 休学
+- `3`: 退学
+- `4`: 毕业
+
+## 事务处理
+
+所有退宿操作在一个事务中执行：
+
+```java
+@Transactional(rollbackFor = Exception.class)
+public Boolean classTeacherStayawaySelectedBeds(List<Long> bedIds, Long classId)
+```
+
+如果任何一步操作失败，整个退宿操作会回滚，确保数据一致性。
+
+## 异常处理
+
+- 床位ID列表为空时抛出 `IllegalArgumentException`
+- SQL执行异常时抛出 `RuntimeException`
+- 记录详细的日志信息用于问题排查
+
+## 适用场景
+
+此退宿逻辑适用于以下场景：
+
+1. **学生主动退宿申请** - 通过前端界面提交退宿申请，经审批后执行
+2. **学生退学处理** - 学生退学时自动释放床位
+3. **学生毕业处理** - 学生毕业时自动释放床位
+4. **学生休学处理** - 学生休学时释放床位
+
+## 后续使用建议
+
+在实现学生退学、毕业、休学脚本时，可以参考此退宿逻辑的SQL操作顺序：
+
+1. 首先更新 `xg_student_msg` 表清空宿舍信息
+2. 然后更新 `xg_dorm_bed_student` 表标记退宿状态
+3. 最后更新 `xg_dorm_bed` 表释放床位
+
+**注意**: 不同场景可能需要根据具体业务逻辑调整条件判断。