# EduNexus 前端组件API接口文档

## 按组件类型分类的API接口

### 1. 认证相关组件 (Auth Components)

#### LoginForm组件
- **前端服务**: `authService`
- **API调用**: `login(username: string)`
- **后端文件**: `auth.controller.ts`
- **接口**: `POST /api/auth/login`
- **参数**: username, password
- **说明**: 用户登录

#### RegisterForm组件
- **前端服务**: `authService`
- **API调用**: `register(data: RegisterDto)`
- **后端文件**: `auth.controller.ts`
- **接口**: `POST /api/auth/register`
- **参数**: realName, email, phone, password, gender
- **说明**: 用户注册

#### UserProfile组件
- **前端服务**: `authService`
- **API调用**: 
  - `me()`
  - `updateProfile(data: UpdateProfileDto)`
  - `changePassword(data: ChangePasswordDto)`
- **后端文件**: `auth.controller.ts`
- **接口**: 
  - `GET /api/auth/me`
  - `PUT /api/auth/profile`
  - `POST /api/auth/change-password`
- **说明**: 获取用户信息、更新用户资料、修改密码

### 2. 仪表板组件 (Dashboard Components)

#### TeacherDashboard组件
- **前端服务**: 
  - `analyticsService`
  - `commonService`
- **API调用**: 
  - `getClassPerformance()`
  - `getRadar()`
  - `getScoreDistribution()`
  - `getSchedule()`
  - `getTeacherStats()`
- **后端文件**: 
  - `analytics.controller.ts`
  - `common.controller.ts`
- **接口**: 
  - `GET /api/analytics/class-performance`
  - `GET /api/analytics/radar`
  - `GET /api/analytics/score-distribution`
  - `GET /api/schedule`
  - `GET /api/analytics/teacher-stats`
- **说明**: 获取教师统计数据、班级表现、知识图谱、成绩分布、课表

#### StudentDashboard组件
- **前端服务**: 
  - `analyticsService`
  - `commonService`
- **API调用**: 
  - `getStudentGrowth()`
  - `getStudentRadar()`
  - `getSchedule()`
- **后端文件**: 
  - `analytics.controller.ts`
  - `common.controller.ts`
- **接口**: 
  - `GET /api/analytics/student-growth`
  - `GET /api/analytics/student-radar`
  - `GET /api/schedule`
- **说明**: 获取学生成长数据、学生能力雷达图、课表

### 3. 作业管理组件 (Assignment Components)

#### TeacherAssignmentList组件
- **前端服务**: `assignmentService`
- **API调用**: `getTeachingAssignments()`
- **后端文件**: `assignment.controller.ts`
- **接口**: `GET /api/assignments/teaching`
- **参数**: 无
- **说明**: 获取教师发布的作业列表

#### StudentAssignmentList组件
- **前端服务**: `assignmentService`
- **API调用**: `getStudentAssignments()`
- **后端文件**: `assignment.controller.ts`
- **接口**: `GET /api/assignments/learning`
- **参数**: 无
- **说明**: 获取学生需要完成的作业列表

#### CreateAssignmentModal组件
- **前端服务**: `assignmentService`
- **API调用**: `publishAssignment(data: any)`
- **后端文件**: `assignment.controller.ts`
- **接口**: `POST /api/assignments`
- **参数**: examId, classId, title, startTime, endTime, allowLateSubmission, autoScoreEnabled
- **说明**: 创建并发布作业

#### AssignmentStats组件
- **前端服务**: `assignmentService`
- **API调用**: `getAssignmentStats(id: string)`
- **后端文件**: `assignment.controller.ts`
- **接口**: `GET /api/assignments/:id/stats`
- **参数**: assignmentId
- **说明**: 获取作业统计数据

### 4. 考试管理组件 (Exam Components)

#### ExamEditor组件
- **前端服务**: 
  - `examService`
  - `questionService`
- **API调用**: 
  - `getExamDetail(id: string)`
  - `saveExam(exam: ExamDetailDto)`
  - `search(filter: any)`
- **后端文件**: 
  - `exam.controller.ts`
  - `question.controller.ts`
