MZC/KnowMathBot/docs/architecture.md

总体目标

面向初中数学，将「知识图谱、AI 数字人答疑、个性化推荐、用户管理、习题测评、学情统计」模块进行集成与接口对接，实现：

• 统一身份与权限（学生/教师）
• 统一数据标识（知识点编码、题目 ID、会话 ID、用户 ID）
• 统一对外 API（前端/第三方模块只对接一个入口）
• 跨模块数据互通（测评→学情→推荐；问答→知识点→推荐 等）

架构形态（推荐落地）

采用“集成中台 API（单体可演进） + 模块适配器”：

• 集成中台（本项目 backend/）：
  • 统一鉴权与用户管理
  • 统一 API 网关入口（后续可拆成独立网关）
  • 统一数据模型与日志（问答日志、测评记录、推荐结果）
  • 对外暴露稳定的 REST API（OpenAPI 文档）
• 外部模块（可为独立服务/已有系统）：
  • 知识图谱（Neo4j/GraphDB/自建）
  • 数字人（LLM + RAG + TTS/ASR + Avatar 渲染）
  • 推荐（规则/ML/LLM）
  • 判题（规则判分/步骤评分/LLM judge）
  • 统计（OLAP/报表服务）

先做成单体后端的好处：开发/答辩演示最稳；后期需要时，再把各模块路由/适配器拆微服务。

关键数据流（跨模块协同）

• 测评闭环：学生作答 → 测评模块产出 attempt（判分/错因）→ 学情统计聚合（知识点掌握度）→ 推荐模块推送巩固练习/知识点 → 数字人讲解错题
• 问答闭环：学生提问 → 数字人答疑记录 session/messages →（可选）知识点识别 knowledge_code → 学情统计记录“疑难点” → 推荐推送讲解/练习

统一鉴权与权限模型

• JWT：前端登录获取 access_token，后续带 Authorization: Bearer <token>
• 角色：teacher / student
• 权限：
  • 题目创建、知识点维护：teacher
  • 学生个人数据：仅本人（或教师端按班级扩展）

统一标识规范（跨模块对接核心）

• user_id：UUID（中台统一发号）
• knowledge_code：字符串编码（推荐使用稳定编码，如 J7-FUNC-001）
• exercise_id：UUID（中台题库可托管，或映射外部题库 ID）
• session_id：UUID（问答会话）

对接方式

• 同步接口（REST）：适用于查询/提交/获取结果
• 异步事件（可选）：测评完成、推荐生成等可发布事件（后期可上 Redis Stream / RabbitMQ / Kafka）