# 学员评议接口说明 接口统一前缀:`/evaluation`。所有接口都要求请求头携带 `Authorization: Bearer `。 本模块只有学员端和管理端。教师端没有接口;评价不支持匿名,只有管理员能够查看班级实名评价明细。 ## 状态与评分枚举 - 任务状态:`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` 处理。服务端会校验课程存在、截止时间晚于当前时间和课程结束时间,并将课程所属班级当前未删除的学员固化为目标记录。同一课次存在未撤回任务时不能重复发起;原任务已撤回时允许重新发起一条新任务。创建成功后通过消息中心向目标学员推送待评价消息。 ### 发起任务职级选项 `GET /evaluation/admin/levels` 返回 `sys_level` 中全部未隐藏的污水、污泥职级,格式为 `value/label/parentValue`。该接口不从 班级导航树推导职级,因此没有班级的职级也会返回。页面选择职级后,再按 `value`(职级ID) 筛选班级。 ### 分页筛选任务 `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 } ``` 返回课程、班级、教师、上课日期、上课时段、截止时间、总人数、待评/已评人数、完成率及任务状态。 其中 `courseDate` 固定为 `yyyy-MM-dd`;`evaluationProgress` 固定为“已评人数/总人数”,例如 `1/3`;`completionRate` 为 0~100 的数值,例如 `33.33`。列表应直接展示 `evaluationProgress`,不要自行交换 `pendingCount/submittedCount/totalCount` 的顺序。 `totalCount` 是发起任务时写入 `evaluation_record` 的目标学员人数,不是班级当前人数。 任务与初始学员记录使用同一创建时间,查询仅纳入记录创建时间不晚于任务创建时间的学员; 后补进旧任务的记录不计入已评、待评、总人数,也不能参与该任务的提交和完成状态判断。 列表、详情及导出均采用该口径;前端应直接使用 `evaluationProgress` 和 `completionRate`, 不要用班级接口返回的最新人数重新计算。例如发起时有 2 人、已评 1 人,之后班级新增 1 人, 旧任务仍为 `1/2`、`50.0`,新增学员不参与旧任务;重新发起的新任务才读取当时的班级名单。 ### 查看实名详情 `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` 已部署过旧版学员评议表的环境还必须执行一次可重复运行的增量脚本: `practical-business/src/main/resources/sql/evaluation_reissue.sql` 建表脚本创建 `evaluation_task` 和 `evaluation_record` 两张表,并包含唯一键、列表查询索引及关联外键。增量脚本把“同课次唯一”调整为“同课次未撤回任务唯一”,缺少该迁移时数据库仍会拒绝撤回后的重新发起。