MZC/KnowMathBot/docs/data-contract.md

跨模块数据契约（核心字段）

1) 用户（User）

• user_id：UUID（中台统一）
• username：登录名（唯一）
• role：teacher | student

2) 知识点（KnowledgePoint）

• knowledge_code：字符串（跨模块稳定主键，强烈建议人工规划编码体系）
• name：知识点名称（如“一元一次方程”）
• grade：junior（可扩展七/八/九年级）

3) 题目（Exercise）

• exercise_id：UUID（中台题库）或外部题库 ID 映射
• title/body：题干
• knowledge_code：题目关联的知识点编码
• difficulty：1-5（可选）

4) 作答记录（Attempt）

• attempt_id：UUID
• user_id
• exercise_id
• answer：学生答案（文本/LaTeX）
• is_correct / score：判题结果（可空，支持异步回填）
• created_at

5) 数字人问答（Chat）

• session_id：UUID
• user_id
• messages[]：{sender: "user"|"assistant", content, created_at}
• knowledge_code：可选（用于统计与推荐）

6) 推荐（Recommendation）

• item_type：exercise | knowledge | lesson
• item_ref：外部引用（exercise_id / knowledge_code / lesson_id 等）
• reason：推荐原因（可选）

事件规范（可选，便于异步解耦）

当前实现先走 REST；后续上消息队列时可直接沿用这些事件结构。

• attempt.submitted
  • attempt_id, user_id, exercise_id, knowledge_code?, answer, created_at
• attempt.graded
  • attempt_id, is_correct, score, rubric?, feedback?
• chat.asked
  • session_id, user_id, question, knowledge_code?, created_at
• chat.answered
  • session_id, answer, sources[]
• recommendation.generated
  • user_id, items[]