Nexus_Edu/API_BCK.md

# API接口文档

## 考试相关API

### 1. 考试列表
**前端组件**: `ExamList` (src/features/exam/components/ExamList.tsx)
**API调用**: `examService.getMyExams()`
**后端文件**: `exam.controller.ts` -> `getExams`
**后端路由**: `exam.routes.ts` -> `GET /api/exams`
**参数**: 无
**返回数据**: 
- items: 考试列表
- totalCount: 总数
- pageIndex: 页码
- pageSize: 页大小

### 2. 获取考试详情
**前端组件**: `ExamEditor` (src/features/exam/components/ExamEditor.tsx)
**API调用**: `examService.getExamDetail(examId)`
**后端文件**: `exam.controller.ts` -> `getExamDetail`
**后端路由**: `exam.routes.ts` -> `GET /api/exams/:id`
**参数**: examId (路径参数)
**返回数据**: 考试详细信息，包括树形结构

### 3. 保存考试
**前端组件**: `ExamEditor` (src/features/exam/components/ExamEditor.tsx)
**API调用**: `examService.saveExam(exam)`
**后端文件**: `exam.controller.ts` -> `updateExamStructure` / `createExam`
**后端路由**: `exam.routes.ts` -> `POST /api/exams` / `PUT /api/exams/:id/structure`
**参数**: 
- subjectId: 科目ID
- title: 标题
- suggestedDuration: 建议时长
- rootNodes: 树形结构
- id: 考试ID（更新时需要）

### 4. 获取考试统计
**前端组件**: `ExamStats` (src/features/exam/components/ExamStats.tsx)
**API调用**: `examService.getStats(examId)`
**后端文件**: `analytics.controller.ts` -> `getScoreDistribution`
**后端路由**: `analytics.routes.ts` -> `GET /analytics/distribution`
**参数**: examId (路径参数)
**返回数据**: 
- averageScore: 平均分
- passRate: 及格率
- maxScore: 最高分
- minScore: 最低分
- scoreDistribution: 分数分布
- wrongQuestions: 错题列表

## 认证相关API

### 1. 用户登录
**前端组件**: `LoginForm` (src/features/auth/components/LoginForm.tsx)
**API调用**: `authService.login(username)`
**后端文件**: `auth.controller.ts` -> `login`
**后端路由**: `auth.routes.ts` -> `POST /api/auth/login`
**参数**: username (邮箱或手机号)
**返回数据**: 
- token: 认证令牌
- user: 用户信息

### 2. 获取用户信息
**前端组件**: 多个组件使用
**API调用**: `authService.me()`
**后端文件**: `auth.controller.ts` -> `me`
**后端路由**: `auth.routes.ts` -> `GET /api/auth/me`
**参数**: 无
**返回数据**: 用户详细信息

### 3. 更新用户资料
**前端组件**: `ProfileSettings` (src/features/settings/components/ProfileSettings.tsx)
**API调用**: `authService.updateProfile(data)`
**后端文件**: `auth.controller.ts` -> `updateProfile`
**后端路由**: `auth.routes.ts` -> `PUT /api/auth/profile`
**参数**: 
- name: 姓名
- email: 邮箱
- phone: 手机号
- avatar: 头像

### 4. 修改密码
**前端组件**: `SecuritySettings` (src/features/settings/components/SecuritySettings.tsx)
**API调用**: `authService.changePassword(data)`
**后端文件**: `auth.controller.ts` -> `changePassword`
**后端路由**: `auth.routes.ts` -> `PUT /api/auth/change-password`
**参数**: 
- oldPassword: 旧密码
- newPassword: 新密码

## 组织/班级相关API

### 1. 获取班级列表
**前端组件**: `ClassCard` (src/features/class/components/ClassCard.tsx)
**API调用**: `orgService.getClasses(role)`
**后端文件**: `org.controller.ts` -> `getClasses`
**后端路由**: `org.routes.ts` -> `GET /api/org/classes`
**参数**: role (可选，角色过滤)
**返回数据**: 班级列表

