## 总体目标

面向**初中数学**，将「知识图谱、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）