EduGraderAI

English | 中文

---

English

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 to demonstrate a realistic human-in-the-loop workflow:

AI / rule-based pre-grading → teacher review → score publishing → student correction

The goal is not to provide a production-ready school management platform. Instead, the project helps learners understand how to design and implement an AI-enabled full-stack application with frontend pages, backend APIs, relational data modeling, file upload, image recognition, rule-based grading, authentication, and review workflows.

Why This Demo

This project is suitable for learning:

• Full-stack application architecture with React, Go, and MySQL.
• Product-oriented workflow design for real-world AI applications.
• Human-in-the-loop AI design using confidence scores and review states.
• Integration of vision models for image-to-structured-data extraction.
• Practical API design for teacher, student, and admin roles.
• Data traceability across submission, grading, review, publishing, and correction.

Key Features

• Teachers can create, publish, and manage homework.
• Students can answer online or upload paper homework images.
• Image recognition extracts answers; students confirm or edit them before submission.
• Multiple-choice, true / false, and fill-in-the-blank questions are graded by rules.
• Short-answer questions, abnormal answers, and low-confidence recognition results are routed to teacher review.
• Teachers can confirm or modify AI / rule-based grading results before publishing scores.
• Students can view results, explanations, feedback, and submit corrections.
• Teachers can view homework statistics and correction summaries.

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Ant Design 5
Backend	Go 1.22, Gin, GORM, JWT
Database	MySQL 8
AI	DashScope Qwen-VL image recognition; Mock mode when no API key is provided
Grading	Rule engine + confidence score + teacher review status

Project Structure

EduGraderAI/
├── backend/                 # Go backend service
│   ├── cmd/server/           # Server entry point
│   ├── config/               # Example configuration and config docs
│   ├── internal/             # Handlers, services, models, middleware
│   └── postman/              # Postman collection and API testing docs
├── docs/
│   ├── db/database.sql       # MySQL schema and demo seed data
│   ├── qwen/                 # Qwen-VL image recognition notes
│   └── PRD.md                # Bilingual product and learning demo overview
├── frontend/                 # React frontend application
└── README.md                 # Project entry document

Documentation

Document	Description
Product & Project Overview	Bilingual learning demo overview, PRD, feature scope, technical design, demo flow
Qwen Vision Recognition Guide	Image recognition workflow, API details, configuration
Backend Configuration	Database, JWT, upload directory, AI model configuration
Postman API Testing	API collection import and testing guide

Database Setup

1. Install MySQL 8.x.
2. Run the database initialization script:

mysql -u root -p < docs/db/database.sql

The script creates the edugraderai database, tables, and demo seed data. You do not need to create the database manually.

3. Copy backend/config/config.example.yaml to backend/config/config.yaml, then update the MySQL connection if needed. You can also override local secrets with environment variables such as MYSQL_PASSWORD or MYSQL_DSN. See backend/config/README.md for details.

Quick Start

Start the backend. The default address is http://localhost:8080.

cd backend
# Copy config/config.example.yaml to config/config.yaml first if config.yaml does not exist.
.\build.ps1 -Run

Alternatively:

cd backend
go run ./cmd/server/

Start the frontend. The default address is http://localhost:3000.

cd frontend
npm install
npm run dev

During local development, Vite proxies /api, /uploads, and /health to http://localhost:8080. For previewing a production build without the Vite dev proxy, create frontend/.env.local and set:

VITE_API_BASE_URL=http://localhost:8080

Health check:

GET http://localhost:8080/health

Expected response:

{"status":"ok"}

Demo Accounts

All demo accounts use the password 123456.

Username	Role	Description
teacher001	Teacher / Admin	Manage homework, review answers, publish scores, manage teachers
student001	Student	Answer online, upload images, view results, submit corrections
student002	Student	Optional second student for testing

Recommended Demo Flow

1. Log in as student001.
2. Open My Homework and select Math Chapter 6 Practice.
3. Answer online, or upload an answer sheet image and confirm the recognized answers.
4. Submit the homework and let the system generate AI / rule-based grading results.
5. Log in as teacher001.
6. Open homework submissions and review the student submission.
7. Confirm or modify questions marked as need_review.
8. Publish the result.
9. Log in again as the student, view the result, and submit corrections for wrong answers.
10. Review homework statistics and correction summaries as the teacher.

See docs/PRD.md for the full product and demo flow.

Optional Image Recognition Configuration

The project supports DashScope Qwen-VL for paper homework image recognition. If no API key is available, Mock mode can be used for local demonstration.

Example backend/config/config.yaml:

