sql更新、架构更新

docs/architecture/api-design.md

@@ -0,0 +1,82 @@
+# API 设计（基础架构 + 业务功能）
+## 1. API 设计原则
+- 对外统一前缀：`/api/*`。
+- 统一响应结构：`code/message/data/traceId`。
+- 认证策略：JWT + RBAC，网关做统一鉴权透传。
+- API 冻结点：
+  - 基础架构 API 在 M3 冻结。
+  - 业务 API 在 M5 冻结。
+
+## 2. 基础架构 API（M3）
+### 2.1 认证域（auth）
+- `POST /api/auth/login`
+- `POST /api/auth/refresh`
+- `GET /api/auth/current-user`
+
+### 2.2 权限与组织域（upms）
+- `GET /api/upms/routes`
+- `GET /api/upms/current-user`
+- `GET /api/upms/areas/tree`
+- `GET /api/upms/tenants/tree`
+- `GET /api/upms/depts/tree`
+
+### 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 完成联调，不新增破坏性变更。