Commit 6525db95 authored by wujipeng's avatar wujipeng
Browse files

管理员-教务管理-教案管理

parent e34240ea
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
/**
* 管理员端教案分页及导出查询条件。
*
* <p>复用教师端的关键字、状态和授课日期范围字段,并增加教师筛选。管理员身份
* 始终由服务端登录态校验,查询对象不包含任何权限相关字段。</p>
*/
@Data
@EqualsAndHashCode(callSuper = true)
public class TeachingPlanAdminQueryDTO extends TeachingPlanQueryDTO {
@ApiModelProperty("所属教师用户ID;为空时查询全部教师")
private String teacherId;
}
package com.platform.business.model.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
/**
* 管理员编辑及审核教案请求。
*
* <p>正文结构与教师端保持一致;审核人、审核时间由服务端根据当前登录管理员写入,
* 因此本对象故意不暴露 reviewerId、reviewerName 和 reviewTime。</p>
*/
@Data
@EqualsAndHashCode(callSuper = true)
public class TeachingPlanAdminUpdateDTO extends TeachingPlanSaveDTO {
@ApiModelProperty(value = "目标状态:DRAFT/PENDING/APPROVED/REJECTED", required = true)
private String status;
@ApiModelProperty("审核意见,可为空,最多2000个字符")
private String reviewOpinion;
}
......@@ -76,6 +76,23 @@ public class TeachingPlanEntity {
/** 审核展示状态:DRAFT、PENDING、APPROVED、REJECTED。 */
private String status;
/** 最近一次执行管理端保存操作的管理员用户 ID。 */
@TableField("reviewer_id")
private String reviewerId;
/** 最近一次审核人的姓名快照,避免用户改名后历史展示发生变化。 */
@TableField("reviewer_name")
private String reviewerName;
/** 管理员最近一次保存的审核意见,允许为空。 */
@TableField("review_opinion")
private String reviewOpinion;
/** 最近一次管理端保存或审核时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
@TableField("review_time")
private Date reviewTime;
/** 逻辑删除标记:0 正常,1 删除。 */
@TableLogic(value = "0", delval = "1")
@TableField("del_flag")
......
package com.platform.business.model.vo;
import lombok.Data;
/** 管理员端教案列表的教师筛选选项,仅返回存在有效教案的教师。 */
@Data
public class TeachingPlanTeacherOptionVO {
/** 教师用户ID,作为分页查询的 teacherId 入参。 */
private String teacherId;
/** 教师当前显示姓名。 */
private String teacherName;
}
......@@ -28,6 +28,19 @@ public class TeachingPlanVO {
private String afterClassSummary;
private String status;
/** 最近一次执行管理端保存操作的管理员用户ID。 */
private String reviewerId;
/** 最近一次审核人姓名快照,不随用户后续改名而改变。 */
private String reviewerName;
/** 最近一次管理员保存的审核意见。 */
private String reviewOpinion;
/** 最近一次管理端保存或审核时间。 */
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date reviewTime;
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private Date createTime;
......
......@@ -20,6 +20,12 @@ public final class TeachingPlanConstants {
/** 单个结构化正文的安全上限,防止异常请求占用过多数据库空间。 */
public static final int MAX_CONTENT_LENGTH = 20000;
/** 审核意见对应数据库 VARCHAR(2000)。 */
public static final int MAX_REVIEW_OPINION_LENGTH = 2000;
/** 审核人姓名快照对应数据库 VARCHAR(100)。 */
public static final int MAX_REVIEWER_NAME_LENGTH = 100;
public static final int MAX_ATTACHMENT_COUNT = 10;
public static final long MAX_ATTACHMENT_SIZE = 50L * 1024 * 1024;
......
package com.platform.business.controller;
import com.platform.business.model.dto.TeachingPlanAdminQueryDTO;
import com.platform.business.model.dto.TeachingPlanAdminUpdateDTO;
import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.TeachingPlanTeacherOptionVO;
import com.platform.business.model.vo.TeachingPlanVO;
import com.platform.business.service.AuthenticatedUserService;
import com.platform.business.service.TeachingPlanService;
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.util.StringUtils;
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.RestController;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.List;
/**
* 管理员端“教务管理-教案管理”接口。
*
* <p>每个入口都会解析当前登录用户并校验“管理员”角色。管理员更新可以跨教师、跨
* 状态执行,但审核人信息始终取登录态,接口不会信任客户端提交的审核人身份。</p>
*/
@Api(tags = "管理员端-教案管理")
@RestController
@RequestMapping("/teaching/plan/admin")
public class TeachingPlanAdminController extends BaseController {
@Resource
private TeachingPlanService teachingPlanService;
@Resource
private AuthenticatedUserService authenticatedUserService;
@ApiOperation("分页查询全部教师的教案")
@PostMapping("/page")
public TableDataInfo page(@RequestBody(required = false) TeachingPlanAdminQueryDTO query,
HttpServletRequest request) {
TeachingPlanAdminQueryDTO safeQuery = query == null
? new TeachingPlanAdminQueryDTO() : query;
normalizePage(safeQuery);
currentAdmin(request);
startPage(safeQuery.getPageNum(), safeQuery.getPageSize());
return getDataTable(teachingPlanService.adminList(safeQuery));
}
@ApiOperation("查询任意有效教案详情")
@GetMapping("/{id}")
public Result<TeachingPlanVO> detail(@PathVariable String id, HttpServletRequest request) {
currentAdmin(request);
return Result.data(teachingPlanService.adminDetail(id));
}
@ApiOperation("管理员编辑正文并设置任意教案状态")
@PutMapping("/{id}")
public Result<TeachingPlanVO> update(@PathVariable String id,
@RequestBody TeachingPlanAdminUpdateDTO body,
HttpServletRequest request) {
UserEntity admin = currentAdmin(request);
return Result.data(teachingPlanService.adminUpdate(
id, body, admin.getId(), reviewerName(admin)));
}
@ApiOperation("查询存在有效教案的教师筛选选项")
@GetMapping("/teachers")
public Result<List<TeachingPlanTeacherOptionVO>> teacherOptions(HttpServletRequest request) {
currentAdmin(request);
return Result.data(teachingPlanService.adminTeacherOptions());
}
@ApiOperation("按当前筛选条件导出全部教案清单Excel")
@PostMapping("/export")
public void exportList(@RequestBody(required = false) TeachingPlanAdminQueryDTO query,
HttpServletRequest request,
HttpServletResponse response) {
currentAdmin(request);
teachingPlanService.exportAdminList(query, response);
}
@ApiOperation("导出单份教案Word")
@GetMapping("/{id}/export")
public void exportDetail(@PathVariable String id,
HttpServletRequest request,
HttpServletResponse response) {
currentAdmin(request);
teachingPlanService.exportAdminDetail(id, response);
}
/** 统一分页默认值并限制单次最大查询量,避免页面参数导致超大分页。 */
void normalizePage(TeachingPlanAdminQueryDTO query) {
int pageNum = query.getPageNum() == null || query.getPageNum() < 1 ? 1 : query.getPageNum();
int pageSize = query.getPageSize() == null || query.getPageSize() < 1
? 10 : query.getPageSize();
query.setPageNum(pageNum);
query.setPageSize(Math.min(pageSize, 100));
}
/** 解析登录用户并校验管理员角色,所有管理端入口统一调用本方法。 */
private UserEntity currentAdmin(HttpServletRequest request) {
UserEntity admin = authenticatedUserService.current(request);
authenticatedUserService.requireAdmin(admin);
return admin;
}
/**
* 优先保存真实姓名;历史账号没有姓名时依次使用账号、手机号和用户ID,
* 确保审核记录始终有可展示的责任人快照。
*/
private String reviewerName(UserEntity admin) {
if (StringUtils.hasText(admin.getNickName())) {
return admin.getNickName().trim();
}
if (StringUtils.hasText(admin.getUsername())) {
return admin.getUsername().trim();
}
if (StringUtils.hasText(admin.getPhoneNumber())) {
return admin.getPhoneNumber().trim();
}
return admin.getId();
}
}
package com.platform.business.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.platform.business.model.dto.TeachingPlanAdminQueryDTO;
import com.platform.business.model.dto.TeachingPlanQueryDTO;
import com.platform.business.model.entity.TeachingPlanEntity;
import com.platform.business.model.vo.TeachingPlanTeacherOptionVO;
import com.platform.business.model.vo.TeachingPlanVO;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
......@@ -41,4 +43,24 @@ public interface TeachingPlanMapper extends BaseMapper<TeachingPlanEntity> {
/** 仅逻辑删除仍属于当前教师且仍为草稿的教案。 */
int deleteDraft(@Param("id") String id,
@Param("teacherId") String teacherId);
/** 管理员查询全部教师的教案,分页由控制器中的 PageHelper 提供。 */
List<TeachingPlanVO> selectAdminList(@Param("query") TeachingPlanAdminQueryDTO query);
/** 管理员查询任意一条未删除教案,不施加教师归属限制。 */
TeachingPlanVO selectAdminDetail(@Param("id") String id);
/**
* 管理员更新前锁定目标记录,确保正文、状态和审核元数据在同一事务中一致写入。
*/
TeachingPlanEntity selectAdminPlanForUpdate(@Param("id") String id);
/**
* 管理员原子更新教案正文、任意目标状态和审核信息。
* WHERE 条件仍限制逻辑删除标记,防止并发删除后继续写入。
*/
int updateAdmin(@Param("plan") TeachingPlanEntity plan);
/** 查询存在有效教案的教师,供管理端教师筛选下拉框使用。 */
List<TeachingPlanTeacherOptionVO> selectAdminTeacherOptions();
}
package com.platform.business.service;
import com.platform.business.model.dto.TeachingPlanAdminQueryDTO;
import com.platform.business.model.dto.TeachingPlanAdminUpdateDTO;
import com.platform.business.model.dto.TeachingPlanQueryDTO;
import com.platform.business.model.dto.TeachingPlanSaveDTO;
import com.platform.business.model.dto.TeachingPlanStatusDTO;
import com.platform.business.model.vo.TeachingPlanAttachmentVO;
import com.platform.business.model.vo.TeachingPlanTeacherOptionVO;
import com.platform.business.model.vo.TeachingPlanVO;
import org.springframework.web.multipart.MultipartFile;
import javax.servlet.http.HttpServletResponse;
import java.util.List;
/** 教师端教案管理业务接口。所有方法都要求显式传入服务端解析出的当前教师 ID。 */
/**
* 教案管理业务接口。
*
* <p>教师端方法显式接收登录教师 ID 并限制数据归属;管理员端方法由控制器完成角色
* 校验,涉及审核的写操作还显式接收当前管理员 ID 和姓名。</p>
*/
public interface TeachingPlanService {
List<TeachingPlanVO> list(TeachingPlanQueryDTO query, String teacherId);
......@@ -30,4 +39,23 @@ public interface TeachingPlanService {
boolean deleteAttachment(String id, String attachmentId, String teacherId);
void downloadAttachment(String id, String attachmentId, String teacherId);
/** 按管理员筛选条件查询全部教师的教案,分页由控制器负责启动。 */
List<TeachingPlanVO> adminList(TeachingPlanAdminQueryDTO query);
/** 查询任意未逻辑删除教案,并装配其有效附件。 */
TeachingPlanVO adminDetail(String id);
/** 管理员原子保存正文、任意目标状态及可信审核人快照。 */
TeachingPlanVO adminUpdate(String id, TeachingPlanAdminUpdateDTO request,
String reviewerId, String reviewerName);
/** 返回至少拥有一份有效教案的教师筛选选项。 */
List<TeachingPlanTeacherOptionVO> adminTeacherOptions();
/** 按查询条件导出全部匹配教案,不应用分页参数。 */
void exportAdminList(TeachingPlanAdminQueryDTO query, HttpServletResponse response);
/** 将单份教案正文、审核信息和附件名称导出为Word。 */
void exportAdminDetail(String id, HttpServletResponse response);
}
......@@ -4,6 +4,8 @@ import com.baomidou.mybatisplus.core.toolkit.IdWorker;
import com.platform.business.constant.TeachingPlanConstants;
import com.platform.business.mapper.TeachingPlanAttachmentMapper;
import com.platform.business.mapper.TeachingPlanMapper;
import com.platform.business.model.dto.TeachingPlanAdminQueryDTO;
import com.platform.business.model.dto.TeachingPlanAdminUpdateDTO;
import com.platform.business.model.dto.TeachingPlanQueryDTO;
import com.platform.business.model.dto.TeachingPlanSaveDTO;
import com.platform.business.model.dto.TeachingPlanStatusDTO;
......@@ -11,16 +13,37 @@ import com.platform.business.model.entity.BsFileEntity;
import com.platform.business.model.entity.TeachingPlanAttachmentEntity;
import com.platform.business.model.entity.TeachingPlanEntity;
import com.platform.business.model.vo.TeachingPlanAttachmentVO;
import com.platform.business.model.vo.TeachingPlanTeacherOptionVO;
import com.platform.business.model.vo.TeachingPlanVO;
import com.platform.business.service.BsFileService;
import com.platform.business.service.TeachingPlanService;
import com.platform.exception.BusinessException;
import org.apache.poi.ss.usermodel.Cell;
import org.apache.poi.ss.usermodel.CellStyle;
import org.apache.poi.ss.usermodel.FillPatternType;
import org.apache.poi.ss.usermodel.Font;
import org.apache.poi.ss.usermodel.IndexedColors;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.xssf.streaming.SXSSFWorkbook;
import org.apache.poi.xwpf.usermodel.ParagraphAlignment;
import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.apache.poi.xwpf.usermodel.XWPFRun;
import org.apache.poi.xwpf.usermodel.XWPFTable;
import org.apache.poi.xwpf.usermodel.XWPFTableCell;
import org.apache.poi.xwpf.usermodel.XWPFTableRow;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.util.StringUtils;
import org.springframework.web.multipart.MultipartFile;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.OutputStream;
import java.net.URLEncoder;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Date;
......@@ -30,7 +53,7 @@ import java.util.Locale;
import java.util.Map;
/**
* 教师端教案管理核心业务实现。
* 教师端与管理员端教案管理核心业务实现。
*
* <p>服务层不信任客户端提交的数据归属:每个入口都使用 JWT 解析得到的教师 ID,
* 并在查询或更新 SQL 中再次携带该 ID。正文、附件和状态各自还有独立的状态限制,
......@@ -223,6 +246,161 @@ public class TeachingPlanServiceImpl implements TeachingPlanService {
bsFileService.downloadFile(attachment.getFileId());
}
@Override
public List<TeachingPlanVO> adminList(TeachingPlanAdminQueryDTO query) {
TeachingPlanAdminQueryDTO safeQuery = query == null
? new TeachingPlanAdminQueryDTO() : query;
normalizeAdminQuery(safeQuery);
// 管理列表不装配附件,避免分页结果产生不必要的大对象;详情接口会返回完整附件。
return teachingPlanMapper.selectAdminList(safeQuery);
}
@Override
public TeachingPlanVO adminDetail(String id) {
requireId(id, "教案ID不能为空");
TeachingPlanVO plan = teachingPlanMapper.selectAdminDetail(id);
if (plan == null) {
throw new BusinessException("教案不存在");
}
fillAttachments(Collections.singletonList(plan));
return plan;
}
@Override
@Transactional(rollbackFor = Exception.class)
public TeachingPlanVO adminUpdate(String id, TeachingPlanAdminUpdateDTO request,
String reviewerId, String reviewerName) {
requireId(id, "教案ID不能为空");
requireId(reviewerId, "无法获取当前管理员身份");
reviewerName = requireText(reviewerName, "管理员姓名",
TeachingPlanConstants.MAX_REVIEWER_NAME_LENGTH);
validateAndNormalizeSaveRequest(request);
String targetStatus = normalizeStatus(request == null ? null : request.getStatus(), false);
String reviewOpinion = trimToNull(request.getReviewOpinion());
if (reviewOpinion != null
&& reviewOpinion.length() > TeachingPlanConstants.MAX_REVIEW_OPINION_LENGTH) {
throw new BusinessException("审核意见不能超过2000个字符");
}
// 行锁使正文、目标状态和审核人快照成为一次原子修改;管理员不受教师状态机限制。
TeachingPlanEntity current = teachingPlanMapper.selectAdminPlanForUpdate(id);
if (current == null) {
throw new BusinessException("教案不存在");
}
TeachingPlanEntity update = toEntity(request);
update.setId(id);
update.setStatus(targetStatus);
update.setReviewerId(reviewerId);
update.setReviewerName(reviewerName);
update.setReviewOpinion(reviewOpinion);
update.setReviewTime(new Date());
if (teachingPlanMapper.updateAdmin(update) != 1) {
throw new BusinessException("教案状态已变化,请刷新后重试");
}
return adminDetail(id);
}
@Override
public List<TeachingPlanTeacherOptionVO> adminTeacherOptions() {
return teachingPlanMapper.selectAdminTeacherOptions();
}
@Override
public void exportAdminList(TeachingPlanAdminQueryDTO query, HttpServletResponse response) {
TeachingPlanAdminQueryDTO safeQuery = query == null
? new TeachingPlanAdminQueryDTO() : query;
normalizeAdminQuery(safeQuery);
List<TeachingPlanVO> plans = teachingPlanMapper.selectAdminList(safeQuery);
// SXSSFWorkbook 只在内存保留固定数量的行,导出较多教案时不会线性占用堆内存。
SXSSFWorkbook workbook = new SXSSFWorkbook(100);
try {
Sheet sheet = workbook.createSheet("教案清单");
String[] headers = {"教案ID", "教案标题", "课程名称", "教师", "授课日期", "课时",
"状态", "审核人", "审核意见", "审核时间", "更新时间"};
Row header = sheet.createRow(0);
CellStyle headerStyle = createExcelHeaderStyle(workbook);
for (int i = 0; i < headers.length; i++) {
Cell cell = header.createCell(i);
cell.setCellValue(headers[i]);
cell.setCellStyle(headerStyle);
}
int rowIndex = 1;
for (TeachingPlanVO plan : plans) {
Row row = sheet.createRow(rowIndex++);
writeExcelCell(row, 0, plan.getId());
writeExcelCell(row, 1, plan.getTitle());
writeExcelCell(row, 2, plan.getCourseName());
writeExcelCell(row, 3, plan.getTeacherName());
writeExcelCell(row, 4, formatDate(plan.getTeachingDate(), "yyyy-MM-dd"));
writeExcelCell(row, 5, plan.getClassHours());
writeExcelCell(row, 6, plan.getStatus());
writeExcelCell(row, 7, plan.getReviewerName());
writeExcelCell(row, 8, plan.getReviewOpinion());
writeExcelCell(row, 9, formatDate(plan.getReviewTime(), "yyyy-MM-dd HH:mm:ss"));
writeExcelCell(row, 10, formatDate(plan.getUpdateTime(), "yyyy-MM-dd HH:mm:ss"));
}
// 使用固定列宽,避免流式工作簿为自动宽度重新跟踪全部历史行。
int[] widths = {24, 28, 24, 16, 14, 10, 14, 16, 36, 22, 22};
for (int i = 0; i < widths.length; i++) {
sheet.setColumnWidth(i, widths[i] * 256);
}
writeDownloadResponse(response, workbook,
"教案清单.xlsx",
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
} catch (IOException e) {
throw new BusinessException("导出教案清单失败");
} finally {
// dispose 会删除 SXSSF 写盘产生的临时文件,避免长期运行后占满临时目录。
workbook.dispose();
try {
workbook.close();
} catch (IOException ignored) {
// 主响应已经处理完成,关闭临时工作簿失败不覆盖原始业务异常。
}
}
}
@Override
public void exportAdminDetail(String id, HttpServletResponse response) {
TeachingPlanVO plan = adminDetail(id);
try (XWPFDocument document = new XWPFDocument()) {
XWPFParagraph title = document.createParagraph();
title.setAlignment(ParagraphAlignment.CENTER);
XWPFRun titleRun = title.createRun();
titleRun.setBold(true);
titleRun.setFontSize(18);
titleRun.setText(plan.getTitle());
XWPFTable summary = document.createTable(1, 2);
writeWordTableRow(summary.getRow(0), "教师", plan.getTeacherName());
addWordTableRow(summary, "课程名称", plan.getCourseName());
addWordTableRow(summary, "授课日期", formatDate(plan.getTeachingDate(), "yyyy-MM-dd"));
addWordTableRow(summary, "课时", value(plan.getClassHours()));
addWordTableRow(summary, "状态", plan.getStatus());
addWordSection(document, "教学目标", plan.getTeachingObjectives());
addWordSection(document, "教学内容", plan.getTeachingContent());
addWordSection(document, "教学重点", plan.getKeyPoints());
addWordSection(document, "教学难点", plan.getDifficultPoints());
addWordSection(document, "教学方法", plan.getTeachingMethods());
addWordSection(document, "教学过程", plan.getTeachingProcess());
addWordSection(document, "课后总结", plan.getAfterClassSummary());
addWordSection(document, "审核人", plan.getReviewerName());
addWordSection(document, "审核意见", plan.getReviewOpinion());
addWordSection(document, "审核时间",
formatDate(plan.getReviewTime(), "yyyy-MM-dd HH:mm:ss"));
addWordSection(document, "附件", attachmentNames(plan.getAttachments()));
writeDownloadResponse(response, document,
safeFilename(plan.getTitle()) + "-教案.docx",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document");
} catch (IOException e) {
throw new BusinessException("导出教案失败");
}
}
/** 将附件一次性批量装配到列表结果,避免分页结果中出现逐条查询。 */
private void fillAttachments(List<TeachingPlanVO> plans) {
if (plans == null || plans.isEmpty()) {
......@@ -281,19 +459,41 @@ public class TeachingPlanServiceImpl implements TeachingPlanService {
/** 规范化列表筛选值并验证日期区间。 */
private void normalizeQuery(TeachingPlanQueryDTO query) {
query.setKeyword(trimToNull(query.getKeyword()));
String status = trimToNull(query.getStatus());
status = status == null ? TeachingPlanConstants.STATUS_ALL : status.toUpperCase(Locale.ROOT);
if (!TeachingPlanConstants.STATUS_ALL.equals(status)
&& !TeachingPlanConstants.STATUSES.contains(status)) {
throw new BusinessException("筛选状态只能是 ALL、DRAFT、PENDING、APPROVED 或 REJECTED");
}
query.setStatus(status);
query.setStatus(normalizeStatus(query.getStatus(), true));
if (query.getStartDate() != null && query.getEndDate() != null
&& query.getStartDate().after(query.getEndDate())) {
throw new BusinessException("授课日期开始值不能晚于结束值");
}
}
/** 管理端在教师端通用筛选基础上额外清洗 teacherId。 */
private void normalizeAdminQuery(TeachingPlanAdminQueryDTO query) {
normalizeQuery(query);
query.setTeacherId(trimToNull(query.getTeacherId()));
}
/**
* 统一规范化教案状态。
*
* @param allowAll 查询条件允许使用 ALL;更新请求只能使用四个真实业务状态
*/
private String normalizeStatus(String value, boolean allowAll) {
String status = trimToNull(value);
if (status == null) {
if (allowAll) {
return TeachingPlanConstants.STATUS_ALL;
}
throw new BusinessException("目标状态不能为空");
}
status = status.toUpperCase(Locale.ROOT);
if ((allowAll && TeachingPlanConstants.STATUS_ALL.equals(status))
|| TeachingPlanConstants.STATUSES.contains(status)) {
return status;
}
String prefix = allowAll ? "筛选状态只能是 ALL、" : "教案状态只能是 ";
throw new BusinessException(prefix + "DRAFT、PENDING、APPROVED 或 REJECTED");
}
/** 校验并原地清洗结构化教案字段,保证新增和编辑使用完全相同的规则。 */
private void validateAndNormalizeSaveRequest(TeachingPlanSaveDTO request) {
if (request == null) {
......@@ -379,6 +579,123 @@ public class TeachingPlanServiceImpl implements TeachingPlanService {
return vo;
}
/** 创建管理员清单统一的深色表头样式。 */
private CellStyle createExcelHeaderStyle(SXSSFWorkbook workbook) {
CellStyle style = workbook.createCellStyle();
style.setFillForegroundColor(IndexedColors.DARK_BLUE.getIndex());
style.setFillPattern(FillPatternType.SOLID_FOREGROUND);
Font font = workbook.createFont();
font.setBold(true);
font.setColor(IndexedColors.WHITE.getIndex());
style.setFont(font);
return style;
}
/** 所有Excel值按文本写入,避免长ID被电子表格自动转为科学计数法。 */
private void writeExcelCell(Row row, int column, Object cellValue) {
row.createCell(column).setCellValue(value(cellValue));
}
/** 写入Word基本信息表格的一行。 */
private void addWordTableRow(XWPFTable table, String label, String content) {
writeWordTableRow(table.createRow(), label, content);
}
/** 重置单元格默认段落内容并写入标签和值。 */
private void writeWordTableRow(XWPFTableRow row, String label, String content) {
while (row.getTableCells().size() < 2) {
row.addNewTableCell();
}
writeWordCell(row.getCell(0), label);
writeWordCell(row.getCell(1), content);
}
private void writeWordCell(XWPFTableCell cell, String content) {
cell.removeParagraph(0);
XWPFParagraph paragraph = cell.addParagraph();
writeWordText(paragraph.createRun(), content);
}
/** 将长正文按“标题 + 内容”段落写入Word,并正确保留换行。 */
private void addWordSection(XWPFDocument document, String label, String content) {
XWPFParagraph heading = document.createParagraph();
XWPFRun headingRun = heading.createRun();
headingRun.setBold(true);
headingRun.setText(label);
XWPFParagraph body = document.createParagraph();
writeWordText(body.createRun(), content);
}
private void writeWordText(XWPFRun run, String content) {
String[] lines = value(content).split("\\r?\\n", -1);
for (int i = 0; i < lines.length; i++) {
if (i > 0) {
run.addBreak();
}
run.setText(lines[i]);
}
}
/** 将附件名称汇总为可读列表;导出不暴露服务器文件路径和文件ID。 */
private String attachmentNames(List<TeachingPlanAttachmentVO> attachments) {
if (attachments == null || attachments.isEmpty()) {
return "无";
}
StringBuilder builder = new StringBuilder();
for (int i = 0; i < attachments.size(); i++) {
if (i > 0) {
builder.append('\n');
}
builder.append(i + 1).append(". ").append(value(attachments.get(i).getFileName()));
}
return builder.toString();
}
private String formatDate(Date date, String pattern) {
return date == null ? "" : new SimpleDateFormat(pattern).format(date);
}
private String value(Object value) {
return value == null ? "" : String.valueOf(value);
}
/** 清理Windows和浏览器下载文件名中的非法字符,并限制过长标题。 */
private String safeFilename(String title) {
String safe = value(title).replaceAll("[\\\\/:*?\"<>|]", "_").trim();
if (safe.isEmpty()) {
safe = "未命名";
}
return safe.length() > 80 ? safe.substring(0, 80) : safe;
}
/** 写入Excel响应,采用RFC 5987格式保证中文文件名跨浏览器可用。 */
private void writeDownloadResponse(HttpServletResponse response, SXSSFWorkbook workbook,
String filename, String contentType) throws IOException {
prepareDownloadResponse(response, filename, contentType);
try (OutputStream output = response.getOutputStream()) {
workbook.write(output);
output.flush();
}
}
/** 写入Word响应,响应头规则与Excel保持一致。 */
private void writeDownloadResponse(HttpServletResponse response, XWPFDocument document,
String filename, String contentType) throws IOException {
prepareDownloadResponse(response, filename, contentType);
try (OutputStream output = response.getOutputStream()) {
document.write(output);
output.flush();
}
}
private void prepareDownloadResponse(HttpServletResponse response, String filename,
String contentType) throws IOException {
String encoded = URLEncoder.encode(filename, "UTF-8").replace("+", "%20");
response.setCharacterEncoding("UTF-8");
response.setContentType(contentType);
response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + encoded);
}
private String requireText(String value, String fieldName, int maxLength) {
String normalized = trimToNull(value);
if (normalized == null) {
......
......@@ -19,6 +19,10 @@
p.teaching_process AS teachingProcess,
p.after_class_summary AS afterClassSummary,
p.status,
p.reviewer_id AS reviewerId,
p.reviewer_name AS reviewerName,
p.review_opinion AS reviewOpinion,
p.review_time AS reviewTime,
p.create_time AS createTime,
p.update_time AS updateTime
</sql>
......@@ -106,4 +110,86 @@
AND status = 'DRAFT'
AND del_flag = 0
</update>
<!--
管理员分页和Excel导出复用同一查询。关键字覆盖标题、课程和教师姓名;
LIKE查询保留前后模糊匹配,以符合页面搜索体验。
-->
<select id="selectAdminList" resultType="com.platform.business.model.vo.TeachingPlanVO">
SELECT <include refid="planColumns"/>
FROM teaching_plan p
LEFT JOIN user u ON u.id = p.teacher_id
WHERE p.del_flag = 0
<if test="query.keyword != null and query.keyword != ''">
AND (p.title LIKE CONCAT('%', #{query.keyword}, '%')
OR p.course_name LIKE CONCAT('%', #{query.keyword}, '%')
OR u.nick_name LIKE CONCAT('%', #{query.keyword}, '%'))
</if>
<if test="query.teacherId != null and query.teacherId != ''">
AND p.teacher_id = #{query.teacherId}
</if>
<if test="query.status != null and query.status != '' and query.status != 'ALL'">
AND p.status = #{query.status}
</if>
<if test="query.startDate != null">
AND p.teaching_date <![CDATA[>=]]> #{query.startDate}
</if>
<if test="query.endDate != null">
AND p.teaching_date <![CDATA[<=]]> #{query.endDate}
</if>
ORDER BY p.update_time DESC, p.id DESC
</select>
<select id="selectAdminDetail" resultType="com.platform.business.model.vo.TeachingPlanVO">
SELECT <include refid="planColumns"/>
FROM teaching_plan p
LEFT JOIN user u ON u.id = p.teacher_id
WHERE p.id = #{id}
AND p.del_flag = 0
</select>
<!-- 行锁必须在事务中调用,管理端不存在教师归属条件。 -->
<select id="selectAdminPlanForUpdate"
resultType="com.platform.business.model.entity.TeachingPlanEntity">
SELECT *
FROM teaching_plan
WHERE id = #{id}
AND del_flag = 0
FOR UPDATE
</select>
<update id="updateAdmin">
UPDATE teaching_plan
SET title = #{plan.title},
course_name = #{plan.courseName},
teaching_date = #{plan.teachingDate},
class_hours = #{plan.classHours},
teaching_objectives = #{plan.teachingObjectives},
teaching_content = #{plan.teachingContent},
key_points = #{plan.keyPoints},
difficult_points = #{plan.difficultPoints},
teaching_methods = #{plan.teachingMethods},
teaching_process = #{plan.teachingProcess},
after_class_summary = #{plan.afterClassSummary},
status = #{plan.status},
reviewer_id = #{plan.reviewerId},
reviewer_name = #{plan.reviewerName},
review_opinion = #{plan.reviewOpinion},
review_time = #{plan.reviewTime},
update_time = CURRENT_TIMESTAMP
WHERE id = #{plan.id}
AND del_flag = 0
</update>
<!-- 只提供拥有有效教案的教师,避免筛选列表出现永远查不到数据的选项。 -->
<select id="selectAdminTeacherOptions"
resultType="com.platform.business.model.vo.TeachingPlanTeacherOptionVO">
SELECT p.teacher_id AS teacherId,
COALESCE(MAX(u.nick_name), p.teacher_id) AS teacherName
FROM teaching_plan p
LEFT JOIN user u ON u.id = p.teacher_id
WHERE p.del_flag = 0
GROUP BY p.teacher_id
ORDER BY teacherName ASC, p.teacher_id ASC
</select>
</mapper>
......@@ -18,12 +18,17 @@ CREATE TABLE IF NOT EXISTS teaching_plan (
teaching_process MEDIUMTEXT NOT NULL COMMENT '教学过程',
after_class_summary MEDIUMTEXT NULL COMMENT '课后总结',
status VARCHAR(16) NOT NULL DEFAULT 'DRAFT' COMMENT 'DRAFT/PENDING/APPROVED/REJECTED',
reviewer_id VARCHAR(64) NULL COMMENT '最近一次管理端保存的管理员用户ID',
reviewer_name VARCHAR(100) NULL COMMENT '最近一次审核人姓名快照',
review_opinion VARCHAR(2000) NULL COMMENT '最近一次审核意见',
review_time DATETIME NULL COMMENT '最近一次管理端保存或审核时间',
del_flag TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除:0正常,1删除',
create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
PRIMARY KEY (id),
KEY idx_teaching_plan_teacher_status (teacher_id, del_flag, status),
KEY idx_teaching_plan_teacher_date (teacher_id, del_flag, teaching_date)
KEY idx_teaching_plan_teacher_date (teacher_id, del_flag, teaching_date),
KEY idx_teaching_plan_admin_filter (del_flag, status, teaching_date, teacher_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='教师教案';
CREATE TABLE IF NOT EXISTS teaching_plan_attachment (
......@@ -39,3 +44,75 @@ CREATE TABLE IF NOT EXISTS teaching_plan_attachment (
KEY idx_teaching_plan_attachment_plan (plan_id, del_flag),
KEY idx_teaching_plan_attachment_file (file_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='教案附件关联';
--
-- 管理端审核字段增量迁移。
-- teaching_plan 可能已由旧版本脚本创建,因此不能只依赖上面的 CREATE TABLE IF NOT EXISTS;
-- 下面逐项检查字段和索引,允许本脚本在开发、测试和生产环境安全重复执行。
-- 旧的已通过/已驳回记录没有可信审核人来源,迁移时有意保持审核字段为 NULL。
--
DELIMITER $$
DROP PROCEDURE IF EXISTS migrate_teaching_plan_admin$$
CREATE PROCEDURE migrate_teaching_plan_admin()
BEGIN
IF NOT EXISTS (
SELECT 1 FROM information_schema.columns
WHERE table_schema = DATABASE()
AND table_name = 'teaching_plan'
AND column_name = 'reviewer_id'
) THEN
ALTER TABLE teaching_plan
ADD COLUMN reviewer_id VARCHAR(64) NULL
COMMENT '最近一次管理端保存的管理员用户ID' AFTER status;
END IF;
IF NOT EXISTS (
SELECT 1 FROM information_schema.columns
WHERE table_schema = DATABASE()
AND table_name = 'teaching_plan'
AND column_name = 'reviewer_name'
) THEN
ALTER TABLE teaching_plan
ADD COLUMN reviewer_name VARCHAR(100) NULL
COMMENT '最近一次审核人姓名快照' AFTER reviewer_id;
END IF;
IF NOT EXISTS (
SELECT 1 FROM information_schema.columns
WHERE table_schema = DATABASE()
AND table_name = 'teaching_plan'
AND column_name = 'review_opinion'
) THEN
ALTER TABLE teaching_plan
ADD COLUMN review_opinion VARCHAR(2000) NULL
COMMENT '最近一次审核意见' AFTER reviewer_name;
END IF;
IF NOT EXISTS (
SELECT 1 FROM information_schema.columns
WHERE table_schema = DATABASE()
AND table_name = 'teaching_plan'
AND column_name = 'review_time'
) THEN
ALTER TABLE teaching_plan
ADD COLUMN review_time DATETIME NULL
COMMENT '最近一次管理端保存或审核时间' AFTER review_opinion;
END IF;
IF NOT EXISTS (
SELECT 1 FROM information_schema.statistics
WHERE table_schema = DATABASE()
AND table_name = 'teaching_plan'
AND index_name = 'idx_teaching_plan_admin_filter'
) THEN
ALTER TABLE teaching_plan
ADD INDEX idx_teaching_plan_admin_filter
(del_flag, status, teaching_date, teacher_id);
END IF;
END$$
CALL migrate_teaching_plan_admin()$$
DROP PROCEDURE IF EXISTS migrate_teaching_plan_admin$$
DELIMITER ;
# 教师端教案管理接口
# 教案管理接口
所有接口统一使用前缀 `/teaching/plan/teacher`,并从请求头 `Authorization` 解析当前用户。
教师端接口统一使用前缀 `/teaching/plan/teacher`,并从请求头 `Authorization` 解析当前用户。
服务端要求用户具有 `phone_role.role_name=教师`,且不会接收客户端传入的 `teacherId`。
部署前执行 `src/main/resources/sql/teaching_plan.sql` 创建教案主表和附件关联表。
......@@ -78,3 +78,103 @@
每份教案最多保留 10 个附件,支持 PDF、DOC、DOCX、PPT、PPTX,扩展名不区分大小写,单个附件不得超过
50 MiB。上传和删除附件仅允许在 `DRAFT` 状态执行;下载在任意有效状态均可执行。接口不返回服务器文件路径。
## 5. 管理员端接口约定
管理员接口统一使用前缀 `/teaching/plan/admin`。每个入口都会从 `Authorization` 中解析当前用户,
并要求 `phone_role.role_name=管理员`。审核人 ID、审核人姓名和审核时间均由服务端写入,前端无法指定。
管理员使用与教师端相同的简化正文结构,不包含原型中的班级、课程类型、章节、职业等级和结构化教学环节。
管理员可编辑任意有效教案,并可直接设置 `DRAFT`、`PENDING`、`APPROVED` 或 `REJECTED`,不受教师端状态机限制。
### 5.1 分页查询
`POST /teaching/plan/admin/page`
```json
{
"pageNum": 1,
"pageSize": 10,
"keyword": "高处作业",
"teacherId": "190000000000000001",
"status": "APPROVED",
"startDate": "2026-08-01",
"endDate": "2026-08-31"
}
```
- `keyword` 同时模糊匹配教案标题、课程名称和教师姓名。
- `teacherId` 为空时查询全部教师。
- `status` 为空或 `ALL` 时查询全部状态,状态值不区分大小写。
- 日期范围按授课日期筛选并包含起止日。
- 页码默认 1,每页默认 10 条,单页最多 100 条。
- 返回项目统一的 `TableDataInfo`;列表不返回附件,详情接口返回有效附件。
### 5.2 教师筛选选项与详情
- `GET /teaching/plan/admin/teachers`:返回至少拥有一份有效教案的教师 ID 和姓名。
- `GET /teaching/plan/admin/{id}`:返回任意未逻辑删除的教案详情、审核信息和有效附件。
详情在原有字段基础上增加:
```json
{
"reviewerId": "190000000000000099",
"reviewerName": "教务管理员",
"reviewOpinion": "内容完整,同意通过",
"reviewTime": "2026-08-17 15:00:00"
}
```
### 5.3 管理员编辑和审核
`PUT /teaching/plan/admin/{id}`
```json
{
"title": "高处作业安全教案",
"courseName": "高处作业安全",
"teachingDate": "2026-08-20",
"classHours": 2,
"teachingObjectives": "掌握高处作业基本安全要求",
"teachingContent": "安全防护用品使用和风险识别",
"keyPoints": "正确使用安全带",
"difficultPoints": "复杂环境风险识别",
"teachingMethods": "讲授、演示与案例讨论",
"teachingProcess": "导入、讲授、演示、练习和总结",
"afterClassSummary": "课堂目标已完成",
"status": "APPROVED",
"reviewOpinion": "内容完整,同意通过"
}
```
正文校验规则与教师端一致。`status` 必填,管理员允许在任意当前状态间直接切换;`reviewOpinion`
可为空,最多 2000 个字符。正文、状态、审核人快照和审核时间在同一事务中保存。
### 5.4 导出
- `POST /teaching/plan/admin/export`:请求体与分页查询一致,但忽略 `pageNum/pageSize`,将全部匹配记录导出为 Excel。
- `GET /teaching/plan/admin/{id}/export`:导出单份 Word 教案,包含全部简化正文、教师信息、审核信息和附件名称。
下载响应使用标准 Office MIME 类型和 `filename*=UTF-8''...` 响应头,前端应以二进制 Blob 接收。
## 6. 数据库升级
新部署和旧环境均执行 `src/main/resources/sql/teaching_plan.sql`。脚本会创建缺失表,并通过
`information_schema` 幂等补充以下管理端字段和筛选索引:
- `reviewer_id`:最近一次管理端保存的管理员用户 ID。
- `reviewer_name`:审核人姓名快照。
- `review_opinion`:最近一次审核意见。
- `review_time`:最近一次管理端保存或审核时间。
- `idx_teaching_plan_admin_filter`:管理端状态、日期和教师筛选索引。
历史数据没有可信的审核人来源,因此脚本不会为旧的 `APPROVED/REJECTED` 记录伪造审核信息。
## 7. 常见错误
- 未登录、令牌失效:`未获取到登录凭证` 或 `登录凭证无效或已过期`。
- 非管理员调用管理端接口:`只有管理员可以访问管理端接口`。
- 教案不存在或已逻辑删除:`教案不存在`。
- 非法状态或日期范围:返回对应的业务参数错误。
- 导出流写入失败:`导出教案清单失败` 或 `导出教案失败`。
package com.platform.business.controller;
import com.platform.business.model.dto.TeachingPlanAdminQueryDTO;
import com.platform.business.model.dto.TeachingPlanAdminUpdateDTO;
import com.platform.business.model.entity.UserEntity;
import com.platform.business.model.vo.TeachingPlanVO;
import com.platform.business.service.AuthenticatedUserService;
import com.platform.business.service.TeachingPlanService;
import com.platform.exception.BusinessException;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.test.util.ReflectionTestUtils;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.doThrow;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/** 管理员教案控制器的分页、角色校验和审核人来源测试。 */
@ExtendWith(MockitoExtension.class)
class TeachingPlanAdminControllerTest {
@Mock
private TeachingPlanService teachingPlanService;
@Mock
private AuthenticatedUserService authenticatedUserService;
private TeachingPlanAdminController controller;
@BeforeEach
void setUp() {
controller = new TeachingPlanAdminController();
ReflectionTestUtils.setField(controller, "teachingPlanService", teachingPlanService);
ReflectionTestUtils.setField(controller, "authenticatedUserService", authenticatedUserService);
}
@Test
void normalizePageShouldApplyDefaultsAndMaximum() {
TeachingPlanAdminQueryDTO defaults = new TeachingPlanAdminQueryDTO();
controller.normalizePage(defaults);
assertEquals(1, defaults.getPageNum());
assertEquals(10, defaults.getPageSize());
TeachingPlanAdminQueryDTO oversized = new TeachingPlanAdminQueryDTO();
oversized.setPageNum(3);
oversized.setPageSize(500);
controller.normalizePage(oversized);
assertEquals(3, oversized.getPageNum());
assertEquals(100, oversized.getPageSize());
}
@Test
void detailShouldStopBeforeServiceWhenUserIsNotAdmin() {
MockHttpServletRequest request = new MockHttpServletRequest();
UserEntity ordinaryUser = new UserEntity();
when(authenticatedUserService.current(request)).thenReturn(ordinaryUser);
doThrow(new BusinessException("只有管理员可以访问管理端接口"))
.when(authenticatedUserService).requireAdmin(ordinaryUser);
assertThrows(BusinessException.class, () -> controller.detail("plan-1", request));
verify(teachingPlanService, never()).adminDetail(any());
}
@Test
void updateShouldUseAuthenticatedAdministratorAsReviewer() {
MockHttpServletRequest request = new MockHttpServletRequest();
UserEntity administrator = new UserEntity();
administrator.setId("admin-1");
administrator.setNickName("教务管理员");
when(authenticatedUserService.current(request)).thenReturn(administrator);
when(teachingPlanService.adminUpdate(eq("plan-1"), any(), eq("admin-1"), eq("教务管理员")))
.thenReturn(new TeachingPlanVO());
controller.update("plan-1", new TeachingPlanAdminUpdateDTO(), request);
verify(authenticatedUserService).requireAdmin(administrator);
verify(teachingPlanService).adminUpdate(
eq("plan-1"), any(), eq("admin-1"), eq("教务管理员"));
}
}
package com.platform.business.mapper;
import org.apache.ibatis.builder.xml.XMLMapperBuilder;
import org.apache.ibatis.io.Resources;
import org.apache.ibatis.session.Configuration;
import org.junit.jupiter.api.Test;
import java.io.InputStream;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** 确保教案管理端新增SQL在应用启动前即可被MyBatis完整解析和注册。 */
class TeachingPlanMapperXmlTest {
@Test
void mapperXmlShouldParseAndRegisterAdminStatements() throws Exception {
String resource = "com/platform/business/mapper/TeachingPlanMapper.xml";
Configuration configuration = new Configuration();
try (InputStream input = Resources.getResourceAsStream(resource)) {
XMLMapperBuilder builder = new XMLMapperBuilder(
input, configuration, resource, configuration.getSqlFragments());
builder.parse();
}
String namespace = "com.platform.business.mapper.TeachingPlanMapper.";
assertTrue(configuration.hasStatement(namespace + "selectAdminList"));
assertTrue(configuration.hasStatement(namespace + "selectAdminDetail"));
assertTrue(configuration.hasStatement(namespace + "selectAdminPlanForUpdate"));
assertTrue(configuration.hasStatement(namespace + "updateAdmin"));
assertTrue(configuration.hasStatement(namespace + "selectAdminTeacherOptions"));
}
}
package com.platform.business.service.impl;
import com.platform.business.constant.TeachingPlanConstants;
import com.platform.business.mapper.TeachingPlanAttachmentMapper;
import com.platform.business.mapper.TeachingPlanMapper;
import com.platform.business.model.dto.TeachingPlanAdminQueryDTO;
import com.platform.business.model.dto.TeachingPlanAdminUpdateDTO;
import com.platform.business.model.entity.TeachingPlanEntity;
import com.platform.business.model.vo.TeachingPlanAttachmentVO;
import com.platform.business.model.vo.TeachingPlanVO;
import com.platform.business.service.BsFileService;
import com.platform.exception.BusinessException;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;
import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.ArgumentCaptor;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.mock.web.MockHttpServletResponse;
import java.io.ByteArrayInputStream;
import java.util.Collections;
import java.util.Date;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.anyList;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/** 管理员教案查询、宽松审核、身份审计以及Excel/Word导出的单元测试。 */
@ExtendWith(MockitoExtension.class)
class TeachingPlanAdminServiceImplTest {
@Mock
private TeachingPlanMapper teachingPlanMapper;
@Mock
private TeachingPlanAttachmentMapper attachmentMapper;
@Mock
private BsFileService bsFileService;
@InjectMocks
private TeachingPlanServiceImpl teachingPlanService;
@Test
void adminListShouldNormalizeAllSupportedFilters() {
when(teachingPlanMapper.selectAdminList(any())).thenReturn(Collections.emptyList());
TeachingPlanAdminQueryDTO query = new TeachingPlanAdminQueryDTO();
query.setKeyword(" 安全课 ");
query.setTeacherId(" teacher-1 ");
query.setStatus("approved");
teachingPlanService.adminList(query);
assertEquals("安全课", query.getKeyword());
assertEquals("teacher-1", query.getTeacherId());
assertEquals(TeachingPlanConstants.STATUS_APPROVED, query.getStatus());
}
@Test
void adminListShouldRejectInvalidStatusAndDateRange() {
TeachingPlanAdminQueryDTO invalidStatus = new TeachingPlanAdminQueryDTO();
invalidStatus.setStatus("unknown");
assertThrows(BusinessException.class, () -> teachingPlanService.adminList(invalidStatus));
TeachingPlanAdminQueryDTO invalidDates = new TeachingPlanAdminQueryDTO();
invalidDates.setStartDate(new Date(2_000L));
invalidDates.setEndDate(new Date(1_000L));
assertThrows(BusinessException.class, () -> teachingPlanService.adminList(invalidDates));
verify(teachingPlanMapper, never()).selectAdminList(invalidDates);
}
@Test
void adminUpdateShouldAllowAnyTransitionAndWriteAuthenticatedReviewer() {
TeachingPlanEntity approved = new TeachingPlanEntity();
approved.setId("plan-1");
approved.setStatus(TeachingPlanConstants.STATUS_APPROVED);
when(teachingPlanMapper.selectAdminPlanForUpdate("plan-1")).thenReturn(approved);
when(teachingPlanMapper.updateAdmin(any())).thenReturn(1);
when(teachingPlanMapper.selectAdminDetail("plan-1")).thenReturn(planVo());
when(attachmentMapper.selectByPlanIds(anyList())).thenReturn(Collections.emptyList());
TeachingPlanAdminUpdateDTO request = validRequest();
request.setStatus("draft");
request.setReviewOpinion(" 退回草稿重新整理 ");
teachingPlanService.adminUpdate("plan-1", request, "admin-1", "教务管理员");
ArgumentCaptor<TeachingPlanEntity> captor = ArgumentCaptor.forClass(TeachingPlanEntity.class);
verify(teachingPlanMapper).updateAdmin(captor.capture());
TeachingPlanEntity update = captor.getValue();
assertEquals(TeachingPlanConstants.STATUS_DRAFT, update.getStatus());
assertEquals("admin-1", update.getReviewerId());
assertEquals("教务管理员", update.getReviewerName());
assertEquals("退回草稿重新整理", update.getReviewOpinion());
assertNotNull(update.getReviewTime());
}
@Test
void adminUpdateShouldRejectMissingPlanAndOversizedOpinion() {
TeachingPlanAdminUpdateDTO missingPlanRequest = validRequest();
missingPlanRequest.setStatus(TeachingPlanConstants.STATUS_APPROVED);
when(teachingPlanMapper.selectAdminPlanForUpdate("missing")).thenReturn(null);
assertThrows(BusinessException.class, () -> teachingPlanService.adminUpdate(
"missing", missingPlanRequest, "admin-1", "管理员"));
TeachingPlanAdminUpdateDTO oversized = validRequest();
oversized.setStatus(TeachingPlanConstants.STATUS_REJECTED);
oversized.setReviewOpinion(repeat('评', TeachingPlanConstants.MAX_REVIEW_OPINION_LENGTH + 1));
assertThrows(BusinessException.class, () -> teachingPlanService.adminUpdate(
"plan-1", oversized, "admin-1", "管理员"));
verify(teachingPlanMapper, never()).updateAdmin(any());
}
@Test
void exportAdminListShouldCreateFilteredExcelWithExpectedHeaders() throws Exception {
TeachingPlanVO plan = planVo();
plan.setReviewerName("教务管理员");
plan.setReviewOpinion("内容完整");
when(teachingPlanMapper.selectAdminList(any()))
.thenReturn(Collections.singletonList(plan));
MockHttpServletResponse response = new MockHttpServletResponse();
TeachingPlanAdminQueryDTO query = new TeachingPlanAdminQueryDTO();
query.setTeacherId("teacher-1");
teachingPlanService.exportAdminList(query, response);
assertTrue(response.getContentType().contains("spreadsheetml.sheet"));
assertTrue(response.getHeader("Content-Disposition").contains(".xlsx"));
try (XSSFWorkbook workbook = new XSSFWorkbook(
new ByteArrayInputStream(response.getContentAsByteArray()))) {
assertEquals("教案ID", workbook.getSheetAt(0).getRow(0).getCell(0).getStringCellValue());
assertEquals("plan-1", workbook.getSheetAt(0).getRow(1).getCell(0).getStringCellValue());
assertEquals("高处作业安全教案",
workbook.getSheetAt(0).getRow(1).getCell(1).getStringCellValue());
}
}
@Test
void exportAdminDetailShouldCreateWordWithContentAndAttachmentNames() throws Exception {
TeachingPlanVO plan = planVo();
plan.setReviewerName("教务管理员");
plan.setReviewOpinion("审核通过");
when(teachingPlanMapper.selectAdminDetail("plan-1")).thenReturn(plan);
TeachingPlanAttachmentVO attachment = new TeachingPlanAttachmentVO();
attachment.setPlanId("plan-1");
attachment.setFileName("安全演示.pptx");
when(attachmentMapper.selectByPlanIds(anyList()))
.thenReturn(Collections.singletonList(attachment));
MockHttpServletResponse response = new MockHttpServletResponse();
teachingPlanService.exportAdminDetail("plan-1", response);
assertTrue(response.getContentType().contains("wordprocessingml.document"));
assertTrue(response.getHeader("Content-Disposition").contains(".docx"));
try (XWPFDocument document = new XWPFDocument(
new ByteArrayInputStream(response.getContentAsByteArray()))) {
StringBuilder text = new StringBuilder();
document.getParagraphs().forEach(paragraph -> text.append(paragraph.getText()));
document.getTables().forEach(table -> text.append(table.getText()));
assertTrue(text.toString().contains("高处作业安全教案"));
assertTrue(text.toString().contains("审核通过"));
assertTrue(text.toString().contains("安全演示.pptx"));
}
}
@Test
void adminDetailShouldRejectMissingOrDeletedPlan() {
when(teachingPlanMapper.selectAdminDetail("missing")).thenReturn(null);
assertThrows(BusinessException.class, () -> teachingPlanService.adminDetail("missing"));
}
private TeachingPlanAdminUpdateDTO validRequest() {
TeachingPlanAdminUpdateDTO request = new TeachingPlanAdminUpdateDTO();
request.setTitle("高处作业安全教案");
request.setCourseName("高处作业安全");
request.setTeachingDate(new Date());
request.setClassHours(2);
request.setTeachingObjectives("掌握高处作业基本安全要求");
request.setTeachingContent("安全防护用品使用和风险识别");
request.setKeyPoints("正确使用安全带");
request.setDifficultPoints("复杂环境风险识别");
request.setTeachingMethods("讲授、演示与案例讨论");
request.setTeachingProcess("导入、讲授、演示、练习和总结");
request.setAfterClassSummary("课堂目标已完成");
return request;
}
private TeachingPlanVO planVo() {
TeachingPlanVO plan = new TeachingPlanVO();
plan.setId("plan-1");
plan.setTeacherId("teacher-1");
plan.setTeacherName("王老师");
plan.setTitle("高处作业安全教案");
plan.setCourseName("高处作业安全");
plan.setTeachingDate(new Date());
plan.setClassHours(2);
plan.setTeachingObjectives("掌握安全要求");
plan.setTeachingContent("安全防护用品使用");
plan.setKeyPoints("正确使用安全带");
plan.setDifficultPoints("风险识别");
plan.setTeachingMethods("讲授与演示");
plan.setTeachingProcess("导入、讲授和总结");
plan.setAfterClassSummary("目标已完成");
plan.setStatus(TeachingPlanConstants.STATUS_APPROVED);
plan.setUpdateTime(new Date());
return plan;
}
private String repeat(char character, int count) {
StringBuilder builder = new StringBuilder(count);
for (int i = 0; i < count; i++) {
builder.append(character);
}
return builder.toString();
}
}
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