# API 设计（基础架构 + 业务功能）
## 1. API 设计原则
- 对外统一前缀：`/api/*`。
- 统一响应结构：`code/message/data/traceId`，其中 `code=0` 表示成功，非 0 表示业务失败。
- 认证策略：JWT + RBAC，网关做统一鉴权透传。
- API 冻结点：
  - 基础架构 API 在 M3 冻结。
  - 业务 API 在 M5 冻结。

## 2. 基础架构 API（M3）
### 2.1 认证域（auth）
- `POST /api/auth/tokens`（登录）
- `POST /api/auth/tokens/refresh`（刷新）
- `GET /api/auth/users/current`（当前用户）

### 2.2 权限与组织域（upms）
- `GET /api/upms/routes`
- `GET /api/upms/users/current`
- `GET /api/upms/areas`
- `GET /api/upms/tenants`
- `GET /api/upms/departments`

### 2.3 基础扩展 API（建议补充）
- 文件域
  - `POST /api/upms/files/upload`
  - `GET /api/upms/files/{fileId}`
- 站内消息域
  - `GET /api/upms/messages/inbox`
  - `POST /api/upms/messages/{messageId}/read`

## 3. 业务功能 API（M5）
### 3.1 课程域（course）
- `POST /api/course/courses`
- `GET /api/course/courses/{courseId}`
- `POST /api/course/courses/{courseId}/chapters`
- `POST /api/course/knowledge-points`
- `POST /api/course/chapters/{chapterId}/knowledge-relations`
- `GET /api/course/students/{studentId}/mastery`

### 3.2 习题/作业/批改域（question）
- 题库与题目
  - `POST /api/question/banks`
  - `POST /api/question/questions`
  - `POST /api/question/banks/{bankId}/questions/{questionId}`
- 试卷与作业
  - `POST /api/question/papers`
  - `POST /api/question/assignments`
  - `POST /api/question/assignments/{assignmentId}/targets`
- 提交与批改
  - `POST /api/question/submissions`
  - `POST /api/question/submissions/{submissionId}/answers`
  - `POST /api/question/grading/tasks`
  - `GET /api/question/grading/tasks/{taskId}`
- 错题与复习
  - `GET /api/question/wrong-questions`
  - `POST /api/question/review/plans/generate`
  - `POST /api/question/review/executions`

### 3.3 成就域（achievement）
- `POST /api/achievement/definitions`
- `POST /api/achievement/rules/templates`
- `GET /api/achievement/users/{userId}/records`
- `GET /api/achievement/users/{userId}/progress`
- `POST /api/achievement/events/trigger`

### 3.4 推荐域（recommendation）
- `POST /api/recommendation/tasks`
- `GET /api/recommendation/tasks/{taskId}/items`
- `POST /api/recommendation/items/{itemId}/feedback`
- `GET /api/recommendation/effects/daily`

### 3.5 AI 知识域（ai）
- `POST /api/ai/knowledge/files`
- `POST /api/ai/knowledge/files/{fileId}/sync`
- `GET /api/ai/knowledge/sync-tasks/{taskId}`
- `POST /api/ai/retrieval/query`
- `GET /api/ai/health`

## 4. API 阶段交付映射
- M3：`auth + upms + file/message 基础扩展`
- M5：`course + question + achievement + recommendation + ai`
- M6：前后端按冻结 API 完成联调，不新增破坏性变更。