# 学员评议接口说明 接口统一前缀:`/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` 处理。服务端会校验课程存在、截止时间晚于当前时间和课程结束时间,并将课程所属班级当前未删除的学员固化为目标记录。同一课次不能重复发起。创建成功后通过消息中心向目标学员推送待评价消息。 ### 分页筛选任务 `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` 两张表,并包含唯一键、列表查询索引及关联外键。