chore: initial import to Nexus_Edu

2025-11-28 19:23:19 +08:00
commit 38244630a7
153 changed files with 22541 additions and 0 deletions
--- a/480
+++ b/480
@@ -0,0 +1,480 @@
+# 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. **实时更新**: 某些操作（如提交作业）可能需要实时更新界面状态