### 2. 获取班级成员
**前端组件**: `ClassSettings` (src/features/class/components/ClassSettings.tsx)
**API调用**: `orgService.getClassMembers(classId)`
**后端文件**: `org.controller.ts` -> `getClassMembers`
**后端路由**: `org.routes.ts` -> `GET /api/org/classes/:classId/members`
**参数**: classId (路径参数)
**返回数据**: 班级成员列表

### 3. 加入班级
**前端组件**: `JoinClassModal` (src/features/class/components/JoinClassModal.tsx)
**API调用**: `orgService.joinClass(inviteCode)`
**后端文件**: `org.controller.ts` -> `joinClass`
**后端路由**: `org.routes.ts` -> `POST /api/org/classes/join`
**参数**: inviteCode (邀请码)
**返回数据**: 操作结果

### 4. 创建班级
**前端组件**: `CreateClassModal` (src/features/class/components/CreateClassModal.tsx)
**API调用**: `orgService.createClass(data)`
**后端文件**: `org.controller.ts` -> `createClass`
**后端路由**: `org.routes.ts` -> `POST /api/org/classes`
**参数**: 
- name: 班级名称
- description: 班级描述
- grade: 年级
- subject: 科目

## 题库相关API

### 1. 搜索题目
**前端组件**: `QuestionCard` (src/features/question/components/QuestionCard.tsx)
**API调用**: `questionService.search(filter)`
**后端文件**: `question.controller.ts` -> `search`
**后端路由**: `question.routes.ts` -> `POST /api/questions/search`
**参数**: 
- subjectId: 科目ID
- difficulty: 难度
- type: 题型
- keyword: 关键词
**返回数据**: 题目列表

### 2. 解析文本
**前端组件**: `ImportModal` (src/features/exam/components/ImportModal.tsx)
**API调用**: `questionService.parseText(rawText)`
**后端文件**: `question.controller.ts` -> `parseText`
**后端路由**: `question.routes.ts` -> `POST /api/questions/parse-text`
**参数**: text (原始文本)
**返回数据**: 解析后的题目列表

### 3. 创建题目
**前端组件**: `QuestionModal` (src/features/question/components/QuestionModal.tsx)
**API调用**: `questionService.create(data)`
**后端文件**: `question.controller.ts` -> `create`
**后端路由**: `question.routes.ts` -> `POST /api/questions`
**参数**: 
- content: 题目内容
- type: 题型
- difficulty: 难度
- answer: 答案
- explanation: 解析
- knowledgePoints: 知识点

### 4. 更新题目
**前端组件**: `QuestionModal` (src/features/question/components/QuestionModal.tsx)
**API调用**: `questionService.update(id, data)`
**后端文件**: `question.controller.ts` -> `update`
**后端路由**: `question.routes.ts` -> `PUT /api/questions/:id`
**参数**: 
- id: 题目ID
- content: 题目内容
- type: 题型
- difficulty: 难度
- answer: 答案
- explanation: 解析
- knowledgePoints: 知识点

### 5. 删除题目
**前端组件**: `QuestionModal` (src/features/question/components/QuestionModal.tsx)
**API调用**: `questionService.delete(id)`
**后端文件**: `question.controller.ts` -> `delete`
**后端路由**: `question.routes.ts` -> `DELETE /api/questions/:id`
**参数**: id (路径参数)
**返回数据**: 操作结果

## 作业相关API

### 1. 获取教师作业列表
**前端组件**: `TeacherAssignmentList` (src/features/assignment/components/TeacherAssignmentList.tsx)
**API调用**: `assignmentService.getTeachingAssignments()`
**后端文件**: `assignment.controller.ts` -> `getTeachingAssignments`
**后端路由**: `assignment.routes.ts` -> `GET /api/assignments/teaching`
**参数**: 无
**返回数据**: 教师作业列表

### 2. 获取学生作业列表
**前端组件**: `StudentAssignmentList` (src/features/assignment/components/StudentAssignmentList.tsx)
**API调用**: `assignmentService.getStudentAssignments()`
**后端文件**: `assignment.controller.ts` -> `getStudentAssignments`
**后端路由**: `assignment.routes.ts` -> `GET /api/assignments/learning`
**参数**: 无
**返回数据**: 学生作业列表

