MZC/KnowMathBot/docs/api-contract.md

API 契约（集成中台对外接口）

基地址：/api/v1

鉴权：除公开接口外，均需 HTTP Header：

• Authorization: Bearer <access_token>

1) 鉴权与用户

• POST /auth/register
  • body：{username, password, role}
  • resp：用户公开信息
• POST /auth/token
  • form：username, password
  • resp：{access_token, token_type}
• GET /users/me
  • resp：当前用户

2) 知识图谱（占位对接）

• GET /knowledge-graph/knowledge/{knowledge_code}
  • resp：知识点信息（后续可扩展相关节点、关系、例题）
• POST /knowledge-graph/knowledge/{knowledge_code}?name=...（teacher）
  • 作用：写入/更新知识点（演示用）

3) AI 数字人答疑（占位对接）

• POST /digital-human/ask
  • body：{session_id?, question, knowledge_code?}
  • resp：{session_id, answer, sources[]}

4) 个性化推荐（占位对接）

• POST /recommendation/recommend
  • body：{knowledge_code?, limit}
  • resp：{items: [{item_type, item_ref, reason?}]}

5) 习题测评（可联调）

• POST /assessment/exercises（teacher）
  • body：{title, body, knowledge_code?, difficulty?}
  • resp：exercise
• GET /assessment/exercises?knowledge_code=...
  • resp：exercise 列表
• POST /assessment/exercises/{exercise_id}/attempts
  • body：{answer}
  • resp：attempt（当前判分占位，支持后续回填）
• GET /assessment/attempts/me

6) 学情统计（可联调）

• GET /learning-analytics/me
  • resp：{attempts_total, correct_total, accuracy}

OpenAPI

启动后在 http://localhost:8000/docs 查看完整可交互接口文档（可直接用于前后端联调）。