# 学生退宿逻辑详细说明

## 概述

本文档详细描述了学生宿舍管理系统中退宿操作的具体实现逻辑，包括前端界面、后端服务调用、数据库操作等各个层面的详细说明。

## 业务流程

### 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` 表释放床位

**注意**: 不同场景可能需要根据具体业务逻辑调整条件判断。