# 教案管理接口 教师端接口统一使用前缀 `/teaching/plan/teacher`,并从请求头 `Authorization` 解析当前用户。 服务端要求用户具有 `phone_role.role_name=教师`,且不会接收客户端传入的 `teacherId`。 部署前执行 `src/main/resources/sql/teaching_plan.sql` 创建教案主表和附件关联表。 ## 1. 分页查询教案 `POST /teaching/plan/teacher/page` ```json { "pageNum": 1, "pageSize": 10, "keyword": "高处作业", "status": "DRAFT", "startDate": "2026-08-01", "endDate": "2026-08-31" } ``` `status` 支持 `ALL`、`DRAFT`、`PENDING`、`APPROVED`、`REJECTED`。关键字同时匹配教案标题和课程名称, 日期范围包含起止日期。返回项目统一的 `TableDataInfo` 分页结构,每条教案均包含当前有效附件。 ## 2. 新增、详情、编辑和删除 - `POST /teaching/plan/teacher`:新增教案,状态固定为 `DRAFT`。 - `GET /teaching/plan/teacher/{id}`:查询本人教案详情。 - `PUT /teaching/plan/teacher/{id}`:编辑本人草稿。 - `DELETE /teaching/plan/teacher/{id}`:逻辑删除本人草稿及附件关系。 新增或编辑请求示例: ```json { "title": "高处作业安全教案", "courseName": "高处作业安全", "teachingDate": "2026-08-20", "classHours": 2, "teachingObjectives": "掌握高处作业基本安全要求", "teachingContent": "安全防护用品使用和风险识别", "keyPoints": "正确使用安全带", "difficultPoints": "复杂环境风险识别", "teachingMethods": "讲授、演示与案例讨论", "teachingProcess": "导入、讲授、演示、练习和总结", "afterClassSummary": "选填的课后总结" } ``` 标题和课程名称最多 200 个字符;六个教学正文均为必填项且单项最多 20000 个字符;课时必须为正整数。 状态不是 `DRAFT` 时,编辑和删除接口都会拒绝操作。 ## 3. 状态流转 `PUT /teaching/plan/teacher/{id}/status` ```json { "status": "PENDING" } ``` 本期状态由教案所属教师本人维护,不记录审核意见或历史。只允许以下流转: - `DRAFT → PENDING` - `PENDING → APPROVED` - `PENDING → REJECTED` - `REJECTED → DRAFT` `APPROVED` 为终态。驳回教案必须先退回 `DRAFT`,才能继续编辑、删除或管理附件。 ## 4. 附件 - `POST /teaching/plan/teacher/{id}/attachments`:使用 `multipart/form-data`,字段名为 `files`,可在一个请求中上传多个文件。 - `DELETE /teaching/plan/teacher/{id}/attachments/{attachmentId}`:删除单个草稿附件。 - `GET /teaching/plan/teacher/{id}/attachments/{attachmentId}/download`:校验教师、教案和附件关系后下载。 每份教案最多保留 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. 常见错误 - 未登录、令牌失效:`未获取到登录凭证` 或 `登录凭证无效或已过期`。 - 非管理员调用管理端接口:`只有管理员可以访问管理端接口`。 - 教案不存在或已逻辑删除:`教案不存在`。 - 非法状态或日期范围:返回对应的业务参数错误。 - 导出流写入失败:`导出教案清单失败` 或 `导出教案失败`。