Commit fb3c0f0e authored by wujipeng's avatar wujipeng
Browse files

教务管理-班级管理-班级详情-学员名单-优化

parent 29ed92a5
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.List;
/** 班级学员名单导出请求。 */
@Data
public class ClassStudentExportDTO {
@ApiModelProperty(value = "导出范围:ALL/SELECTED", required = true)
private String scope;
@ApiModelProperty("scope=SELECTED时必填,最多500人")
private List<String> studentIds;
}
package com.platform.business.model.dto;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import java.util.Date;
/** 班级详情统一结业办理请求,兼容单人和批量场景。 */
@Data
@EqualsAndHashCode(callSuper = true)
public class ClassStudentGraduationDTO extends ClassStudentIdsDTO {
@ApiModelProperty(value = "结业日期", required = true)
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date graduationDate;
@ApiModelProperty("结业批次")
private String batchNo;
@ApiModelProperty("结业说明")
private String remark;
@ApiModelProperty(value = "未达标处理模式:ALL/PASSED_ONLY", required = true)
private String mode;
@ApiModelProperty("是否发放电子结业证书")
private Boolean issueCertificate;
@ApiModelProperty("是否发送站内通知")
private Boolean notifyStudent;
}
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.List;
/** 管理员在班级详情中执行批量学员操作时使用的基础请求。 */
@Data
public class ClassStudentIdsDTO {
@ApiModelProperty(value = "学员用户ID列表,单次最多500人", required = true)
private List<String> studentIds;
}
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
/** 班级详情中的单人或批量转班请求。 */
@Data
@EqualsAndHashCode(callSuper = true)
public class ClassStudentTransferDTO extends ClassStudentIdsDTO {
@ApiModelProperty(value = "目标班级ID", required = true)
private Integer targetClassId;
}
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.List;
/**
* 班级名单编辑学员资料请求。
*
* <p>字段与原型名单列保持一致,只允许维护个人资料,不允许通过本接口直接篡改班级关系、
* 考试成绩、出勤率或账户状态;这些信息分别由转班、考试、考勤和结业接口维护。</p>
*/
@Data
public class ClassStudentUpdateDTO {
@ApiModelProperty(value = "姓名", required = true)
private String name;
@ApiModelProperty(value = "手机号", required = true)
private String phone;
@ApiModelProperty("人员类别,可多选")
private List<String> personTypes;
@ApiModelProperty("所在单位")
private String workUnit;
@ApiModelProperty("最高学历")
private String highestEducation;
}
package com.platform.business.model.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.util.Date;
/** 学员移除或转班的不可变审计记录,当前有效关系仍由class_student保存。 */
@Data
@TableName("class_student_change_log")
public class ClassStudentChangeLogEntity {
@TableId(value = "id", type = IdType.AUTO)
private Long id;
private String userId;
private Integer sourceClassId;
private Integer targetClassId;
private String operationType;
private String operatorId;
@TableField("operation_time")
private Date operationTime;
}
package com.platform.business.model.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.util.Date;
/** 班级维度的结业办理记录,保留批次、说明、证书和通知结果。 */
@Data
@TableName("student_graduation_record")
public class StudentGraduationRecordEntity {
@TableId(value = "id", type = IdType.AUTO)
private Long id;
private Integer classId;
private String userId;
private Date graduationDate;
private String batchNo;
private String remark;
private Boolean certificateIssued;
private String certificateNo;
private Boolean notificationRequested;
private String operatorId;
@TableField("create_time")
private Date createTime;
}
package com.platform.business.model.vo; package com.platform.business.model.vo;
import com.fasterxml.jackson.annotation.JsonIgnore;
import lombok.Data; import lombok.Data;
import java.math.BigDecimal; import java.math.BigDecimal;
import java.util.List;
/** 班级详情中的学员名单及其真实统计数据。 */ /** 班级详情中的学员名单及其真实统计数据。 */
@Data @Data
...@@ -16,12 +18,50 @@ public class ClassAdminStudentVO { ...@@ -16,12 +18,50 @@ public class ClassAdminStudentVO {
private String phone; private String phone;
/** 人员类别原始多选值;兼容旧数据时由user_type1/user_type2补齐。 */
private List<String> personTypes;
/** 表格展示值,多个类别使用中文顿号连接。 */
private String personTypeName;
@JsonIgnore
private String personTypesJson;
@JsonIgnore
private String legacyPersonType1;
@JsonIgnore
private String legacyPersonType2;
private String workUnit;
private String highestEducation;
/** NORMAL和LATE记录占全部有效出勤记录的百分比。 */ /** NORMAL和LATE记录占全部有效出勤记录的百分比。 */
private BigDecimal attendanceRate; private BigDecimal attendanceRate;
/** 最近一场已发布考试成绩;没有已发布成绩时为空。 */ /** 最近一场已发布考试成绩;没有已发布成绩时为空。 */
private Double examScore; private Double examScore;
/** 最近一次已发布理论考试成绩。 */
private Double theoryScore;
/** 最近一次已发布实训考试成绩。 */
private Double practicalScore;
/** 理论、实训成绩均存在时的平均分。 */
private Double averageScore;
/** 是否满足原型约定的“理论、实训平均分不低于60分”。 */
private Boolean graduationEligible;
private String accountStatus;
private String accountStatusName;
/** 已结业、已归档人员不可再次勾选办理结业。 */
private Boolean selectable;
private String learningStatus; private String learningStatus;
private String learningStatusName; private String learningStatusName;
......
package com.platform.business.model.vo;
import lombok.AllArgsConstructor;
import lombok.Data;
/** 由业务层生成的下载文件,控制器只负责设置HTTP响应头并写出字节。 */
@Data
@AllArgsConstructor
public class ClassStudentExportFileVO {
private String fileName;
private byte[] content;
}
package com.platform.business.model.vo;
import lombok.Data;
import java.util.ArrayList;
import java.util.List;
/** 结业办理结果,前端可直接使用人数和跳过原因生成Toast或结果明细。 */
@Data
public class ClassStudentGraduationResultVO {
private Integer graduatedCount = 0;
private Integer skippedCount = 0;
private List<String> graduatedStudentIds = new ArrayList<>();
private List<SkippedStudent> skippedStudents = new ArrayList<>();
/** 未被结业的学员及业务原因。 */
@Data
public static class SkippedStudent {
private String studentId;
private String name;
private String reason;
public SkippedStudent(String studentId, String name, String reason) {
this.studentId = studentId;
this.name = name;
this.reason = reason;
}
}
}
package com.platform.business.model.vo;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/** 转班、移除等班级关系操作的统一结果。 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ClassStudentOperationResultVO {
private Integer affectedCount;
}
...@@ -32,6 +32,11 @@ public final class ClassAdminConstants { ...@@ -32,6 +32,11 @@ public final class ClassAdminConstants {
public static final int MAX_LOCATION_LENGTH = 255; public static final int MAX_LOCATION_LENGTH = 255;
public static final int MAX_REMARK_LENGTH = 1000; public static final int MAX_REMARK_LENGTH = 1000;
public static final int MAX_CAPACITY = 200; public static final int MAX_CAPACITY = 200;
public static final int MAX_BATCH_STUDENTS = 500;
public static final String GRADUATION_MODE_ALL = "ALL";
public static final String GRADUATION_MODE_PASSED_ONLY = "PASSED_ONLY";
public static final String EXPORT_SCOPE_ALL = "ALL";
public static final String EXPORT_SCOPE_SELECTED = "SELECTED";
public static final int MIN_TRAINING_YEAR = 2000; public static final int MIN_TRAINING_YEAR = 2000;
public static final int MAX_TRAINING_YEAR = 2100; public static final int MAX_TRAINING_YEAR = 2100;
......
...@@ -4,10 +4,20 @@ import com.github.pagehelper.PageHelper; ...@@ -4,10 +4,20 @@ import com.github.pagehelper.PageHelper;
import com.platform.business.constant.ClassAdminConstants; import com.platform.business.constant.ClassAdminConstants;
import com.platform.business.model.dto.ClassAdminQueryDTO; import com.platform.business.model.dto.ClassAdminQueryDTO;
import com.platform.business.model.dto.ClassAdminSaveDTO; import com.platform.business.model.dto.ClassAdminSaveDTO;
import com.platform.business.model.dto.ClassStudentExportDTO;
import com.platform.business.model.dto.ClassStudentGraduationDTO;
import com.platform.business.model.dto.ClassStudentIdsDTO;
import com.platform.business.model.dto.ClassStudentTransferDTO;
import com.platform.business.model.dto.ClassStudentUpdateDTO;
import com.platform.business.model.entity.UserEntity; import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.ClassAdminDetailVO; import com.platform.business.model.vo.ClassAdminDetailVO;
import com.platform.business.model.vo.ClassAdminOptionsVO; import com.platform.business.model.vo.ClassAdminOptionsVO;
import com.platform.business.model.vo.ClassAdminTreeVO; import com.platform.business.model.vo.ClassAdminTreeVO;
import com.platform.business.model.vo.ClassAdminOptionVO;
import com.platform.business.model.vo.ClassAdminStudentVO;
import com.platform.business.model.vo.ClassStudentExportFileVO;
import com.platform.business.model.vo.ClassStudentGraduationResultVO;
import com.platform.business.model.vo.ClassStudentOperationResultVO;
import com.platform.business.service.AuthenticatedUserService; import com.platform.business.service.AuthenticatedUserService;
import com.platform.business.service.ClassAdminService; import com.platform.business.service.ClassAdminService;
import com.platform.controller.BaseController; import com.platform.controller.BaseController;
...@@ -26,6 +36,10 @@ import org.springframework.web.bind.annotation.RestController; ...@@ -26,6 +36,10 @@ import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource; import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.List; import java.util.List;
/** /**
...@@ -105,6 +119,82 @@ public class ClassAdminController extends BaseController { ...@@ -105,6 +119,82 @@ public class ClassAdminController extends BaseController {
return Result.data(classAdminService.detail(id)); return Result.data(classAdminService.detail(id));
} }
@ApiOperation("班级学员详情")
@GetMapping("/{classId}/students/{userId}")
public Result<ClassAdminStudentVO> studentDetail(@PathVariable("classId") Integer classId,
@PathVariable("userId") String userId,
HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.studentDetail(classId, userId));
}
@ApiOperation("编辑班级学员资料")
@PutMapping("/{classId}/students/{userId}")
public Result<ClassAdminStudentVO> updateStudent(@PathVariable("classId") Integer classId,
@PathVariable("userId") String userId,
@RequestBody ClassStudentUpdateDTO body,
HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.updateStudent(classId, userId, body));
}
@ApiOperation("转班目标班级选项")
@GetMapping("/{classId}/students/transfer-options")
public Result<List<ClassAdminOptionVO>> transferOptions(
@PathVariable("classId") Integer classId, HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.transferOptions(classId));
}
@ApiOperation("单人或批量移除班级学员")
@PostMapping("/{classId}/students/remove")
public Result<ClassStudentOperationResultVO> removeStudents(
@PathVariable("classId") Integer classId,
@RequestBody ClassStudentIdsDTO body,
HttpServletRequest request) {
UserEntity operator = requireAdmin(request);
return Result.data(classAdminService.removeStudents(classId, body, operator));
}
@ApiOperation("单人或批量转班")
@PostMapping("/{classId}/students/transfer")
public Result<ClassStudentOperationResultVO> transferStudents(
@PathVariable("classId") Integer classId,
@RequestBody ClassStudentTransferDTO body,
HttpServletRequest request) {
UserEntity operator = requireAdmin(request);
return Result.data(classAdminService.transferStudents(classId, body, operator));
}
@ApiOperation("单人或批量办理结业")
@PostMapping("/{classId}/students/graduation")
public Result<ClassStudentGraduationResultVO> graduateStudents(
@PathVariable("classId") Integer classId,
@RequestBody ClassStudentGraduationDTO body,
HttpServletRequest request) {
UserEntity operator = requireAdmin(request);
return Result.data(classAdminService.graduateStudents(classId, body, operator));
}
@ApiOperation("导出班级学员名单CSV")
@PostMapping("/{classId}/students/export")
public void exportStudents(@PathVariable("classId") Integer classId,
@RequestBody ClassStudentExportDTO body,
HttpServletRequest request,
HttpServletResponse response) throws IOException {
requireAdmin(request);
ClassStudentExportFileVO file = classAdminService.exportStudents(classId, body);
// filename*使用RFC 5987编码,中文班级名称在Chrome、Edge等浏览器中不会乱码。
String encoded = URLEncoder.encode(file.getFileName(), StandardCharsets.UTF_8.name())
.replace("+", "%20");
response.setCharacterEncoding(StandardCharsets.UTF_8.name());
response.setContentType("text/csv;charset=UTF-8");
response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + encoded);
response.setContentLength(file.getContent().length);
response.getOutputStream().write(file.getContent());
response.getOutputStream().flush();
}
/** 将异常分页参数限制在PageHelper可接受的安全范围内。 */ /** 将异常分页参数限制在PageHelper可接受的安全范围内。 */
void normalizePage(ClassAdminQueryDTO query) { void normalizePage(ClassAdminQueryDTO query) {
if (query.getPageNum() == null || query.getPageNum() < 1) { if (query.getPageNum() == null || query.getPageNum() < 1) {
......
...@@ -40,6 +40,46 @@ public interface ClassMapper extends BaseMapper<ClassEntity> { ...@@ -40,6 +40,46 @@ public interface ClassMapper extends BaseMapper<ClassEntity> {
List<ClassAdminStudentVO> selectAdminStudents(@Param("classId") Integer classId, List<ClassAdminStudentVO> selectAdminStudents(@Param("classId") Integer classId,
@Param("examId") Integer examId); @Param("examId") Integer examId);
/** 查询并校验班级中的一个学员,字段口径与完整名单一致。 */
ClassAdminStudentVO selectAdminStudent(@Param("classId") Integer classId,
@Param("userId") String userId);
/** 锁定源班有效关系,批量写操作据此防止并发转班或重复移除。 */
List<String> lockAdminStudentIds(@Param("classId") Integer classId,
@Param("userIds") List<String> userIds);
/** 目标班选项只包含待开课或进行中的班级,状态最终仍由服务层二次校验。 */
List<ClassAdminOptionVO> selectTransferClassOptions(@Param("excludeClassId") Integer excludeClassId,
@Param("today") Date today);
int countAdminStudentPhone(@Param("phone") String phone,
@Param("excludeUserId") String excludeUserId);
int updateAdminStudentProfile(@Param("userId") String userId,
@Param("name") String name,
@Param("phone") String phone,
@Param("personTypesJson") String personTypesJson,
@Param("personType1") String personType1,
@Param("personType2") String personType2,
@Param("workUnit") String workUnit,
@Param("highestEducation") String highestEducation,
@Param("updateTime") Date updateTime);
int deleteAdminStudentRelations(@Param("classId") Integer classId,
@Param("userIds") List<String> userIds);
int insertAdminStudentRelations(@Param("classId") Integer classId,
@Param("userIds") List<String> userIds);
/** 只清理未开始、未作答、未发布成绩的后续考试名册,历史考试记录绝不删除。 */
int deletePendingExamStudents(@Param("classId") Integer classId,
@Param("userIds") List<String> userIds,
@Param("now") Date now);
int graduateAdminStudent(@Param("userId") String userId,
@Param("graduationTime") Date graduationTime,
@Param("updateTime") Date updateTime);
List<ClassAdminOptionVO> selectAdminLevelOptions(); List<ClassAdminOptionVO> selectAdminLevelOptions();
List<ClassAdminOptionVO> selectAdminHeadTeacherOptions(); List<ClassAdminOptionVO> selectAdminHeadTeacherOptions();
......
package com.platform.business.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.platform.business.model.entity.ClassStudentChangeLogEntity;
import org.apache.ibatis.annotations.Mapper;
/** 班级学员关系变更审计Mapper。 */
@Mapper
public interface ClassStudentChangeLogMapper extends BaseMapper<ClassStudentChangeLogEntity> {
}
package com.platform.business.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.platform.business.model.entity.StudentGraduationRecordEntity;
import org.apache.ibatis.annotations.Mapper;
/** 学员结业记录Mapper。 */
@Mapper
public interface StudentGraduationRecordMapper extends BaseMapper<StudentGraduationRecordEntity> {
}
...@@ -2,11 +2,21 @@ package com.platform.business.service; ...@@ -2,11 +2,21 @@ package com.platform.business.service;
import com.platform.business.model.dto.ClassAdminQueryDTO; import com.platform.business.model.dto.ClassAdminQueryDTO;
import com.platform.business.model.dto.ClassAdminSaveDTO; import com.platform.business.model.dto.ClassAdminSaveDTO;
import com.platform.business.model.dto.ClassStudentExportDTO;
import com.platform.business.model.dto.ClassStudentGraduationDTO;
import com.platform.business.model.dto.ClassStudentIdsDTO;
import com.platform.business.model.dto.ClassStudentTransferDTO;
import com.platform.business.model.dto.ClassStudentUpdateDTO;
import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.ClassAdminCardVO; import com.platform.business.model.vo.ClassAdminCardVO;
import com.platform.business.model.vo.ClassAdminDetailVO; import com.platform.business.model.vo.ClassAdminDetailVO;
import com.platform.business.model.vo.ClassAdminOptionsVO; import com.platform.business.model.vo.ClassAdminOptionsVO;
import com.platform.business.model.vo.ClassAdminOptionVO; import com.platform.business.model.vo.ClassAdminOptionVO;
import com.platform.business.model.vo.ClassAdminTreeVO; import com.platform.business.model.vo.ClassAdminTreeVO;
import com.platform.business.model.vo.ClassAdminStudentVO;
import com.platform.business.model.vo.ClassStudentExportFileVO;
import com.platform.business.model.vo.ClassStudentGraduationResultVO;
import com.platform.business.model.vo.ClassStudentOperationResultVO;
import java.util.List; import java.util.List;
...@@ -27,4 +37,22 @@ public interface ClassAdminService { ...@@ -27,4 +37,22 @@ public interface ClassAdminService {
ClassAdminDetailVO update(Integer classId, ClassAdminSaveDTO request); ClassAdminDetailVO update(Integer classId, ClassAdminSaveDTO request);
ClassAdminDetailVO detail(Integer classId); ClassAdminDetailVO detail(Integer classId);
ClassAdminStudentVO studentDetail(Integer classId, String userId);
ClassAdminStudentVO updateStudent(Integer classId, String userId, ClassStudentUpdateDTO request);
List<ClassAdminOptionVO> transferOptions(Integer classId);
ClassStudentOperationResultVO removeStudents(Integer classId, ClassStudentIdsDTO request,
UserEntity operator);
ClassStudentOperationResultVO transferStudents(Integer classId, ClassStudentTransferDTO request,
UserEntity operator);
ClassStudentGraduationResultVO graduateStudents(Integer classId,
ClassStudentGraduationDTO request,
UserEntity operator);
ClassStudentExportFileVO exportStudents(Integer classId, ClassStudentExportDTO request);
} }
package com.platform.business.service.impl; package com.platform.business.service.impl;
import com.alibaba.fastjson2.JSON;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.platform.business.constant.AccountAdminConstants;
import com.platform.business.constant.ClassAdminConstants; import com.platform.business.constant.ClassAdminConstants;
import com.platform.business.mapper.ClassMapper; import com.platform.business.mapper.ClassMapper;
import com.platform.business.mapper.ClassStudentChangeLogMapper;
import com.platform.business.mapper.StudentGraduationRecordMapper;
import com.platform.business.model.dto.ClassAdminQueryDTO; import com.platform.business.model.dto.ClassAdminQueryDTO;
import com.platform.business.model.dto.ClassAdminSaveDTO; import com.platform.business.model.dto.ClassAdminSaveDTO;
import com.platform.business.model.dto.ClassStudentExportDTO;
import com.platform.business.model.dto.ClassStudentGraduationDTO;
import com.platform.business.model.dto.ClassStudentIdsDTO;
import com.platform.business.model.dto.ClassStudentTransferDTO;
import com.platform.business.model.dto.ClassStudentUpdateDTO;
import com.platform.business.model.dto.NotificationPublishDTO;
import com.platform.business.model.entity.ClassStudentChangeLogEntity;
import com.platform.business.model.entity.ClassEntity; import com.platform.business.model.entity.ClassEntity;
import com.platform.business.model.entity.StudentGraduationRecordEntity;
import com.platform.business.model.entity.SysLevelEntity; import com.platform.business.model.entity.SysLevelEntity;
import com.platform.business.model.entity.SysPhoneRoleEntity; import com.platform.business.model.entity.SysPhoneRoleEntity;
import com.platform.business.model.entity.UserEntity; import com.platform.business.model.entity.UserEntity;
...@@ -16,6 +29,10 @@ import com.platform.business.model.vo.ClassAdminOptionVO; ...@@ -16,6 +29,10 @@ import com.platform.business.model.vo.ClassAdminOptionVO;
import com.platform.business.model.vo.ClassAdminOptionsVO; import com.platform.business.model.vo.ClassAdminOptionsVO;
import com.platform.business.model.vo.ClassAdminStudentVO; import com.platform.business.model.vo.ClassAdminStudentVO;
import com.platform.business.model.vo.ClassAdminTreeVO; import com.platform.business.model.vo.ClassAdminTreeVO;
import com.platform.business.model.vo.ClassStudentExportFileVO;
import com.platform.business.model.vo.ClassStudentGraduationResultVO;
import com.platform.business.model.vo.ClassStudentOperationResultVO;
import com.platform.business.service.BusinessNotificationPublisher;
import com.platform.business.service.ClassAdminService; import com.platform.business.service.ClassAdminService;
import com.platform.business.service.SysLevelService; import com.platform.business.service.SysLevelService;
import com.platform.business.service.SysPhoneRoleService; import com.platform.business.service.SysPhoneRoleService;
...@@ -27,17 +44,23 @@ import org.springframework.transaction.annotation.Transactional; ...@@ -27,17 +44,23 @@ import org.springframework.transaction.annotation.Transactional;
import javax.annotation.Resource; import javax.annotation.Resource;
import java.time.LocalDate; import java.time.LocalDate;
import java.time.temporal.ChronoUnit; import java.time.temporal.ChronoUnit;
import java.nio.charset.StandardCharsets;
import java.text.SimpleDateFormat;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Arrays; import java.util.Arrays;
import java.util.Collections; import java.util.Collections;
import java.util.Comparator; import java.util.Comparator;
import java.util.Date; import java.util.Date;
import java.util.LinkedHashMap; import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List; import java.util.List;
import java.util.Locale; import java.util.Locale;
import java.util.Map; import java.util.Map;
import java.util.Set; import java.util.Set;
import java.util.TreeSet; import java.util.TreeSet;
import java.util.TimeZone;
import java.util.UUID;
import java.util.stream.Collectors;
/** /**
* 管理员端班级管理实现。 * 管理员端班级管理实现。
...@@ -60,6 +83,15 @@ public class ClassAdminServiceImpl implements ClassAdminService { ...@@ -60,6 +83,15 @@ public class ClassAdminServiceImpl implements ClassAdminService {
@Resource @Resource
private SysPhoneRoleService phoneRoleService; private SysPhoneRoleService phoneRoleService;
@Resource
private ClassStudentChangeLogMapper changeLogMapper;
@Resource
private StudentGraduationRecordMapper graduationRecordMapper;
@Resource
private BusinessNotificationPublisher notificationPublisher;
@Override @Override
public List<ClassAdminCardVO> page(ClassAdminQueryDTO query) { public List<ClassAdminCardVO> page(ClassAdminQueryDTO query) {
ClassAdminQueryDTO normalized = query == null ? new ClassAdminQueryDTO() : query; ClassAdminQueryDTO normalized = query == null ? new ClassAdminQueryDTO() : query;
...@@ -194,12 +226,237 @@ public class ClassAdminServiceImpl implements ClassAdminService { ...@@ -194,12 +226,237 @@ public class ClassAdminServiceImpl implements ClassAdminService {
students = Collections.emptyList(); students = Collections.emptyList();
} }
for (ClassAdminStudentVO student : students) { for (ClassAdminStudentVO student : students) {
applyLearningStatus(student, detail.getStatus()); enrichStudent(student, detail.getStatus());
} }
detail.setStudents(students); detail.setStudents(students);
return detail; return detail;
} }
@Override
@Transactional(readOnly = true)
public ClassAdminStudentVO studentDetail(Integer classId, String userId) {
ClassEntity clazz = requireExistingClass(classId);
ClassAdminStudentVO student = requireStudent(classId, userId);
enrichStudent(student, resolveClassStatus(
clazz.getStartDate(), clazz.getEndDate(), businessToday()));
return student;
}
@Override
@Transactional(rollbackFor = Exception.class)
public ClassAdminStudentVO updateStudent(Integer classId, String userId,
ClassStudentUpdateDTO request) {
ClassEntity clazz = requireExistingClass(classId);
requireStudent(classId, userId);
if (request == null) {
throw new BusinessException("学员信息不能为空");
}
String name = requireText(request.getName(), "姓名", 100);
String phone = requireText(request.getPhone(), "手机号", 32);
if (!phone.matches("^1\\d{10}$")) {
throw new BusinessException("手机号需为1开头的11位数字");
}
if (classMapper.countAdminStudentPhone(phone, userId) > 0) {
throw new BusinessException("手机号已被其他账户使用");
}
List<String> personTypes = normalizePersonTypes(request.getPersonTypes());
String workUnit = optionalText(request.getWorkUnit(), "所在单位", 255);
String education = optionalText(request.getHighestEducation(), "最高学历", 64);
UserEntity existingUser = userService.getById(userId);
if (existingUser == null) {
throw new BusinessException("学员账户不存在或已删除");
}
String oldPhone = existingUser.getPhoneNumber();
int updated = classMapper.updateAdminStudentProfile(userId, name, phone,
personTypes.isEmpty() ? null : JSON.toJSONString(personTypes),
personTypes.isEmpty() ? null : personTypes.get(0),
personTypes.size() < 2 ? null : personTypes.get(1),
workUnit, education, new Date());
if (updated != 1) {
throw new BusinessException("学员信息已发生变化,请刷新后重试");
}
syncStudentPhoneRole(oldPhone, phone);
ClassAdminStudentVO result = requireStudent(classId, userId);
enrichStudent(result, resolveClassStatus(clazz.getStartDate(), clazz.getEndDate(), businessToday()));
return result;
}
@Override
@Transactional(readOnly = true)
public List<ClassAdminOptionVO> transferOptions(Integer classId) {
requireExistingClass(classId);
List<ClassAdminOptionVO> options = classMapper.selectTransferClassOptions(
classId, businessSqlDate());
return options == null ? Collections.emptyList() : options;
}
@Override
@Transactional(rollbackFor = Exception.class)
public ClassStudentOperationResultVO removeStudents(Integer classId,
ClassStudentIdsDTO request,
UserEntity operator) {
requireExistingClass(classId);
List<String> userIds = normalizeStudentIds(request == null ? null : request.getStudentIds());
lockAndRequireAllStudents(classId, userIds);
Date now = new Date();
writeChangeLogs(userIds, classId, null, "REMOVE", operator, now);
// 先清理未来考试占位,再删除当前班级关系;任何一步失败均由事务整体回滚。
classMapper.deletePendingExamStudents(classId, userIds, now);
int affected = classMapper.deleteAdminStudentRelations(classId, userIds);
if (affected != userIds.size()) {
throw new BusinessException("学员班级关系已发生变化,请刷新后重试");
}
return new ClassStudentOperationResultVO(affected);
}
@Override
@Transactional(rollbackFor = Exception.class)
public ClassStudentOperationResultVO transferStudents(Integer classId,
ClassStudentTransferDTO request,
UserEntity operator) {
requireExistingClass(classId);
if (request == null || request.getTargetClassId() == null) {
throw new BusinessException("目标班级不能为空");
}
if (classId.equals(request.getTargetClassId())) {
throw new BusinessException("目标班级不能是当前班级");
}
ClassEntity target = requireExistingClass(request.getTargetClassId());
String targetStatus = resolveClassStatus(target.getStartDate(), target.getEndDate(), businessToday());
if (!ClassAdminConstants.STATUS_UPCOMING.equals(targetStatus)
&& !ClassAdminConstants.STATUS_ONGOING.equals(targetStatus)) {
throw new BusinessException("目标班级必须是待开课或进行中状态");
}
List<String> userIds = normalizeStudentIds(request.getStudentIds());
lockAndRequireAllStudents(classId, userIds);
Date now = new Date();
writeChangeLogs(userIds, classId, target.getId(), "TRANSFER", operator, now);
classMapper.deletePendingExamStudents(classId, userIds, now);
int deleted = classMapper.deleteAdminStudentRelations(classId, userIds);
if (deleted != userIds.size()) {
throw new BusinessException("学员班级关系已发生变化,请刷新后重试");
}
int inserted = classMapper.insertAdminStudentRelations(target.getId(), userIds);
if (inserted != userIds.size()) {
throw new BusinessException("目标班级绑定失败,请稍后重试");
}
return new ClassStudentOperationResultVO(inserted);
}
@Override
@Transactional(rollbackFor = Exception.class)
public ClassStudentGraduationResultVO graduateStudents(Integer classId,
ClassStudentGraduationDTO request,
UserEntity operator) {
ClassEntity clazz = requireExistingClass(classId);
if (request == null || request.getGraduationDate() == null) {
throw new BusinessException("结业日期不能为空");
}
String mode = trimToNull(request.getMode());
mode = mode == null ? ClassAdminConstants.GRADUATION_MODE_ALL
: mode.toUpperCase(Locale.ROOT);
if (!ClassAdminConstants.GRADUATION_MODE_ALL.equals(mode)
&& !ClassAdminConstants.GRADUATION_MODE_PASSED_ONLY.equals(mode)) {
throw new BusinessException("未达标学员处理模式无效");
}
String batchNo = optionalText(request.getBatchNo(), "结业批次", 100);
String remark = optionalText(request.getRemark(), "结业说明", 1000);
List<String> userIds = normalizeStudentIds(request.getStudentIds());
lockAndRequireAllStudents(classId, userIds);
ClassStudentGraduationResultVO result = new ClassStudentGraduationResultVO();
List<String> notifyIds = new ArrayList<>();
Date now = new Date();
for (String userId : userIds) {
ClassAdminStudentVO student = requireStudent(classId, userId);
enrichStudent(student, resolveClassStatus(
clazz.getStartDate(), clazz.getEndDate(), businessToday()));
if (!AccountAdminConstants.STATUS_PENDING.equals(student.getAccountStatus())
&& !AccountAdminConstants.STATUS_STUDYING.equals(student.getAccountStatus())) {
result.getSkippedStudents().add(new ClassStudentGraduationResultVO.SkippedStudent(
userId, student.getName(), "当前账户状态不支持结业"));
continue;
}
if (ClassAdminConstants.GRADUATION_MODE_PASSED_ONLY.equals(mode)
&& !Boolean.TRUE.equals(student.getGraduationEligible())) {
result.getSkippedStudents().add(new ClassStudentGraduationResultVO.SkippedStudent(
userId, student.getName(), "理论或实训成绩未达标"));
continue;
}
if (classMapper.graduateAdminStudent(userId, request.getGraduationDate(), now) != 1) {
throw new BusinessException("学员状态已发生变化,请刷新后重试:" + student.getName());
}
StudentGraduationRecordEntity record = new StudentGraduationRecordEntity();
record.setClassId(classId);
record.setUserId(userId);
record.setGraduationDate(request.getGraduationDate());
record.setBatchNo(batchNo);
record.setRemark(remark);
record.setCertificateIssued(Boolean.TRUE.equals(request.getIssueCertificate()));
record.setCertificateNo(Boolean.TRUE.equals(request.getIssueCertificate())
? generateGraduationCertificateNo() : null);
record.setNotificationRequested(Boolean.TRUE.equals(request.getNotifyStudent()));
record.setOperatorId(operator == null ? null : operator.getId());
record.setCreateTime(now);
if (graduationRecordMapper.insert(record) != 1) {
throw new BusinessException("结业记录保存失败,请稍后重试");
}
result.getGraduatedStudentIds().add(userId);
if (Boolean.TRUE.equals(request.getNotifyStudent())) {
notifyIds.add(userId);
}
}
result.setGraduatedCount(result.getGraduatedStudentIds().size());
result.setSkippedCount(result.getSkippedStudents().size());
if (!notifyIds.isEmpty()) {
publishGraduationNotification(clazz, request.getGraduationDate(), notifyIds, operator);
}
return result;
}
@Override
@Transactional(readOnly = true)
public ClassStudentExportFileVO exportStudents(Integer classId, ClassStudentExportDTO request) {
ClassEntity clazz = requireExistingClass(classId);
String scope = request == null ? null : trimToNull(request.getScope());
scope = scope == null ? ClassAdminConstants.EXPORT_SCOPE_ALL : scope.toUpperCase(Locale.ROOT);
if (!ClassAdminConstants.EXPORT_SCOPE_ALL.equals(scope)
&& !ClassAdminConstants.EXPORT_SCOPE_SELECTED.equals(scope)) {
throw new BusinessException("导出范围只支持ALL或SELECTED");
}
List<ClassAdminStudentVO> students = classMapper.selectAdminStudents(classId, null);
if (students == null) {
students = Collections.emptyList();
}
if (ClassAdminConstants.EXPORT_SCOPE_SELECTED.equals(scope)) {
List<String> selected = normalizeStudentIds(request.getStudentIds());
Set<String> selectedSet = new LinkedHashSet<>(selected);
students = students.stream().filter(item -> selectedSet.contains(item.getUserId()))
.collect(Collectors.toList());
if (students.size() != selectedSet.size()) {
throw new BusinessException("部分所选学员已不在当前班级,请刷新后重试");
}
}
for (ClassAdminStudentVO student : students) {
enrichStudent(student, resolveClassStatus(clazz.getStartDate(), clazz.getEndDate(), businessToday()));
}
String csv = buildStudentCsv(clazz, students, scope);
String date = formatDate(new Date(), "yyyy-MM-dd");
String suffix = ClassAdminConstants.EXPORT_SCOPE_SELECTED.equals(scope)
? "_选中" + students.size() + "名" : "";
String safeName = (clazz.getName() == null ? "班级" : clazz.getName())
.replaceAll("[\\\\/:*?\"<>|]", "_");
return new ClassStudentExportFileVO(
safeName + "_学员名单" + suffix + "_" + date + ".csv",
("\uFEFF" + csv).getBytes(StandardCharsets.UTF_8));
}
/** /**
* 规范查询值。该方法会直接回写DTO,使MyBatis动态SQL只接收去空格、转大写后的值。 * 规范查询值。该方法会直接回写DTO,使MyBatis动态SQL只接收去空格、转大写后的值。
*/ */
...@@ -445,20 +702,257 @@ public class ClassAdminServiceImpl implements ClassAdminService { ...@@ -445,20 +702,257 @@ public class ClassAdminServiceImpl implements ClassAdminService {
else course.setStatusName("信息待补全"); else course.setStatusName("信息待补全");
} }
private void applyLearningStatus(ClassAdminStudentVO student, String classStatus) { /**
if (ClassAdminConstants.STATUS_UPCOMING.equals(classStatus)) { * 将数据库中的兼容字段整理为前端稳定模型。
*
* <p>账户真实状态优先于班级日期:管理员手工办理结业后即刻显示“已结业”,不能等到
* 班级结束;旧数据没有account_status时,SQL已经按首次登录和删除标记完成回退。</p>
*/
private void enrichStudent(ClassAdminStudentVO student, String classStatus) {
List<String> personTypes = parsePersonTypes(student);
student.setPersonTypes(personTypes);
student.setPersonTypeName(personTypes.isEmpty() ? null : String.join("、", personTypes));
String accountStatus = trimToNull(student.getAccountStatus());
if (accountStatus != null) {
accountStatus = accountStatus.toUpperCase(Locale.ROOT);
}
student.setAccountStatus(accountStatus);
if (AccountAdminConstants.STATUS_PENDING.equals(accountStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_PENDING); student.setLearningStatus(ClassAdminConstants.LEARNING_PENDING);
student.setLearningStatusName("待开课"); student.setLearningStatusName("待激活");
} else if (ClassAdminConstants.STATUS_ONGOING.equals(classStatus)) { student.setAccountStatusName("待激活");
student.setSelectable(true);
} else if (AccountAdminConstants.STATUS_STUDYING.equals(accountStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_ACTIVE); student.setLearningStatus(ClassAdminConstants.LEARNING_ACTIVE);
student.setLearningStatusName("在读"); student.setLearningStatusName("在读");
} else if (ClassAdminConstants.STATUS_ENDED.equals(classStatus)) { student.setAccountStatusName("在读");
student.setSelectable(true);
} else if (AccountAdminConstants.STATUS_GRADUATED.equals(accountStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_COMPLETED); student.setLearningStatus(ClassAdminConstants.LEARNING_COMPLETED);
student.setLearningStatusName("已结业"); student.setLearningStatusName("已结业");
student.setAccountStatusName("已结业");
student.setSelectable(false);
} else if (AccountAdminConstants.STATUS_ARCHIVED.equals(accountStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_COMPLETED);
student.setLearningStatusName("已归档");
student.setAccountStatusName("已归档");
student.setSelectable(false);
} else if (ClassAdminConstants.STATUS_UPCOMING.equals(classStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_PENDING);
student.setLearningStatusName("待开课");
student.setAccountStatusName("信息待补全");
student.setSelectable(true);
} else if (ClassAdminConstants.STATUS_ONGOING.equals(classStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_ACTIVE);
student.setLearningStatusName("在读");
student.setAccountStatusName("信息待补全");
student.setSelectable(true);
} else { } else {
student.setLearningStatus(ClassAdminConstants.LEARNING_UNKNOWN); student.setLearningStatus(ClassAdminConstants.LEARNING_UNKNOWN);
student.setLearningStatusName("信息待补全"); student.setLearningStatusName("信息待补全");
student.setAccountStatusName("信息待补全");
student.setSelectable(false);
}
if (student.getTheoryScore() != null && student.getPracticalScore() != null) {
double average = Math.round((student.getTheoryScore() + student.getPracticalScore())
* 50.0D) / 100.0D;
student.setAverageScore(average);
student.setExamScore(average);
student.setGraduationEligible(average >= 60.0D);
} else {
student.setAverageScore(null);
student.setGraduationEligible(false);
}
}
/** JSON人员类别损坏时回退到两个旧列,保证历史账户仍可展示和导出。 */
private List<String> parsePersonTypes(ClassAdminStudentVO student) {
LinkedHashSet<String> values = new LinkedHashSet<>();
String json = trimToNull(student.getPersonTypesJson());
if (json != null) {
try {
List<String> parsed = JSON.parseArray(json, String.class);
if (parsed != null) {
parsed.stream().map(this::trimToNull).filter(item -> item != null)
.forEach(values::add);
}
} catch (RuntimeException ignored) {
// 历史脏JSON不阻断班级详情,下面继续使用旧人员类别列兜底。
}
}
String legacy1 = trimToNull(student.getLegacyPersonType1());
String legacy2 = trimToNull(student.getLegacyPersonType2());
if (legacy1 != null) values.add(legacy1);
if (legacy2 != null) values.add(legacy2);
return new ArrayList<>(values);
}
private List<String> normalizePersonTypes(List<String> values) {
if (values == null || values.isEmpty()) {
return Collections.emptyList();
}
LinkedHashSet<String> result = new LinkedHashSet<>();
for (String value : values) {
String normalized = trimToNull(value);
if (normalized == null) continue;
if (normalized.length() > 32) {
throw new BusinessException("人员类别单项不能超过32个字符");
}
result.add(normalized);
}
if (result.size() > 10) {
throw new BusinessException("人员类别最多选择10项");
}
return new ArrayList<>(result);
}
private ClassEntity requireExistingClass(Integer classId) {
requireClassId(classId);
ClassEntity clazz = classMapper.selectById(classId);
if (clazz == null) {
throw new BusinessException("班级不存在或已删除");
}
return clazz;
}
private ClassAdminStudentVO requireStudent(Integer classId, String userId) {
String normalizedId = trimToNull(userId);
if (normalizedId == null) {
throw new BusinessException("学员ID不能为空");
}
ClassAdminStudentVO student = classMapper.selectAdminStudent(classId, normalizedId);
if (student == null) {
throw new BusinessException("学员不在当前班级或关系已变更");
}
return student;
}
private List<String> normalizeStudentIds(List<String> rawIds) {
if (rawIds == null || rawIds.isEmpty()) {
throw new BusinessException("请至少选择一名学员");
} }
LinkedHashSet<String> ids = new LinkedHashSet<>();
for (String rawId : rawIds) {
String id = trimToNull(rawId);
if (id == null) {
throw new BusinessException("学员ID不能为空");
}
ids.add(id);
}
if (ids.size() > ClassAdminConstants.MAX_BATCH_STUDENTS) {
throw new BusinessException("单次批量操作不能超过500名学员");
}
return new ArrayList<>(ids);
}
private void lockAndRequireAllStudents(Integer classId, List<String> userIds) {
List<String> locked = classMapper.lockAdminStudentIds(classId, userIds);
Set<String> actual = locked == null ? Collections.emptySet() : new LinkedHashSet<>(locked);
if (actual.size() != userIds.size() || !actual.containsAll(userIds)) {
throw new BusinessException("部分学员已不在当前班级,请刷新后重试");
}
}
private void writeChangeLogs(List<String> userIds, Integer sourceClassId,
Integer targetClassId, String operationType,
UserEntity operator, Date operationTime) {
for (String userId : userIds) {
ClassStudentChangeLogEntity log = new ClassStudentChangeLogEntity();
log.setUserId(userId);
log.setSourceClassId(sourceClassId);
log.setTargetClassId(targetClassId);
log.setOperationType(operationType);
log.setOperatorId(operator == null ? null : operator.getId());
log.setOperationTime(operationTime);
if (changeLogMapper.insert(log) != 1) {
throw new BusinessException("班级关系变更记录保存失败,请稍后重试");
}
}
}
/**
* 学员手机号同时是登录账号和phone_role关联键;名单编辑手机号时必须同步迁移“学员”角色,
* 否则资料更新成功后用户会因旧角色映射无法登录。
*/
private void syncStudentPhoneRole(String oldPhone, String newPhone) {
if (newPhone.equals(oldPhone)) {
return;
}
if (oldPhone != null) {
phoneRoleService.remove(new LambdaQueryWrapper<SysPhoneRoleEntity>()
.eq(SysPhoneRoleEntity::getPhone, oldPhone)
.eq(SysPhoneRoleEntity::getRoleName, "学员"));
}
long existing = phoneRoleService.count(new LambdaQueryWrapper<SysPhoneRoleEntity>()
.eq(SysPhoneRoleEntity::getPhone, newPhone)
.eq(SysPhoneRoleEntity::getRoleName, "学员"));
if (existing == 0) {
SysPhoneRoleEntity role = new SysPhoneRoleEntity();
role.setPhone(newPhone);
role.setRoleName("学员");
if (!phoneRoleService.save(role)) {
throw new BusinessException("学员登录角色同步失败,请稍后重试");
}
}
}
private String generateGraduationCertificateNo() {
return "CERT-" + businessToday().getYear() + "-"
+ UUID.randomUUID().toString().replace("-", "").substring(0, 12).toUpperCase(Locale.ROOT);
}
private void publishGraduationNotification(ClassEntity clazz, Date graduationDate,
List<String> recipientIds, UserEntity operator) {
NotificationPublishDTO message = new NotificationPublishDTO();
message.setEventId("CLASS-GRADUATION-" + clazz.getId() + "-" + UUID.randomUUID());
message.setMessageType("SYSTEM");
message.setTitle("结业办理完成");
message.setSummary("您已完成“" + clazz.getName() + "”培训结业办理");
message.setContent("您已于" + formatDate(graduationDate, "yyyy年MM月dd日")
+ "完成“" + clazz.getName() + "”培训结业办理,历史成绩和培训记录将继续保留。");
message.setBusinessType("CLASS_GRADUATION");
message.setBusinessId(String.valueOf(clazz.getId()));
message.setPriority("NORMAL");
message.setRecipientUserIds(recipientIds);
notificationPublisher.publish(message, operator == null ? null : operator.getId(),
operator == null || trimToNull(operator.getNickName()) == null
? "管理员" : operator.getNickName());
}
private String buildStudentCsv(ClassEntity clazz, List<ClassAdminStudentVO> students,
String scope) {
List<String> lines = new ArrayList<>();
lines.add("班级名称," + csv(clazz.getName()));
lines.add("工种," + csv(clazz.getOccupation()));
lines.add("培训年度," + csv(clazz.getTrainingYear() == null
? "" : clazz.getTrainingYear() + " 学年"));
lines.add("导出范围," + csv(ClassAdminConstants.EXPORT_SCOPE_SELECTED.equals(scope)
? "勾选的 " + students.size() + " 名学员" : "全班学员"));
lines.add("学员人数," + students.size());
lines.add("导出时间," + csv(formatDate(new Date(), "yyyy-MM-dd HH:mm:ss")));
lines.add("");
lines.add("序号,姓名,手机号,人员类别,所在单位,学历");
for (int i = 0; i < students.size(); i++) {
ClassAdminStudentVO student = students.get(i);
lines.add((i + 1) + "," + csv(student.getName()) + "," + csv(student.getPhone())
+ "," + csv(student.getPersonTypeName()) + "," + csv(student.getWorkUnit())
+ "," + csv(student.getHighestEducation()));
}
return String.join("\r\n", lines);
}
/** CSV字段统一使用双引号包裹,并将内部双引号按RFC 4180规则转义。 */
private String csv(Object value) {
String text = value == null ? "" : String.valueOf(value);
return "\"" + text.replace("\"", "\"\"") + "\"";
}
private String formatDate(Date date, String pattern) {
SimpleDateFormat formatter = new SimpleDateFormat(pattern, Locale.CHINA);
formatter.setTimeZone(TimeZone.getTimeZone(ClassAdminConstants.BUSINESS_ZONE));
return formatter.format(date);
} }
private Long calculateDurationDays(Date startDate, Date endDate) { private Long calculateDurationDays(Date startDate, Date endDate) {
......
...@@ -89,6 +89,221 @@ ...@@ -89,6 +89,221 @@
- 全班及个人出勤率;只有 `NORMAL/LATE` 计入出勤分子,`ABSENT/LEAVE` 计入分母。 - 全班及个人出勤率;只有 `NORMAL/LATE` 计入出勤分子,`ABSENT/LEAVE` 计入分母。
- 最近一场 `exam.mark_flag=true` 的考试,以及考生侧 `mark_flag=true` 的正式成绩。 - 最近一场 `exam.mark_flag=true` 的考试,以及考生侧 `mark_flag=true` 的正式成绩。
- 最近考试中 60 分及以上人数占有效成绩人数的比例;没有正式成绩时通过率返回 `null`。 - 最近考试中 60 分及以上人数占有效成绩人数的比例;没有正式成绩时通过率返回 `null`。
- 完整学员姓名和手机号。个人学习状态按班级日期派生为待开课、在读或已结业。 - 学员名单返回姓名、手机号、人员类别、所在单位、学历、账户状态、出勤和理论/实训成绩。
- 学员状态优先采用账户真实状态;只有旧数据缺少账户状态时才按班级日期回退展示。
- `graduationEligible=true` 表示最近已发布的理论和实训成绩都存在,且两者平均分不低于 60。
- `selectable=false` 表示学员已经结业或归档,前端应禁止再次勾选办理结业。
百分比字段以 `0~100` 的数值返回并最多保留两位小数,空值由页面展示为“—”。 百分比字段以 `0~100` 的数值返回并最多保留两位小数,空值由页面展示为“—”。
### 学员字段示例
```json
{
"relationId": 1801,
"userId": "1900000000000000101",
"name": "张三",
"phone": "13800000000",
"personTypes": ["在职", "从业"],
"personTypeName": "在职、从业",
"workUnit": "市第一污水处理厂",
"highestEducation": "本科",
"attendanceRate": 92.5,
"theoryScore": 78.0,
"practicalScore": 82.0,
"averageScore": 80.0,
"graduationEligible": true,
"accountStatus": "STUDYING",
"accountStatusName": "在读",
"learningStatus": "ACTIVE",
"learningStatusName": "在读",
"selectable": true
}
```
## 7. 学员详情与编辑
### 7.1 查询当前班级学员详情
`GET /class/admin/{classId}/students/{userId}`
接口会同时校验班级和成员关系。学员已被其他管理员转班或移除时返回业务错误,不会泄露其他
班级资料。响应字段与班级详情中的单条 `students` 完全一致,可直接复用账户管理的详情组件。
### 7.2 编辑名单资料
`PUT /class/admin/{classId}/students/{userId}`
```json
{
"name": "张三",
"phone": "13800000000",
"personTypes": ["在职"],
"workUnit": "市第一污水处理厂",
"highestEducation": "本科"
}
```
- 姓名、手机号必填;手机号必须是以 `1` 开头的 11 位数字且全系统唯一。
- 人员类别最多 10 项,单项最长 32 个字符;空数组表示清空。
- 编辑手机号会同步更新登录账号和 `phone_role` 的“学员”角色映射。
- 本接口不能修改出勤率、考试成绩、账户状态或班级关系。
## 8. 转班目标选项
`GET /class/admin/{classId}/students/transfer-options`
```json
[
{
"value": "21",
"label": "2026 污水一级 2 班",
"parentValue": "ONGOING",
"extra": "污水一级"
}
]
```
只返回待开课或进行中班级,并排除当前班。`value` 是提交转班接口所需的目标班级 ID;前端
不得把班级名称作为 ID 提交。弹窗每次打开时重新请求选项,避免使用已结课的缓存班级。
## 9. 移除学员
`POST /class/admin/{classId}/students/remove`
```json
{
"studentIds": ["1900000000000000101", "1900000000000000102"]
}
```
成功响应:
```json
{
"affectedCount": 2
}
```
- 单人和批量使用同一接口,ID 自动去重,单次最多 500 人。
- 仅删除当前有效的 `class_student` 关系,账号、已答试卷、成绩和出勤记录保留。
- 尚未开始且没有作答、提交和正式成绩的后续考试占位名单会同步清理。
- 服务端先锁定全部成员关系;任一学员已不在本班时整个请求回滚。
## 10. 转班
`POST /class/admin/{classId}/students/transfer`
```json
{
"studentIds": ["1900000000000000101", "1900000000000000102"],
"targetClassId": 21
}
```
成功响应结构与移除接口一致。源班解绑、目标班绑定、未来考试名单清理和历史记录写入在同一事务
完成。目标班不能是当前班,也不能是已结课或信息不完整班级。转回历史班级时,原班考试成绩
仍保留;新班不会继承原班成绩。
## 11. 结业办理
`POST /class/admin/{classId}/students/graduation`
```json
{
"studentIds": ["1900000000000000101", "1900000000000000102"],
"graduationDate": "2026-11-05",
"batchNo": "2026年第4批",
"remark": "完成规定课程与考核",
"mode": "PASSED_ONLY",
"issueCertificate": true,
"notifyStudent": true
}
```
`mode`:
- `ALL`:把所选待激活/在读学员全部结业,不受成绩限制。
- `PASSED_ONLY`:只结业 `graduationEligible=true` 的学员,其他人员返回跳过原因。
响应示例:
```json
{
"graduatedCount": 1,
"skippedCount": 1,
"graduatedStudentIds": ["1900000000000000101"],
"skippedStudents": [
{
"studentId": "1900000000000000102",
"name": "李四",
"reason": "理论或实训成绩未达标"
}
]
}
```
结业成功后账户状态更新为 `GRADUATED`,学员仍保留在名单中,但 `selectable=false`。勾选发证
时生成独立电子结业证书编号;勾选通知时只给实际成功结业的学员发送站内消息。
## 12. 导出学员名单
`POST /class/admin/{classId}/students/export`
导出全班:
```json
{
"scope": "ALL"
}
```
导出勾选学员:
```json
{
"scope": "SELECTED",
"studentIds": ["1900000000000000101"]
}
```
响应为 `text/csv;charset=UTF-8` 文件流,文件自带 UTF-8 BOM。CSV 包含班级信息、导出范围、
导出时间及“序号/姓名/手机号/人员类别/所在单位/学历”六列;逗号、换行和双引号均已转义。
前端应从 `Content-Disposition` 的 `filename*` 读取文件名。交互规则为:有勾选时提交
`SELECTED`,无勾选时提交 `ALL`。
## 13. 前端联调流程
1. 打开班级详情时调用 `GET /class/admin/{id}`,将 `students` 渲染到“学员名单”Tab。
2. 全选仅选择 `selectable=true` 的行,并维护半选状态;选中数大于 0 时启用批量按钮。
3. 点击详情调用第 7.1 节接口;点击编辑提交第 7.2 节接口,成功后替换当前行。
4. 打开转班弹窗时调用第 8 节接口,提交成功后重新获取班级详情和左侧班级树。
5. 移除成功后重新获取详情和树,不在前端自行推算班级人数。
6. 结业弹窗用名单中的理论/实训分和 `graduationEligible` 展示达标摘要;提交后按响应展示跳过项,
然后刷新详情。
7. 下载文件时必须按二进制处理,不要把CSV响应交给统一JSON响应拦截器。
所有JSON接口使用项目统一 `Result` 包装;业务失败由统一异常处理器返回中文 `msg`。发生失败时
前端保留当前选择,展示 `msg` 并重新拉取详情,以处理其他管理员并发修改关系的情况。
## 14. 常见业务错误
| 场景 | 服务端提示 | 前端处理 |
|---|---|---|
| 未选择学员 | 请至少选择一名学员 | 不发请求并高亮选择区 |
| 超过批量上限 | 单次批量操作不能超过500名学员 | 拆分选择或减少人数 |
| 成员并发变化 | 部分学员已不在当前班级,请刷新后重试 | 刷新详情并清空失效选择 |
| 转入当前班 | 目标班级不能是当前班级 | 保持弹窗并重新选择 |
| 转入已结课班 | 目标班级必须是待开课或进行中状态 | 刷新目标班选项 |
| 手机号重复 | 手机号已被其他账户使用 | 保持编辑弹窗并定位手机号 |
| 重复结业 | 当前账户状态不支持结业 | 在结果明细中展示跳过原因 |
## 15. 数据库部署
部署应用前执行 `sql/class_management.sql`。新增表:
- `class_student_change_log`:保存移除/转班历史,不影响当前班级权限判断。
- `student_graduation_record`:保存班级维度结业批次、说明、证书和通知请求。
脚本使用 `create table if not exists`,可重复执行;所有建表语句均不指定字符集或排序规则,沿用
目标数据库默认配置。上线顺序为:备份数据库 → 执行脚本 → 部署后端 → 前端联调验证。
...@@ -188,17 +188,33 @@ ...@@ -188,17 +188,33 @@
</select> </select>
<!-- <!--
学员名单一次性关联个人出勤率和指定的最近已发布考试成绩, 学员名单一次性关联个人资料、出勤率以及最近已发布的理论/实训成绩。
避免详情页按学员循环访问数据库造成N+1查询。 结业资格必须同时具有两类成绩,因此不能继续只读取最近一场任意类型考试。
--> -->
<select id="selectAdminStudents" resultType="com.platform.business.model.vo.ClassAdminStudentVO"> <sql id="adminStudentSelect">
select select
cs_member.id as relationId, cs_member.id as relationId,
cs_member.user_id as userId, cs_member.user_id as userId,
student.nick_name as name, student.nick_name as name,
student.phone_number as phone, student.phone_number as phone,
student.person_types as personTypesJson,
student.user_type1 as legacyPersonType1,
student.user_type2 as legacyPersonType2,
coalesce(nullif(student.work_unit, ''), student.company_name1, student.factory) as workUnit,
student.highest_education as highestEducation,
case
when upper(trim(student.account_status)) in ('PENDING','STUDYING','GRADUATED','ARCHIVED')
then upper(trim(student.account_status))
when coalesce(student.del_flag, 0) = 1 then 'ARCHIVED'
when coalesce(student.first_login_flag, 0) = 1 then 'PENDING'
else 'STUDYING'
end as accountStatus,
attendance.attendanceRate, attendance.attendanceRate,
examResult.examScore case when theoryResult.score is null or practiceResult.score is null then null
else round((theoryResult.score + practiceResult.score) / 2.0, 2)
end as examScore,
theoryResult.score as theoryScore,
practiceResult.score as practicalScore
from class_student cs_member from class_student cs_member
left join user student on student.id = cs_member.user_id left join user student on student.id = cs_member.user_id
left join ( left join (
...@@ -212,18 +228,145 @@ ...@@ -212,18 +228,145 @@
and record.status in ('NORMAL', 'LATE', 'ABSENT', 'LEAVE') and record.status in ('NORMAL', 'LATE', 'ABSENT', 'LEAVE')
group by record.user_id group by record.user_id
) attendance on attendance.user_id = cs_member.user_id ) attendance on attendance.user_id = cs_member.user_id
left join ( left join exam_student theoryResult on theoryResult.id = (
select student_id, max(score) as examScore select theory_student.id
from exam_student from exam_student theory_student
where exam_id = #{examId,jdbcType=INTEGER} inner join exam theory_exam on theory_exam.id = theory_student.exam_id
and mark_flag = 1 where theory_student.class_id = #{classId}
and score is not null and theory_student.student_id = cs_member.user_id
group by student_id and theory_exam.type = '理论考试'
) examResult on examResult.student_id = cs_member.user_id and theory_exam.mark_flag = 1
and theory_student.mark_flag = 1
and theory_student.score is not null
order by theory_exam.exam_time desc, theory_exam.id desc, theory_student.id desc
limit 1
)
left join exam_student practiceResult on practiceResult.id = (
select practice_student.id
from exam_student practice_student
inner join exam practice_exam on practice_exam.id = practice_student.exam_id
where practice_student.class_id = #{classId}
and practice_student.student_id = cs_member.user_id
and practice_exam.type = '实训考试'
and practice_exam.mark_flag = 1
and practice_student.mark_flag = 1
and practice_student.score is not null
order by practice_exam.exam_time desc, practice_exam.id desc, practice_student.id desc
limit 1
)
</sql>
<select id="selectAdminStudents" resultType="com.platform.business.model.vo.ClassAdminStudentVO">
<include refid="adminStudentSelect"/>
where cs_member.class_id = #{classId} where cs_member.class_id = #{classId}
order by student.nick_name asc, student.phone_number asc, cs_member.id asc order by student.nick_name asc, student.phone_number asc, cs_member.id asc
</select> </select>
<select id="selectAdminStudent" resultType="com.platform.business.model.vo.ClassAdminStudentVO">
<include refid="adminStudentSelect"/>
where cs_member.class_id = #{classId}
and cs_member.user_id = #{userId}
order by cs_member.id desc
limit 1
</select>
<!-- FOR UPDATE与业务事务配合,确保校验完成后成员关系不会被另一请求抢先修改。 -->
<select id="lockAdminStudentIds" resultType="java.lang.String">
select user_id
from class_student
where class_id = #{classId}
and user_id in
<foreach collection="userIds" item="userId" open="(" close=")" separator=",">
#{userId}
</foreach>
for update
</select>
<select id="selectTransferClassOptions" resultType="com.platform.business.model.vo.ClassAdminOptionVO">
select cast(c.id as char) as value,
c.name as label,
case when c.start_date &gt; #{today} then 'UPCOMING' else 'ONGOING' end as parentValue,
sl.name as extra
from class c
left join sys_level sl on cast(sl.id as char) = c.level
where c.id != #{excludeClassId}
and c.start_date is not null
and c.end_date is not null
and c.end_date &gt;= #{today}
order by c.start_date asc, c.name asc
</select>
<select id="countAdminStudentPhone" resultType="java.lang.Integer">
select count(*)
from user
where phone_number = #{phone}
and id != #{excludeUserId}
</select>
<update id="updateAdminStudentProfile">
update user
set nick_name = #{name},
phone_number = #{phone},
username = #{phone},
person_types = #{personTypesJson,jdbcType=LONGVARCHAR},
user_type1 = #{personType1,jdbcType=VARCHAR},
user_type2 = #{personType2,jdbcType=VARCHAR},
work_unit = #{workUnit,jdbcType=VARCHAR},
company_name1 = #{workUnit,jdbcType=VARCHAR},
highest_education = #{highestEducation,jdbcType=VARCHAR},
update_time = #{updateTime}
where id = #{userId}
</update>
<delete id="deleteAdminStudentRelations">
delete from class_student
where class_id = #{classId}
and user_id in
<foreach collection="userIds" item="userId" open="(" close=")" separator=",">
#{userId}
</foreach>
</delete>
<insert id="insertAdminStudentRelations">
insert into class_student (class_id, user_id) values
<foreach collection="userIds" item="userId" separator=",">
(#{classId}, #{userId})
</foreach>
</insert>
<!--
移除/转班后只清除尚未开始且没有任何作答、提交、成绩的考试占位记录。
已开始考试及历史答卷继续保留,满足原班成绩可追溯要求。
-->
<delete id="deletePendingExamStudents">
delete student
from exam_student student
inner join exam e on e.id = student.exam_id
where student.class_id = #{classId}
and student.student_id in
<foreach collection="userIds" item="userId" open="(" close=")" separator=",">
#{userId}
</foreach>
and e.exam_time &gt; #{now}
and coalesce(student.submit, 0) = 0
and student.score is null
and student.start_time is null
and student.answer_time is null
and coalesce(student.mark_flag, 0) = 0
</delete>
<update id="graduateAdminStudent">
update user
set account_status = 'GRADUATED',
graduation_time = #{graduationTime},
del_flag = 0,
update_time = #{updateTime}
where id = #{userId}
and upper(coalesce(account_status,
case when first_login_flag = 1 then 'PENDING' else 'STUDYING' end))
in ('PENDING', 'STUDYING')
</update>
<!-- 只向班级表单暴露能归属到污水或污泥工种的启用等级。 --> <!-- 只向班级表单暴露能归属到污水或污泥工种的启用等级。 -->
<select id="selectAdminLevelOptions" resultType="com.platform.business.model.vo.ClassAdminOptionVO"> <select id="selectAdminLevelOptions" resultType="com.platform.business.model.vo.ClassAdminOptionVO">
select select
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment