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;
import com.fasterxml.jackson.annotation.JsonFormat;
import com.platform.business.model.entity.ClassEntity;
import com.platform.business.model.entity.ClassStudentEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;
import java.util.Date;
import java.util.List;
@Data
......@@ -18,12 +16,6 @@ public class ClassDTO extends ClassEntity {
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;
......
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 com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Date;
......@@ -18,5 +21,50 @@ public class ClassEntity {
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;
@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;
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.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 org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import java.util.Date;
import java.util.List;
@Mapper
public interface ClassMapper extends BaseMapper<ClassEntity> {
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;
@Service
@Slf4j
public class NotificationPresenceService {
@Resource
// @Resource
@Resource(name = "stringRedisTemplate")
private StringRedisTemplate redisTemplate;
@Resource
private NotificationNodeIdentity nodeIdentity;
......
......@@ -28,7 +28,8 @@ public class NotificationSocketTicketService {
"local value = redis.call('GET', KEYS[1]); " +
"if value then redis.call('DEL', KEYS[1]); end; return value;", String.class);
@Resource
// @Resource
@Resource(name = "stringRedisTemplate")
private StringRedisTemplate redisTemplate;
@Value("${notification.websocket.ticket-ttl-seconds:60}")
private long ticketTtlSeconds;
......
# 管理员端班级管理接口
接口统一使用 `/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