mula
/
nex_math
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nex_math/README.md

14 KiB
Raw Blame History

数学学习系统（前后端分离版）

把原单文件静态页 math_learning_dashboard_v3.html 重构为可运行的前后端分离系统， 前端采用 Ant Design，包含用户体系与标准 RBAC。 页面结构、题库与学习流程在此基础上重设计：知识点以“初等/高等数学知识图谱” 为全局地基，章节与题目通过关系表挂到图谱节点，不再使用文本标签匹配。 学习状态从浏览器 localStorage 改为 SQLite 持久化；教材目录以 《盖尔范德中学生数学思维丛书》为基础，并支持大模型配置与按章节生成题目。

技术栈

  • 后端：FastAPI + SQLAlchemy + SQLite
  • 前端：React + TypeScript + Vite + Ant Design
  • 公式渲染：KaTeX（支持 $...$ / $$...$$ 与 Markdown 插图）
  • 认证：JWT（HS256）+ PBKDF2 密码散列
  • RBAC：user / role / user_role / permission / role_permission
  • 部署：支持本机直接运行或 docker compose

目录结构

nex_math/
├── backend/          # FastAPI 应用
│   ├── main.py       # 入口（CORS、路由注册）
│   ├── database.py   # SQLite 连接与默认库路径
│   ├── models/       # ORM：教材 / 章节 / 知识点 / 题目 / 记录 / 错题 / 模型配置
│   ├── schemas/      # Pydantic 请求响应模型
│   ├── routers/      # overview / practice / data / analytics / archive / catalog / question-bank / llm
│   ├── services/     # llm_client / question_generator / ai_teacher / question_engine / mastery_engine / recommendation
│   └── seed/         # 目录与题库种子数据
├── frontend/         # Vite + React 前端
│   └── src/
│       ├── pages/    # 九个页面
│       ├── components/
│       ├── api/      # API 客户端
│       └── types/
├── data/math.db      # SQLite 数据库（首次初始化后生成）
└── scripts/          # init.sh / start.sh

界面与导航

  • 左侧菜单栏支持展开 / 收拢两种模式：底部“收拢菜单”按钮或顶栏折叠按钮 一键切换，偏好写入 localStorage 下次进入自动恢复；收拢态只显示图标， 悬停出现文字提示，功能分组以分隔线保留。
  • 窄屏（<768px）自动切换为覆盖式抽屉导航，顶栏汉堡按钮开合，不再挤压内容区。
  • 顶栏统一展示“分区 · 页面说明”、角色标识与头像菜单（设置 / 退出登录）， 与侧栏底部用户卡片入口一致。
  • 全站样式与控件收敛到三层：theme.ts（设计令牌）→ ui.tsx（Page / Panel / Toolbar / DataTable / RowActions / MetricGrid / CountTag / EmptyState 等） → 页面，新页面只组合统一控件，不各写一套尺寸与颜色。

快速开始（本机）

要求：Python 3.10+（推荐使用 uv）、Node.js 18+。

./scripts/init.sh     # 创建虚拟环境、安装依赖、写入种子数据
./scripts/start.sh    # 同时启动后端 :8000 与前端 :5173

打开 http://localhost:5173。

默认账号：

账号 密码 角色 说明
admin admin123 管理员 用户、模型、教材课程、题库管理
student student123 普通用户 学习总览、练习、错题、分析等

首次登录后请通过左侧栏底部用户卡片的“个人设置”修改默认密码， 并在生产环境设置 JWT_SECRET（环境变量）。管理员可在“模型配置”维护多通道模型。 管理员是纯管理账号：不创建学习档案，学习总览/知识地图等学习功能不展示， 学习类接口对管理员返回无权限。

快速开始（Docker）

docker compose up --build

前端 http://localhost:5173，后端文档 http://localhost:8000/docs。 数据库会以卷形式挂载在宿主机的 ./data/math.db。

热加载

  • 前端：Vite 开发服务器自带 HMR，保存代码页面即时更新；
  • 后端：./scripts/start.sh 与 docker compose 均以 uvicorn --reload 启动，Python 代码变更自动重载。

功能对照