### 3. 发布作业
**前端组件**: `CreateAssignmentModal` (src/features/assignment/components/CreateAssignmentModal.tsx)
**API调用**: `assignmentService.publishAssignment(data)`
**后端文件**: `assignment.controller.ts` -> `publishAssignment`
**后端路由**: `assignment.routes.ts` -> `POST /api/assignments`
**参数**: 
- title: 作业标题
- description: 作业描述
- classId: 班级ID
- examId: 考试ID
- startTime: 开始时间
- endTime: 结束时间

### 4. 获取作业统计
**前端组件**: `AssignmentStats` (src/features/assignment/components/AssignmentStats.tsx)
**API调用**: `assignmentService.getAssignmentStats(id)`
**后端文件**: `assignment.controller.ts` -> `getAssignmentStats`
**后端路由**: `assignment.routes.ts` -> `GET /api/assignments/:id/stats`
**参数**: id (路径参数)
**返回数据**: 作业统计数据

## 批改相关API

### 1. 获取提交列表
**前端组件**: `GradingBoard` (src/features/grading/components/GradingBoard.tsx)
**API调用**: `gradingService.getSubmissions(assignmentId)`
**后端文件**: `grading.controller.ts` -> `getSubmissions`
**后端路由**: `grading.routes.ts` -> `GET /api/grading/:assignmentId/list`
**参数**: assignmentId (路径参数)
**返回数据**: 提交列表

### 2. 获取试卷
**前端组件**: `GradingBoard` (src/features/grading/components/GradingBoard.tsx)
**API调用**: `gradingService.getPaper(submissionId)`
**后端文件**: `grading.controller.ts` -> `getPaper`
**后端路由**: `grading.routes.ts` -> `GET /api/grading/submissions/:submissionId`
**参数**: submissionId (路径参数)
**返回数据**: 试卷详情

## 提交相关API

### 1. 获取学生试卷
**前端组件**: `StudentExamRunner` (src/views/StudentExamRunner.tsx)
**API调用**: `submissionService.getStudentPaper(id)`
**后端文件**: `submission.controller.ts` -> `getStudentPaper`
**后端路由**: `submission.routes.ts` -> `GET /api/submissions/:id/paper`
**参数**: id (路径参数)
**返回数据**: 学生试卷详情

### 2. 提交考试
**前端组件**: `StudentExamRunner` (src/views/StudentExamRunner.tsx)
**API调用**: `submissionService.submitExam(data)`
**后端文件**: `submission.controller.ts` -> `submitExam`
**后端路由**: `submission.routes.ts` -> `POST /api/submissions/:assignmentId/submit`
**参数**: 
- assignmentId: 作业ID
- answers: 答案
- submitTime: 提交时间

### 3. 获取提交结果
**前端组件**: `StudentResult` (src/views/StudentResult.tsx)
**API调用**: `submissionService.getSubmissionResult(assignmentId)`
**后端文件**: `submission.controller.ts` -> `getSubmissionResult`
**后端路由**: `submission.routes.ts` -> `GET /api/submissions/:assignmentId/result`
**参数**: assignmentId (路径参数)
**返回数据**: 提交结果详情

## 分析统计API

### 1. 获取班级表现
**前端组件**: `ClassAnalysis` (src/features/class/components/ClassAnalysis.tsx)
**API调用**: `analyticsService.getClassPerformance()`
**后端文件**: `analytics.controller.ts` -> `getClassPerformance`
**后端路由**: `analytics.routes.ts` -> `GET /api/analytics/class/performance`
**参数**: 无
**返回数据**: 班级表现数据

### 2. 获取学生成长
**前端组件**: `StudentDashboard` (src/features/dashboard/components/StudentDashboard.tsx)
**API调用**: `analyticsService.getStudentGrowth()`
**后端文件**: `analytics.controller.ts` -> `getStudentGrowth`
**后端路由**: `analytics.routes.ts` -> `GET /api/analytics/student/growth`
**参数**: 无
**返回数据**: 学生成长数据