qwen:
  api_key: ""
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  model: "qwen-vl-max"
  use_mock_when_no_key: true
  timeout_seconds: 60

Environment variables are also supported: QWEN_API_KEY, QWEN_BASE_URL, QWEN_MODEL.

Note: base_url should end at /v1; do not include /chat/completions.

Frontend Build

cd frontend
npm run build
npm run preview

If the preview server is not hosted behind the Go backend, set VITE_API_BASE_URL before building or in frontend/.env.local so API requests target the backend explicitly.

Security Notes for Public Learning Use

This repository is designed for local learning and classroom demonstration. It is not production-ready. Before publishing forks or deploying the app publicly:

• Do not commit real API keys, database passwords, JWT secrets, tokens, private network addresses, uploaded homework images, or student personal data.
• Keep backend/config/config.yaml, .env*, node_modules/, build outputs, TypeScript build cache files, runtime uploads, and logs out of Git.
• Use environment variables such as MYSQL_PASSWORD, MYSQL_DSN, JWT_SECRET, and QWEN_API_KEY for local secrets.
• Rotate any secret immediately if it was ever committed to a public repository.
• Treat the demo accounts and 123456 password in the seed SQL as sample data only. Change or remove them before any public-facing deployment.
• Replace the placeholder JWT secret change-me-in-local-env with a strong random value outside the repository.
• The backend allows local demo CORS and provides simplified authentication for learning. Harden CORS, password hashing, rate limiting, HTTPS, audit logs, and authorization checks before production use.
• The repository includes an MIT License by default.

Recommended final check before pushing:

git status --ignored
git diff

Make sure ignored local files such as backend/config/config.yaml, frontend/node_modules/, and backend/uploads/ are not staged.

Project Scope

This MVP focuses on a controllable and explainable human-in-the-loop grading workflow.

Not included in the current version:

• Fully automated grading for essays, proofs, or complex subjective questions.
• Production-grade multi-tenancy, advanced permission models, or school system integration.
• 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.

---

中文

EduGraderAI 是一个 面向大学生和开发者学习 AI 应用工程的开源教学 Demo。项目采用中小学课堂作业批改作为样例业务场景，用于展示一个现实可落地的人机协同流程：

AI / 规则初批 → 教师复核 → 成绩发布 → 学生订正

本项目目标不是提供生产级校务平台，而是帮助学习者理解如何设计和实现一个 AI 全栈应用，包括前端页面、后端接口、关系型数据库建模、文件上传、图片识别、规则批改、鉴权和复核流程。

为什么适合作为学习 Demo

本项目适合学习：

• React、Go、MySQL 组成的全栈应用架构。
• 面向真实业务流程的 AI 产品设计。
• 基于置信度和复核状态的人机协同 AI 设计。
• 视觉模型从图片中提取结构化数据的集成方式。
• 教师、学生、管理员多角色 API 设计。
• 提交、批改、复核、发布、订正全链路数据追踪。

核心能力

• 教师创建、发布和管理作业。
• 学生在线答题或上传纸质作业图片。
• 图片识别抽取答案，学生确认或修改后再提交。
• 选择题、判断题、填空题通过规则引擎批改。
• 简答题、异常答案和低置信识别结果进入教师复核。
• 教师可在发布成绩前确认或修改 AI / 规则批改结果。
• 学生可查看结果、解析和反馈，并提交错题订正。
• 教师可查看作业统计与订正汇总。

技术栈

层级	技术
前端	React 18、TypeScript、Vite、Ant Design 5
后端	Go 1.22、Gin、GORM、JWT
数据库	MySQL 8
AI 能力	DashScope 千问 VL 图片识别；无 Key 时支持 Mock
批改策略	规则引擎 + 置信度 + 教师复核状态

项目结构

EduGraderAI/
├── backend/                 # Go 后端服务
│   ├── cmd/server/           # 服务启动入口
│   ├── config/               # 示例配置与配置说明
│   ├── internal/             # 接口、服务、模型、中间件
│   └── postman/              # Postman 集合和接口测试文档
├── docs/
│   ├── db/database.sql       # MySQL 表结构和演示种子数据
│   ├── qwen/                 # 千问 VL 图片识别说明
│   └── PRD.md                # 中英双语产品与学习 Demo 说明
├── frontend/                 # React 前端应用
└── README.md                 # 项目入口文档

文档入口

文档	说明
产品方案与项目说明	中英双语学习 Demo 说明、PRD、功能边界、技术方案、演示流程
千问图片识别方案	图片识别链路、接口与配置说明
后端配置说明	数据库、JWT、上传目录、模型配置
Postman 接口测试	接口集合导入与测试说明

