ocybers/jintowchen/edupal-final

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

update docs

.ide
backend
docs
frontend
.cnb.yml
.gitignore
CLAUDE.md
Dockerfile
README.md

EduPal - 智能教育出题平台

基于 AI 的智能教育出题平台（毕业设计），支持 AI 自动生成题目、分层题库管理、团队协作、在线组卷与智能批阅考试。

技术栈

后端

技术	版本	用途
Python	3.11	运行环境
FastAPI	0.135+	Web 框架
SQLite3	内置	数据库（零配置，本地文件）
PyJWT	2.8+	用户认证 Token
bcrypt	4.1+	密码加密
OpenAI SDK	2.29+	调用 OpenRouter AI 接口
uv	latest	包管理器

前端

技术	版本	用途
React	19	UI 框架
TypeScript	5.9	类型安全
Vite	7	构建工具
Tailwind CSS	v4	样式
shadcn/ui	new-york	UI 组件库
Jotai	2.10	全局状态管理
TanStack Query	5	服务端数据缓存
React Router	7	前端路由
Axios	1.13	HTTP 请求
pnpm	latest	包管理器

AI 服务

OpenRouter — 统一 AI 接口网关
模型：openai/gpt-oss-20b:nitro

项目结构

edupal-final/
├── backend/                  # Python FastAPI 后端
│   ├── main.py               # 应用入口，路由注册，启动建表
│   ├── edupal.db             # SQLite 数据库文件（自动创建）
│   ├── api/
│   │   ├── common.py         # DB连接、JWT工具、success/fail、init_db
│   │   ├── auth.py           # 登录 / 注册 / 用户信息
│   │   ├── question.py       # 题目 CRUD + 权限分层 + 发布/撤回
│   │   ├── generate.py       # AI 异步生成（并发批次 + 草稿入库）
│   │   ├── exam.py           # 试卷 CRUD + 发布 + 答题支持
│   │   ├── team.py           # 团队管理（创建/加入/踢人/解散）
│   │   └── record.py         # 答题记录 + 自动批阅 + AI 智能批阅
│   └── pyproject.toml        # 依赖配置
│
├── frontend/                 # React 前端
│   ├── src/
│   │   ├── lib/
│   │   │   └── api.ts        # 统一 axios 请求封装（含自动 token 注入、401 跳转）
│   │   ├── pages/
│   │   │   ├── welcome/      # 欢迎页 /
│   │   │   ├── auth/         # 登录/注册 /auth
│   │   │   ├── dashboard/    # 仪表盘（统计/快捷操作/最近活动）/dashboard
│   │   │   ├── generate/     # AI 出题（并发生成+实时轮询）/generate
│   │   │   ├── questions/    # 题库管理（权限分层/发布流程）/questions
│   │   │   ├── exams/        # 试卷列表 /exams
│   │   │   │   ├── compose/  # 在线组卷 /exams/compose
│   │   │   │   └── take/     # 在线答题 /exams/take
│   │   │   ├── team/         # 团队管理 /team
│   │   │   └── records/      # 答题记录 /records
│   │   ├── modules/          # Jotai 状态（auth、global）
│   │   ├── components/       # 公共组件（shadcn/ui）
│   │   └── layouts/          # 布局系统（header/router）
│   └── package.json
│
├── Dockerfile                # 一体化镜像（前端编译 + nginx + 后端）
└── README.md

部署（Docker，推荐）

只需一个 Dockerfile，前后端打包进同一镜像，nginx 统一对外暴露 80 端口。

# 构建镜像
docker build -t edupal .

# 运行（数据库持久化到 Docker volume，不随容器删除丢失）
docker run -d \
  -p 80:80 \
  -v edupal_data:/data \
  --restart unless-stopped \
  --name edupal \
  edupal

浏览器访问 http://服务器IP 即可。

若 80 端口已占用，改为 -p 8080:80，访问 http://服务器IP:8080。

默认管理员账号（首次启动自动创建）：

邮箱：admin@ocybers.com
密码：123456

本地开发

环境要求

Python 3.11+
Node.js 18+
uv
pnpm（npm install -g pnpm）

启动后端

cd backend
uv sync
uv run uvicorn main:app --reload
# 运行在 http://localhost:8000
# Swagger 文档：http://localhost:8000/docs

启动前端

cd frontend
pnpm install
pnpm dev
# 运行在 http://localhost:5173（/api 自动代理到 8000）

功能介绍

🤖 AI 智能出题

支持 4 种题型：单选题、判断题、填空题、简答题，可同时选多种
可配置科目、年级、难度、知识点、额外要求
并发启动，每道题生成完立即渲染，实时进度条
生成结果默认保存为草稿，手动选择发布范围

📚 题库管理（权限分层）

我的题目 / 草稿 / 公开题库 / 团队题库
支持搜索、题型/难度筛选、分页
草稿可发布（公开或发布到指定团队），已发布可撤回为草稿

👥 团队协作

创建团队自动生成 8 位邀请码
通过邀请码加入团队
队长可管理成员（踢人/解散），成员可退出
题目和试卷均支持发布到团队，仅成员可见

📝 试卷管理

从题库搜索选题，支持调整顺序
草稿 / 公开发布 / 发布到团队
可设置答题时限

🎯 在线考试 + AI 智能批阅

倒计时/正计时，时间到自动提交
侧边答题卡显示进度，点击快速跳转
提交后即时显示成绩概览（百分比 + 优秀/良好/及格/需努力）
客观题（单选/判断）自动批阅
主观题（填空/简答）AI 打分（0-2分），给出评语和得分要点

📊 答题记录

历史记录列表，显示分数、正确率、用时
逐题详情：我的答案、正确答案、AI 评语
可在历史记录中重新触发 AI 批阅

API 接口总览

前缀	说明
`POST /api/auth/register`	注册
`POST /api/auth/login`	登录
`GET /api/auth/me`	当前用户信息
`GET /api/question/list`	题目列表（scope: mine/draft/public/team）
`POST /api/question/create`	新建题目
`POST /api/question/publish/{id}`	发布题目
`POST /api/generate/start`	启动 AI 生成任务
`GET /api/generate/status/{batch_id}`	查询生成进度
`GET /api/exam/list`	试卷列表
`GET /api/exam/detail/{id}`	试卷详情（含题目）
`POST /api/record/submit`	提交答卷
`GET /api/record/list`	我的答题记录
`GET /api/record/result/{id}`	答题详情
`POST /api/record/ai_review/{id}`	AI 批阅主观题