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`