# 【学习工作】作业清晰：教师作业智能评阅与反馈辅助系统
—
## 1. Demo 简介
**是什么**：作业清晰是一款面向教师的 Web 作业智能评阅与反馈辅助系统。教师创建批改批次后上传学生作业 PDF，系统通过异步任务自动完成 OCR 识别和 AI 辅助评分，生成结构化评分结果后进入人工复核环节，教师可确认系统评分或修改最终评分并填写依据，形成"系统初评 → 人工复核 → 最终评分写回"的完整闭环。
**技术架构**：Vue3 + TypeScript + Element Plus 前端，Java 21 + Spring Boot + MyBatis-Plus 主后端，Python + FastAPI AI/OCR 服务，PostgreSQL + MinIO + RabbitMQ 基础设施，Docker Compose 部署。三端分离，通过内部 HTTP 和消息队列协作。
**面向谁**：有日常作业、课堂练习或阶段测验管理需求的教师。当前以高校课程作业为验证场景，系统架构支持扩展到中小学场景。
**核心功能**：
| 功能 | 说明 |
|—|—|
| 创建批改批次 | 教师填写批次标题、课程名称、班级名称，创建一个作业评阅批次 |
| 上传作业 + 异步评阅 | 上传单份 PDF 作业，系统自动保存到 MinIO 并创建异步评阅任务，通过 RabbitMQ 投递给 Java Worker 消费 |
| AI 辅助评分 | Python AI 服务接收作业文件，执行 OCR 识别、答案结构化和评分计算，返回结构化 JSON（含系统评分、满分、评分置信度） |
| 人工复核闭环 | 教师可"确认系统评分"或"修改最终评分"，修改时必须填写复核依据，最终评分写回数据库并更新状态为 REVIEWED |
**Demo 界面**：
上图：Demo 初始界面，包含四步流程引导（创建批次 → 上传 PDF → 评阅任务 → 查看结果）
—
## 2. Demo 创作思路
**灵感来源**：
在观察教师处理作业和阶段练习的过程中，我发现"看作业"本身并不是唯一耗时的部分，真正消耗精力的是整理、记录、对照和反馈之间来回切换。教师在日常教学中需要反复收集、查看、整理和反馈学生作业，常常面临材料分散、记录繁琐、反馈不及时等问题。许多重复性的事务占用了教师本可以用于备课、答疑和关注学生学习情况的时间。
**想解决的问题**：
- 教师批改作业时面临的重复性整理工作占用大量时间
- AI 辅助评阅如果只是黑箱给分，教师不敢信任
- 标准答案可能有误，不能盲目按答案文本比对
- 手写公式、矩阵、推导步骤难以用普通 OCR 处理
- 批量作业整理、姓名学号识别、成绩表导出占用大量时间
**方向选择与深化**：
报名时想做"作业整理与反馈辅助"，用 TRAE 开发过程中进一步发现，教师真正需要的不只是"整理清楚"，更是"评阅有据可查"。因此将创意深化为"智能评阅 + 证据链 + 人工复核"——让作业处理从整理到评分全流程清晰可追溯。
系统不替代教师的专业判断，而是通过集中的信息呈现和顺畅的复核流程，帮助教师把更多时间投入到教学设计、学生沟通和个性化指导中。从效率角度看，产品可以降低作业管理中的重复操作；从教学支持角度看，它有助于让教师更及时地发现需要关注的学习问题，并形成更完整的作业反馈闭环。
**为什么做这个方向**：
- 市面上的学生端搜题工具很多，但教师端批量评阅工具很少
- 纯 OCR 只能识别文字，无法处理公式和推导步骤
- 纯 AI 给分是黑箱，教师需要看到扣分依据才能信任
- 低风险作业可以自动处理，高风险作业应被筛出给教师复核
—
## 3. Demo 体验地址
本次提交采用****交互式 HTML 格式文件****。
**体验方式**：下载附件中的 `作业清晰-Demo.zip`，解压后用浏览器打开 `作业清晰-Demo.html` 即可体验完整流程。
作业清晰-Demo.zip (8.6 KB)
该 HTML Demo 完整还原了真实系统的交互流程，内置 Mock 数据模拟后端响应：
1. 点击"创建批次"按钮，系统生成批次 ID
2. 点击上传区域选择 PDF 文件（已模拟文件选择）
3. 点击"上传并创建评阅任务"，触发异步评阅任务
4. 观察任务时间线：PENDING → QUEUED → RUNNING → SUCCEEDED
5. 查看评分结果：系统评分 86.50 / 满分 100
6. 进行人工复核：选择"确认系统评分"或"修改最终评分"
7. 提交复核，最终评分写回，状态变为 REVIEWED
> **说明**：真实系统采用 Vue3 + Java 21 + Python FastAPI 三端架构，需 PostgreSQL + MinIO + RabbitMQ 基础设施。为方便评审体验，此处提供独立 HTML 交互 Demo，完整还原了前端交互逻辑和业务流程。真实系统的源码、测试报告和 Smoke Test 记录见下方 TRAE 实践过程。
—
## 4. TRAE 实践过程
### 整体开发策略
本项目采用****文档驱动 + 契约先行 + 分阶段冻结****的开发策略，全程使用 TRAE 辅助开发。从需求文档到工程骨架，从最小闭环到人工复核，每个阶段都有明确的目标、冻结决策和验收标准。
```
阶段0：需求分析与文档体系搭建（39份设计文档 + 决策冻结）
阶段1A-1B：工程骨架搭建（monorepo + 三端骨架 + Docker Compose 基础设施）
阶段1C：最小闭环（MinIO 文件存储 + RabbitMQ 异步任务 + Python Mock AI + Java 落库）
阶段1D：前端可见闭环（Vue3 工作台 + 任务轮询 + 评分结果展示）
阶段1E：人工复核闭环（确认/修改评分 + Worker 防覆盖 + 状态流转保护）
```
### 阶段0：需求分析与文档体系搭建
**做什么**：在写任何代码之前，先用 TRAE 完成完整的需求分析和设计文档体系。最终产出 39 份设计文档，覆盖产品需求、MVP 范围、用户角色、功能模块、页面结构、技术栈决策、系统架构、数据库 Schema、API 契约、Java 后端规范、Python AI 服务规范、前端规范、异步任务规范、OCR 管线、评分引擎、证据链、人工复核、导出、安全、日志、模型网关、错误处理、测试计划、部署指南、开发计划、验收标准等。
**关键决策**：
- Java 主后端负责业务数据写入，Python AI 服务只负责 OCR 和评分计算，不直接写数据库
- 业务主键统一使用 UUID，由应用层生成
- 异步链路：Java 创建任务 → Java 发布 RabbitMQ 消息 → Java Worker 消费 → Java 调用 Python 内部 HTTP → Python 返回结构化 JSON → Java 校验并落库
- Stage 1 先用 Mock AI 结果，不接入真实 OCR/公式识别/LLM
- 所有状态枚举统一为大写英文值，跨端一致
**文档体系截图**：
上图：在 TRAE 中创建批次并选择作业文件
### 阶段1A-1B：工程骨架搭建
**做什么**：基于冻结的决策和契约，搭建 monorepo 工程骨架。
- 前端：Vue3 + TypeScript + Vite + Element Plus，pnpm 管理依赖
- Java 后端：Spring Boot + MyBatis-Plus + Maven Wrapper，包名 `com.teachergrading.platform`
- Python AI 服务：FastAPI + Pydantic，Python 3.12
- 基础设施：Docker Compose 编排 PostgreSQL、RabbitMQ、MinIO
- 契约：OpenAPI YAML、JSON Schema、状态枚举 YAML，三端共享
**关键产出**：三端健康检查接口均可访问，前端 `http://127.0.0.1:5173`，Java `GET /api/v1/health`，Python `GET /internal/health`。
### 阶段1C：最小闭环
**做什么**：跑通第一条端到端业务链路。
```
教师创建批次 → 上传单份 PDF → Java 校验并保存到 MinIO
→ Java 创建 submission 和 grading_job → 发布 RabbitMQ 消息
→ Java Worker 消费消息 → 调用 Python Mock 接口
→ Python 返回固定格式的模拟 OCR/评分结果
→ Java 校验 JSON Schema 并保存到 PostgreSQL
→ 前端轮询任务状态并展示结果
```
**Python Mock AI 接口**（`POST /internal/v1/ai/process-submission`）：
返回结构化 JSON，顶层包含 `status`、`jobId`、`warnings`、`errors`、`result`、`modelCalls`。`result` 中包含身份识别、OCR 文本块、公式块、结构化答案和评分结果（系统评分 86.50，满分 100，状态 REVIEW_REQUIRED）。
**评阅任务处理过程**：
上图：评阅任务时间线，展示从 PENDING 到 RUNNING 的异步处理流程
### 阶段1D：前端可见闭环
**做什么**：用 Vue3 + Element Plus 实现教师工作台前端。
- 四步流程引导：创建批次 → 上传 PDF → 轮询任务 → 查看结果
- 批次创建表单：标题（必填）、课程名称、班级名称、描述
- PDF 上传：拖拽上传 + 点击选择，文件校验（仅 .pdf）
- 任务轮询：每 2 秒轮询 Job 状态，超时 30 次后提示
- 结果展示：系统评分、满分、最终评分、结果状态标签
**测试通过**：
Java 后端 34 个单元测试全部通过（0 failures / 0 errors），前端 `pnpm build` 构建通过。真实 Smoke Test 由人工完成：创建批次 → 上传 PDF → Job SUCCEEDED → REVIEW_REQUIRED → 复核提交 → REVIEWED → finalScore 正确展示。
### 阶段1E：人工复核闭环
**做什么**：实现从 REVIEW_REQUIRED 到 REVIEWED 的最小人工复核闭环。
- **确认系统评分（CONFIRMED）**：`finalScore` 必须等于 `systemScore`
- **修改最终评分（MODIFIED）**：`finalScore` 在 0 到 maxScore 范围内，必须填写复核说明
- **Worker 防覆盖**：已 REVIEWED 的结果不会被迟到的 AI 处理结果覆盖，`finalScore` 不会被重置
- **单次复核保护**：没有多次复核历史表，已复核结果不允许再次提交覆盖
- **maxScore 链路**：`grading_results.max_score` → QueryService → OpenAPI → 前端，前端不再硬编码满分值
**评分结果与人工复核**：
上图：系统评分 86.50，状态 REVIEW_REQUIRED，显示人工复核表单
**复核完成**：
上图：教师修改最终评分为 88.00 并填写复核说明，提交后状态变为 REVIEWED，最终评分已写回
### 开发心得
**1. 文档驱动开发比直接写代码更高效**
一开始花了不少时间写 39 份设计文档，看起来很慢，但后续每个阶段的开发都有明确依据，减少了返工。特别是 `docs/34_DECISIONS.md` 冻结了所有技术决策后，Java、Python、前端三端的协作有了统一标准。
**2. 契约先行避免跨端对接地狱**
在写代码前先定义 OpenAPI YAML、JSON Schema 和状态枚举 YAML，三端共享。Java 后端、Python AI 服务和前端 TypeScript 类型都基于同一套契约生成，避免了"接口对不上"的问题。
**3. 分阶段冻结让进度可控**
每个阶段（Stage 1A → 1B → 1C → 1D → 1E）都有明确的目标、冻结决策和验收标准。一个阶段封板后才进入下一个，不在当前阶段堆叠功能。这让每次开发都聚焦在一个可验证的闭环上。
**4. Mock 先行，逐步替换真实能力**
Stage 1 先用 Python Mock 返回固定结构的评分结果，把三端联调链路跑通。真实 OCR、公式识别和 LLM 评分留到 Stage 2 逐步接入。这样做的好处是：基础设施问题（MinIO 连接、RabbitMQ 投递、数据库迁移）在 Mock 阶段就暴露出来了，不会和 AI 模型问题混在一起。
**5. Worker 防覆盖是一个容易被忽略的细节**
人工复核完成后，如果迟到的 AI 处理结果覆盖了 `finalScore`，教师的修改就白做了。在 Stage 1E 中增加了防护：已 REVIEWED 的结果不会被覆盖，`finalScore` 不会被重置，`submissions` 不会回退状态。
### 关键任务对话 Session ID
以下 Session ID 对应 TRAE 中完成关键开发任务的对话记录（双击对话可复制 Session ID）：
1. **Session 1**（2026/7/8 22:04:10）- 项目需求分析与参赛方案规划
`1577240507175:01a3ede0c869393a1b17135d7deff814_6a4e56c44fb5300f5ca061e7.6a4e58da4fb5300f5ca06255.6a4e58da4fb5300f5ca06254:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/8 22:04:10)`
2. **Session 2**（2026/7/8 21:55:16）- Demo 交互体验与前端开发
`1577240507175:cc1d2dcce11cfe76f400dabde5094b7e_6a4e56c44fb5300f5ca061e7.6a4e56c44fb5300f5ca061ea.6a4e56c44fb5300f5ca061e8:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/8 21:55:16)`
3. **Session 3**（2026/7/8 22:04:03）- 评分结果展示与人工复核功能
`1577240507175:01a3ede0c869393a1b17135d7deff814_6a4e56c44fb5300f5ca061e7.6a4e58d34fb5300f5ca0624b.6a4e58d34fb5300f5ca06249:TRAE Work CN.0.1.30.no_sid.no_ppe.T(2026/7/8 22:04:03)`
—
## 报名帖链接
报名帖：[【学习工作赛道】作业清晰：教师作业整理与反馈辅助系统]( 【学习工作】作业清晰：教师作业整理与反馈辅助系统 )
—
## 当前阶段与后续规划
**已完成**：
- 教师创建批改批次
- 单份 PDF 上传与 MinIO 存储
- RabbitMQ 异步任务投递与 Java Worker 消费
- Python Mock AI 评分（结构化 JSON 返回）
- 评分结果展示与人工复核闭环（确认/修改/写回）
- 34 个 Java 单元测试全部通过
- 真实 Smoke Test 验证完整流程
**后续规划**：
- 批次中心与批量处理工作流（批次列表、多文件上传队列、失败重试）
- 真实 OCR（PaddleOCR）与公式识别
- LLM 语义评分与评语生成
- 评分证据链可视化（原图区域 + OCR 文本 + 评分点对照）
- Excel 成绩导出与 PDF 批改报告
- 用户登录、JWT 认证与 RBAC 权限控制
—
*本项目全程使用 TRAE 辅助开发，从需求文档生成到三端代码实现，从契约设计到测试验证，TRAE 在每个阶段都深度参与了开发过程。*