Commit 7ada3155 authored by wujipeng's avatar wujipeng
Browse files

Merge remote-tracking branch 'origin/dev-v1.0' into dev-v1.0

parents 04355d28 a6e34844
# 学员评议接口说明
接口统一前缀:`/evaluation`。所有接口都要求请求头携带 `Authorization: Bearer <token>`。
本模块只有学员端和管理端。教师端没有接口;评价不支持匿名,只有管理员能够查看班级实名评价明细。
## 状态与评分枚举
- 任务状态:`PENDING`(待评价)、`COMPLETED`(全部完成)、`EXPIRED`(已过期)、`REVOKED`(已撤回)。
- 学员记录状态:`PENDING`(未提交)、`SUBMITTED`(已提交)。
- 七维度评分:`GOOD`(好)、`FAIR`(较好)、`OK`(尚可)、`POOR`(差)。
## 学员端
### 分页查询我的评价
`POST /evaluation/student/page`
```json
{
"status": "PENDING",
"pageNum": 1,
"pageSize": 10
}
```
学员端状态筛选含义:
- `PENDING`:本人未提交且任务仍在截止时间内。
- `COMPLETED`:本人已经提交,不要求班级其他学员全部完成。
- `EXPIRED`:本人未提交且任务已经过期。
客户端提交的用户ID不会被采信,服务端始终使用JWT中的当前用户。
### 查看本人评价任务
`GET /evaluation/student/{taskId}`
只返回当前用户自己的评价表单或已提交内容。已撤回任务和未分配给本人的任务均不可访问。
### 提交评价
`POST /evaluation/student/{taskId}/submit`
```json
{
"teachingAttitude": "GOOD",
"teachingContent": "GOOD",
"teachingMethod": "FAIR",
"teachingMeans": "GOOD",
"demonstration": "GOOD",
"guidance": "FAIR",
"classHourCompletion": "GOOD",
"comment": "讲解清晰,建议增加实操时间"
}
```
七个维度全部必填。课程结束前、任务过期后或任务撤回后不能提交;提交成功后不能再次提交或修改。
## 管理端
下列接口除JWT外还会校验当前用户是否具有“管理员”角色。
### 发起评议任务
`POST /evaluation/admin/task`
```json
{
"subjectId": 123,
"deadline": "2026-08-14"
}
```
`subjectId` 对应 `class_subject.id`。`deadline` 同时支持 `yyyy-MM-dd` 和 `yyyy-MM-dd HH:mm:ss`;只传日期时按当日 `23:59:59` 处理。服务端会校验课程存在、截止时间晚于当前时间和课程结束时间,并将课程所属班级当前未删除的学员固化为目标记录。同一课次不能重复发起。创建成功后通过消息中心向目标学员推送待评价消息。
### 分页筛选任务
`POST /evaluation/admin/page`
```json
{
"courseName": "污泥输送",
"classId": 1,
"teacherId": "1900000000000000001",
"startDate": "2026-08-01",
"endDate": "2026-08-31",
"status": "PENDING",
"type": "实训",
"pageNum": 1,
"pageSize": 10
}
```
返回课程、班级、教师、上课时间、截止时间、总人数、待评/已评人数、完成率及任务状态。
### 查看实名详情
`GET /evaluation/admin/{taskId}?studentName=张`
`studentName` 可选。返回任务基础信息、目标学员实名评价记录和七个维度的四档统计及四分制平均分。姓名筛选仅影响明细列表,不改变任务整体统计。
### 撤回任务
- 单条:`PUT /evaluation/admin/{taskId}/revoke`
- 批量:`PUT /evaluation/admin/batch-revoke`
批量请求:
```json
{
"taskIds": ["1910000000000000001", "1910000000000000002"]
}
```
只有 `PENDING` 任务可以撤回。批量撤回最多100条,采用同一事务;其中任一任务不符合条件时整批回滚。
### 导出
- 按列表筛选条件导出汇总:`POST /evaluation/admin/export`,请求体与管理端分页筛选一致。
- 导出单任务实名明细和维度统计:`GET /evaluation/admin/{taskId}/export`。
响应文件格式为 `.xlsx`。
## 数据库部署
先确保项目基础表以及消息中心表已经部署,再执行:
`practical-business/src/main/resources/sql/evaluation.sql`
建表脚本创建 `evaluation_task` 和 `evaluation_record` 两张表,并包含唯一键、列表查询索引及关联外键。
-- 学员评议模块(MySQL 5.7+/8.0)
-- 执行前提:class_subject、class、class_student、user 等基础业务表已经存在。
-- 设计说明:一个评价任务对应一节具体课程;evaluation_record 在发起时固化该班级的目标学员。
create table if not exists evaluation_task (
id varchar(32) not null comment '评价任务ID(雪花算法字符串)',
subject_id int not null comment '关联课次 class_subject.id,同一课次只允许发起一次',
status varchar(16) not null comment 'PENDING/COMPLETED/EXPIRED/REVOKED',
deadline datetime(3) not null comment '评价截止时间',
created_by varchar(64) not null comment '发起管理员 user.id',
created_time datetime(3) not null,
update_time datetime(3) not null,
revoked_at datetime(3) null comment '撤回时间',
revoked_by varchar(64) null comment '撤回管理员 user.id',
primary key (id),
unique key uk_evaluation_task_subject (subject_id),
key idx_evaluation_task_status_deadline (status, deadline),
key idx_evaluation_task_created (created_time),
constraint fk_evaluation_task_subject foreign key (subject_id)
references class_subject (id),
constraint fk_evaluation_task_creator foreign key (created_by)
references user (id),
constraint fk_evaluation_task_revoker foreign key (revoked_by)
references user (id)
) engine=InnoDB default charset=utf8mb4 collate=utf8mb4_unicode_ci comment='学员评议任务';
create table if not exists evaluation_record (
id varchar(32) not null comment '学员评价记录ID',
task_id varchar(32) not null comment '评价任务ID',
student_id varchar(64) not null comment '目标学员 user.id;发起时固化且不匿名',
status varchar(16) not null default 'PENDING' comment 'PENDING/SUBMITTED',
teaching_attitude varchar(8) null comment '教学态度:GOOD/FAIR/OK/POOR',
teaching_content varchar(8) null comment '教学内容:GOOD/FAIR/OK/POOR',
teaching_method varchar(8) null comment '教学方法:GOOD/FAIR/OK/POOR',
teaching_means varchar(8) null comment '教学手段:GOOD/FAIR/OK/POOR',
demonstration varchar(8) null comment '讲解示范:GOOD/FAIR/OK/POOR',
guidance varchar(8) null comment '巡回指导:GOOD/FAIR/OK/POOR',
class_hour_completion varchar(8) null comment '课时完成情况:GOOD/FAIR/OK/POOR',
comment varchar(1000) null comment '意见与建议',
submitted_at datetime(3) null comment '提交时间',
created_time datetime(3) not null,
update_time datetime(3) not null,
primary key (id),
unique key uk_evaluation_record_task_student (task_id, student_id),
key idx_evaluation_record_student (student_id, status, task_id),
key idx_evaluation_record_task_status (task_id, status),
constraint fk_evaluation_record_task foreign key (task_id)
references evaluation_task (id),
constraint fk_evaluation_record_student foreign key (student_id)
references user (id)
) engine=InnoDB default charset=utf8mb4 collate=utf8mb4_unicode_ci comment='学员实名评价记录及任务目标快照';
package com.platform.business.service.impl;
import com.platform.business.constant.EvaluationConstants;
import com.platform.business.mapper.EvaluationRecordMapper;
import com.platform.business.mapper.EvaluationTaskMapper;
import com.platform.business.model.dto.EvaluationSubmitDTO;
import com.platform.business.model.dto.EvaluationTaskCreateDTO;
import com.platform.business.model.dto.NotificationPublishDTO;
import com.platform.business.model.entity.ClassSubjectEntity;
import com.platform.business.model.entity.EvaluationRecordEntity;
import com.platform.business.model.entity.EvaluationTaskEntity;
import com.platform.business.model.vo.EvaluationTaskVO;
import com.platform.business.model.vo.StudentEvaluationTaskVO;
import com.platform.business.service.BusinessNotificationPublisher;
import com.platform.business.service.ClassSubjectService;
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.ArgumentCaptor;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import java.text.SimpleDateFormat;
import java.util.Arrays;
import java.util.Calendar;
import java.util.Date;
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.verify;
import static org.mockito.Mockito.when;
/** 评价服务关键事务流程的单元测试,不依赖真实数据库或消息中间件。 */
@ExtendWith(MockitoExtension.class)
class EvaluationServiceImplTest {
@Mock
private EvaluationTaskMapper taskMapper;
@Mock
private EvaluationRecordMapper recordMapper;
@Mock
private ClassSubjectService classSubjectService;
@Mock
private BusinessNotificationPublisher notificationPublisher;
@InjectMocks
private EvaluationServiceImpl service;
private ClassSubjectEntity endedSubject;
@BeforeEach
void setUp() throws Exception {
// 构造已经结束的课程,提交测试不会受真实系统时间或数据库时区影响。
Calendar calendar = Calendar.getInstance();
calendar.add(Calendar.DAY_OF_MONTH, -1);
Date yesterday = new SimpleDateFormat("yyyy-MM-dd").parse(
new SimpleDateFormat("yyyy-MM-dd").format(calendar.getTime()));
endedSubject = new ClassSubjectEntity();
endedSubject.setId(101);
endedSubject.setClassId(10);
endedSubject.setSubjectName("污泥输送与处理");
endedSubject.setDate(yesterday);
endedSubject.setTimeFrame("09:00-10:00");
}
@Test
void createTaskShouldSnapshotStudentsAndPublishNotification() {
EvaluationTaskCreateDTO request = new EvaluationTaskCreateDTO();
request.setSubjectId(101);
Calendar deadline = Calendar.getInstance();
deadline.add(Calendar.DAY_OF_MONTH, 2);
request.setDeadline(new SimpleDateFormat("yyyy-MM-dd").format(deadline.getTime()));
when(classSubjectService.getById(101)).thenReturn(endedSubject);
when(taskMapper.selectCount(any())).thenReturn(0L);
when(taskMapper.selectActiveStudentIdsByClassId(10)).thenReturn(Arrays.asList("S1", "S2"));
when(taskMapper.insert(any(EvaluationTaskEntity.class))).thenReturn(1);
when(recordMapper.batchInsert(any())).thenReturn(2);
when(notificationPublisher.publish(any(NotificationPublishDTO.class), eq("A1"), eq("管理员甲")))
.thenReturn("event-id");
EvaluationTaskVO view = new EvaluationTaskVO();
view.setId("TASK-1");
when(taskMapper.selectTaskView(any())).thenReturn(view);
service.createTask(request, "A1", "管理员甲");
// 评价记录必须按班级人数批量固化,通知接收人也必须使用同一份学员快照。
verify(recordMapper).batchInsert(any());
ArgumentCaptor<NotificationPublishDTO> messageCaptor = ArgumentCaptor.forClass(NotificationPublishDTO.class);
verify(notificationPublisher).publish(messageCaptor.capture(), eq("A1"), eq("管理员甲"));
assertEquals(Arrays.asList("S1", "S2"), messageCaptor.getValue().getRecipientUserIds());
assertEquals("EVALUATION", messageCaptor.getValue().getBusinessType());
}
@Test
void submitShouldPersistScoresAndTryToCompleteTask() {
EvaluationTaskEntity task = pendingTask();
EvaluationRecordEntity record = new EvaluationRecordEntity();
record.setId("R1");
record.setTaskId("T1");
record.setStudentId("S1");
record.setStatus(EvaluationConstants.RECORD_PENDING);
StudentEvaluationTaskVO result = new StudentEvaluationTaskVO();
result.setTaskId("T1");
result.setRecordStatus(EvaluationConstants.RECORD_SUBMITTED);
when(taskMapper.selectByIdForUpdate("T1")).thenReturn(task);
when(classSubjectService.getById(101)).thenReturn(endedSubject);
when(recordMapper.selectByTaskAndStudentForUpdate("T1", "S1")).thenReturn(record);
when(recordMapper.submitPending(eq(record), any(Date.class))).thenReturn(1);
when(taskMapper.selectStudentTask("T1", "S1")).thenReturn(result);
StudentEvaluationTaskVO actual = service.submit("T1", validSubmission(), "S1");
assertEquals(EvaluationConstants.RECORD_SUBMITTED, actual.getRecordStatus());
assertEquals(EvaluationConstants.SCORE_GOOD, record.getTeachingAttitude());
verify(taskMapper).completeIfAllSubmitted(eq("T1"), any(Date.class));
}
@Test
void submitShouldRejectAlreadySubmittedRecord() {
EvaluationRecordEntity record = new EvaluationRecordEntity();
record.setStatus(EvaluationConstants.RECORD_SUBMITTED);
when(taskMapper.selectByIdForUpdate("T1")).thenReturn(pendingTask());
when(classSubjectService.getById(101)).thenReturn(endedSubject);
when(recordMapper.selectByTaskAndStudentForUpdate("T1", "S1")).thenReturn(record);
BusinessException exception = assertThrows(BusinessException.class,
() -> service.submit("T1", validSubmission(), "S1"));
assertEquals("评价已提交,不能重复提交或修改", exception.getMessage());
}
private EvaluationTaskEntity pendingTask() {
Calendar deadline = Calendar.getInstance();
deadline.add(Calendar.DAY_OF_MONTH, 1);
EvaluationTaskEntity task = new EvaluationTaskEntity();
task.setId("T1");
task.setSubjectId(101);
task.setStatus(EvaluationConstants.TASK_PENDING);
task.setDeadline(deadline.getTime());
return task;
}
private EvaluationSubmitDTO validSubmission() {
EvaluationSubmitDTO request = new EvaluationSubmitDTO();
request.setTeachingAttitude("good");
request.setTeachingContent("GOOD");
request.setTeachingMethod("FAIR");
request.setTeachingMeans("GOOD");
request.setDemonstration("GOOD");
request.setGuidance("FAIR");
request.setClassHourCompletion("GOOD");
request.setComment("讲解清晰");
return request;
}
}
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