# KnowMathBot（知数伴学）代码目录与功能对照

> 本文档说明项目主要目录、文件及其承担的职责，便于答辩、维护与二次开发。

## 一、项目顶层结构

| 路径 | 类型 | 功能说明 |
|------|------|----------|
| `backend/` | 后端工程 | Python + FastAPI 服务、数据库访问、业务 API |
| `frontend/` | 前端工程 | React + TypeScript 单页应用 |
| `docs/` | 文档 | 代码结构说明、论文插图等辅助材料 |

---

## 二、后端（`backend/`）

| 路径 | 功能说明 |
|------|----------|
| `requirements.txt` | Python 依赖清单（FastAPI、SQLModel、Neo4j 驱动等） |
| `.env` | 运行配置（数据库 URL、JWT、Neo4j、大模型 API 等，勿提交密钥） |
| `app/main.py` | **应用入口**：创建 FastAPI 实例、启动时初始化数据库、挂载各业务路由、健康检查 |
| `app/db.py` | **数据库连接**：SQLModel 引擎、建表、轻量迁移、会话 `get_session` |
| `app/deps.py` | **依赖注入**：解析 JWT、获取当前用户、角色权限校验 |
| `app/models.py` | **ORM 实体**：用户、习题、作答、错题、会话、推荐、模块登记等表结构 |
| `app/schemas.py` | **API 模型**：请求/响应的 Pydantic 结构（与前端 TypeScript 类型对应） |

### `app/core/` 核心配置与安全

| 路径 | 功能说明 |
|------|----------|
| `core/config.py` | 从 `.env` 加载应用名、API 前缀、JWT、MySQL、Neo4j、TTS、DeepSeek 等配置 |
| `core/security.py` | 密码哈希/校验、JWT 签发与解析 |

### `app/routers/` 业务接口（均挂载在 `/api/v1`）

| 路径 | 功能说明 | 主要接口示例 |
|------|----------|----------------|
| `routers/auth.py` | **认证**：用户注册、登录颁发 Token | `POST /auth/register`, `POST /auth/token` |
| `routers/users.py` | **用户**：当前登录用户信息 | `GET /users/me` |
| `routers/knowledge_graph.py` | **知识图谱**：目录/知识点查询与维护、习题批量导入、前置关系 | `GET /catalog`, `GET/POST /knowledge/{code}`, `POST /exercises/import` |
| `routers/assessment.py` | **题库与测评**：习题 CRUD、作答提交、规则+模型判题、权重与错题 | `GET/POST /exercises`, `POST /exercises/{id}/attempts` |
| `routers/recommendation.py` | **个性化推荐**：按知识点或错题优先组卷 | `POST /recommendation/recommend` |
| `routers/digital_human.py` | **数字人**：多轮问答、语音资源、大模型与 TTS | `POST /digital-human/ask`, 语音资源 CRUD |
| `routers/learning_analytics.py` | **学情分析**：个人/全班统计、知识点维度 breakdown、错题本 | `GET /learning-analytics/me`, `/me/knowledge-breakdown` |
| `routers/modules.py` | **模块登记**：子服务地址与启用状态（扩展集成） | `GET/POST /modules` |

### `app/integrations/` 外部集成

| 路径 | 功能说明 |
|------|----------|
| `integrations/neo4j.py` | Neo4j 客户端封装：约束、知识点 MERGE、目录查询、前置边维护 |

### `app/data/` 静态数据

| 路径 | 功能说明 |
|------|----------|
| `data/knowledge_catalog.py` | 默认初中数学知识点目录（与 `frontend/src/data/knowledgeCatalog.ts` 一致） |

### `app/utils/` 公共工具

| 路径 | 功能说明 |
|------|----------|
| `utils/knowledge_codes.py` | 知识点编码解析（多值分隔、族前缀） |
| `utils/exercise_knowledge.py` | 习题与知识点匹配、组卷范围过滤 |
| `utils/exercise_constants.py` | 习题常量（如解析占位「暂无」） |
| `utils/neo4j_exercise.py` | 从 Neo4j 回填习题年级/类别/知识点名 |