- **接口**: 
  - `GET /api/exams/:id`
  - `PUT /api/exams/:id/structure`
  - `POST /api/questions/search`
- **说明**: 获取考试详情、保存考试结构、搜索题目

#### ExamList组件
- **前端服务**: `examService`
- **API调用**: `getMyExams()`
- **后端文件**: `exam.controller.ts`
- **接口**: `GET /api/exams`
- **参数**: subjectId, status
- **说明**: 获取我的考试列表

#### ExamStats组件
- **前端服务**: `examService`
- **API调用**: `getStats(id: string)`
- **后端文件**: `exam.controller.ts`
- **接口**: `GET /api/exams/:id/stats`
- **参数**: examId
- **说明**: 获取考试统计数据

### 5. 批改管理组件 (Grading Components)

#### GradingBoard组件
- **前端服务**: `gradingService`
- **API调用**: 
  - `getSubmissions(assignmentId: string)`
  - `getPaper(submissionId: string)`
  - `submitGrade(data: any)`
- **后端文件**: `grading.controller.ts`
- **接口**: 
  - `GET /api/grading/:assignmentId/list`
  - `GET /api/grading/submissions/:submissionId`
  - `POST /api/grading/submissions/:submissionId`
- **说明**: 获取作业提交列表、获取答卷详情、提交批改结果

#### SubmissionSidebar组件
- **前端服务**: `gradingService`
- **API调用**: `getSubmissions(assignmentId: string)`
- **后端文件**: `grading.controller.ts`
- **接口**: `GET /api/grading/:assignmentId/list`
- **参数**: assignmentId
- **说明**: 获取作业提交列表

### 6. 学生考试组件 (Student Exam Components)

#### StudentExamRunner组件
- **前端服务**: `submissionService`
- **API调用**: 
  - `getStudentPaper(assignmentId: string)`
  - `submitExam(data: SubmitExamDto)`
- **后端文件**: `submission.controller.ts`
- **接口**: 
  - `GET /api/submissions/:assignmentId/paper`
  - `POST /api/submissions/:assignmentId/submit`
- **说明**: 获取学生答题卡、提交答案

#### StudentResult组件
- **前端服务**: `submissionService`
- **API调用**: `getSubmissionResult(assignmentId: string)`
- **后端文件**: `submission.controller.ts`
- **接口**: `GET /api/submissions/:submissionId/result`
- **参数**: submissionId
- **说明**: 查看考试结果

### 7. 题库管理组件 (Question Components)

#### QuestionCard组件
- **前端服务**: `questionService`
- **API调用**: `search(filter: any)`
- **后端文件**: `question.controller.ts`
- **接口**: `POST /api/questions/search`
- **参数**: subjectId, questionType, difficulty, keyword, createdBy, sortBy, page, pageSize
- **说明**: 搜索题目

#### QuestionModal组件
- **前端服务**: `questionService`
- **API调用**: 
  - `create(data: any)`
  - `update(id: string, data: any)`
  - `delete(id: string)`
- **后端文件**: `question.controller.ts`
- **接口**: 
  - `POST /api/questions`
  - `PUT /api/questions/:id`
  - `DELETE /api/questions/:id`
- **说明**: 创建、更新、删除题目

#### SubjectSelector组件
- **前端服务**: `curriculumService`
- **API调用**: `getSubjects()`
- **后端文件**: `curriculum.controller.ts`
- **接口**: `GET /api/curriculum/subjects`
- **参数**: 无
- **说明**: 获取学科列表

### 8. 课程管理组件 (Curriculum Components)

#### KnowledgeGraph组件
- **前端服务**: `curriculumService`
- **API调用**: `getTree(id: string)`
- **后端文件**: `curriculum.controller.ts`
- **接口**: `GET /api/curriculum/textbooks/:id/tree`
- **参数**: id (textbookId或subjectId)
- **说明**: 获取教材知识树结构

#### TextbookModal组件
- **前端服务**: `curriculumService`
- **API调用**: 
  - `getTextbooksBySubject(subjectId: string)`
  - `createTextbook(data: any)`
  - `updateTextbook(id: string, data: any)`
  - `deleteTextbook(id: string)`