数据库准备

1. 安装 MySQL 8.x。
2. 执行数据库初始化脚本：

mysql -u root -p < docs/db/database.sql

脚本内包含建库 edugraderai、表结构和演示种子数据，无需手动创建数据库。

3. 复制 backend/config/config.example.yaml 为 backend/config/config.yaml，然后按需修改 MySQL 连接信息。也可以使用环境变量 MYSQL_PASSWORD / MYSQL_DSN 覆盖本地敏感配置。详细说明见 backend/config/README.md。

快速启动

启动后端，默认地址为 http://localhost:8080。

cd backend
# 如果 config.yaml 不存在，请先复制 config/config.example.yaml 为 config/config.yaml。
.\build.ps1 -Run

也可以直接运行：

cd backend
go run ./cmd/server/

启动前端，默认地址为 http://localhost:3000。

cd frontend
npm install
npm run dev

本地开发时，Vite 会把 /api、/uploads 和 /health 代理到 http://localhost:8080。如果需要预览生产构建且不经过 Vite 开发代理，请创建 frontend/.env.local 并设置：

VITE_API_BASE_URL=http://localhost:8080

健康检查：

GET http://localhost:8080/health

期望返回：

{"status":"ok"}

演示账号

演示账号密码均为 123456。

账号	角色	说明
teacher001	教师 / 管理员	管理作业、复核答案、发布成绩、管理教师
student001	学生	在线答题、上传图片、查看结果、提交订正
student002	学生	可用于第二名学生测试

推荐演示流程

1. 学生登录 student001。
2. 进入“我的作业”，选择“数学第六章练习”。
3. 在线答题，或上传答题卡图片并确认识别结果。
4. 提交作业，系统生成 AI / 规则批改结果。
5. 教师登录 teacher001。
6. 进入作业提交列表，打开学生提交记录。
7. 对 need_review 题目进行确认或改分。
8. 发布成绩。
9. 学生再次登录，查看结果，并对错题提交订正。
10. 教师查看作业统计与订正汇总。

完整产品说明和演示流程见 docs/PRD.md。

图片识别配置（可选）

项目支持通过 DashScope 千问 VL 识别纸质作业图片。若没有 API Key，可使用 Mock 模式完成本地演示。

backend/config/config.yaml 示例：

qwen:
  api_key: ""
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  model: "qwen-vl-max"
  use_mock_when_no_key: true
  timeout_seconds: 60

也可通过环境变量覆盖：QWEN_API_KEY、QWEN_BASE_URL、QWEN_MODEL。

注意：base_url 只填写到 /v1，不要包含 /chat/completions。

前端构建

cd frontend
npm run build
npm run preview

如果预览服务没有部署在 Go 后端同源地址下，请在构建前或 frontend/.env.local 中设置 VITE_API_BASE_URL，让 API 请求明确指向后端服务。

面向公开学习的安全说明

本仓库定位是本地学习和课堂演示项目，不是生产级系统。发布 fork 或公开部署前请确认：

• 不提交真实 API Key、数据库密码、JWT 密钥、Token、内网地址、上传的作业图片或学生个人隐私数据。
• 不提交 backend/config/config.yaml、.env*、node_modules/、构建产物、TypeScript 构建缓存、运行时上传文件和日志。
• 本地敏感配置优先通过 MYSQL_PASSWORD、MYSQL_DSN、JWT_SECRET、QWEN_API_KEY 等环境变量提供。
• 如果任何真实密钥曾被提交到公开仓库，请立即废弃并轮换。
• 种子 SQL 中的演示账号和 123456 密码仅用于 Demo，公开部署前必须修改或移除。
• 占位 JWT 密钥 change-me-in-local-env 必须在仓库外替换为强随机值。
• 后端默认配置面向本地演示，鉴权和 CORS 都经过简化。生产使用前需要补齐密码哈希、严格 CORS、限流、HTTPS、审计日志和更细粒度权限校验。
• 仓库已默认包含 MIT License。

推送前建议最后检查：

git status --ignored
git diff

确认 backend/config/config.yaml、frontend/node_modules/、backend/uploads/ 等本地忽略文件没有被加入暂存区。

项目边界

当前 MVP 聚焦可控、可解释的人机协同批改流程。

当前版本不包含：

• 作文、证明题等复杂主观题的完全自动评分。
• 生产级多租户、复杂权限模型或校务系统集成。
• 大规模题库、智能组卷或个性化学习推荐。
• 多页 PDF、批量扫描或完整 OCR 生产流水线。
• 生产级监控、审计、容灾或高可用部署。