# 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](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. 数据库

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

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

复制配置并修改：

```bash
copy backend\.env.example backend\.env
```

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

### 2. 后端（默认端口 **8010**）

```bash
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. 前端

```bash
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/CODE_STRUCTURE.md) — 代码目录与职责  
- [docs/api-contract.md](docs/api-contract.md) — 接口约定（若与 `/docs` 有差异以 OpenAPI 为准）  

## 许可证

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