# 教案管理接口 教师端接口统一使用前缀 `/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": "高处作业", "courseType": "theory", "status": "DRAFT", "startDate": "2026-08-01", "endDate": "2026-08-31" } ``` `courseType` 支持 `ALL`、`theory`、`practice`;`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": "高处作业安全教案", "courseType": "theory", "applicableCourse": "污水处理一级", "vocationalLevel": "初级工", "trainingInstitution": "实训平台", "preparationDate": "2026-08-18", "teachingDate": "2026-08-20", "chapterTopic": "第一章 高处作业安全", "durationMinutes": 90, "className": "污水处理一级一班", "teachingPurpose": "1. 知识目标:掌握安全要求\n2. 能力目标:正确使用防护用品", "practiceContent": null, "practiceEquipment": null, "keyPoints": "正确使用安全带", "difficultPoints": "复杂环境风险识别", "teachingAids": "安全带实物与事故案例视频", "steps": [ { "stageName": "讲授新课", "content": "安全防护用品使用和风险识别", "method": "讲授与演示", "durationMinutes": 60 } ], "teachingNote": "选填的教学后记", "signature": "王老师" } ``` 教案名称和章节最多 50 个字符;课时范围为 15 至 480 分钟;授课日期不得早于编写日期。 基本信息中的必填字段与 HTML 原型一致,教学环节只要存在就必须填写环节名称。理论课保存时会清空隐藏的 实训内容和实训设备。编辑教学环节采用事务内全量替换,状态不是 `DRAFT` 时拒绝编辑和删除。 ## 3. 状态流转 `PUT /teaching/plan/teacher/{id}/status` ```json { "status": "PENDING" } ``` 教师端只允许以下流转,审核通过和退回由管理员端执行: - `DRAFT → PENDING` - `REJECTED → DRAFT` 提交时记录 `submittedTime`;再次提交会刷新该时间。驳回教案必须先恢复为 `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 个附件,支持常见演示文稿、文档、视频和图片格式,扩展名不区分大小写,单个附件 不得超过 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", "className": "污水处理一级一班", "courseType": "theory", "status": "APPROVED", "startDate": "2026-08-01", "endDate": "2026-08-31" } ``` - `keyword` 同时模糊匹配教案名称、章节和教师姓名。 - `className` 按授课班级精确筛选,`courseType` 按理论课/实训课精确筛选。 - `GET /teaching/plan/admin/classes`返回当前有效教案中实际存在的授课班级选项, 其`value`可直接提交到`className`查询条件。 - `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": "高处作业安全教案", "courseType": "theory", "applicableCourse": "污水处理一级", "vocationalLevel": "初级工", "trainingInstitution": "实训平台", "preparationDate": "2026-08-18", "teachingDate": "2026-08-20", "chapterTopic": "第一章 高处作业安全", "durationMinutes": 90, "className": "污水处理一级一班", "teachingPurpose": "掌握高处作业基本安全要求", "keyPoints": "正确使用安全带", "difficultPoints": "复杂环境风险识别", "teachingAids": "安全带实物与事故案例视频", "steps": [], "teachingNote": "课堂目标已完成", "signature": "王老师", "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` 幂等补充原型字段、教学环节子表、管理端审核字段和筛选索引。旧版字段会被保守映射到新字段:课程名称映射为 适用课程、课时数按每课时 45 分钟映射、教学目标映射为教学目的;无法可靠推导的职业等级、班级等字段使用 “未设置”占位,便于管理员后续补录。 旧版 `key_points`、`difficult_points` 曾定义为非空字段,而新版页面中的教学重点和教学难点均为可选项。 迁移会显式将这两列调整为可空,并保留已有内容;否则教师留空保存时会在数据库插入阶段失败。迁移脚本可重复执行, 数据库升级完成后可通过 `information_schema.columns` 确认两列的 `IS_NULLABLE` 均为 `YES`。 管理端审核字段包括: - `reviewer_id`:最近一次管理端保存的管理员用户 ID。 - `reviewer_name`:审核人姓名快照。 - `review_opinion`:最近一次审核意见。 - `review_time`:最近一次管理端保存或审核时间。 - `idx_teaching_plan_admin_filter`:管理端状态、日期和教师筛选索引。 历史数据没有可信的审核人来源,因此脚本不会为旧的 `APPROVED/REJECTED` 记录伪造审核信息。 ## 7. 常见错误 - 未登录、令牌失效:`未获取到登录凭证` 或 `登录凭证无效或已过期`。 - 非管理员调用管理端接口:`只有管理员可以访问管理端接口`。 - 教案不存在或已逻辑删除:`教案不存在`。 - 非法状态或日期范围:返回对应的业务参数错误。 - 导出流写入失败:`导出教案清单失败` 或 `导出教案失败`。