静态版模块 新系统位置 说明
学习总览 / 学习总览 指标卡 + 掌握度 + 推荐计划
知识地图 知识地图 知识点掌握度；点击卡片查看定义、掌握度、相关知识点，以及讲了它的教材章节与视频课程（可一键进入本章测试）
章节测试 章节测试 选书→选章→按掌握度动态抽取 5 题，可“换一套”；唯一的组卷与练习入口
错题本 错题本 记录每道错题的题干、你的错误回答、正确答案与解析
练习记录 练习记录 展开记录可回看每题作答与详细解析
今日任务 今日任务 推荐今日章节 → 做章节测试 → 对章节提交掌握反馈
学习分析 学习分析 正确率、错题、诊断排序
导出 / 导入档案 个人设置 → 学习档案 /api/archive/export、/api/archive/import
教材 / 课程 教材 / 课程 盖尔范德丛书书目（ISBN）+ 在线课程链接
教材详情 点击教材卡片 查看章节目录、每章知识点、题目数量并直接开始本章测试
题库管理 题库管理 列出/筛选/删除题目，按教材章节调用模型生成
模型配置 模型配置 多通道模型配置、通道命名、默认通道与连通测试
用户管理 用户管理（管理员） 创建用户、启停账号、切换角色、重置密码
个人设置 左侧栏底部用户卡片 → 个人设置（主内容区整页） 修改昵称/密码，导出与导入学习档案
教材课程管理 教材课程管理（管理员） 教材/课程维护；章节可新增/编辑/删除，也可按教材 AI 自动生成目录，章节可直接跳转到对应题库
题库生成 题库管理 先选教材，再选章节与数量，按章节调用大模型生成新题

学习数据（掌握度、练习记录、错题、每日完成）按用户隔离，同一账号的数据互相独立。 练习提交时会保存每题题目快照与作答（错误选项、正确答案、解析），因此题库后续 删题也不影响错题本与练习记录的逐题回看；所有明细均归属当前用户，用户之间不可见。

RBAC 权限

权限码 说明 管理员 普通用户
learning:use 学习总览/练习/错题/分析/档案 ✘ ✔
users:manage 用户管理 ✔ ✘
llm:manage 模型配置 ✔ ✘
catalog:manage 教材/课程管理 ✔ ✘
question-bank:manage 题库管理与生成 ✔ ✘
knowledge:manage 知识图谱管理 ✔ ✘

