2026-04-16 15:46:29 +08:00
|
|
|
|
# API 设计（基础架构 + 业务功能）
|
|
|
|
|
|
## 1. API 设计原则
|
|
|
|
|
|
- 对外统一前缀：`/api/*`。
|
2026-04-16 18:12:09 +08:00
|
|
|
|
- 统一响应结构：`code/message/data/traceId`，其中 `code=0` 表示成功，非 0 表示业务失败。
|
2026-04-16 15:46:29 +08:00
|
|
|
|
- 认证策略：JWT + RBAC，网关做统一鉴权透传。
|
|
|
|
|
|
- API 冻结点：
|
|
|
|
|
|
- 基础架构 API 在 M3 冻结。
|
|
|
|
|
|
- 业务 API 在 M5 冻结。
|
|
|
|
|
|
|
|
|
|
|
|
## 2. 基础架构 API（M3）
|
|
|
|
|
|
### 2.1 认证域（auth）
|
2026-04-16 18:12:09 +08:00
|
|
|
|
- `POST /api/auth/tokens`（登录）
|
|
|
|
|
|
- `POST /api/auth/tokens/refresh`（刷新）
|
|
|
|
|
|
- `GET /api/auth/users/current`（当前用户）
|
2026-04-16 15:46:29 +08:00
|
|
|
|
|
|
|
|
|
|
### 2.2 权限与组织域（upms）
|
|
|
|
|
|
- `GET /api/upms/routes`
|
2026-04-16 18:12:09 +08:00
|
|
|
|
- `GET /api/upms/users/current`
|
|
|
|
|
|
- `GET /api/upms/areas`
|
|
|
|
|
|
- `GET /api/upms/tenants`
|
|
|
|
|
|
- `GET /api/upms/departments`
|
2026-04-16 15:46:29 +08:00
|
|
|
|
|
|
|
|
|
|
### 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 完成联调，不新增破坏性变更。
|