### 3. 获取能力雷达图
**前端组件**: `TeacherDashboard` (src/features/dashboard/components/TeacherDashboard.tsx)
**API调用**: `analyticsService.getRadar()`
**后端文件**: `analytics.controller.ts` -> `getRadar`
**后端路由**: `analytics.routes.ts` -> `GET /api/analytics/radar`
**参数**: 无
**返回数据**: 能力雷达图数据

### 4. 获取学生能力雷达图
**前端组件**: `StudentDashboard` (src/features/dashboard/components/StudentDashboard.tsx)
**API调用**: `analyticsService.getStudentRadar()`
**后端文件**: `analytics.controller.ts` -> `getStudentRadar`
**后端路由**: `analytics.routes.ts` -> `GET /api/analytics/student/radar`
**参数**: 无
**返回数据**: 学生能力雷达图数据

### 5. 获取成绩分布
**前端组件**: `TeacherDashboard` (src/features/dashboard/components/TeacherDashboard.tsx)
**API调用**: `analyticsService.getScoreDistribution()`
**后端文件**: `analytics.controller.ts` -> `getScoreDistribution`
**后端路由**: `analytics.routes.ts` -> `GET /api/analytics/distribution`
**参数**: 无
**返回数据**: 成绩分布数据

### 6. 获取教师统计数据
**前端组件**: `TeacherDashboard` (src/features/dashboard/components/TeacherDashboard.tsx)
**API调用**: `analyticsService.getTeacherStats()`
**后端文件**: `analytics.controller.ts` -> `getTeacherStats`
**后端路由**: `analytics.routes.ts` -> `GET /api/analytics/teacher-stats`
**参数**: 无
**返回数据**: 教师统计数据

## 课程相关API

### 1. 获取科目列表
**前端组件**: `SubjectSelector` (src/features/question/components/SubjectSelector.tsx)
**API调用**: `curriculumService.getSubjects()`
**后端文件**: `curriculum.controller.ts` -> `getSubjects`
**后端路由**: `curriculum.routes.ts` -> `GET /api/curriculum/subjects`
**参数**: 无
**返回数据**: 科目列表

