一个给小学生练习加减乘除的web应用，可以定制化自动生成计算题练习。顺便靠AI把前端做的好看点，就是为了能让孩子能每天多练几题……
KidsMathQuest 是一个面向 6-12 岁儿童的数学学习应用，采用家长端 + 儿童端双端分离设计：
- 家长端：管理孩子信息、定制每日练习、生成可打印试卷、追踪学习进度
- 儿童端：沉浸式答题体验、虚拟键盘支持、即时反馈、徽章激励系统
设计风格灵感来自《动物森友会》，采用温暖柔和的配色与圆润可爱的 UI 元素，让学习像游戏一样有趣。
| 功能模块 | 说明 |
|---|---|
| 每日练习 | 根据家长配置的题目列表进行练习，支持虚拟键盘输入 |
| 即时反馈 | 答对/答错动画反馈，答错自动收录至错题本 |
| 结算领奖 | 完成练习后领取积分，连续打卡有额外奖励 |
| 徽章系统 | 达成成就解锁徽章，激励持续学习 |
| 错题复习 | 针对性复习历史错题，巩固薄弱环节 |
| 功能模块 | 说明 |
|---|---|
| 儿童管理 | 添加、编辑、管理多个孩子的学习档案 |
| 练习配置 | 自定义每日题目数量、难度范围、运算类型 |
| 试卷生成 | 自动生成 A4 数学试卷，支持打印 |
| 学习统计 | 正确率分析、连续打卡天数、历史记录追踪 |
登录页面
练习结果与奖励
试卷生成与打印预览
graph TB
subgraph Browser[用户浏览器]
B[Chrome / Safari / Edge]
end
subgraph Nginx[Nginx 反向代理]
N[容器端口 80:3000]
end
subgraph Frontend[React 前端应用]
F[React 18 + TypeScript + Vite + Tailwind CSS<br/>动物森友会风格 UI]
F1[家长端]
F2[儿童端]
F3[共享组件]
F --> F1
F --> F2
F --> F3
end
subgraph Backend[Node.js 后端 API]
BE[Express + TypeScript + JWT + bcryptjs]
BE1[Controllers]
BE2[Services]
BE3[Middleware]
BE --> BE1
BE --> BE2
BE --> BE3
end
subgraph Database[数据库层]
D1[SQLite 本地<br/>开发环境<br/>Docker Volume]
D2[PostgreSQL<br/>生产环境<br/>Cloud Profile]
end
B -->|HTTP| N
N --> F
F -->|REST API| BE
BE -->|Prisma ORM| D1
BE -->|Prisma ORM| D2
graph LR
subgraph Parent[家长端流程]
P1[浏览器] -->|注册/登录| P2[后端API]
P2 -->|添加儿童| P3[数据库]
P1 -->|配置练习题目| P2
P1 -->|查看学习统计| P2
end
subgraph Child[儿童端流程]
C1[浏览器] -->|儿童登录| C2[后端API]
C2 -->|获取题目| C3[数据库]
C1 -->|提交答案| C2
C1 -->|记录结果/解锁徽章| C2
end
前端技术栈
- React 18 + TypeScript + Vite
- Tailwind CSS 响应式布局
- 动物森友会风格 UI（animal-island-ui）
- Lucide 图标库
后端技术栈
- Node.js 18 + Express + TypeScript
- Prisma ORM + SQLite（本地）/ PostgreSQL（云端）
- JWT 身份认证
- bcryptjs 密码加密
部署方式
- Docker + Docker Compose 一键部署
- Docker Hub 镜像托管
- 跨平台支持（Windows / macOS / Linux）
graph TB
subgraph Deploy1[方式一：Docker Hub 镜像部署（推荐）]
D1_1[开发者] -->|git clone| D1_2[服务器]
D1_2 -->|docker-compose up| D1_3[运行中]
D1_2 -.->|docker pull 自动| D1_4[Docker Hub<br/>- backend<br/>- frontend]
end
subgraph Deploy2[方式二：本地构建部署]
D2_1[开发者] -->|git clone| D2_2[服务器]
D2_2 -->|docker-compose build| D2_3[运行中]
D2_2 -.->|本地构建| D2_4[Docker Build<br/>- backend<br/>- frontend]
end
subgraph DockerHost[Docker Host 服务器]
subgraph Compose[Docker Compose 编排]
subgraph Network[Docker Network app-network]
end
subgraph Frontend[Frontend 容器]
F1[Nginx]
F2[React App]
F3[Port: 80]
end
subgraph Backend[Backend 容器]
B1[Node.js]
B2[Express]
B3[Port: 5000]
end
Frontend --> Network
Backend --> Network
end
subgraph Volumes[Docker Volumes 数据持久化]
V1[db-data 数据库]
V2[uploads 头像上传]
end
end
- Docker 20.10+
- Docker Compose 2.0+
# 1. 克隆项目
git clone https://github.com/bk4ice/KidsMathQuest.git
cd KidsMathQuest
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，修改 JWT_SECRET 为强密码
# 3. 优先拉取线上镜像
docker pull bllxk/kidsmathquest-backend:latest
docker pull bllxk/kidsmathquest-frontend:latest
# 4. 一键启动
docker-compose up
# 5. 访问应用
# 家长端登录：http://localhost:3000/login
# 儿童端登录：http://localhost:3000/child-login
# 后端 API：http://localhost:5000如果你本地已经有这两个镜像，Docker 会直接使用本地镜像；如果没有，就会先尝试拉取线上镜像。
后端和前端都使用同一个根目录 .env。
cp .env.example .env
# 后端
cd backend
npm install
npx prisma db push # 第一次拉代码后先执行，创建 SQLite 文件和表结构
npm run dev
# 前端
cd ../frontend
npm install
npm run dev# 后台运行
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
# 停止并删除数据卷（谨慎使用）
docker-compose down -vcd backend
npm install
npm run dev # 启动开发服务器（带热重载）cd frontend
npm install
npm run dev # 启动 Vite 开发服务器cd backend
npx prisma db push # 首次运行或 schema 变更后同步数据库
npx prisma migrate dev # 创建迁移
npx prisma studio # 可视化数据库管理| 变量名 | 必填 | 默认值 | 说明 |
|---|---|---|---|
PORT |
否 | 5000 |
服务监听端口 |
FRONTEND_PORT |
否 | 3000 |
前端开发/容器映射端口 |
DATABASE_URL |
是 | - | SQLite 文件路径（本地建议 file:./prisma/dev.db，Docker 会覆盖为 /app/prisma/dev.db） |
JWT_SECRET |
是 | - | 必须修改！ JWT 签名密钥 |
NODE_ENV |
否 | development |
运行环境 |
- 前端不再依赖
VITE_API_BASE_URL，统一使用相对路径/api和/uploads - 本地开发时，
DATABASE_URL保持相对路径file:./prisma/dev.db，这样从backend目录启动最稳定 - Docker 会读取根目录
.env，并在docker-compose.yml中覆盖为容器内路径file:/app/prisma/dev.db - 如果你已经有现成的
backend/prisma/dev.db，直接挂载后就能继续使用
KidsMathQuest/
├── backend/ # Node.js 后端服务
│ ├── src/
│ │ ├── controllers/ # 请求控制器
│ │ ├── services/ # 业务逻辑层
│ │ ├── routes/ # 路由定义
│ │ ├── middleware/ # 中间件（认证等）
│ │ └── utils/ # 工具函数
│ ├── prisma/
│ │ ├── schema.prisma # 数据库模型定义
│ │ └── migrations/ # 数据库迁移文件
│ ├── uploads/ # 用户上传文件（头像等）
│ └── Dockerfile
│
├── frontend/ # React 前端应用
│ ├── src/
│ │ ├── components/ # 可复用 UI 组件
│ │ ├── pages/ # 页面组件
│ │ ├── contexts/ # React Context（认证等）
│ │ └── services/ # API 封装
│ ├── public/ # 静态资源（图片、字体）
│ └── Dockerfile
│
├── docker-compose.yml # Docker Compose 配置
├── .env.example # 环境变量模板
└── screenshots/ # 【截图存放目录】
前端端口修改：
编辑 docker-compose.yml，修改 frontend 服务的 ports 映射：
frontend:
ports:
- "8080:80" # 将 8080 改为你想要的端口后端端口修改：
修改 .env 文件中的 PORT 变量，同时更新 docker-compose.yml 中的端口映射：
backend:
environment:
- PORT=8000 # 修改为想要的端口
ports:
- "8000:8000"修改后需要重启服务：
docker-compose down
docker-compose up不会。数据库文件通过 Docker named volume (db-data) 持久化存储，容器重启或重建不会丢失数据。只有执行 docker-compose down -v 时才会删除数据卷。
# 备份 SQLite 数据库
docker cp kidsmathquest-backend-1:/app/data/dev.db ./backup.db
# 恢复
docker cp ./backup.db kidsmathquest-backend-1:/app/data/dev.db参考「环境变量」章节中的「使用 PostgreSQL（可选）」部分。
如果遇到类似 The column ... does not exist in the current database 的错误，说明数据库 schema 与代码不同步。
本地开发环境：
cd backend
npx prisma db pushDocker 部署环境：
# 方案1：删除旧数据库 volume（会丢失数据）
docker-compose down -v
docker-compose up
# 方案2：进入容器手动同步 schema（保留数据）
docker exec -it kidsmathquest-backend-1 npx prisma db push原因：当代码更新了数据库模型（添加/修改字段），但本地或 Docker 中的数据库文件还是旧版本时，就会出现 schema 不匹配。运行上述命令可将数据库 schema 同步到最新版本。
以下是在家长端生成并打印试卷的完整操作流程：
flowchart TD
A[登录家长端] --> B[进入试卷配置页面]
B --> C[点击新建配置]
C --> D[配置试卷参数]
D --> D1[设置运算步数]
D --> D2[设置题目数量]
D --> D3[配置每项运算类型和范围]
D --> D4[设置结果范围]
D --> D5[选择进位/退位规则]
D --> D6[设置余数规则]
D --> D7[选择是否显示答案]
D --> E[点击添加题目]
E --> F[可重复添加多次]
F --> G[保存配置]
G --> H[点击生成试卷]
H --> I[预览试卷内容]
I --> J{是否满意}
J -->|否| C
J -->|是| K[点击打印按钮]
K --> L[选择打印机]
L --> M[打印完成]
-
登录家长端
- 访问
http://localhost:3000/login - 输入家长账号和密码登录
- 访问
-
进入试卷配置页面
- 登录后进入家长端仪表盘
- 点击"试卷配置"或"生成试卷"菜单
-
新建配置
- 点击"新建配置"按钮创建新的试卷配置
- 或选择已有配置进行编辑
-
配置试卷参数
- 运算步数：选择一步、两步或三步运算
- 题目数量：设置生成的题目总数（如 20、30、45 等）
- 每项运算：配置每个运算项的数值范围和运算类型（加/减/乘/除）
- 结果范围：限制最终结果的范围
- 进位/退位：选择是否强制进位或退位
- 余数规则：对于除法运算，设置是否要求整除
- 显示答案：选择是否在试卷中显示参考答案
-
添加题目
- 配置参数后，点击"添加题目"按钮
- 系统会根据当前配置生成一份题目配置
- 可重复点击"添加题目"多次，添加多份不同的题目配置
- 点击"清空题目"可清除已添加的所有题目
- 重要：只有添加的题目才会被保存并用于儿童端练习
-
保存配置
- 点击"保存"按钮保存当前配置
- 可选：设置为"默认配置"，供儿童端每日练习使用
- 保存时会保存所有已添加的题目配置
-
生成试卷
- 点击"生成试卷"按钮
- 系统根据已添加的题目配置自动生成 A4 格式的数学试卷
-
预览和打印
- 预览试卷内容，确认无误后点击"打印"
- 选择打印机，调整打印设置（纸张大小、边距等）
- 点击确认打印
- 配置保存后可重复使用，无需每次重新设置
- 重要：配置参数后必须点击"添加题目"按钮，题目才会被保存并生效
- 可重复点击"添加题目"多次，添加多份不同的题目配置
- 儿童端练习会使用已添加的题目列表，与打印试卷使用相同的逻辑
- 打印前建议先预览，确认题目难度和数量合适
- 可以为不同年龄段的孩子保存多套配置
- 生成试卷的同时会自动保存到历史记录，方便查看
以下展示5个常见的试卷配置场景，说明在家长端的具体操作流程。
适用场景：小学一年级，练习基础加减法运算
flowchart TD
A[登录家长端] --> B[进入试卷配置页面]
B --> C[点击新建配置]
C --> D[配置参数]
D --> D1[运算步数: 一步运算]
D --> D2[题目数量: 30]
D --> D3[第1项: 1-99, 加法/减法]
D --> D4[结果范围: 0-100]
D --> D5[进位/退位: 随机]
D --> D6[余数设置: 结果整除]
D --> D7[显示答案: 否]
D --> E[点击添加题目]
E --> F[保存配置]
F --> G[生成试卷]
G --> H[预览/打印]
操作步骤：
- 进入「试卷配置」页面
- 点击「新建配置」
- 配置参数：
- 运算步数：选择「一步运算」
- 题目数量：设置为 30
- 公式配置：第1项最小值 1，最大值 99，运算符选择
+(加法)和-(减法) - 结果范围：最小值 0，最大值 100
- 进位/退位：选择「随机」（允许进位和退位）
- 余数设置：选择「结果整除」
- 是否显示答案：选择「不显示」
- 点击「添加题目」按钮（重要！）
- 点击「保存配置」
- 点击「生成试卷」即可预览或打印
生成题目示例：
45 + 23 = ?
78 - 15 = ?
56 + 34 = ?
适用场景：小学三年级，练习混合运算顺序
flowchart TD
A[进入试卷配置页面] --> B[点击新建配置]
B --> C[配置参数]
C --> C1[运算步数: 两步运算]
C --> C2[题目数量: 20]
C --> C3[启用括号: 是]
C --> C4[第1项: 1-20, 加法/减法]
C --> C5[第2项: 1-20, 乘法]
C --> C6[结果范围: 1-100]
C --> C7[进位/退位: 随机]
C --> C8[余数设置: 结果整除]
C --> D[点击添加题目]
D --> E[保存配置]
E --> F[生成试卷]
操作步骤：
- 进入「试卷配置」页面
- 点击「新建配置」
- 配置参数：
- 运算步数：选择「两步运算」
- 题目数量：设置为 20
- 启用括号：勾选「启用括号」
- 公式配置：
- 第1项：最小值 1，最大值 20，运算符选择
+(加法)和-(减法) - 第2项：最小值 1，最大值 20，运算符选择
×(乘法)
- 第1项：最小值 1，最大值 20，运算符选择
- 结果范围：最小值 1，最大值 100
- 进位/退位：选择「随机」
- 余数设置：选择「结果整除」
- 点击「添加题目」按钮（重要！）
- 点击「保存配置」
- 点击「生成试卷」
生成题目示例：
(5 + 3) × 4 = ?
(12 - 4) × 2 = ?
(6 + 7) × 3 = ?
适用场景：巩固乘法口诀
flowchart TD
A[进入试卷配置页面] --> B[点击新建配置]
B --> C[配置参数]
C --> C1[运算步数: 一步运算]
C --> C2[题目数量: 45<br/>覆盖1-9所有组合]
C --> C3[第1项: 1-9, 乘法]
C --> C4[结果范围: 1-81]
C --> C5[余数设置: 结果整除]
C --> D[点击添加题目]
D --> E[保存配置]
E --> F[生成试卷]
操作步骤：
- 进入「试卷配置」页面
- 点击「新建配置」
- 配置参数：
- 运算步数：选择「一步运算」
- 题目数量：设置为 45（覆盖 1-9 所有组合）
- 公式配置：第1项最小值 1，最大值 9，运算符选择
×(乘法) - 结果范围：最小值 1，最大值 81
- 余数设置：选择「结果整除」
- 点击「添加题目」按钮（重要！）
- 点击「保存配置」
- 点击「生成试卷」
生成题目示例：
3 × 7 = ?
8 × 6 = ?
9 × 4 = ?
适用场景：练习基础除法
flowchart TD
A[进入试卷配置页面] --> B[点击新建配置]
B --> C[配置参数]
C --> C1[运算步数: 一步运算]
C --> C2[题目数量: 30]
C --> C3[第1项: 2-81, 除法]
C --> C4[结果范围: 1-9<br/>确保商在1-9之间]
C --> C5[余数设置: 结果整除<br/>确保能整除]
C --> C6[显示答案: 是<br/>方便家长批改]
C --> D[点击添加题目]
D --> E[保存配置]
E --> F[生成试卷]
操作步骤：
- 进入「试卷配置」页面
- 点击「新建配置」
- 配置参数：
- 运算步数：选择「一步运算」
- 题目数量：设置为 30
- 公式配置：第1项最小值 2，最大值 81，运算符选择
÷(除法) - 结果范围：最小值 1，最大值 9（确保商在 1-9 之间）
- 余数设置：选择「结果整除」（确保能整除）
- 是否显示答案：选择「显示答案」（方便家长批改）
- 点击「添加题目」按钮（重要！）
- 点击「保存配置」
- 点击「生成试卷」
生成题目示例：
24 ÷ 4 = ?
45 ÷ 5 = ?
63 ÷ 7 = ?
适用场景：小学高年级，综合运算能力训练
flowchart TD
A[进入试卷配置页面] --> B[点击新建配置]
B --> C[配置参数]
C --> C1[运算步数: 三步运算]
C --> C2[题目数量: 15]
C --> C3[启用括号: 是]
C --> C4[第1项: 1-50, 加法/减法]
C --> C5[第2项: 1-10, 乘法/除法]
C --> C6[第3项: 1-20, 加法/减法]
C --> C7[结果范围: 0-200]
C --> C8[余数设置: 结果整除]
C --> C9[进位/退位: 随机]
C --> D[点击添加题目]
D --> E[保存配置]
E --> F[生成试卷]
操作步骤：
- 进入「试卷配置」页面
- 点击「新建配置」
- 配置参数：
- 运算步数：选择「三步运算」
- 题目数量：设置为 15
- 启用括号：勾选「启用括号」
- 公式配置：
- 第1项：最小值 1，最大值 50，运算符选择
+(加法)和-(减法) - 第2项：最小值 1，最大值 10，运算符选择
×(乘法)和÷(除法) - 第3项：最小值 1，最大值 20，运算符选择
+(加法)和-(减法)
- 第1项：最小值 1，最大值 50，运算符选择
- 结果范围：最小值 0，最大值 200
- 余数设置：选择「结果整除」
- 进位/退位：选择「随机」
- 点击「添加题目」按钮（重要！）
- 点击「保存配置」
- 点击「生成试卷」
生成题目示例：
12 + 5 × 3 - 8 = ?
(25 - 10) ÷ 5 + 7 = ?
8 × 4 + 15 ÷ 3 = ?
提示：配置保存后，可将其设置为「默认配置」，这样儿童端每日练习会自动使用该配置生成题目。
首次运行后，访问 http://localhost:3000/register 进入注册页面创建家长账号，登录后可在家长端添加儿童账号，即可开始使用。
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支：
git checkout -b feature/xxx - 提交更改：
git commit -m 'Add xxx' - 推送分支：
git push origin feature/xxx - 创建 Pull Request
本项目离不开以下优秀开源项目的启发与支持：
- animal-island-ui —— 本项目 UI 视觉风格的设计源泉，温暖可爱的动物森友会风格组件库，为儿童端界面提供了极大的灵感。
- PrimarySchoolMathematics —— 小学数学出题逻辑的参考实现，为本项目的试卷生成与练习题目算法提供了基础思路。
- 生产环境必须修改
JWT_SECRET，使用随机强密码 - 切勿提交
.env文件到版本控制 - 生产部署请启用 HTTPS
- 定期更新依赖以修复安全漏洞
MIT © bllxk