- **后端文件**: `curriculum.controller.ts`
- **接口**: 
  - `GET /api/curriculum/subjects/:id/textbooks`
  - `POST /api/curriculum/textbooks`
  - `PUT /api/curriculum/textbooks/:id`
  - `DELETE /api/curriculum/textbooks/:id`
- **说明**: 获取教材列表、创建、更新、删除教材

#### TreeNode组件
- **前端服务**: `curriculumService`
- **API调用**: `getTree(id: string)`
- **后端文件**: `curriculum.controller.ts`
- **接口**: `GET /api/curriculum/textbooks/:id/tree`
- **参数**: id
- **说明**: 获取课程树结构

### 9. 班级管理组件 (Class Components)

#### ClassCard组件
- **前端服务**: `orgService`
- **API调用**: `getClasses(role?: string)`
- **后端文件**: `org.controller.ts`
- **接口**: `GET /api/org/classes`
- **参数**: role
- **说明**: 获取我的班级列表

#### CreateClassModal组件
- **前端服务**: `orgService`
- **API调用**: `createClass(data: CreateClassDto)`
- **后端文件**: `org.controller.ts`
- **接口**: `POST /api/org/classes`
- **参数**: name, gradeId
- **说明**: 创建新班级

#### JoinClassModal组件
- **前端服务**: `orgService`
- **API调用**: `joinClass(inviteCode: string)`
- **后端文件**: `org.controller.ts`
- **接口**: `POST /api/org/classes/join`
- **参数**: inviteCode
- **说明**: 通过邀请码加入班级

#### ClassAnalysis组件
- **前端服务**: `orgService`
- **API调用**: `getClassMembers(classId: string)`
- **后端文件**: `org.controller.ts`
- **接口**: `GET /api/org/classes/:id/members`
- **参数**: classId
- **说明**: 获取班级成员列表

### 10. 消息组件 (Message Components)

#### CreateMessageModal组件
- **前端服务**: `messageService`
- **API调用**: 
  - `getMessages()`
  - `createMessage(data: CreateMessageDto)`
- **后端文件**: `common.controller.ts`
- **接口**: 
  - `GET /api/messages`
  - `POST /api/messages`
- **说明**: 获取消息列表、创建消息

#### NotificationList组件
- **前端服务**: `messageService`
- **API调用**: `getMessages()`
- **后端文件**: `common.controller.ts`
- **接口**: `GET /api/messages`
- **参数**: 无
- **说明**: 获取消息列表

### 11. 日程组件 (Schedule Components)

#### Timetable组件
- **前端服务**: `scheduleService`
- **API调用**: `getWeekSchedule()`
- **后端文件**: `common.controller.ts`
- **接口**: `GET /api/schedule`
- **参数**: 无
- **说明**: 获取周日程

#### EventModal组件
- **前端服务**: `scheduleService`
- **API调用**: 
  - `addEvent(data: CreateScheduleDto)`
  - `deleteEvent(id: string)`
- **后端文件**: `common.controller.ts`
- **接口**: 
  - `POST /api/schedule`
  - `DELETE /api/schedule/:id`
- **说明**: 添加日程、删除日程

### 12. 设置组件 (Settings Components)

#### ProfileSettings组件
- **前端服务**: `authService`
- **API调用**: `updateProfile(data: UpdateProfileDto)`
- **后端文件**: `auth.controller.ts`
- **接口**: `PUT /api/auth/profile`
- **参数**: realName, avatarUrl, bio, gender
- **说明**: 更新用户资料

#### SecuritySettings组件
- **前端服务**: `authService`
- **API调用**: `changePassword(data: ChangePasswordDto)`
- **后端文件**: `auth.controller.ts`
- **接口**: `POST /api/auth/change-password`
- **参数**: oldPassword, newPassword
- **说明**: 修改密码

## 未使用但可能需要的API

### 1. 用户管理
- **前端服务**: `authService`
- **API调用**: `updateProfile(data: UpdateProfileDto)`
- **后端文件**: `auth.controller.ts`
- **接口**: `PUT /api/auth/profile`
- **参数**: realName, avatarUrl, bio, gender
- **说明**: 更新用户资料
- **使用状态**: 已在ProfileSettings组件中使用