### 2. 获取教材树
**前端组件**: `KnowledgeGraph` (src/features/curriculum/components/KnowledgeGraph.tsx)
**API调用**: `curriculumService.getTree(id)`
**后端文件**: `curriculum.controller.ts` -> `getTree
**后端路由**: `curriculum.routes.ts` -> `GET /api/curriculum/textbooks/:id/tree`
**参数**: id (路径参数)
**返回数据**: 教材树形结构

### 3. 获取科目教材
**前端组件**: `TextbookModal` (src/features/curriculum/components/TextbookModal.tsx)
**API调用**: `curriculumService.getTextbooksBySubject(subjectId)`
**后端文件**: `curriculum.controller.ts` -> `getTextbooksBySubject`
**后端路由**: `curriculum.routes.ts` -> `GET /api/curriculum/subjects/:subjectId/textbooks`
**参数**: subjectId (路径参数)
**返回数据**: 教材列表

### 4. 创建教材
**前端组件**: `TextbookModal` (src/features/curriculum/components/TextbookModal.tsx)
**API调用**: `curriculumService.createTextbook(data)`
**后端文件**: `curriculum.controller.ts` -> `createTextbook`
**后端路由**: `curriculum.routes.ts` -> `POST /api/curriculum/textbooks`
**参数**: 
- name: 教材名称
- subjectId: 科目ID
- description: 教材描述

### 5. 更新教材
**前端组件**: `TextbookModal` (src/features/curriculum/components/TextbookModal.tsx)
**API调用**: `curriculumService.updateTextbook(id, data)`
**后端文件**: `curriculum.controller.ts` -> `updateTextbook`
**后端路由**: `curriculum.routes.ts` -> `PUT /api/curriculum/textbooks/:id`
**参数**: 
- id: 教材ID
- name: 教材名称
- subjectId: 科目ID
- description: 教材描述

### 6. 删除教材
**前端组件**: `TextbookModal` (src/features/curriculum/components/TextbookModal.tsx)
**API调用**: `curriculumService.deleteTextbook(id)`
**后端文件**: `curriculum.controller.ts` -> `deleteTextbook`
**后端路由**: `curriculum.routes.ts` -> `DELETE /api/curriculum/textbooks/:id`
**参数**: id (路径参数)
**返回数据**: 操作结果

### 7. 创建单元
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.createUnit(data)`
**后端文件**: `curriculum.controller.ts` -> `createUnit
**后端路由**: `curriculum.routes.ts` -> `POST /api/curriculum/units`
**参数**: 
- name: 单元名称
- textbookId: 教材ID
- description: 单元描述

### 8. 更新单元
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.updateUnit(id, data)`
**后端文件**: `curriculum.controller.ts` -> `updateUnit
**后端路由**: `curriculum.routes.ts` -> `PUT /api/curriculum/units/:id`
**参数**: 
- id: 单元ID
- name: 单元名称
- textbookId: 教材ID
- description: 单元描述

### 9. 删除单元
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.deleteUnit(id)`
**后端文件**: `curriculum.controller.ts` -> `deleteUnit
**后端路由**: `curriculum.routes.ts` -> `DELETE /api/curriculum/units/:id`
**参数**: id (路径参数)
**返回数据**: 操作结果

### 10. 创建课时
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.createLesson(data)`
**后端文件**: `curriculum.controller.ts` -> `createLesson
**后端路由**: `curriculum.routes.ts` -> `POST /api/curriculum/lessons`
**参数**: 
- name: 课时名称
- unitId: 单元ID
- description: 课时描述

### 11. 更新课时
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.updateLesson(id, data)`
**后端文件**: `curriculum.controller.ts` -> `updateLesson
**后端路由**: `curriculum.routes.ts` -> `PUT /api/curriculum/lessons/:id`
**参数**: 
- id: 课时ID
- name: 课时名称
- unitId: 单元ID
- description: 课时描述

### 12. 删除课时
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.deleteLesson(id)`
**后端文件**: `curriculum.controller.ts` -> `deleteLesson
**后端路由**: `curriculum.routes.ts` -> `DELETE /api/curriculum/lessons/:id`
**参数**: id (路径参数)
**返回数据**: 操作结果

### 13. 创建知识点
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.createKnowledgePoint(data)`
**后端文件**: `curriculum.controller.ts` -> `createKnowledgePoint
**后端路由**: `curriculum.routes.ts` -> `POST /api/curriculum/knowledge-points`
**参数**: 
- name: 知识点名称
- lessonId: 课时ID
- description: 知识点描述

### 14. 更新知识点
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.updateKnowledgePoint(id, data)`
**后端文件**: `curriculum.controller.ts` -> `updateKnowledgePoint
**后端路由**: `curriculum.routes.ts` -> `PUT /api/curriculum/knowledge-points/:id`
**参数**: 
- id: 知识点ID
- name: 知识点名称
- lessonId: 课时ID
- description: 知识点描述

### 15. 删除知识点
**前端组件**: `CurriculumNodeModal` (src/features/curriculum/components/CurriculumNodeModal.tsx)
**API调用**: `curriculumService.deleteKnowledgePoint(id)`
**后端文件**: `curriculum.controller.ts` -> `deleteKnowledgePoint
**后端路由**: `curriculum.routes.ts` -> `DELETE /api/curriculum/knowledge-points/:id`
**参数**: id (路径参数)
**返回数据**: 操作结果

## 消息相关API

### 1. 获取消息列表
**前端组件**: `NotificationList` (src/features/dashboard/components/NotificationList.tsx)
**API调用**: `messageService.getMessages()`
**后端文件**: `message.controller.ts` -> `getMessages`
**后端路由**: `message.routes.ts` -> `GET /api/common/messages`
**参数**: 无
**返回数据**: 消息列表

