481 lines
14 KiB
Plaintext
481 lines
14 KiB
Plaintext
# 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. **实时更新**: 某些操作（如提交作业）可能需要实时更新界面状态
|