# 01-核心状态修改

## 📋 概述

本分文档详细说明学生退学、休学、毕业处理中的核心状态修改内容，包括学生学籍状态和用户登录状态的变更逻辑。

## 🎯 核心状态修改

### 1. 学生学籍状态

#### 📊 数据库表结构
**表名**: `xg_student_msg`
**主键**: `id` (bigint(20), 雪花ID)
**核心字段**: `student_status` (char(1))
**关联字段**: `student_no` (varchar(32), 学号)

#### 🎯 字典数据定义
系统使用 `student_status` 字典类型，具体定义如下：

| 字典值 | 标签 | 说明 | 样式类 |
|--------|------|------|--------|
| `1` | 在读 | 正常在校学习状态 | primary |
| `2` | 休学 | 暂时停止学业 | warning |
| `3` | 复学 | 从休学状态恢复 | info |
| `4` | 退学 | 终止学籍 | danger |
| `5` | 毕业 | 正常毕业 | success |

**重要说明**:
- 数据库字段 `student_status` 为 char(1) 类型
- 字典类型为 `xg_student_status`
- 状态值与数据库字段值直接对应，无需转换

#### 🔄 处理逻辑
- **休学**: `student_status = '2'`（休学）
- **退学**: `student_status = '4'`（退学）
- **毕业**: `student_status = '5'`（毕业）

#### 📝 前端界面实现
**文件位置**: `web/src/views/xg/xsjcxx/stuPersonalMsg/index.vue`
**字段绑定**: `form.studentStatus`
**字典类型**: `student_status`

```vue
<el-form-item label="学籍状态" prop="studentStatus">
  <el-select v-model="form.studentStatus" placeholder="请选择学籍状态" disabled>
    <el-option v-for="dict in student_status" :key="dict.value" :label="dict.label" :value="dict.value" />
  </el-select>
</el-form-item>
```

#### 💾 SQL处理脚本
```sql
-- 参数说明：
-- @student_id: 学生ID (主键)
-- @student_no: 学生学号
-- @change_type: 变更类型 (XIU_XUE-休学, TUI_XUE-退学, BI_YE-毕业)
-- @operator_id: 操作员ID

-- 休学处理
UPDATE xg_student_msg
SET student_status = '2',
    update_by = @operator_id,
    update_time = NOW()
WHERE id = @student_id
  AND deleted = 0;

-- 退学处理
UPDATE xg_student_msg
SET student_status = '3',
    update_by = @operator_id,
    update_time = NOW()
WHERE id = @student_id
  AND deleted = 0;

-- 毕业处理
UPDATE xg_student_msg
SET student_status = '4',
    update_by = @operator_id,
    update_time = NOW()
WHERE id = @student_id
  AND deleted = 0;
```

### 2. 用户登录状态

#### 📊 数据库表结构
**表名**: `sys_user`
**主键**: `user_id` (bigint(20))
**核心字段**: `status` (char(1))
**关联字段**: `user_name` (varchar(30), 对应学生学号)

#### 🎯 状态定义
| 字段值 | 状态 | 说明 |
|--------|------|------|
| `0` | 正常 | 账号正常使用 |
| `1` | 停用 | 账号已被禁用 |

#### 🔄 处理逻辑
- **休学**: 可选择保留账号（`status` 保持 `0`）或禁用账号（`status = '1'`）
- **退学**: 必须禁用账号（`status = '1'`）
- **毕业**: 必须禁用账号（`status = '1'`）

#### 📝 后端实体类
**文件位置**: `backend/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/domain/SysUser.java`
**状态字段**: `private String status;` (0-正常，1-停用)

**状态变更记录实体**:
**文件位置**: `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/XgStudentStatusChange.java`
- `changeType`: 异动类型 (TUI_XUE-退学, XIU_XUE-休学, FU_XUE-复学, BI_YE-毕业)
- `processStatus`: 处理状态 (0-未处理，1-已处理)
- `source`: 来源 (manual-手动, import-导入, workflow-工作流)