### 2. 标记已读
**前端组件**: `NotificationList` (src/features/dashboard/components/NotificationList.tsx)
**API调用**: `messageService.markAsRead(id)`
**后端文件**: `message.controller.ts` -> `markAsRead
**后端路由**: `message.routes.ts` -> `POST /api/common/messages/:id/read`
**参数**: id (路径参数)
**返回数据**: 操作结果

### 3. 创建消息
**前端组件**: `CreateMessageModal` (src/features/message/components/CreateMessageModal.tsx)
**API调用**: `messageService.createMessage(data)`
**后端文件**: `message.controller.ts` -> `createMessage
**后端路由**: `message.routes.ts` -> `POST /api/common/messages`
**参数**: 
- title: 消息标题
- content: 消息内容
- type: 消息类型
- recipientIds: 接收者ID列表

## 日程相关API

### 1. 获取日程
**前端组件**: `ScheduleList` (src/features/dashboard/components/ScheduleList.tsx)
**API调用**: `scheduleService.getWeekSchedule()`
**后端文件**: `schedule.controller.ts` -> `getWeekSchedule
**后端路由**: `schedule.routes.ts` -> `GET /api/common/schedule/week`
**参数**: 无
**返回数据**: 周日程数据

### 2. 添加日程
**前端组件**: `EventModal` (src/features/schedule/components/EventModal.tsx)
**API调用**: `scheduleService.addEvent(data)`
**后端文件**: `schedule.controller.ts` -> `addEvent
**后端路由**: `schedule.routes.ts` -> `POST /api/common/schedule`
**参数**: 
- title: 日程标题
- startTime: 开始时间
- endTime: 结束时间
- type: 日程类型
- description: 日程描述

### 3. 删除日程
**前端组件**: `EventModal` (src/features/schedule/components/EventModal.tsx)
**API调用**: `scheduleService.deleteEvent(id)`
**后端文件**: `schedule.controller.ts` -> `deleteEvent
**后端路由**: `schedule.routes.ts` -> `DELETE /api/common/schedule/:id`
**参数**: id (路径参数)
**返回数据**: 操作结果

## 公共API

### 1. 获取日程
**前端组件**: `Timetable` (src/features/schedule/components/Timetable.tsx)
**API调用**: `commonService.getSchedule()`
**后端文件**: `common.controller.ts` -> `getSchedule
**后端路由**: `common.routes.ts` -> `GET /api/common/schedule`
**参数**: 无
**返回数据**: 日程数据

## 未实现的API

### 1. 考试节点管理
**需要实现**:
- 添加考试节点: `POST /api/exams/:id/nodes`
- 更新考试节点: `PUT /api/exams/:id/nodes/:nodeId`
- 删除考试节点: `DELETE /api/exams/:id/nodes/:nodeId`

### 2. 更新考试基本信息
**需要实现**:
- 更新考试: `PUT /api/exams/:id`

### 3. 删除考试
**需要实现**:
- 删除考试: `DELETE /api/exams/:id`

### 4. 作业管理
**需要实现**:
- 获取作业详情: `GET /api/assignments/:id`
- 更新作业: `PUT /api/assignments/:id`
- 删除作业: `DELETE /api/assignments/:id`

### 5. 批改管理
**需要实现**:
- 保存批改结果: `POST /api/grading/submissions/:submissionId/grade`
- 获取批改详情: `GET /api/grading/submissions/:submissionId/grade`

### 6. 提交管理
**需要实现**:
- 获取提交列表: `GET /api/submissions`
- 更新提交状态: `PUT /api/submissions/:id`
- 删除提交: `DELETE /api/submissions/:id`

### 7. 课程管理
**需要实现**:
- 获取单元详情: `GET /api/curriculum/units/:id`
- 获取课时详情: `GET /api/curriculum/lessons/:id`
- 获取知识点详情: `GET /api/curriculum/knowledge-points/:id`

### 8. 消息管理
**需要实现**:
- 获取消息详情: `GET /api/common/messages/:id`
- 更新消息: `PUT /api/common/messages/:id`
- 删除消息: `DELETE /api/common/messages/:id`

### 9. 日程管理
**需要实现**:
- 获取日程详情: `GET /api/common/schedule/:id`
- 更新日程: `PUT /api/common/schedule/:id`

### 10. 公共管理
**需要实现**:
- 其他公共接口