Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
邬吉朋
practical_train
Commits
fb3c0f0e
Commit
fb3c0f0e
authored
Nov 05, 2026
by
wujipeng
Browse files
教务管理-班级管理-班级详情-学员名单-优化
parent
29ed92a5
Changes
25
Hide whitespace changes
Inline
Side-by-side
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/ClassStudentExportDTO.java
0 → 100644
View file @
fb3c0f0e
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
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/ClassStudentGraduationDTO.java
0 → 100644
View file @
fb3c0f0e
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
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/ClassStudentIdsDTO.java
0 → 100644
View file @
fb3c0f0e
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
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/ClassStudentTransferDTO.java
0 → 100644
View file @
fb3c0f0e
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
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/dto/ClassStudentUpdateDTO.java
0 → 100644
View file @
fb3c0f0e
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
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/entity/ClassStudentChangeLogEntity.java
0 → 100644
View file @
fb3c0f0e
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
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/entity/StudentGraduationRecordEntity.java
0 → 100644
View file @
fb3c0f0e
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
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/vo/ClassAdminStudentVO.java
View file @
fb3c0f0e
package
com.platform.business.model.vo
;
import
com.fasterxml.jackson.annotation.JsonIgnore
;
import
lombok.Data
;
import
java.math.BigDecimal
;
import
java.util.List
;
/** 班级详情中的学员名单及其真实统计数据。 */
@Data
...
...
@@ -16,12 +18,50 @@ public class ClassAdminStudentVO {
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记录占全部有效出勤记录的百分比。 */
private
BigDecimal
attendanceRate
;
/** 最近一场已发布考试成绩;没有已发布成绩时为空。 */
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
learningStatusName
;
...
...
practical-api/practical-business-api/src/main/java/com/platform/business/model/vo/ClassStudentExportFileVO.java
0 → 100644
View file @
fb3c0f0e
package
com.platform.business.model.vo
;
import
lombok.AllArgsConstructor
;
import
lombok.Data
;
/** 由业务层生成的下载文件,控制器只负责设置HTTP响应头并写出字节。 */
@Data
@AllArgsConstructor
public
class
ClassStudentExportFileVO
{
private
String
fileName
;
private
byte
[]
content
;
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/vo/ClassStudentGraduationResultVO.java
0 → 100644
View file @
fb3c0f0e
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
;
}
}
}
practical-api/practical-business-api/src/main/java/com/platform/business/model/vo/ClassStudentOperationResultVO.java
0 → 100644
View file @
fb3c0f0e
package
com.platform.business.model.vo
;
import
lombok.AllArgsConstructor
;
import
lombok.Data
;
import
lombok.NoArgsConstructor
;
/** 转班、移除等班级关系操作的统一结果。 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public
class
ClassStudentOperationResultVO
{
private
Integer
affectedCount
;
}
practical-business/src/main/java/com/platform/business/constant/ClassAdminConstants.java
View file @
fb3c0f0e
...
...
@@ -32,6 +32,11 @@ public final class ClassAdminConstants {
public
static
final
int
MAX_LOCATION_LENGTH
=
255
;
public
static
final
int
MAX_REMARK_LENGTH
=
1000
;
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
MAX_TRAINING_YEAR
=
2100
;
...
...
practical-business/src/main/java/com/platform/business/controller/ClassAdminController.java
View file @
fb3c0f0e
...
...
@@ -4,10 +4,20 @@ import com.github.pagehelper.PageHelper;
import
com.platform.business.constant.ClassAdminConstants
;
import
com.platform.business.model.dto.ClassAdminQueryDTO
;
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.ClassAdminDetailVO
;
import
com.platform.business.model.vo.ClassAdminOptionsVO
;
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.ClassAdminService
;
import
com.platform.controller.BaseController
;
...
...
@@ -26,6 +36,10 @@ import org.springframework.web.bind.annotation.RestController;
import
javax.annotation.Resource
;
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
;
/**
...
...
@@ -105,6 +119,82 @@ public class ClassAdminController extends BaseController {
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可接受的安全范围内。 */
void
normalizePage
(
ClassAdminQueryDTO
query
)
{
if
(
query
.
getPageNum
()
==
null
||
query
.
getPageNum
()
<
1
)
{
...
...
practical-business/src/main/java/com/platform/business/mapper/ClassMapper.java
View file @
fb3c0f0e
...
...
@@ -40,6 +40,46 @@ public interface ClassMapper extends BaseMapper<ClassEntity> {
List
<
ClassAdminStudentVO
>
selectAdminStudents
(
@Param
(
"classId"
)
Integer
classId
,
@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
>
selectAdminHeadTeacherOptions
();
...
...
practical-business/src/main/java/com/platform/business/mapper/ClassStudentChangeLogMapper.java
0 → 100644
View file @
fb3c0f0e
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
>
{
}
practical-business/src/main/java/com/platform/business/mapper/StudentGraduationRecordMapper.java
0 → 100644
View file @
fb3c0f0e
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
>
{
}
practical-business/src/main/java/com/platform/business/service/ClassAdminService.java
View file @
fb3c0f0e
...
...
@@ -2,11 +2,21 @@ package com.platform.business.service;
import
com.platform.business.model.dto.ClassAdminQueryDTO
;
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.ClassAdminDetailVO
;
import
com.platform.business.model.vo.ClassAdminOptionsVO
;
import
com.platform.business.model.vo.ClassAdminOptionVO
;
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
;
...
...
@@ -27,4 +37,22 @@ public interface ClassAdminService {
ClassAdminDetailVO
update
(
Integer
classId
,
ClassAdminSaveDTO
request
);
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
);
}
practical-business/src/main/java/com/platform/business/service/impl/ClassAdminServiceImpl.java
View file @
fb3c0f0e
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.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.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.StudentGraduationRecordEntity
;
import
com.platform.business.model.entity.SysLevelEntity
;
import
com.platform.business.model.entity.SysPhoneRoleEntity
;
import
com.platform.business.model.entity.UserEntity
;
...
...
@@ -16,6 +29,10 @@ import com.platform.business.model.vo.ClassAdminOptionVO;
import
com.platform.business.model.vo.ClassAdminOptionsVO
;
import
com.platform.business.model.vo.ClassAdminStudentVO
;
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.SysLevelService
;
import
com.platform.business.service.SysPhoneRoleService
;
...
...
@@ -27,17 +44,23 @@ import org.springframework.transaction.annotation.Transactional;
import
javax.annotation.Resource
;
import
java.time.LocalDate
;
import
java.time.temporal.ChronoUnit
;
import
java.nio.charset.StandardCharsets
;
import
java.text.SimpleDateFormat
;
import
java.util.ArrayList
;
import
java.util.Arrays
;
import
java.util.Collections
;
import
java.util.Comparator
;
import
java.util.Date
;
import
java.util.LinkedHashMap
;
import
java.util.LinkedHashSet
;
import
java.util.List
;
import
java.util.Locale
;
import
java.util.Map
;
import
java.util.Set
;
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 {
@Resource
private
SysPhoneRoleService
phoneRoleService
;
@Resource
private
ClassStudentChangeLogMapper
changeLogMapper
;
@Resource
private
StudentGraduationRecordMapper
graduationRecordMapper
;
@Resource
private
BusinessNotificationPublisher
notificationPublisher
;
@Override
public
List
<
ClassAdminCardVO
>
page
(
ClassAdminQueryDTO
query
)
{
ClassAdminQueryDTO
normalized
=
query
==
null
?
new
ClassAdminQueryDTO
()
:
query
;
...
...
@@ -194,12 +226,237 @@ public class ClassAdminServiceImpl implements ClassAdminService {
students
=
Collections
.
emptyList
();
}
for
(
ClassAdminStudentVO
student
:
students
)
{
applyLearningStatus
(
student
,
detail
.
getStatus
());
enrichStudent
(
student
,
detail
.
getStatus
());
}
detail
.
setStudents
(
students
);
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只接收去空格、转大写后的值。
*/
...
...
@@ -445,20 +702,257 @@ public class ClassAdminServiceImpl implements ClassAdminService {
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
.
setLearningStatusName
(
"待开课"
);
}
else
if
(
ClassAdminConstants
.
STATUS_ONGOING
.
equals
(
classStatus
))
{
student
.
setLearningStatusName
(
"待激活"
);
student
.
setAccountStatusName
(
"待激活"
);
student
.
setSelectable
(
true
);
}
else
if
(
AccountAdminConstants
.
STATUS_STUDYING
.
equals
(
accountStatus
))
{
student
.
setLearningStatus
(
ClassAdminConstants
.
LEARNING_ACTIVE
);
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
.
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
{
student
.
setLearningStatus
(
ClassAdminConstants
.
LEARNING_UNKNOWN
);
student
.
setLearningStatusName
(
"信息待补全"
);
student
.
setAccountStatusName
(
"信息待补全"
);
student
.
setSelectable
(
false
);
}
if
(
student
.
getTheoryScore
()
!=
null
&&
student
.
getPracticalScore
()
!=
null
)
{
double
average
=
Math
.
round
((
student
.
getTheoryScore
()
+
student
.
getPracticalScore
())
*
50.0
D
)
/
100.0
D
;
student
.
setAverageScore
(
average
);
student
.
setExamScore
(
average
);
student
.
setGraduationEligible
(
average
>=
60.0
D
);
}
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
)
{
...
...
practical-business/src/main/resources/class-management-api.md
View file @
fb3c0f0e
...
...
@@ -89,6 +89,221 @@
-
全班及个人出勤率;只有
`NORMAL/LATE`
计入出勤分子,
`ABSENT/LEAVE`
计入分母。
-
最近一场
`exam.mark_flag=true`
的考试,以及考生侧
`mark_flag=true`
的正式成绩。
-
最近考试中 60 分及以上人数占有效成绩人数的比例;没有正式成绩时通过率返回
`null`
。
-
完整学员姓名和手机号。个人学习状态按班级日期派生为待开课、在读或已结业。
-
学员名单返回姓名、手机号、人员类别、所在单位、学历、账户状态、出勤和理论/实训成绩。
-
学员状态优先采用账户真实状态;只有旧数据缺少账户状态时才按班级日期回退展示。
-
`graduationEligible=true`
表示最近已发布的理论和实训成绩都存在,且两者平均分不低于 60。
-
`selectable=false`
表示学员已经结业或归档,前端应禁止再次勾选办理结业。
百分比字段以
`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`
,可重复执行;所有建表语句均不指定字符集或排序规则,沿用
目标数据库默认配置。上线顺序为:备份数据库 → 执行脚本 → 部署后端 → 前端联调验证。
practical-business/src/main/resources/com/platform/business/mapper/ClassMapper.xml
View file @
fb3c0f0e
...
...
@@ -188,17 +188,33 @@
</select>
<!--
学员名单一次性关联个人
出勤率和指定的最近已发布考试
成绩
,
避免详情页按学员循环访问数据库造成N+1查询
。
学员名单一次性关联个人
资料、出勤率以及最近已发布的理论/实训
成绩
。
结业资格必须同时具有两类成绩,因此不能继续只读取最近一场任意类型考试
。
-->
<s
elect
id=
"selectAdminStudents"
resultType=
"com.platform.business.model.vo.ClassAdminStudentVO
"
>
<s
ql
id=
"adminStudentSelect
"
>
select
cs_member.id as relationId,
cs_member.user_id as userId,
student.nick_name as name,
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,
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
left join user student on student.id = cs_member.user_id
left join (
...
...
@@ -212,18 +228,145 @@
and record.status in ('NORMAL', 'LATE', 'ABSENT', 'LEAVE')
group by record.user_id
) attendance on attendance.user_id = cs_member.user_id
left join (
select student_id, max(score) as examScore
from exam_student
where exam_id = #{examId,jdbcType=INTEGER}
and mark_flag = 1
and score is not null
group by student_id
) examResult on examResult.student_id = cs_member.user_id
left join exam_student theoryResult on theoryResult.id = (
select theory_student.id
from exam_student theory_student
inner join exam theory_exam on theory_exam.id = theory_student.exam_id
where theory_student.class_id = #{classId}
and theory_student.student_id = cs_member.user_id
and theory_exam.type = '理论考试'
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}
order by student.nick_name asc, student.phone_number asc, cs_member.id asc
</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
>
#{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
>
= #{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
>
#{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
...
...
Prev
1
2
Next
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment