MZC/KnowMathBot

KnowMathBot（知数伴学）

面向初中数学的 Web 教学辅助系统：统一登录后，提供知识图谱、AI 数字人答疑、习题测评与个性化组卷、学情统计等模块，数据经 FastAPI 中台与 MySQL / Neo4j 互通。

技术栈

层级	技术
后端	FastAPI、SQLModel（MySQL）、Neo4j、JWT
前端	React、TypeScript、Vite、Cytoscape.js、KaTeX
大模型	DeepSeek Chat Completions（问答、规则判题兜底）
语音	GPT-SoVITS HTTP（可选）/ 浏览器 Web Speech 兜底

更细的目录与文件说明见 docs/CODE_STRUCTURE.md。

目录结构

KnowMathBot/
├── backend/          # FastAPI 服务（app/routers、integrations、utils）
├── frontend/         # React 单页应用
└── docs/             # 结构说明、接口约定等

环境要求

• Python 3.10+
• Node.js 18+（前端）
• MySQL 8+（业务数据）
• Neo4j 5+（知识图谱，可选但推荐）
• DeepSeek API Key（数字人 / 自动判题，可选）

本地运行

1. 数据库

创建空库（表由后端启动时自动创建）：

CREATE DATABASE IF NOT EXISTS knowmathbot
  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

复制配置并修改：

copy backend\.env.example backend\.env

至少配置：DATABASE_URL、JWT_SECRET_KEY、NEO4J_*；数字人需 DEEPSEEK_API_KEY（见 backend/app/core/config.py 或现有 .env）。

2. 后端（默认端口 8010）

cd backend
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8010

• 接口文档：http://localhost:8010/docs
  
• 健康检查：http://localhost:8010/health
  

3. 前端

cd frontend
npm install
npm run dev

访问：http://localhost:5173

开发代理（frontend/vite.config.ts）：/api、/health → http://localhost:8010。

4. 使用流程

1. 登录页注册教师 / 学生账号
   
2. 教师：维护知识图谱、导入习题、查看全班学情
   
3. 学生：图谱查询、数字人提问、组卷练习、查看个人学情与错题本
   

功能概览（已实现）

模块	说明
用户与鉴权	注册 / 登录、JWT、教师 / 学生角色
知识图谱	Neo4j 存储知识点、类别、递进关系；Cytoscape 预览
习题测评	建题、CSV/JSON 导入、作答、规则判题 + DeepSeek 兜底、错题本
个性化组卷	topic_weight（按知识点 + 错题权重）、personalized（错题优先）
数字人	多轮会话、例题从题库抽取、DeepSeek 讲解、可选 TTS
学情统计	个人 / 全班正确率、按年级·类别·知识点 breakdown

说明：当前为 Prompt + 题库检索 + 图谱结构化查询，未使用向量 RAG。

相关文档

• docs/CODE_STRUCTURE.md — 代码目录与职责
  
• docs/api-contract.md — 接口约定（若与 /docs 有差异以 OpenAPI 为准）
  

许可证

毕业设计项目，按学校/指导教师要求使用。