### 2. 密码管理
- **前端服务**: `authService`
- **API调用**: `changePassword(data: ChangePasswordDto)`
- **后端文件**: `auth.controller.ts`
- **接口**: `POST /api/auth/change-password`
- **参数**: oldPassword, newPassword
- **说明**: 修改密码
- **使用状态**: 已在SecuritySettings组件中使用

### 3. 知识点管理
- **前端服务**: `curriculumService`
- **API调用**: `createKnowledgePoint(data: any)`
- **后端文件**: `curriculum.controller.ts`
- **接口**: `POST /api/curriculum/knowledge-points`
- **参数**: lessonId, name, difficulty, description
- **说明**: 创建知识点
- **使用状态**: 未在前端组件中直接使用

### 4. 课时管理
- **前端服务**: `curriculumService`
- **API调用**: `createLesson(data: any)`
- **后端文件**: `curriculum.controller.ts`
- **接口**: `POST /api/curriculum/lessons`
- **参数**: unitId, name, sortOrder
- **说明**: 创建课时
- **使用状态**: 未在前端组件中直接使用

### 5. 单元管理
- **前端服务**: `curriculumService`
- **API调用**: `createUnit(data: any)`
- **后端文件**: `curriculum.controller.ts`
- **接口**: `POST /api/curriculum/units`
- **参数**: textbookId, name, sortOrder
- **说明**: 创建单元
- **使用状态**: 未在前端组件中直接使用

### 6. 消息管理
- **前端服务**: `messageService`
- **API调用**: `markAsRead(id: string)`
- **后端文件**: `common.controller.ts`
- **接口**: `PUT /api/messages/:id/read`
- **参数**: id
- **说明**: 标记消息为已读
- **使用状态**: 未在前端组件中直接使用

### 7. 统计分析
- **前端服务**: `analyticsService`
- **API调用**: `getClassPerformance()`
- **后端文件**: `analytics.controller.ts`
- **接口**: `GET /api/analytics/class-performance`
- **参数**: 无
- **说明**: 获取班级表现
- **使用状态**: 已在TeacherDashboard组件中使用

### 8. 学生成长
- **前端服务**: `analyticsService`
- **API调用**: `getStudentGrowth()`
- **后端文件**: `analytics.controller.ts`
- **接口**: `GET /api/analytics/student-growth`
- **参数**: 无
- **说明**: 获取学生成长数据
- **使用状态**: 已在StudentDashboard组件中使用

## API参数类型说明

### 基础数据类型
- **string**: 文本类型
- **number**: 数字类型
- **boolean**: 布尔类型
- **Date**: 日期类型
- **Array**: 数组类型
- **Object**: 对象类型

### 特殊类型
- **UserRole**: 'Student' | 'Teacher' | 'Admin'
- **QuestionType**: 'SingleChoice' | 'MultipleChoice' | 'TrueFalse' | 'Subjective' | 'FillBlank'
- **SubmissionStatus**: 'Pending' | 'Submitted' | 'Graded' | 'Late'
- **ExamStatus**: 'Draft' | 'Published' | 'Archived'
- **Difficulty**: 1-5 (数字，1为最简单，5为最难)

### 枚举类型
- **NodeType**: 'Group' | 'Question'
- **SortOrder**: 数字，表示排序顺序
- **Message Type**: 'System' | 'Teacher' | 'Student'

## 数据格式说明

### 分页数据格式
```typescript
{
  items: T[],
  totalCount: number,
  pageIndex: number,
  pageSize: number
}
```

### 树形数据格式
```typescript
{
  id: string,
  name: string,
  children?: TreeNode[]
}
```

### 统计数据格式
```typescript
{
  total: number,
  passed: number,
  average: number,
  distribution: Array<{ range: string, count: number }>
}
```

## 注意事项

1. **认证**: 大部分API都需要用户认证，需要在请求头中包含JWT token
2. **权限**: 某些API需要特定权限（如教师权限）
3. **分页**: 列表类API通常支持分页，需要传入page和pageSize参数
4. **错误处理**: 前端需要处理各种可能的错误情况，如网络错误、权限不足、数据不存在等
5. **实时更新**: 某些操作（如提交作业）可能需要实时更新界面状态