K12Study/docs/architecture/api-design.md

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 完成联调，不新增破坏性变更。