CODE_STRUCTURE.md 6.7 KB
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 |