EduGraderAI is an open-source educational demo for college students and developers learning AI application engineering. It uses a K-12 classroom homework grading scenario as the sample domain. The current version is an MVP that validates a complete human-in-the-loop workflow:
Student submission
→ AI / rule-based pre-grading
→ Teacher review
→ Score publishing
→ Student correction
This document covers learning goals, product goals, user roles, feature scope, core workflows, technical implementation, demo paths, MVP boundaries, and future roadmap. For setup instructions and demo accounts, see README.md.
EduGraderAI is primarily intended for college students and developers who want to learn how to build a realistic AI-enabled full-stack application. The K-12 homework grading scenario is intentionally simple and easy to verify, making it suitable for studying product design, backend APIs, frontend workflows, database modeling, AI integration, and human-in-the-loop decision making.
Within the sample product scenario, EduGraderAI reduces repetitive grading work through rule-based grading, image recognition, confidence scoring, and teacher review, while helping students receive feedback faster and complete corrections sooner.
The current version is not a full school management system and does not attempt to fully automate grading for complex subjective questions. Instead, it focuses on verifiable and realistic capabilities:
- Objective questions and structured fill-in-the-blank questions can be graded automatically.
- Paper homework images can be recognized into structured answers.
- Recognized answers must be confirmed or edited by students before submission.
- Low-confidence, ambiguous, or subjective answers are routed to teacher review.
- Teachers publish scores after required reviews are completed.
- Students view results and submit corrections.
In K-12 classroom teaching, homework grading is frequent, repetitive, and often concentrated within a short period of time. Teachers may need to grade assignments from multiple classes. Objective questions are easy to judge but still time-consuming at scale, while short-answer questions, proofs, and essays require professional judgment.
Students need timely feedback. If results are delayed, correction and knowledge reinforcement are also delayed.
EduGraderAI follows a practical principle: AI improves efficiency but does not overstep teacher authority. The system handles high-confidence deterministic questions first and explicitly routes uncertain cases to teachers.
| Goal | Description |
|---|---|
| Improve grading efficiency | Provide near real-time pre-grading for objective and structured questions |
| Improve result trustworthiness | Keep confidence scores, review status, and feedback for each question |
| Shorten feedback loop | Allow students to view results and correct mistakes after publication |
| Support paper homework | Convert paper answers into structured submissions through image recognition |
| Ensure traceability | Preserve submission, recognition, grading, review, publishing, and correction records |
| Role | Responsibilities |
|---|---|
| Teacher | Manage classes and homework, review AI / rule-based grading, publish scores, view statistics and corrections |
| Student | View homework, answer online or upload images, view results, submit corrections |
| Admin | Maintain basic teacher account management |
- Dashboard: pending reviews, recent homework, basic statistics.
- Classes and students: view basic class and student information.
- Courses and homework: create, edit, delete, and publish homework.
- Submission list: view submission status, scores, and pending review counts.
- Review page: view student answers, AI scores, confidence, feedback, original images, and confirm or modify scores.
- Score publishing: publish results after required reviews are completed.
- Analytics: view average score, accuracy, mistake distribution, and correction summaries.
- My homework: view pending, submitted, and published homework.
- Online answering: answer questions and submit directly.
- Image upload: upload paper homework images, review recognized answers, and edit them before submission.
- Result view: view total score, per-question score, correctness, feedback, and explanations.
- Corrections: submit corrected answers for wrong questions and view correction history.
The MVP only includes lightweight teacher account management. Complex organization structures and fine-grained permission models are outside the current scope.
Teacher publishes homework
→ Student answers online / uploads image for recognition
→ Student confirms recognized answers and submits
→ System performs rule-based grading and generates confidence / review status
→ Teacher reviews low-confidence or subjective answers
→ Teacher publishes scores
→ Student views results and submits corrections
→ Teacher reviews statistics and correction summaries
The workflow follows two principles:
- Automate deterministic cases: objective questions and standardized fill-in-the-blank questions are graded automatically.
- Review uncertain cases manually: low-confidence recognition, ambiguous fill-in answers, and subjective questions are reviewed by teachers.
| Principle | Description |
|---|---|
| Separate recognition from grading | The vision model extracts question numbers and answers; it does not determine final scores |
| Rules first | Deterministic question types use a rule engine for stability and explainability |
| Confidence-driven review | Low-confidence recognition or grading results are marked as need_review |
| Teacher final confirmation | Required review items must be handled by teachers before score publication |
| Full traceability | Recognition results, grading logs, review records, and correction records are preserved |
| Question Type | MVP Strategy | Notes |
|---|---|---|
| Multiple choice | Auto grading | Match standard answer |
| True / false | Auto grading | Match standard answer |
| Fill-in-the-blank | Rule grading + review when needed | Normalize answers before matching; ambiguous answers require review |
| Short answer | Assisted judgment + teacher review | Rules or keywords may assist, but the strategy remains conservative |
| Essay / proof | Not auto-graded in MVP | Planned for future versions |
- Image recognition is implemented with Qwen-VL or Mock mode.
- Recognition output includes question number, recognized answer, per-question confidence, and overall confidence.
- The frontend displays recognized answers for student confirmation or editing.
- Low-confidence recognized answers are highlighted for teacher attention.
- Standard answers are not sent to the vision model, preventing the model from directly grading by seeing answers.
| Status | Meaning |
|---|---|
submitted |
Student has submitted; waiting for grading |
ai_graded |
Pre-grading is completed and no required review remains |
need_review |
At least one answer requires teacher review |
reviewed |
Teacher review is completed but result is not published yet |
published |
Score is published; student can view result and correct mistakes |
| Status | Meaning |
|---|---|
auto_pass |
System result can be accepted automatically |
need_review |
Teacher review is required |
teacher_confirmed |
Teacher confirms the system result |
teacher_modified |
Teacher modifies score or feedback |
files.ocr_*: image recognition status, confidence, result JSON, and error message.ai_grading_logs: grading process logs.submission_answers: answers, scores, confidence, and review status for each question.correction_records: student corrections and correction feedback.
| Layer | Technology |
|---|---|
| Frontend | React 18, TypeScript, Vite, Ant Design 5 |
| Backend | Go 1.22, Gin, GORM, JWT |
| Database | MySQL 8 |
| AI Recognition | DashScope Qwen-VL; Mock mode when no API key is available |
| Grading | Rule engine, confidence score, review state machine |
| Module | Description |
|---|---|
backend/internal/services/qwen_vision.go |
Image recognition service |
backend/internal/services/grading.go |
Rule-based grading service |
backend/internal/handlers/student.go |
Student homework, submission, and correction APIs |
backend/internal/handlers/teacher.go |
Teacher homework, review, publishing, and analytics APIs |
frontend/ |
Student, teacher, and admin pages |
| API | Description |
|---|---|
GET /health |
Health check |
POST /api/auth/login |
Login |
POST /api/files/upload |
File upload |
POST /api/ai/qwen/recognize-homework-image |
Image recognition |
POST /api/student/homeworks/:id/submit |
Online homework submission |
POST /api/student/homeworks/:id/submit-by-recognition |
Submission after image recognition confirmation |
GET /api/teacher/homeworks/:id/submissions |
Teacher views submission list |
POST /api/teacher/answers/:id/review |
Teacher reviews one answer |
POST /api/teacher/submissions/:id/publish-result |
Publish result |
POST /api/student/answers/:id/corrections |
Student submits correction |
- Run
docs/db/database.sqlto initialize the database. - Update database connection settings in
backend/config/config.yaml. - Start the backend and confirm
http://localhost:8080/healthworks. - Start the frontend and open
http://localhost:3000.
| Username | Password | Role |
|---|---|---|
teacher001 |
123456 |
Teacher |
student001 |
123456 |
Student |
student002 |
123456 |
Student |
- Open the demo answer sheet, save it as a PNG screenshot, or prepare a clear answer sheet image.
- Log in as
student001. - Go to My Homework and select Math Chapter 6 Practice.
- Choose Upload Image and upload the answer sheet.
- Wait for recognition, then check and edit recognized answers if needed.
- Confirm submission; the system performs rule-based grading.
- Log in as
teacher001. - Open homework submissions and select the corresponding submission.
- View original image, recognized answers, AI / rule-based results, and pending review items.
- Confirm or modify questions marked as
need_review. - Publish the result.
- Log in again as the student, view results, and submit corrections for wrong answers.
- Log in as
student001. - Go to My Homework and select Math Chapter 6 Practice.
- Fill in answers online and submit.
- Log in as
teacher001and complete review. - Publish the result.
- The student views the result and submits corrections.
Import the Postman Collection and environment files under backend/postman/, then test in this order:
Health
→ Login Student
→ List Homeworks
→ Submit Homework
→ Login Teacher
→ List Submissions
→ Review Answer
→ Publish Result
→ Login Student
→ Get Submission Result
→ Submit Correction
- Basic teacher, student, and admin roles.
- Homework creation, publishing, submission, review, and score publishing.
- Online answering and image-recognition-based submission.
- Rule-based grading, confidence marking, and teacher review.
- Student corrections and teacher correction summaries.
- Local runnable demo environment.
- Fully automated grading for essays, proofs, or complex subjective questions.
- Production-grade multi-tenancy, complex organization structures, or advanced permission models.
- Large-scale question banks, intelligent paper generation, or personalized learning recommendations.
- Multi-page PDF processing, batch scanning, or a complete OCR production pipeline.
- Production-grade monitoring, auditing, disaster recovery, or high-availability deployment.
| Stage | Direction |
|---|---|
| V1.1 | Improve fill-in answer normalization, low-confidence prompts, and batch review experience |
| V1.2 | Add knowledge tags, mistake book, and class-level weakness analysis |
| V2.0 | Introduce LLM-generated scoring suggestions and feedback drafts for short answers |
| V2.1 | Support rubric-based essay and proof evaluation with teacher confirmation |
| V2.2 | Support multi-image upload, PDF input, batch upload, and better image quality detection |
| V3.0 | Improve multi-organization, multi-teacher collaboration, permissions, and deployment readiness |
- Do not commit real API keys, database passwords, JWT secrets, or other sensitive information.
- Use environment variables to override secrets in configuration files.
- Demo data is fictional and only used for local functional verification.
- Add a clear open-source license before publishing, such as the MIT License.
- The learning audience is college students and developers; the homework-grading business scenario is only a sample domain.
EduGraderAI 是一个面向中小学班级作业场景的 AI 辅助批改系统。当前版本定位为 MVP，用于验证完整的人机协同闭环：
学生提交
→ AI / 规则初批
→ 教师复核
→ 成绩发布
→ 学生订正
本文覆盖产品目标、角色功能、核心流程、技术实现、演示路径、MVP 边界与后续规划。运行环境、数据库初始化和演示账号见 README.md。
EduGraderAI 主要面向大学生和开发者，用于学习如何构建一个真实可用的 AI 应用全栈项目。项目选择中小学作业批改作为样例业务场景，是因为这个场景足够简单、容易验证，适合学习产品设计、后端接口、前端流程、数据库建模、AI 集成以及人机协同决策。
在样例产品场景中，EduGraderAI 通过规则批改、图片识别、置信度标记和教师复核机制，帮助教师减少重复性批改工作，让学生更快获得反馈并完成错题订正。
当前版本不是完整校务系统，也不追求复杂主观题的完全自动评分，而是优先实现以下可验证、可落地的能力：
- 客观题和标准化填空题可自动批改。
- 纸质作业图片可识别为结构化答案。
- 识别结果由学生确认或修改后再进入批改链路。
- 低置信、模糊答案和主观题进入教师复核。
- 教师处理待复核题后发布成绩。
- 学生查看结果并提交订正。
在中小学班级教学中，作业批改具有高频、重复、集中发生的特点。教师往往需要在较短时间内处理多个班级的作业。客观题虽然判断标准明确，但批量批改仍会消耗大量时间；简答题、证明题、作文等主观题又需要教师结合过程与表达进行专业判断。
学生侧更关注反馈时效。如果学生提交作业后需要等待较长时间才能看到结果，错题订正和知识点补漏也会被延迟。
因此，本项目采用“AI 提效但不越权”的设计：系统先处理确定性强的题目，并将不确定结果显式交给教师复核。
| 目标 | 说明 |
|---|---|
| 提升批改效率 | 对选择题、判断题、填空题等高确定性题型进行秒级初批 |
| 提高结果可信度 | 每题保留置信度、复核状态和反馈，低置信题必须人工处理 |
| 缩短反馈链路 | 教师发布后，学生可立即查看结果、解析和订正入口 |
| 支持纸质作业 | 通过图片识别将纸质答案转为结构化提交 |
| 保持可追溯 | 保留提交、识别、批改、复核、发布和订正记录 |
| 角色 | 核心职责 |
|---|---|
| 教师 | 管理班级与作业，查看 AI / 规则初批结果，复核待处理题目，发布成绩，查看统计与订正 |
| 学生 | 查看作业，在线答题或上传图片，查看批改结果，提交错题订正 |
| 管理员 | 维护教师账号等基础管理能力 |
- 工作台：查看待复核任务、近期作业和基础统计。
- 班级 / 学生：查看班级和学生基础信息。
- 课程与作业：创建、编辑、删除、发布作业。
- 提交列表：查看学生提交状态、分数、待复核数量。
- 作业复核：查看每题答案、AI 分数、置信度、评语、原图，支持确认或改分。
- 成绩发布：待复核题处理完成后向学生发布成绩。
- 统计分析：查看平均分、正确率、错题分布和订正情况。
- 我的作业：查看待完成、已提交、已发布成绩的作业。
- 在线答题：按题作答并提交。
- 图片上传：上传纸质作业图片，识别后核对并修正答案。
- 结果查看：查看总分、单题得分、正确性、评语和解析。
- 错题订正：对错题提交订正答案，查看订正记录。
MVP 中仅提供轻量教师账号管理能力，不扩展复杂组织架构和细粒度权限模型。
教师发布作业
→ 学生在线答题 / 上传图片识别
→ 学生核对识别结果并提交
→ 系统规则批改并生成置信度与复核状态
→ 教师复核低置信或主观题
→ 教师发布成绩
→ 学生查看结果并提交订正
→ 教师查看统计与订正汇总
该闭环强调两个原则：
- 自动化处理确定性问题：客观题、标准化填空题优先自动批改。
- 人工处理不确定问题：低置信识别、模糊填空、简答题等交由教师复核。
| 原则 | 说明 |
|---|---|
| 识别与批改分离 | 图片模型只抽取题号与答案，不直接决定最终分数 |
| 规则优先 | 高确定性题型采用规则引擎，保证稳定性和可解释性 |
| 置信度驱动复核 | 对低置信识别或低置信批改结果标记为 need_review |
| 教师最终确认 | 成绩发布前，待复核结果必须由教师处理 |
| 全链路留痕 | 保留识别结果、批改日志、复核记录和订正记录 |
| 题型 | MVP 策略 | 说明 |
|---|---|---|
| 选择题 | 自动批改 | 标准答案匹配 |
| 判断题 | 自动批改 | 标准答案匹配 |
| 填空题 | 规则批改 + 必要时复核 | 归一化后匹配，模糊答案进入复核 |
| 简答题 | 辅助判断 + 教师复核 | 可使用规则或关键词辅助，但保持保守策略 |
| 作文 / 证明题 | 暂不自动评分 | 作为后续扩展方向 |
- 图片识别由千问 VL 或 Mock 实现。
- 识别输出包含题号、识别答案、单题置信度和整体置信度。
- 前端展示识别结果，学生可修改后提交。
- 单题识别置信度低于阈值时，即使规则批改可判断，也会提示教师关注。
- 标准答案不会交给图片识别模型，避免模型直接“看答案判分”。
| 状态 | 含义 |
|---|---|
submitted |
学生已提交，等待批改 |
ai_graded |
系统已完成初批，无必须复核项 |
need_review |
存在待教师复核题目 |
reviewed |
教师已完成复核，但尚未发布 |
published |
成绩已发布，学生可查看并订正 |
| 状态 | 含义 |
|---|---|
auto_pass |
系统自动判定，可直接采用 |
need_review |
需要教师复核 |
teacher_confirmed |
教师确认系统结果 |
teacher_modified |
教师修改分数或反馈 |
files.ocr_*：图片识别状态、置信度、结果 JSON 和错误信息。ai_grading_logs：批改过程日志。submission_answers：每题答案、分数、置信度、复核状态。correction_records：学生订正答案与订正反馈。
| 层级 | 技术 |
|---|---|
| 前端 | React 18、TypeScript、Vite、Ant Design 5 |
| 后端 | Go 1.22、Gin、GORM、JWT |
| 数据库 | MySQL 8 |
| AI 识别 | DashScope 千问 VL，支持无 Key Mock |
| 批改 | 规则引擎、置信度、复核状态机 |
| 模块 | 说明 |
|---|---|
backend/internal/services/qwen_vision.go |
图片识别服务 |
backend/internal/services/grading.go |
规则批改服务 |
backend/internal/handlers/student.go |
学生作业、提交、订正接口 |
backend/internal/handlers/teacher.go |
教师作业、复核、发布、统计接口 |
frontend/ |
学生端、教师端和管理端页面 |
| 接口 | 说明 |
|---|---|
GET /health |
健康检查 |
POST /api/auth/login |
登录 |
POST /api/files/upload |
文件上传 |
POST /api/ai/qwen/recognize-homework-image |
图片识别 |
POST /api/student/homeworks/:id/submit |
在线答题提交 |
POST /api/student/homeworks/:id/submit-by-recognition |
图片识别确认后提交 |
GET /api/teacher/homeworks/:id/submissions |
教师查看提交列表 |
POST /api/teacher/answers/:id/review |
教师复核单题 |
POST /api/teacher/submissions/:id/publish-result |
发布成绩 |
POST /api/student/answers/:id/corrections |
学生提交订正 |
- 执行
docs/db/database.sql初始化数据库。 - 修改
backend/config/config.yaml中的数据库连接信息。 - 启动后端，确认
http://localhost:8080/health返回正常。 - 启动前端，访问
http://localhost:3000。
| 账号 | 密码 | 角色 |
|---|---|---|
teacher001 |
123456 |
教师 |
student001 |
123456 |
学生 |
student002 |
123456 |
学生 |
- 打开 演示答题卡，截图保存为 PNG，或准备清晰答题卡图片。
- 使用
student001登录。 - 进入“我的作业”，选择“数学第六章练习”。
- 选择“上传图片”，上传答题卡。
- 等待识别完成，检查并修正识别答案。
- 确认提交，系统完成规则批改。
- 使用
teacher001登录。 - 进入作业提交列表，打开对应提交。
- 查看原图、识别答案、AI / 规则初批结果和待复核题。
- 对
need_review题目进行确认或改分。 - 发布成绩。
- 学生重新查看结果，并对错题提交订正。
- 使用
student001登录。 - 进入“我的作业”，选择“数学第六章练习”。
- 直接在线填写答案并提交。
- 使用
teacher001登录并完成复核。 - 教师发布成绩。
- 学生查看结果并提交订正。
可导入 backend/postman/ 下的 Postman Collection 与环境文件，按以下顺序测试：
Health
→ Login Student
→ List Homeworks
→ Submit Homework
→ Login Teacher
→ List Submissions
→ Review Answer
→ Publish Result
→ Login Student
→ Get Submission Result
→ Submit Correction
- 教师、学生、管理员基础角色。
- 作业创建、发布、提交、复核、发布成绩。
- 在线答题与图片识别提交。
- 规则批改、置信度标记、教师复核。
- 学生错题订正与教师订正汇总。
- 本地环境可运行验证。
- 作文、证明题等复杂主观题的完全自动评分。
- 多租户、复杂组织架构、生产级权限模型。
- 大规模题库、智能组卷、个性化学习推荐。
- 多页 PDF、批量扫描、生产级 OCR 流水线。
- 生产级监控、审计、容灾和高可用部署。
| 阶段 | 方向 |
|---|---|
| V1.1 | 优化填空题归一化、低置信提示、教师批量复核体验 |
| V1.2 | 增加知识点标签、错题本、班级薄弱点分析 |
| V2.0 | 引入 LLM 为简答题提供评分建议和反馈草稿 |
| V2.1 | 支持作文、证明题分维度评分，但保留教师确认 |
| V2.2 | 支持多图、PDF、批量上传和更完善的图片质量检测 |
| V3.0 | 完善多组织、多教师协同、权限与部署能力 |
- 仓库不应提交真实 API Key、数据库密码、JWT 密钥或其他敏感信息。
- 配置文件中的密钥建议通过环境变量覆盖。
- 演示数据均为虚构数据，仅用于本地功能验证。
- 如需正式开源发布，建议补充
LICENSE、贡献说明和更完善的部署文档。 - 学习受众是大学生和开发者；作业批改业务只是样例域，不代表项目的真实服务对象。