错题蛙 QuizFrog

小学生错题收集与智能记忆系统。

拍照收集错题 → AI识别整理 → 艾宾浩斯记忆曲线复习 → 生成A4试卷打印练习

环境要求

依赖	版本	用途
Python	3.8+	后端运行
Node.js	18+	前端运行
npm	9+	前端包管理
Kimi API Key	—	图片识别 + AI解析（可选）

数据库使用 SQLite，无需额外安装，开箱即用。

安装依赖

1. 克隆项目

git clone <仓库地址>
cd QuizFrog

2. 后端依赖

cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

requirements.txt 包含：

fastapi — Web 框架
uvicorn — ASGI 服务器
sqlalchemy — ORM
aiosqlite — 异步 SQLite 驱动
httpx — HTTP 客户端（调用 Kimi API）
pillow — 图片处理
reportlab — PDF 生成
python-jose — JWT 认证
passlib[bcrypt] — 密码加密
pydantic — 数据验证

3. 前端依赖

cd frontend
npm install

4. 环境变量

# 复制配置模板
cp .env.example .env

编辑 .env：

# Kimi API Key（图片识别和AI解析需要）
# 获取地址：https://platform.moonshot.cn/
KIMI_API_KEY=sk-你的密钥

# 其他配置一般不需要修改
DATABASE_URL=sqlite+aiosqlite:///./edu_system.db
JWT_SECRET=修改为一个随机字符串

启动项目

需要同时启动后端和前端，建议开两个终端窗口。

终端 1：启动后端

cd backend
venv\Scripts\activate     # Windows
# source venv/bin/activate  # macOS/Linux

# 初始化数据库（首次运行需要）
python init_db.py

# 启动服务
uvicorn app.main:app --reload --port 8000

看到 Uvicorn running on http://0.0.0.0:8000 表示启动成功。

终端 2：启动前端

cd frontend
npm run dev

看到 Ready in x.xs 表示启动成功。

访问

浏览器访问：http://localhost:3000
局域网访问：http://你的IP:3000（需将前端和后端绑定 0.0.0.0，见下方说明）
API 文档：http://localhost:8000/docs

使用说明

第一步：注册账号

打开 http://localhost:3000，点击「注册」，输入用户名、密码、昵称和年级。

第二步：收集错题

两种方式：

拍照识别（需要 Kimi API Key）：
1. 点底部导航「收集」
2. 选择科目（数学/语文/英语）
3. 点「拍照识别」，上传或拍照错题图片
4. AI 自动识别题目、答案、错误原因，确认后保存
手动输入：
1. 切换到「手动输入」模式
2. 填写题目、正确答案、你的答案、错误原因
3. 点「保存错题」

第三步：智能复习

点底部导航「复习」
看到题目后先自己回忆，再点「查看答案」
根据掌握程度选择评分（完全不会 → 非常熟练）
系统根据艾宾浩斯记忆曲线自动安排下次复习时间

复习间隔（默认）：1天 → 2天 → 4天 → 7天 → 15天 → 30天可在「设置」页面自定义。

第四步：错题库管理

点底部导航「错题库」：

按科目筛选
点击展开查看详细信息
可触发「AI深度解析」获取解题思路、知识点讲解、类似练习题

第五步：生成试卷

点底部导航「打印」
选择科目、题目数量、是否附带答案
点「生成试卷」，下载 A4 PDF
打印后即可练习

局域网访问（手机/平板）

默认只能本机访问，若需局域网内其他设备访问：

修改 frontend/next.config.js 中的 destination 为你的局域网 IP：
```
destination: 'http://192.168.x.x:8000/api/:path*'
```

后端绑定 0.0.0.0：

uvicorn app.main:app --reload --port 8000 --host 0.0.0.0

前端绑定 0.0.0.0：
```
npm run dev -- --hostname 0.0.0.0
```
手机浏览器访问 http://192.168.x.x:3000

项目结构

QuizFrog/
├── backend/                  # FastAPI 后端
│   ├── app/
│   │   ├── models/           # 数据库模型
│   │   ├── schemas/          # API 数据格式
│   │   ├── routers/          # API 路由
│   │   ├── services/         # 业务逻辑
│   │   │   ├── ocr_service.py       # Kimi Vision OCR
│   │   │   ├── ai_analysis.py       # AI 深度解析
│   │   │   ├── spaced_repetition.py # 艾宾浩斯算法
│   │   │   └── pdf_service.py       # PDF 生成
│   │   └── main.py           # 应用入口
│   └── requirements.txt
│
├── frontend/                 # Next.js 前端
│   └── src/
│       ├── app/              # 页面路由
│       ├── components/       # UI 组件
│       ├── lib/              # API客户端、状态管理
│       └── types/            # TypeScript 类型
│
└── .env.example              # 环境变量模板

费用说明

功能	是否收费	说明
收集错题（手动输入）	免费	不调用 API
收集错题（拍照识别）	按 Kimi API 计费	调用 vision 模型
AI 深度解析	按 Kimi API 计费	调用纯文本模型，成本较低
复习、错题库、试卷生成	免费	纯本地功能

AI 功能均为手动触发，不会自动调用，完全由用户控制。