#### 💾 SQL处理脚本
```sql
-- 参数说明：
-- @student_no: 学生学号 (对应sys_user.user_name)
-- @change_type: 变更类型 (XIU_XUE-休学, TUI_XUE-退学, BI_YE-毕业)
-- @operator_id: 操作员ID

-- 退学/毕业：禁用用户账号
UPDATE sys_user
SET status = '1',
    update_by = @operator_id,
    update_time = NOW(),
    remark = CONCAT(COALESCE(remark, ''), ' | 学生状态变更-', @change_type, '-', NOW())
WHERE user_name = @student_no
  AND account_type = '2'  -- 学生账户类型
  AND del_flag = '0';

-- 休学：可选保留账号（根据业务需求决定是否执行）
-- UPDATE sys_user
-- SET status = '1',  -- 如需禁用则取消注释
--     update_by = @operator_id,
--     update_time = NOW(),
--     remark = CONCAT(COALESCE(remark, ''), ' | 学生休学-', NOW())
-- WHERE user_name = @student_no
--   AND account_type = '2'
--   AND del_flag = '0';
```

### 3. 学生状态变更记录

#### 📊 数据库表结构
**表名**: `xg_student_status_change`
**主键**: `id` (bigint(20), 雪花ID)
**核心字段**:
- `student_id`: 学生ID
- `student_no`: 学号
- `change_type`: 异动类型 (TUI_XUE/退学, XIU_XUE/休学, FU_XUE/复学, BI_YE/毕业)
- `apply_date`: 申请/登记日期
- `effective_date`: 生效日期
- `reason`: 异动原因
- `operator_id`: 经办人ID
- `operator_name`: 经办人姓名
- `process_status`: 处理状态 (0=未处理，1=已处理)

#### 🔄 业务流程
1. **创建变更记录**: 插入 `xg_student_status_change` 表
2. **更新学生状态**: 修改 `xg_student_msg.student_status`
3. **更新用户状态**: 根据变更类型修改 `sys_user.status`
4. **标记处理完成**: 更新 `process_status = 1`

#### 📝 后端实现
**控制器**: `XgStudentStatusChangeController`
**服务类**: `XgStudentStatusChangeServiceImpl`
**实体类**: `XgStudentStatusChange`

```java
// 变更类型枚举
public enum ChangeType {
    TUI_XUE("退学"),
    XIU_XUE("休学"),
    FU_XUE("复学"),
    BI_YE("毕业");
}
```

## 🔄 业务处理逻辑

### 1. 状态变更流程

#### 📋 完整处理流程
```
1. 创建状态变更记录 (xg_student_status_change)
2. 验证学生当前状态和业务规则
3. 更新学生学籍状态 (xg_student_msg.student_status)
4. 根据变更类型处理用户登录状态 (sys_user.status)
5. 记录操作日志和审计信息
6. 触发后续业务处理 (组织关系、经济资助等)
```

#### ⚡ 事务处理要求
```sql
-- 建议使用数据库事务确保数据一致性
START TRANSACTION;

-- 步骤1: 创建变更记录
INSERT INTO xg_student_status_change (...) VALUES (...);

-- 步骤2: 更新学生状态
UPDATE xg_student_msg SET student_status = ?, update_time = NOW() WHERE id = ?;

-- 步骤3: 更新用户状态 (如需要)
UPDATE sys_user SET status = ?, update_time = NOW() WHERE user_name = ?;

-- 提交事务
COMMIT;
```

### 2. 数据一致性考虑

#### 🔗 关联数据验证
- **学生存在性**: 确保 `xg_student_msg.id` 存在且 `deleted = 0`
- **用户关联性**: 确保 `sys_user.user_name` 与学生学号一致
- **状态合法性**: 验证目标状态在字典范围内
- **权限校验**: 确保操作员具有相应权限

#### 🛡️ 数据完整性约束
```sql
-- 检查学生是否存在
SELECT COUNT(1) FROM xg_student_msg
WHERE id = @student_id AND deleted = 0;

-- 检查用户账号状态
SELECT user_id, status FROM sys_user
WHERE user_name = @student_no AND del_flag = '0';
```

### 3. 业务规则说明

#### 📊 状态变更矩阵

| 当前状态 | 可变更状态 | 说明 |
|----------|------------|------|
| 在读(1) | 休学(2)、退学(4)、毕业(5) | 正常学籍状态下的变更 |
| 休学(2) | 复学(3)、退学(4)、毕业(5) | 休学状态下的恢复或终止 |
| 复学(3) | 休学(2)、退学(4)、毕业(5) | 复学后的再次变更 |
| 其他状态 | 需特殊审批 | 异常状态需要额外处理 |

#### ⚠️ 业务约束
- **休学限制**: 同一学年内休学不能超过规定次数
- **退学限制**: 退学后不能恢复为正常学籍
- **毕业限制**: 毕业状态为最终状态，不允许变更
- **时间约束**: 状态变更需要满足学年学期要求

### 4. 异常处理机制

