## 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` 查看完整可交互接口文档（可直接用于前后端联调）。