1. 功能概述
面向学校教务场景的代课闭环管理。核心解决：教师临时缺勤时，代课协商结果无法快速沉淀、台账手工修改易留责任空隙、巡课异常处理缺乏链路化追溯。
核心业务指标：①代课申请平均闭环时长 ≤ 2 小时；②台账与现场一致率 ≥ 98%；③留痕可导出 Excel 完整存档率 100%。
2. 角色与权限矩阵
| 操作 | 管理员 | 校级领导 | 普通教师 |
|---|
| Excel 批量导入台账 | ✓ | — | — |
| 台账编辑 | ✓ | — | — |
| 台账查看 | 全校 | 全校 | 本人 |
| 发起代课申请 | — | — | ✓ |
| 代课申请审批 | — | ✓ | — |
| 上课打卡 | — | — | ✓ |
| 巡课异常登记/提醒 | — | ✓ | — |
| 操作留痕查看/导出 | ✓ | ✓ | 本人 |
3. 核心实体与字段建模
3.1 课程台账 Course
- id, date(日期), period(上课时段), class_name(班级), subject(科目)
- original_teacher(原定教师), actual_teacher(实际教师, 默认=原定, 可被代课审批回写)
- status(正常/代课/异常), last_modified_by, last_modified_at
3.2 代课申请 SubstituteRequest
- id, applicant_id, course_id, requested_substitute(已协商代课教师)
- reason(2-200字), negotiation_note(协商记录, 选填)
- status(待审核/通过/驳回/已闭环), reviewer_id, review_comment, reviewed_at
3.3 巡课异常 Inspection
- id, course_id, inspector_id, expected_teacher, on_site_teacher
- reminder_sent_to, reminder_time, status(待处理/已闭环), closed_by_request_id
4. 状态生命周期
代课申请：待审核 → 通过 → 已闭环（系统自动回写台账"实际上课教师"）
代课申请（驳回）：待审核 → 驳回 → 退回提交人 → 修改后重新提交 → 待审核
巡课异常：待处理 → 教师收到提醒补交代课申请 → 领导审批通过 → 系统自动回写台账 → 已闭环
打卡：未打卡 → 已打卡（记录时间 + GPS）
5. User Stories
- 作为管理员，我希望通过 Excel 批量导入全校课程台账，以便快速建立学期排课基线。
- 作为普通教师，我希望只能查看本人相关台账而不能编辑，以免误改他人课程。
- 作为教师，我希望在手机端发起代课申请并填写已协商的代课教师，以便提交校级领导审核。
- 作为校级领导，我希望在手机端审批代课申请，通过后系统自动回写台账，避免手工修改留责任空隙。
- 作为实际上课教师，我希望手机一键完成上课打卡确认，以便证明已到岗上课。
- 作为校级领导，我希望巡课发现异常时只发提醒不改台账，以便相关教师自行补交代课申请闭环。
- 作为管理员，我希望所有代课申请、审批、打卡、巡课提醒留痕并可导出 Excel，以便后期追溯存档。
6. 验收标准 (AC)
AC-1 Excel 批量导入
- Given 管理员上传符合模板的 Excel 文件
- When 点击"批量导入"
- Then 系统校验字段完整性，成功行写入台账，失败行返回错误明细，并记录操作留痕。
AC-2 权限隔离
- Given 普通教师登录系统
- When 进入课程台账
- Then 仅显示本人相关课程，不出现"导入/编辑"按钮；调用编辑接口返回 403。
AC-3 代课申请提交
- Given 教师填写了已协商的代课教师和原因（≥2字）
- When 提交申请
- Then 申请状态变为"待审核"，推送给校级领导；若代课教师或原因为空，提交失败并提示校验错误。
AC-4 审批回写台账
- Given 领导对"待审核"申请点击"通过"
- When 系统处理审批
- Then 台账中对应课程的"实际上课教师"被自动回写为代课教师，台账状态变为"代课"，并记录留痕；驳回则状态变为"驳回"并退回提交人。
AC-5 上课打卡
- Given 实际上课教师位于上课时间窗内且 GPS 匹配教学楼
- When 点击"一键打卡"
- Then 记录打卡时间与位置，状态变"已打卡"；重复打卡提示"已完成"；位置不匹配则提示异常。
AC-6 巡课异常闭环
- Given 领导发现现场人员与台账不一致
- When 登记巡课异常
- Then 系统向相关教师发送消息提醒，台账不被直接修改；教师补交代课申请并审批通过后，台账自动回写，异常状态变"已闭环"。
AC-7 留痕导出
- Given 管理员/领导进入操作留痕
- When 点击"导出 Excel"
- Then 导出包含代课申请、审批、打卡、巡课提醒四类记录的完整 Excel，字段齐全可存档。
7. 字段字典（核心）
| 字段 | 类型 | 校验 | 控件 |
|---|
| date | date | 必填，不早于今天-30天 | 日期选择器 |
| period | enum | 必填，枚举第1-2/3-4/5-6/7-8节 | 下拉 |
| class_name | string | 必填，2-20字 | 下拉/输入 |
| original_teacher | string | 必填，姓名2-10字 | 下拉 |
| requested_substitute | string | 必填，不能=原任课教师 | 下拉 |
| reason | string | 必填，2-200字 | 文本域 |
| review_comment | string | 驳回时必填 | 文本域 |
8. 异常与边界状态
- 空状态：台账无数据时显示"暂无课程，请通过 Excel 批量导入"插画提示。
- 加载态：表格使用骨架屏，避免空白跳动；按钮 loading 防重复提交。
- 网络错误：统一 Toast"网络异常，请稍后重试"，自动重试 1 次。
- 权限异常：403 时跳转"无权限"提示页，不暴露任何业务字段。
- 数据截断：教师姓名/班级超长使用 ellipsis，hover 显示完整。
- 并发冲突：同一条台账被多次代课申请关联时，先审批通过者生效，后到者提示"该课程已有生效代课"。
- 巡课提醒幂等：同一课程 30 分钟内重复登记异常，仅发送 1 次提醒。
9. 交互流程（端到端）
流程 A 代课审批回写：教师手机发起 → 领导手机审批 → 通过 → 系统自动回写台账"实际教师" → 实际教师手机打卡 → 留痕记录。
流程 B 巡课异常闭环：领导巡课发现不一致 → 发提醒（不改台账）→ 教师收到提醒 → 补交代课申请 → 领导审批通过 → 系统自动回写台账 → 异常状态变已闭环。
流程 C 留痕存档：管理员进入操作留痕 → 按时间/类型筛选 → 导出 Excel（含申请、审批、打卡、巡课四类）→ 存档。