#### 🔍 错误场景处理
- **学生不存在**: 返回错误信息，提示检查学生ID
- **状态冲突**: 当前状态不允许变更到目标状态
- **用户不存在**: 记录警告，但不阻断业务处理
- **权限不足**: 返回无权限错误

#### 📝 错误日志记录
```sql
-- 记录处理失败的详细信息
INSERT INTO sys_oper_log (
    title, business_type, method, request_method,
    operator_type, oper_name, dept_name,
    oper_url, oper_ip, oper_location,
    oper_param, json_result, status, error_msg, oper_time
) VALUES (
    '学生状态变更', 2, 'updateStudentStatus', 'PUT',
    1, @operator_name, @dept_name,
    '/student/status/change', @client_ip, @location,
    @request_param, @result_json, 1, @error_msg, NOW()
);
```

## 🛠️ 技术实现细节

### 1. 后端服务层实现

#### 📂 核心类文件
- **实体类**: `XgStudentMsg.java` - 学生信息实体
- **变更实体**: `XgStudentStatusChange.java` - 状态变更记录
- **控制器**: `XgStudentStatusChangeController.java` - API接口
- **服务类**: `XgStudentStatusChangeServiceImpl.java` - 业务逻辑

#### 🔧 关键方法实现
```java
@Service
public class XgStudentStatusChangeServiceImpl implements IXgStudentStatusChangeService {

    @Transactional(rollbackFor = Exception.class)
    public Boolean processStudentStatusChange(XgStudentStatusChangeBo bo) {
        // 1. 验证业务规则
        validateChangeRequest(bo);

        // 2. 创建变更记录
        XgStudentStatusChange change = createChangeRecord(bo);

        // 3. 更新学生状态
        updateStudentStatus(change);

        // 4. 处理用户账号状态
        handleUserAccountStatus(change);

        // 5. 记录操作日志
        logOperation(change);

        return true;
    }
}
```

### 2. 前端界面实现

#### 📱 状态变更界面
- **表单组件**: 使用 `el-select` 绑定字典数据
- **验证规则**: 必填验证和字典值验证
- **状态联动**: 根据变更类型动态显示相关字段

#### 🎨 UI交互逻辑
```vue
<template>
  <el-form :model="form" :rules="rules" ref="statusChangeForm">
    <el-form-item label="变更类型" prop="changeType">
      <el-select v-model="form.changeType" placeholder="请选择变更类型">
        <el-option label="休学" value="XIU_XUE" />
        <el-option label="退学" value="TUI_XUE" />
        <el-option label="毕业" value="BI_YE" />
      </el-select>
    </el-form-item>

    <el-form-item label="生效日期" prop="effectiveDate">
      <el-date-picker
        v-model="form.effectiveDate"
        type="date"
        placeholder="选择生效日期"
        value-format="YYYY-MM-DD"
      />
    </el-form-item>

    <el-form-item label="变更原因" prop="reason">
      <el-input
        v-model="form.reason"
        type="textarea"
        placeholder="请输入变更原因"
        maxlength="500"
        show-word-limit
      />
    </el-form-item>
  </el-form>
</template>
```

## ⚠️ 注意事项

### 1. 操作安全要求
- **权限控制**: 必须验证操作员的变更权限
- **数据备份**: 操作前备份相关数据
- **审计记录**: 记录完整的操作日志
- **业务沟通**: 与相关部门确认处理方案

### 2. 业务连续性考虑
- **流程终止**: 状态变更后终止相关审批流程
- **数据同步**: 确保各模块状态一致性
- **关联处理**: 联动处理组织关系、经济资助等业务
- **状态追溯**: 保留历史状态变更记录

### 3. 性能优化建议
- **批量处理**: 支持多个学生的批量状态变更
- **异步处理**: 大批量操作使用异步处理机制
- **缓存更新**: 变更后及时更新相关缓存
- **索引优化**: 确保查询字段有适当索引

### 4. 监控和告警
- **状态监控**: 监控状态变更的成功率和异常情况
- **业务告警**: 异常状态变更及时告警
- **统计分析**: 定期统计状态变更情况
- **日志分析**: 分析操作日志发现问题

---

## 📅 更新记录

- **2025-12-XX**: 分文档创建，包含核心状态修改逻辑
- **2025-12-XX**: 基于代码分析完善技术实现细节和业务逻辑
- **后续更新**: 根据实际业务需求持续完善

---

*本分文档详细说明学生状态变更的核心数据修改逻辑和技术实现，是整个处理流程的基础步骤。*