### `storage/`（运行时，可选）

| 路径 | 功能说明 |
|------|----------|
| `storage/voice_assets/` | 数字人语音资源文件 |
| `storage/tts/` | 本地 TTS 模型文件（可选） |

---

## 三、前端（`frontend/`）

| 路径 | 功能说明 |
|------|----------|
| `package.json` | 前端依赖与脚本（dev/build） |
| `vite.config.ts` | Vite 配置：开发端口 5173、`/api` 代理到后端 8010 |
| `index.html` | SPA 入口 HTML |

### `src/` 源码

| 路径 | 功能说明 |
|------|----------|
| `main.tsx` | React 挂载根节点，启用路由 |
| `styles.css` | 全局样式（布局、按钮、卡片、表格等） |
| `lib/api.ts` | **后端 API 封装**：类型定义、`fetch`、各模块请求函数 |
| `lib/storage.ts` | 本地存储 JWT Token |
| `data/knowledgeCatalog.ts` | 前端默认知识点目录（Neo4j 不可用时的兜底） |
| `types/cytoscape-cose-bilkent.d.ts` | Cytoscape 布局插件的 TypeScript 声明 |

### `src/routes/` 页面路由

| 路径 | 功能说明 |
|------|----------|
| `routes/App.tsx` | 路由表、登录鉴权包裹 `RequireAuth` |
| `routes/Layout.tsx` | 主导航布局（顶栏、模块入口） |
| `routes/LoginPage.tsx` | 登录 / 注册 |
| `routes/KnowledgePage.tsx` | **知识图谱**：目录、维护、Cytoscape 预览 |
| `routes/AssessmentPage.tsx` | **习题测评**：组卷、作答、教师建题与导入 |
| `routes/DigitalHumanPage.tsx` | **数字人**：对话、Live2D、语音 |
| `routes/AnalyticsPage.tsx` | 学情入口，按角色跳转学生/教师页 |
| `routes/StudentAnalyticsPage.tsx` | **学生学情**：总览、多维度图表、错题本 |
| `routes/TeacherAnalyticsPage.tsx` | **教师学情**：全班统计、错题汇总 |
| `routes/ModulesPage.tsx` | 模块服务登记管理 |

### `src/components/` 可复用组件

| 路径 | 功能说明 |
|------|----------|
| `components/BreakdownCharts.tsx` | 学情 breakdown 的条形图/折线图/饼图（SVG） |

### `dist/`（构建产物）

| 路径 | 功能说明 |
|------|----------|
| `dist/` | `npm run build` 生成的静态文件，可部署到 Nginx 等 |

---

## 四、模块与代码对应关系（速查）

| 业务模块 | 后端路由文件 | 前端页面 |
|----------|--------------|----------|
| 认证与用户 | `auth.py`, `users.py` | `LoginPage.tsx` |
| 知识图谱 | `knowledge_graph.py` + `neo4j.py` | `KnowledgePage.tsx` |
| 题库与测评 | `assessment.py` | `AssessmentPage.tsx` |
| 个性化推荐 | `recommendation.py` | `AssessmentPage.tsx`（组卷按钮） |
| 数字人答疑 | `digital_human.py` | `DigitalHumanPage.tsx` |
| 学情分析 | `learning_analytics.py` | `StudentAnalyticsPage.tsx`, `TeacherAnalyticsPage.tsx` |
| 模块登记 | `modules.py` | `ModulesPage.tsx` |

---

## 五、数据存储对照

| 数据 | 存储位置 | 主要代码 |
|------|----------|----------|
| 用户、习题、作答、错题、会话等 | MySQL（或配置的 SQL 库） | `models.py`, `db.py`, 各 `routers/*.py` |
| 知识点与关系 | Neo4j | `integrations/neo4j.py`, `knowledge_graph.py` |
| 登录态 Token | 浏览器 localStorage | `storage.ts`, `deps.py` |