hzdyjs/退学、休学、复学、毕业/01-核心状态修改.md

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

<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处理脚本

-- 参数说明：
-- @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处理脚本

-- 参数说明：
-- @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

// 变更类型枚举
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. 触发后续业务处理 (组织关系、经济资助等)

⚡ 事务处理要求

-- 建议使用数据库事务确保数据一致性
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 与学生学号一致
• 状态合法性: 验证目标状态在字典范围内
• 权限校验: 确保操作员具有相应权限

🛡️ 数据完整性约束

-- 检查学生是否存在
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
• 状态冲突: 当前状态不允许变更到目标状态
• 用户不存在: 记录警告，但不阻断业务处理
• 权限不足: 返回无权限错误

📝 错误日志记录

-- 记录处理失败的详细信息
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 - 业务逻辑

🔧 关键方法实现

@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交互逻辑

<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: 基于代码分析完善技术实现细节和业务逻辑
• 后续更新: 根据实际业务需求持续完善

---

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