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
Expand all
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
;
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
;
...
...
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 {
...
@@ -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
;
...
...
practical-business/src/main/java/com/platform/business/controller/ClassAdminController.java
View file @
fb3c0f0e
...
@@ -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
)
{
...
...
practical-business/src/main/java/com/platform/business/mapper/ClassMapper.java
View file @
fb3c0f0e
...
@@ -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
();
...
...
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;
...
@@ -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
);
}
}
practical-business/src/main/java/com/platform/business/service/impl/ClassAdminServiceImpl.java
View file @
fb3c0f0e
This diff is collapsed.
Click to expand it.
practical-business/src/main/resources/class-management-api.md
View file @
fb3c0f0e
...
@@ -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`
,可重复执行;所有建表语句均不指定字符集或排序规则,沿用
目标数据库默认配置。上线顺序为:备份数据库 → 执行脚本 → 部署后端 → 前端联调验证。
practical-business/src/main/resources/com/platform/business/mapper/ClassMapper.xml
View file @
fb3c0f0e
...
@@ -188,17 +188,33 @@
...
@@ -188,17 +188,33 @@
</select>
</select>
<!--
<!--
学员名单一次性关联个人
出勤率和指定的最近已发布考试
成绩
,
学员名单一次性关联个人
资料、出勤率以及最近已发布的理论/实训
成绩
。
避免详情页按学员循环访问数据库造成N+1查询
。
结业资格必须同时具有两类成绩,因此不能继续只读取最近一场任意类型考试
。
-->
-->
<s
elect
id=
"selectAdminStudents"
resultType=
"com.platform.business.model.vo.ClassAdminStudentVO
"
>
<s
ql
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
>
#{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
id=
"selectAdminLevelOptions"
resultType=
"com.platform.business.model.vo.ClassAdminOptionVO"
>
select
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