"src/git@gitlab.ruzhoukj.com:wujipeng/ops.git" did not exist on "2f2fc3cfcea6507265f168dbe493c053b0715fe0"
Commit 2fea7e12 authored by wujipeng's avatar wujipeng
Browse files

管理员-教务管理-班级管理

parent 39ea4860
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* 管理员端班级卡片分页查询条件。
*
* <p>分页边界由控制器统一归一化;其余文本、年度和状态条件由业务层校验,
* 防止无效条件直接进入动态SQL。</p>
*/
@Data
public class ClassAdminQueryDTO {
@ApiModelProperty("页码,默认1")
private Integer pageNum;
@ApiModelProperty("每页条数,默认20,最大100")
private Integer pageSize;
@ApiModelProperty("班级名称关键字")
private String keyword;
@ApiModelProperty("工种:污水/污泥")
private String occupation;
@ApiModelProperty("培训年度")
private Integer trainingYear;
@ApiModelProperty("职业等级ID")
private Integer levelId;
@ApiModelProperty("班级状态:UPCOMING/ONGOING/ENDED/UNKNOWN")
private String status;
}
package com.platform.business.model.dto;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Date;
/** 管理员新增或编辑班级时允许提交的字段。 */
@Data
public class ClassAdminSaveDTO {
@ApiModelProperty(value = "班级名称", required = true)
private String name;
@ApiModelProperty(value = "工种:污水/污泥", required = true)
private String occupation;
@ApiModelProperty(value = "培训年度", required = true)
private Integer trainingYear;
@ApiModelProperty(value = "职业等级ID", required = true)
private Integer levelId;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
@ApiModelProperty(value = "培训开始日期", required = true)
private Date startDate;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
@ApiModelProperty(value = "培训结束日期", required = true)
private Date endDate;
@ApiModelProperty("班主任用户ID,可为空")
private String headTeacherId;
@ApiModelProperty("培训地点,可为空")
private String location;
@ApiModelProperty("计划人数,1~200")
private Integer capacity;
@ApiModelProperty("备注,可为空")
private String remark;
}
package com.platform.business.model.dto; package com.platform.business.model.dto;
import com.fasterxml.jackson.annotation.JsonFormat;
import com.platform.business.model.entity.ClassEntity; import com.platform.business.model.entity.ClassEntity;
import com.platform.business.model.entity.ClassStudentEntity; import com.platform.business.model.entity.ClassStudentEntity;
import lombok.Data; import lombok.Data;
import lombok.EqualsAndHashCode; import lombok.EqualsAndHashCode;
import java.util.Date;
import java.util.List; import java.util.List;
@Data @Data
...@@ -18,12 +16,6 @@ public class ClassDTO extends ClassEntity { ...@@ -18,12 +16,6 @@ public class ClassDTO extends ClassEntity {
private List<ClassStudentEntity> studentList; private List<ClassStudentEntity> studentList;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date startDate;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date endDate;
private String userId; private String userId;
......
package com.platform.business.model.entity; package com.platform.business.model.entity;
import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName; import com.baomidou.mybatisplus.annotation.TableName;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data; import lombok.Data;
import java.util.Date; import java.util.Date;
...@@ -18,5 +21,50 @@ public class ClassEntity { ...@@ -18,5 +21,50 @@ public class ClassEntity {
private String level; private String level;
/**
* 班级所属工种。目前管理端仅开放“污水”和“污泥”两个值。
*
* <p>该字段与 {@code level} 分开保存,避免通过等级名称临时截取工种,
* 同时保留旧接口使用等级ID字符串的历史约定。</p>
*/
@TableField("occupation")
@ApiModelProperty("工种:污水/污泥")
private String occupation;
@TableField("training_year")
@ApiModelProperty("培训年度")
private Integer trainingYear;
@TableField("start_date")
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
@ApiModelProperty("培训开始日期")
private Date startDate;
@TableField("end_date")
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
@ApiModelProperty("培训结束日期")
private Date endDate;
@TableField("head_teacher_id")
@ApiModelProperty("班主任用户ID")
private String headTeacherId;
@TableField("location")
@ApiModelProperty("培训地点")
private String location;
@TableField("capacity")
@ApiModelProperty("计划人数")
private Integer capacity;
@TableField("remark")
@ApiModelProperty("班级备注")
private String remark;
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date createTime; private Date createTime;
@TableField("update_time")
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date updateTime;
} }
package com.platform.business.model.vo;
import com.fasterxml.jackson.annotation.JsonFormat;
import lombok.Data;
import java.util.Date;
/** 管理员端班级卡片及班级树叶节点共用的扁平数据。 */
@Data
public class ClassAdminCardVO {
private Integer id;
private String name;
private String occupation;
private Integer trainingYear;
private String levelId;
private String levelName;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date startDate;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date endDate;
private Integer capacity;
private Integer studentCount;
/** 动态状态代码,不在数据库中持久化。 */
private String status;
private String statusName;
}
package com.platform.business.model.vo;
import com.fasterxml.jackson.annotation.JsonFormat;
import lombok.Data;
import java.util.Date;
/** 班级详情中的逻辑课程汇总项。 */
@Data
public class ClassAdminCourseVO {
private String subjectName;
private String type;
private Integer totalHours;
private String teacherId;
private String teacherName;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date firstDate;
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date lastDate;
private String status;
private String statusName;
}
package com.platform.business.model.vo;
import lombok.Data;
import lombok.EqualsAndHashCode;
import java.math.BigDecimal;
import java.util.List;
/** 管理员端班级详情聚合响应。 */
@Data
@EqualsAndHashCode(callSuper = true)
public class ClassAdminDetailVO extends ClassAdminCardVO {
private String headTeacherId;
private String headTeacherName;
private String location;
private String remark;
/** 含开始日和结束日的自然日数量。 */
private Long durationDays;
private Integer courseCount;
private BigDecimal attendanceRate;
private BigDecimal passRate;
private Integer latestExamId;
private String latestExamName;
private List<ClassAdminCourseVO> courses;
private List<ClassAdminStudentVO> students;
}
package com.platform.business.model.vo;
import com.fasterxml.jackson.annotation.JsonFormat;
import lombok.Data;
import java.math.BigDecimal;
import java.util.Date;
/** 最近一场已发布考试及其班级通过率。 */
@Data
public class ClassAdminExamVO {
private Integer examId;
private String examName;
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date examTime;
private BigDecimal passRate;
}
package com.platform.business.model.vo;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/** 管理员端班级表单通用下拉选项。 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ClassAdminOptionVO {
/** 提交给接口的稳定值。 */
private String value;
/** 页面展示文本。 */
private String label;
/** 等级所属工种等父级值;没有父级时为空。 */
private String parentValue;
/** 手机号等补充展示信息;没有补充信息时为空。 */
private String extra;
}
package com.platform.business.model.vo;
import lombok.Data;
import java.util.List;
/** 班级新建/编辑表单一次性加载的选项集合。 */
@Data
public class ClassAdminOptionsVO {
private List<ClassAdminOptionVO> occupations;
private List<Integer> years;
private List<ClassAdminOptionVO> levels;
private List<ClassAdminOptionVO> headTeachers;
}
package com.platform.business.model.vo;
import lombok.Data;
import java.math.BigDecimal;
/** 班级详情中的学员名单及其真实统计数据。 */
@Data
public class ClassAdminStudentVO {
private Integer relationId;
private String userId;
private String name;
private String phone;
/** NORMAL和LATE记录占全部有效出勤记录的百分比。 */
private BigDecimal attendanceRate;
/** 最近一场已发布考试成绩;没有已发布成绩时为空。 */
private Double examScore;
private String learningStatus;
private String learningStatusName;
}
package com.platform.business.model.vo;
import lombok.Data;
import java.util.ArrayList;
import java.util.List;
/** “工种-年度-等级-班级”导航树节点。 */
@Data
public class ClassAdminTreeVO {
/** 节点类型:OCCUPATION、YEAR、LEVEL或CLASS。 */
private String nodeType;
private String label;
private String value;
/** 分组节点下的班级数量。 */
private Integer count;
/** 仅班级叶节点返回。 */
private Integer classId;
/** 仅班级叶节点返回。 */
private Integer studentCount;
private List<ClassAdminTreeVO> children = new ArrayList<>();
}
package com.platform.business.constant;
import java.time.ZoneId;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
import java.util.Set;
/** 管理员端班级管理使用的固定业务规则。 */
public final class ClassAdminConstants {
private ClassAdminConstants() {
}
public static final String OCCUPATION_WASTEWATER = "污水";
public static final String OCCUPATION_SLUDGE = "污泥";
public static final String STATUS_UPCOMING = "UPCOMING";
public static final String STATUS_ONGOING = "ONGOING";
public static final String STATUS_ENDED = "ENDED";
public static final String STATUS_UNKNOWN = "UNKNOWN";
public static final String LEARNING_PENDING = "PENDING";
public static final String LEARNING_ACTIVE = "ACTIVE";
public static final String LEARNING_COMPLETED = "COMPLETED";
public static final String LEARNING_UNKNOWN = "UNKNOWN";
public static final int DEFAULT_PAGE_NUM = 1;
public static final int DEFAULT_PAGE_SIZE = 20;
public static final int MAX_PAGE_SIZE = 100;
public static final int MAX_NAME_LENGTH = 100;
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 MIN_TRAINING_YEAR = 2000;
public static final int MAX_TRAINING_YEAR = 2100;
/** 所有状态和日期计算都以产品约定的中国标准时间为准。 */
public static final ZoneId BUSINESS_ZONE = ZoneId.of("Asia/Shanghai");
public static final Set<String> OCCUPATIONS = Collections.unmodifiableSet(
new HashSet<>(Arrays.asList(OCCUPATION_WASTEWATER, OCCUPATION_SLUDGE)));
public static final Set<String> CLASS_STATUSES = Collections.unmodifiableSet(
new HashSet<>(Arrays.asList(STATUS_UPCOMING, STATUS_ONGOING,
STATUS_ENDED, STATUS_UNKNOWN)));
}
package com.platform.business.controller;
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.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.service.AuthenticatedUserService;
import com.platform.business.service.ClassAdminService;
import com.platform.controller.BaseController;
import com.platform.model.resp.Result;
import com.platform.page.TableDataInfo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import java.util.List;
/**
* 管理员端“教务管理-班级管理”接口。
*
* <p>该控制器使用独立的 {@code /class/admin} 前缀,不改变旧版班级、学生日历和
* 教师日历接口。每个入口都从JWT解析当前用户并校验管理员角色,客户端传入的用户ID
* 不参与权限判断。</p>
*/
@Api(tags = "管理员端-班级管理")
@RestController
@RequestMapping("/class/admin")
public class ClassAdminController extends BaseController {
@Resource
private ClassAdminService classAdminService;
@Resource
private AuthenticatedUserService authenticatedUserService;
@ApiOperation("班级卡片分页")
@PostMapping("/page")
public TableDataInfo page(@RequestBody(required = false) ClassAdminQueryDTO query,
HttpServletRequest request) {
requireAdmin(request);
if (query == null) {
query = new ClassAdminQueryDTO();
}
normalizePage(query);
startPage(query.getPageNum(), query.getPageSize());
try {
return getDataTable(classAdminService.page(query));
} finally {
// 查询参数校验可能在Mapper执行前抛错,显式清理可防止分页上下文污染复用的请求线程。
PageHelper.clearPage();
}
}
@ApiOperation("班级导航树")
@GetMapping("/tree")
public Result<List<ClassAdminTreeVO>> tree(
@RequestParam(value = "keyword", required = false) String keyword,
HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.tree(keyword));
}
@ApiOperation("班级表单选项")
@GetMapping("/options")
public Result<ClassAdminOptionsVO> options(HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.options());
}
@ApiOperation("新增班级")
@PostMapping
public Result<ClassAdminDetailVO> create(@RequestBody ClassAdminSaveDTO body,
HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.create(body));
}
@ApiOperation("编辑班级")
@PutMapping("/{id}")
public Result<ClassAdminDetailVO> update(@PathVariable("id") Integer id,
@RequestBody ClassAdminSaveDTO body,
HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.update(id, body));
}
@ApiOperation("班级详情")
@GetMapping("/{id}")
public Result<ClassAdminDetailVO> detail(@PathVariable("id") Integer id,
HttpServletRequest request) {
requireAdmin(request);
return Result.data(classAdminService.detail(id));
}
/** 将异常分页参数限制在PageHelper可接受的安全范围内。 */
void normalizePage(ClassAdminQueryDTO query) {
if (query.getPageNum() == null || query.getPageNum() < 1) {
query.setPageNum(ClassAdminConstants.DEFAULT_PAGE_NUM);
}
if (query.getPageSize() == null || query.getPageSize() < 1) {
query.setPageSize(ClassAdminConstants.DEFAULT_PAGE_SIZE);
} else if (query.getPageSize() > ClassAdminConstants.MAX_PAGE_SIZE) {
query.setPageSize(ClassAdminConstants.MAX_PAGE_SIZE);
}
}
/** 统一解析JWT并执行管理员角色校验,避免任一新增入口漏掉权限保护。 */
private UserEntity requireAdmin(HttpServletRequest request) {
UserEntity administrator = authenticatedUserService.current(request);
authenticatedUserService.requireAdmin(administrator);
return administrator;
}
}
package com.platform.business.mapper; package com.platform.business.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.platform.business.model.dto.ClassAdminQueryDTO;
import com.platform.business.model.dto.ClassDTO; import com.platform.business.model.dto.ClassDTO;
import com.platform.business.model.entity.ClassEntity; import com.platform.business.model.entity.ClassEntity;
import com.platform.business.model.vo.ClassAdminCardVO;
import com.platform.business.model.vo.ClassAdminCourseVO;
import com.platform.business.model.vo.ClassAdminDetailVO;
import com.platform.business.model.vo.ClassAdminExamVO;
import com.platform.business.model.vo.ClassAdminOptionVO;
import com.platform.business.model.vo.ClassAdminStudentVO;
import com.platform.business.model.vo.ClassVO; import com.platform.business.model.vo.ClassVO;
import org.apache.ibatis.annotations.Mapper; import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import java.util.Date;
import java.util.List; import java.util.List;
@Mapper @Mapper
public interface ClassMapper extends BaseMapper<ClassEntity> { public interface ClassMapper extends BaseMapper<ClassEntity> {
List<ClassVO> queryList(ClassDTO classDTO); List<ClassVO> queryList(ClassDTO classDTO);
/** 管理员卡片分页和导航树复用同一套过滤条件。 */
List<ClassAdminCardVO> selectAdminClasses(@Param("query") ClassAdminQueryDTO query,
@Param("today") Date today);
ClassAdminDetailVO selectAdminDetail(@Param("classId") Integer classId);
List<ClassAdminCourseVO> selectAdminCourses(@Param("classId") Integer classId);
ClassAdminExamVO selectLatestPublishedExam(@Param("classId") Integer classId);
List<ClassAdminStudentVO> selectAdminStudents(@Param("classId") Integer classId,
@Param("examId") Integer examId);
List<ClassAdminOptionVO> selectAdminLevelOptions();
List<ClassAdminOptionVO> selectAdminHeadTeacherOptions();
List<Integer> selectAdminTrainingYears();
int countAdminDuplicateName(@Param("trainingYear") Integer trainingYear,
@Param("name") String name,
@Param("excludeId") Integer excludeId);
int countAdminStudents(@Param("classId") Integer classId);
/** 显式更新可编辑字段,使管理员能够把选填字段清空为NULL。 */
int updateAdminClass(ClassEntity entity);
} }
package com.platform.business.service;
import com.platform.business.model.dto.ClassAdminQueryDTO;
import com.platform.business.model.dto.ClassAdminSaveDTO;
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.ClassAdminTreeVO;
import java.util.List;
/** 管理员端班级管理业务接口,不承载学生端和教师端排课能力。 */
public interface ClassAdminService {
List<ClassAdminCardVO> page(ClassAdminQueryDTO query);
List<ClassAdminTreeVO> tree(String keyword);
ClassAdminOptionsVO options();
ClassAdminDetailVO create(ClassAdminSaveDTO request);
ClassAdminDetailVO update(Integer classId, ClassAdminSaveDTO request);
ClassAdminDetailVO detail(Integer classId);
}
...@@ -22,7 +22,8 @@ import java.util.concurrent.TimeUnit; ...@@ -22,7 +22,8 @@ import java.util.concurrent.TimeUnit;
@Service @Service
@Slf4j @Slf4j
public class NotificationPresenceService { public class NotificationPresenceService {
@Resource // @Resource
@Resource(name = "stringRedisTemplate")
private StringRedisTemplate redisTemplate; private StringRedisTemplate redisTemplate;
@Resource @Resource
private NotificationNodeIdentity nodeIdentity; private NotificationNodeIdentity nodeIdentity;
......
...@@ -28,7 +28,8 @@ public class NotificationSocketTicketService { ...@@ -28,7 +28,8 @@ public class NotificationSocketTicketService {
"local value = redis.call('GET', KEYS[1]); " + "local value = redis.call('GET', KEYS[1]); " +
"if value then redis.call('DEL', KEYS[1]); end; return value;", String.class); "if value then redis.call('DEL', KEYS[1]); end; return value;", String.class);
@Resource // @Resource
@Resource(name = "stringRedisTemplate")
private StringRedisTemplate redisTemplate; private StringRedisTemplate redisTemplate;
@Value("${notification.websocket.ticket-ttl-seconds:60}") @Value("${notification.websocket.ticket-ttl-seconds:60}")
private long ticketTtlSeconds; private long ticketTtlSeconds;
......
package com.platform.business.service.impl;
import com.platform.business.constant.ClassAdminConstants;
import com.platform.business.mapper.ClassMapper;
import com.platform.business.model.dto.ClassAdminQueryDTO;
import com.platform.business.model.dto.ClassAdminSaveDTO;
import com.platform.business.model.entity.ClassEntity;
import com.platform.business.model.entity.SysLevelEntity;
import com.platform.business.model.entity.SysPhoneRoleEntity;
import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.ClassAdminCardVO;
import com.platform.business.model.vo.ClassAdminCourseVO;
import com.platform.business.model.vo.ClassAdminDetailVO;
import com.platform.business.model.vo.ClassAdminExamVO;
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.service.ClassAdminService;
import com.platform.business.service.SysLevelService;
import com.platform.business.service.SysPhoneRoleService;
import com.platform.business.service.UserService;
import com.platform.exception.BusinessException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import javax.annotation.Resource;
import java.time.LocalDate;
import java.time.temporal.ChronoUnit;
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.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.TreeSet;
/**
* 管理员端班级管理实现。
*
* <p>旧版 {@link ClassServiceImpl} 同时承担学生日历和教师日历等历史能力,本实现单独
* 维护管理员页面所需的强校验、聚合查询和动态状态,避免增强管理功能时影响其他端。</p>
*/
@Service
public class ClassAdminServiceImpl implements ClassAdminService {
@Resource
private ClassMapper classMapper;
@Resource
private SysLevelService sysLevelService;
@Resource
private UserService userService;
@Resource
private SysPhoneRoleService phoneRoleService;
@Override
public List<ClassAdminCardVO> page(ClassAdminQueryDTO query) {
ClassAdminQueryDTO normalized = query == null ? new ClassAdminQueryDTO() : query;
normalizeQuery(normalized);
List<ClassAdminCardVO> classes = classMapper.selectAdminClasses(normalized, businessSqlDate());
LocalDate today = businessToday();
classes.forEach(item -> applyClassStatus(item, today));
return classes;
}
@Override
public List<ClassAdminTreeVO> tree(String keyword) {
ClassAdminQueryDTO query = new ClassAdminQueryDTO();
query.setKeyword(keyword);
normalizeQuery(query);
List<ClassAdminCardVO> classes = classMapper.selectAdminClasses(query, businessSqlDate());
return buildTree(classes);
}
@Override
public ClassAdminOptionsVO options() {
ClassAdminOptionsVO result = new ClassAdminOptionsVO();
result.setOccupations(Arrays.asList(
new ClassAdminOptionVO(ClassAdminConstants.OCCUPATION_WASTEWATER,
ClassAdminConstants.OCCUPATION_WASTEWATER, null, null),
new ClassAdminOptionVO(ClassAdminConstants.OCCUPATION_SLUDGE,
ClassAdminConstants.OCCUPATION_SLUDGE, null, null)));
result.setLevels(classMapper.selectAdminLevelOptions());
result.setHeadTeachers(classMapper.selectAdminHeadTeacherOptions());
// 既保留数据库里的历史/未来年度,又始终给新建表单提供当前年度及前两年。
Set<Integer> years = new TreeSet<>(Comparator.reverseOrder());
List<Integer> storedYears = classMapper.selectAdminTrainingYears();
if (storedYears != null) {
storedYears.stream()
.filter(year -> year != null
&& year >= ClassAdminConstants.MIN_TRAINING_YEAR
&& year <= ClassAdminConstants.MAX_TRAINING_YEAR)
.forEach(years::add);
}
int currentYear = businessToday().getYear();
years.add(currentYear);
years.add(currentYear - 1);
years.add(currentYear - 2);
result.setYears(new ArrayList<>(years));
return result;
}
@Override
@Transactional(rollbackFor = Exception.class)
public ClassAdminDetailVO create(ClassAdminSaveDTO request) {
validateSaveRequest(request, null, 0);
ClassEntity entity = toEntity(request);
Date now = new Date();
entity.setCreateTime(now);
entity.setUpdateTime(now);
int inserted = classMapper.insert(entity);
if (inserted != 1 || entity.getId() == null) {
throw new BusinessException("班级创建失败,请稍后重试");
}
return detail(entity.getId());
}
@Override
@Transactional(rollbackFor = Exception.class)
public ClassAdminDetailVO update(Integer classId, ClassAdminSaveDTO request) {
requireClassId(classId);
ClassEntity existing = classMapper.selectById(classId);
if (existing == null) {
throw new BusinessException("班级不存在或已删除");
}
int actualCount = classMapper.countAdminStudents(classId);
validateSaveRequest(request, classId, actualCount);
ClassEntity entity = toEntity(request);
entity.setId(classId);
entity.setUpdateTime(new Date());
int updated = classMapper.updateAdminClass(entity);
if (updated != 1) {
throw new BusinessException("班级信息已发生变化,请刷新后重试");
}
return detail(classId);
}
@Override
@Transactional(readOnly = true)
public ClassAdminDetailVO detail(Integer classId) {
requireClassId(classId);
ClassAdminDetailVO detail = classMapper.selectAdminDetail(classId);
if (detail == null) {
throw new BusinessException("班级不存在或已删除");
}
LocalDate today = businessToday();
applyClassStatus(detail, today);
detail.setDurationDays(calculateDurationDays(detail.getStartDate(), detail.getEndDate()));
List<ClassAdminCourseVO> courses = classMapper.selectAdminCourses(classId);
if (courses == null) {
courses = Collections.emptyList();
}
courses.forEach(course -> applyCourseStatus(course, today));
detail.setCourses(courses);
detail.setCourseCount(courses.size());
ClassAdminExamVO latestExam = classMapper.selectLatestPublishedExam(classId);
Integer examId = latestExam == null ? null : latestExam.getExamId();
if (latestExam != null) {
detail.setLatestExamId(latestExam.getExamId());
detail.setLatestExamName(latestExam.getExamName());
detail.setPassRate(latestExam.getPassRate());
}
List<ClassAdminStudentVO> students = classMapper.selectAdminStudents(classId, examId);
if (students == null) {
students = Collections.emptyList();
}
for (ClassAdminStudentVO student : students) {
applyLearningStatus(student, detail.getStatus());
}
detail.setStudents(students);
return detail;
}
/**
* 规范查询值。该方法会直接回写DTO,使MyBatis动态SQL只接收去空格、转大写后的值。
*/
void normalizeQuery(ClassAdminQueryDTO query) {
String keyword = trimToNull(query.getKeyword());
if (keyword != null && keyword.length() > ClassAdminConstants.MAX_NAME_LENGTH) {
throw new BusinessException("班级名称关键字不能超过100个字符");
}
query.setKeyword(keyword);
String occupation = trimToNull(query.getOccupation());
if (occupation != null && !ClassAdminConstants.OCCUPATIONS.contains(occupation)) {
throw new BusinessException("工种只支持污水或污泥");
}
query.setOccupation(occupation);
if (query.getTrainingYear() != null) {
validateTrainingYear(query.getTrainingYear());
}
String status = trimToNull(query.getStatus());
if (status != null) {
status = status.toUpperCase(Locale.ROOT);
if (!ClassAdminConstants.CLASS_STATUSES.contains(status)) {
throw new BusinessException("班级状态参数无效");
}
}
query.setStatus(status);
}
/**
* 校验并规范新增/编辑请求。编辑时额外检查计划人数不能小于已经绑定的学员数。
*/
private void validateSaveRequest(ClassAdminSaveDTO request, Integer excludeId, int actualCount) {
if (request == null) {
throw new BusinessException("班级信息不能为空");
}
request.setName(requireText(request.getName(), "班级名称",
ClassAdminConstants.MAX_NAME_LENGTH));
String occupation = requireText(request.getOccupation(), "工种", 32);
if (!ClassAdminConstants.OCCUPATIONS.contains(occupation)) {
throw new BusinessException("工种只支持污水或污泥");
}
request.setOccupation(occupation);
if (request.getTrainingYear() == null) {
throw new BusinessException("培训年度不能为空");
}
validateTrainingYear(request.getTrainingYear());
if (request.getLevelId() == null) {
throw new BusinessException("职业等级不能为空");
}
validateLevel(request.getLevelId(), occupation);
if (request.getStartDate() == null || request.getEndDate() == null) {
throw new BusinessException("培训开始日期和结束日期不能为空");
}
LocalDate start = toLocalDate(request.getStartDate());
LocalDate end = toLocalDate(request.getEndDate());
if (start.isAfter(end)) {
throw new BusinessException("培训结束日期不能早于开始日期");
}
if (request.getCapacity() != null) {
if (request.getCapacity() < 1 || request.getCapacity() > ClassAdminConstants.MAX_CAPACITY) {
throw new BusinessException("计划人数必须在1到200之间");
}
if (request.getCapacity() < actualCount) {
throw new BusinessException("计划人数不能小于当前实际学员数" + actualCount);
}
}
request.setHeadTeacherId(trimToNull(request.getHeadTeacherId()));
request.setLocation(optionalText(request.getLocation(), "培训地点",
ClassAdminConstants.MAX_LOCATION_LENGTH));
request.setRemark(optionalText(request.getRemark(), "备注",
ClassAdminConstants.MAX_REMARK_LENGTH));
validateHeadTeacher(request.getHeadTeacherId());
int duplicates = classMapper.countAdminDuplicateName(
request.getTrainingYear(), request.getName(), excludeId);
if (duplicates > 0) {
throw new BusinessException("同一培训年度内班级名称不能重复");
}
}
/** 职业等级必须存在、未隐藏,并通过等级名称前缀确认所属工种。 */
private void validateLevel(Integer levelId, String occupation) {
SysLevelEntity level = sysLevelService.getById(levelId);
if (level == null || Boolean.TRUE.equals(level.getHiddeFlag())) {
throw new BusinessException("职业等级不存在或已停用");
}
String levelName = trimToNull(level.getName());
if (levelName == null || !levelName.startsWith(occupation)) {
throw new BusinessException("职业等级与所选工种不匹配");
}
}
/** 班主任选填;有值时必须关联到未删除且拥有“教师”角色的用户。 */
private void validateHeadTeacher(String teacherId) {
if (teacherId == null) {
return;
}
UserEntity teacher = userService.getById(teacherId);
if (teacher == null || Boolean.TRUE.equals(teacher.getDelFlag())) {
throw new BusinessException("所选班主任不存在或已停用");
}
List<SysPhoneRoleEntity> roles = phoneRoleService.queryByPhone(teacher.getPhoneNumber());
boolean hasTeacherRole = roles != null && roles.stream()
.anyMatch(role -> "教师".equals(role.getRoleName()));
if (!hasTeacherRole) {
throw new BusinessException("所选班主任不具有教师角色");
}
}
/** 只复制管理员允许维护的字段,绝不覆盖班级学员或排课关系。 */
private ClassEntity toEntity(ClassAdminSaveDTO request) {
ClassEntity entity = new ClassEntity();
entity.setName(request.getName());
entity.setOccupation(request.getOccupation());
entity.setTrainingYear(request.getTrainingYear());
entity.setLevel(String.valueOf(request.getLevelId()));
entity.setStartDate(request.getStartDate());
entity.setEndDate(request.getEndDate());
entity.setHeadTeacherId(request.getHeadTeacherId());
entity.setLocation(request.getLocation());
entity.setCapacity(request.getCapacity());
entity.setRemark(request.getRemark());
return entity;
}
/**
* 使用LinkedHashMap按SQL排序稳定组装导航树,并让每个分组节点的count表示后代班级数。
*/
private List<ClassAdminTreeVO> buildTree(List<ClassAdminCardVO> classes) {
if (classes == null || classes.isEmpty()) {
return Collections.emptyList();
}
List<ClassAdminTreeVO> roots = new ArrayList<>();
Map<String, ClassAdminTreeVO> occupations = new LinkedHashMap<>();
Map<String, ClassAdminTreeVO> years = new LinkedHashMap<>();
Map<String, ClassAdminTreeVO> levels = new LinkedHashMap<>();
for (ClassAdminCardVO item : classes) {
String occupationValue = valueOrUnknown(item.getOccupation());
String occupationLabel = item.getOccupation() == null ? "未分类工种" : item.getOccupation();
ClassAdminTreeVO occupation = occupations.get(occupationValue);
if (occupation == null) {
occupation = groupNode("OCCUPATION", occupationLabel, occupationValue);
occupations.put(occupationValue, occupation);
roots.add(occupation);
}
String yearValue = item.getTrainingYear() == null
? "UNKNOWN" : String.valueOf(item.getTrainingYear());
String yearKey = occupationValue + "|" + yearValue;
ClassAdminTreeVO year = years.get(yearKey);
if (year == null) {
year = groupNode("YEAR", item.getTrainingYear() == null
? "未设置年度" : item.getTrainingYear() + " 学年", yearValue);
years.put(yearKey, year);
occupation.getChildren().add(year);
}
String levelValue = valueOrUnknown(item.getLevelId());
String levelKey = yearKey + "|" + levelValue;
ClassAdminTreeVO level = levels.get(levelKey);
if (level == null) {
level = groupNode("LEVEL", item.getLevelName() == null
? "未设置等级" : item.getLevelName(), levelValue);
levels.put(levelKey, level);
year.getChildren().add(level);
}
ClassAdminTreeVO leaf = new ClassAdminTreeVO();
leaf.setNodeType("CLASS");
leaf.setLabel(item.getName());
leaf.setValue(String.valueOf(item.getId()));
leaf.setClassId(item.getId());
leaf.setStudentCount(item.getStudentCount());
leaf.setCount(null);
level.getChildren().add(leaf);
occupation.setCount(occupation.getCount() + 1);
year.setCount(year.getCount() + 1);
level.setCount(level.getCount() + 1);
}
return roots;
}
private ClassAdminTreeVO groupNode(String nodeType, String label, String value) {
ClassAdminTreeVO node = new ClassAdminTreeVO();
node.setNodeType(nodeType);
node.setLabel(label);
node.setValue(value);
node.setCount(0);
return node;
}
private void applyClassStatus(ClassAdminCardVO item, LocalDate today) {
String status = resolveClassStatus(item.getStartDate(), item.getEndDate(), today);
item.setStatus(status);
item.setStatusName(classStatusName(status));
}
/** 包级可见,便于单元测试完整覆盖日期边界。 */
static String resolveClassStatus(Date startDate, Date endDate, LocalDate today) {
if (startDate == null || endDate == null) {
return ClassAdminConstants.STATUS_UNKNOWN;
}
LocalDate start = toLocalDate(startDate);
LocalDate end = toLocalDate(endDate);
if (today.isBefore(start)) {
return ClassAdminConstants.STATUS_UPCOMING;
}
if (today.isAfter(end)) {
return ClassAdminConstants.STATUS_ENDED;
}
return ClassAdminConstants.STATUS_ONGOING;
}
private String classStatusName(String status) {
if (ClassAdminConstants.STATUS_UPCOMING.equals(status)) return "待开课";
if (ClassAdminConstants.STATUS_ONGOING.equals(status)) return "进行中";
if (ClassAdminConstants.STATUS_ENDED.equals(status)) return "已结课";
return "信息待补全";
}
private void applyCourseStatus(ClassAdminCourseVO course, LocalDate today) {
String status = resolveClassStatus(course.getFirstDate(), course.getLastDate(), today);
course.setStatus(status);
if (ClassAdminConstants.STATUS_UPCOMING.equals(status)) course.setStatusName("未开始");
else if (ClassAdminConstants.STATUS_ONGOING.equals(status)) course.setStatusName("进行中");
else if (ClassAdminConstants.STATUS_ENDED.equals(status)) course.setStatusName("已完成");
else course.setStatusName("信息待补全");
}
private void applyLearningStatus(ClassAdminStudentVO student, String classStatus) {
if (ClassAdminConstants.STATUS_UPCOMING.equals(classStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_PENDING);
student.setLearningStatusName("待开课");
} else if (ClassAdminConstants.STATUS_ONGOING.equals(classStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_ACTIVE);
student.setLearningStatusName("在读");
} else if (ClassAdminConstants.STATUS_ENDED.equals(classStatus)) {
student.setLearningStatus(ClassAdminConstants.LEARNING_COMPLETED);
student.setLearningStatusName("已结业");
} else {
student.setLearningStatus(ClassAdminConstants.LEARNING_UNKNOWN);
student.setLearningStatusName("信息待补全");
}
}
private Long calculateDurationDays(Date startDate, Date endDate) {
if (startDate == null || endDate == null) {
return null;
}
return ChronoUnit.DAYS.between(toLocalDate(startDate), toLocalDate(endDate)) + 1;
}
private void validateTrainingYear(Integer year) {
if (year < ClassAdminConstants.MIN_TRAINING_YEAR
|| year > ClassAdminConstants.MAX_TRAINING_YEAR) {
throw new BusinessException("培训年度必须是2000到2100之间的四位年份");
}
}
private void requireClassId(Integer classId) {
if (classId == null || classId <= 0) {
throw new BusinessException("班级ID无效");
}
}
private String requireText(String value, String fieldName, int maxLength) {
String normalized = trimToNull(value);
if (normalized == null) {
throw new BusinessException(fieldName + "不能为空");
}
if (normalized.length() > maxLength) {
throw new BusinessException(fieldName + "不能超过" + maxLength + "个字符");
}
return normalized;
}
private String optionalText(String value, String fieldName, int maxLength) {
String normalized = trimToNull(value);
if (normalized != null && normalized.length() > maxLength) {
throw new BusinessException(fieldName + "不能超过" + maxLength + "个字符");
}
return normalized;
}
private String trimToNull(String value) {
if (value == null) {
return null;
}
String trimmed = value.trim();
return trimmed.isEmpty() ? null : trimmed;
}
private String valueOrUnknown(String value) {
return value == null || value.trim().isEmpty() ? "UNKNOWN" : value;
}
private java.sql.Date businessSqlDate() {
return java.sql.Date.valueOf(businessToday());
}
private LocalDate businessToday() {
return LocalDate.now(ClassAdminConstants.BUSINESS_ZONE);
}
private static LocalDate toLocalDate(Date date) {
return new Date(date.getTime()).toInstant()
.atZone(ClassAdminConstants.BUSINESS_ZONE).toLocalDate();
}
}
# 管理员端班级管理接口
接口统一使用 `/class/admin` 前缀。所有请求都必须携带 `Authorization`,服务端会从 JWT
解析当前用户并校验 `phone_role.role_name=管理员`,不接受客户端传入管理员用户 ID。
部署新版服务前先执行 `src/main/resources/sql/class_management.sql`。脚本可重复执行,并会尽力
从旧等级、排课和班级成员数据回填新增字段;无法推断的旧记录在页面显示“信息待补全”。
## 1. 班级卡片分页
`POST /class/admin/page`
```json
{
"pageNum": 1,
"pageSize": 20,
"keyword": "污水处理",
"occupation": "污水",
"trainingYear": 2026,
"levelId": 1,
"status": "ONGOING"
}
```
- `pageNum` 默认 1;`pageSize` 默认 20、最大 100。
- `occupation` 只支持 `污水`、`污泥`。
- `status` 支持 `UPCOMING`、`ONGOING`、`ENDED`、`UNKNOWN`,不区分大小写。
- 返回项目统一的 `TableDataInfo`,每条记录包含 `levelId/levelName`、计划/实际人数和状态中文名。
班级状态不写入数据库:开始日前为待开课,起止日期内为进行中,结束日后为已结课;缺少日期的
旧数据为信息待补全。
## 2. 班级导航树
`GET /class/admin/tree?keyword=污水`
返回 `OCCUPATION → YEAR → LEVEL → CLASS` 四层节点。分组节点的 `count` 为后代班级数,
班级节点返回 `classId` 和 `studentCount`。关键字只模糊匹配班级名称。
## 3. 表单选项
`GET /class/admin/options`
返回:
- `occupations`:污水、污泥。
- `years`:数据库已有年度,加当前年度及前两年,倒序排列。
- `levels`:`sys_level` 中未隐藏且名称以“污水”或“污泥”开头的等级。
- `headTeachers`:未删除且在 `phone_role` 中具有教师角色的用户,`extra` 为完整手机号。
## 4. 新增班级
`POST /class/admin`
```json
{
"name": "污水处理一级三班",
"occupation": "污水",
"trainingYear": 2026,
"levelId": 1,
"startDate": "2026-09-01",
"endDate": "2027-01-31",
"headTeacherId": "1900000000000000001",
"location": "实训基地A栋301教室",
"capacity": 35,
"remark": "采用理论与实训混合模式"
}
```
班级名称、工种、年度、等级和起止日期必填。同一培训年度内班级名称不能重复;计划人数选填,
填写时必须为 1~200;班主任选填,但有值时必须是有效教师。成功后返回完整班级详情。
## 5. 编辑班级
`PUT /class/admin/{id}`
请求体与新增相同。编辑只更新班级基础信息,不删除或重建已有学员、排课、考试关系;计划人数
有值时不得小于当前实际学员数。清空班主任、地点、计划人数或备注时传 `null` 或空字符串。
## 6. 班级详情
`GET /class/admin/{id}`
详情包含:
- 基础信息、计划/实际人数、培训自然日数和动态班级状态。
- 按课程名称、类型和授课教师聚合的课程列表,课时为全部排课课时之和。
- 全班及个人出勤率;只有 `NORMAL/LATE` 计入出勤分子,`ABSENT/LEAVE` 计入分母。
- 最近一场 `exam.mark_flag=true` 的考试,以及考生侧 `mark_flag=true` 的正式成绩。
- 最近考试中 60 分及以上人数占有效成绩人数的比例;没有正式成绩时通过率返回 `null`。
- 完整学员姓名和手机号。个人学习状态按班级日期派生为待开课、在读或已结业。
百分比字段以 `0~100` 的数值返回并最多保留两位小数,空值由页面展示为“—”。
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