"...service/git@gitlab.ruzhoukj.com:wujipeng/relation.git" did not exist on "e2409a8b4372703c6ca06a066e6956b47cc075ed"
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);
} }
...@@ -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