除登录、健康检查外，所有 /api/* 接口都要求 Authorization: Bearer <token>； 管理接口在后端通过权限依赖二次校验（backend/dependencies.py）。

知识点状态由掌握度自动计算：≥85 已掌握、75–84 基本掌握、60–74 待加强、<60 重点。

教材目录

当前教材基线为《盖尔范德中学生数学思维丛书》（中国科学技术大学出版社）：

分册 ISBN
函数和图像（主教材，已挂章节与题库） 978-7-312-05005-3
代数 978-7-312-04893-7
三角函数 978-7-312-04695-7
坐标方法 978-7-312-05006-0
几何 978-7-312-05779-3

《函数和图像》的章节（引言、第1章 例子 … 第7章 有理函数）已写入数据库， 可据此按章节生成新题；其余分册目录可在 backend/seed/catalog.py 中扩充后重启生效 （幂等同步，不清空学习记录）。

模型配置与题目生成

  1. 打开“模型配置”→“新增通道”，选择 OpenAI / DeepSeek / 阿里千问（百炼）/ OpenAI 兼容；通道名称建议按“服务商 · 模型”填写（例如“阿里千问 · qwen-plus”）， 系统会随服务商选择自动带出默认 Base URL 与模型名。
  2. 填写 API Key 并点击该通道的“测试”；Key 仅保存在本地 data/math.db， 回显只显示末四位。可新增多个通道并用“设为默认”指定生成题目时使用的通道。
  3. 打开“题库管理”，选择教材、章节、数量、难度、该章节知识点（可多选）与 生成使用的模型通道（默认取“默认通道”）， 点击“开始生成”。返回结果会做 JSON 结构校验（4 个选项、唯一答案、非空题干）后 入库并挂到所选教材章节下，可在该章“章节测试”中直接使用；题库页支持筛选与删除。

大模型调用统一走 OpenAI Chat Completions 协议（services/llm_client.py）， 不需要额外 SDK；生成的题若带新知识点，首次作答会自动建立该知识点并参与掌握度计算。 生成提示词要求模型把数学公式写成 LaTeX（$...$ 或 $$...$$）、插图写成 ![图注](图片地址)；题库、练习、错题本与练习记录中的题目内容均由前端 KaTeX 渲染公式并展示图片。

教材章节的 AI 生成与题库跳转

在“教材课程管理”中打开某本教材的“章节”抽屉后：

  1. “添加章节”仍可手动输入名称与内容提示；
  2. “AI 生成章节”按钮位于“添加章节”之后；无需选择数量，选择模型通道与可选说明后， 系统会先查找内置官方目录（函数与图像、三角函数、坐标方法、几何等正式章节）， 再按 ISBN 查询 Open Library / Google Books；查到正式目录时直接按正式章节补齐， 不会让模型自由发挥；如果无法核实正式目录，接口会明确拒绝生成并提示手动添加， 避免产生与原书无关的章节。新章节入库后可继续编辑或删除；
  3. 每个章节行都有“题库”入口，点击后跳转到题库管理并自动筛选该书与章节。

题库管理每道题会标注“使用状态”（已使用次数 / 未使用）。使用过的题目和被 章节挂载的题目不允许删除，只能编辑；题目编辑会保留历史答题快照。

AI 出题配图机制（自动生成，不使用图库/上传）

生成新题弹窗中有一个“需要配图（AI 根据题目自动生成图像）”开关：

  • 不勾选：题目正常生成，不携带图像；
  • 勾选后：提示词要求模型为这道题生成与题目语义一致的原创 SVG（函数图/几何示意图， 含坐标轴与关键标注），模型把它放在 JSON 的 image_svg 字段；
  • 后端把每张 SVG 独立保存为 /api/question-images/generated_*.svg 并自动写入题干， 因此每道题都有自己独立的图，互不共享。

知识点与章节、多知识点

  • 每个章节可维护多个“本章知识点”（教材课程管理 → 章节 → 编辑）；
  • 生成新题先选教材和章节后，知识点下拉自动展示该章节的知识点，可多选；
  • 题目支持多个知识点：列表、练习记录、错题、掌握度与推荐都会按全部知识点统计；
  • 练习提交时如果出现未见过的新知识点，会自动为用户建立并参与掌握度计算。

主要 API

所有接口前缀 /api，交互文档见 http://localhost:8000/docs。

方法 路径 说明
GET /overview 学习总览指标与推荐计划
GET /knowledge 知识点掌握度
GET /knowledge/detail/{id} 知识点详情：定义、相关知识点、关联章节与视频资源
POST/DELETE /knowledge/nodes/{id}/resources、/knowledge/resources/{id} 知识点关联视频/课程（管理员）
GET /practice/chapter/{id} 章节测试组卷（不含答案）
POST /practice/submit 提交答案并判分、更新掌握度与错题
GET/POST /daily、/daily/complete 今日完成状态
GET /errors、/records、/records/{id}、/analytics 错题（含逐题详情）、记录、记录详情、分析
GET/POST /archive/export、/archive/import 学习档案导出 / 恢复
GET /textbooks 教材/课程目录（含章节，登录可用）
POST/PUT/DELETE /textbooks 与 /textbooks/{id} 教材/课程增删改（管理员）
POST/PUT/DELETE /textbooks/.../chapters 章节管理（管理员）
POST /textbooks/{id}/chapters/generate 按教材 AI 生成章节（管理员）
GET/POST/PUT/DELETE /question-bank/questions、…/generate 题库管理：列表/生成/编辑/删除（管理员），已使用题禁止删除
GET /llm/settings 模型通道列表与服务商预设（管理员）
POST/PUT/DELETE /llm/channels 与 /llm/channels/{id} 模型通道增删改（管理员）
PUT /llm/channels/{id}/default 设置默认通道（管理员）
POST /llm/channels/{id}/test、/llm/test 通道连通测试（管理员）
PUT /auth/profile 修改自己的用户昵称
POST /auth/login、/auth/change-password 登录、修改自己的密码
GET /auth/me 当前用户与角色
GET/POST/PUT /users、/users/{id}、/users/roles 用户管理（管理员）

配置

复制 .env.example 并按需修改（本机直接运行时使用环境变量）：

  • DATABASE_URL：留空默认使用 <项目根>/data/math.db
  • CORS_ORIGINS：允许访问的前端地址
  • OPENAI_API_KEY：可选。数据库还没有任何模型通道时，启动会自动创建 “OpenAI · gpt-4o-mini”默认通道并使用该 Key； ai_teacher.py 的逐题讲解仍为本地规则实现
  • JWT_SECRET：JWT 签名密钥，生产环境必须设置

重置演示数据

cd backend
.venv/bin/python -m seed --force

会清空全部用户的学习数据与题库（含 AI 生成题）并重新写入种子数据； 用户、角色、教材目录与模型配置保留。演示账号的学习历史（练习记录、错题本） 现在包含逐题明细，可直接展开查看每题作答。