162 lines
7.2 KiB
Markdown
162 lines
7.2 KiB
Markdown
|
# API 对比分析报告
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
对比 reading-platform-backend (Node.js/NestJS) 和 reading-platform-java (Spring Boot) 的 API 接口差异
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 已补全的接口
|
|||
|
|
|
|||
|
|
### 1. 任务管理相关接口（SchoolTaskController, TeacherTaskController）
|
|||
|
|
|
|||
|
|
#### 任务统计接口
|
|||
|
|
- `GET /api/v1/school/tasks/stats` - 获取任务统计数据
|
|||
|
|
- `GET /api/v1/school/tasks/stats/by-type` - 按任务类型统计
|
|||
|
|
- `GET /api/v1/school/tasks/stats/by-class` - 按班级统计
|
|||
|
|
- `GET /api/v1/school/tasks/stats/monthly` - 月度统计趋势
|
|||
|
|
|
|||
|
|
#### 任务完成情况接口
|
|||
|
|
- `GET /api/v1/school/tasks/:id/completions` - 获取任务完成情况分页
|
|||
|
|
- `PUT /api/v1/school/tasks/:taskId/completions/:studentId` - 更新任务完成状态
|
|||
|
|
|
|||
|
|
#### 任务模板接口
|
|||
|
|
- `GET /api/v1/school/task-templates` - 获取任务模板列表
|
|||
|
|
- `GET /api/v1/school/task-templates/:id` - 获取单个模板
|
|||
|
|
- `GET /api/v1/school/task-templates/default/:taskType` - 获取默认模板
|
|||
|
|
- `POST /api/v1/school/task-templates` - 创建模板
|
|||
|
|
- `PUT /api/v1/school/task-templates/:id` - 更新模板
|
|||
|
|
- `DELETE /api/v1/school/task-templates/:id` - 删除模板
|
|||
|
|
- `POST /api/v1/school/tasks/from-template` - 从模板创建任务
|
|||
|
|
|
|||
|
|
### 2. 通知相关接口
|
|||
|
|
|
|||
|
|
#### 学校管理员通知（SchoolNotificationController - 新增）
|
|||
|
|
- `GET /api/v1/school/notifications` - 获取通知列表
|
|||
|
|
- `GET /api/v1/school/notifications/:id` - 根据 ID 获取通知
|
|||
|
|
- `GET /api/v1/school/notifications/unread-count` - 获取未读数量
|
|||
|
|
- `POST /api/v1/school/notifications/:id/read` - 标记已读
|
|||
|
|
- `POST /api/v1/school/notifications/read-all` - 全部标记已读
|
|||
|
|
|
|||
|
|
### 3. 排课和课表相关接口（SchoolScheduleController）
|
|||
|
|
- `GET /api/v1/school/schedules/timetable` - 获取课表（带日期范围）
|
|||
|
|
- `POST /api/v1/school/schedules/batch` - 批量创建排课
|
|||
|
|
- `GET /api/v1/school/schedules/templates/:id` - 获取单个模板
|
|||
|
|
- `PUT /api/v1/school/schedules/templates/:id` - 更新模板
|
|||
|
|
- `POST /api/v1/school/schedules/templates/:id/apply` - 应用模板
|
|||
|
|
|
|||
|
|
### 4. 新增 DTO
|
|||
|
|
- `TaskTemplateCreateRequest` - 任务模板创建请求
|
|||
|
|
- `TaskTemplateUpdateRequest` - 任务模板更新请求
|
|||
|
|
- `CreateTaskFromTemplateRequest` - 从模板创建任务请求
|
|||
|
|
- `SchedulePlanCreateRequest` - 课表计划创建请求
|
|||
|
|
- `ScheduleTemplateApplyRequest` - 课表模板应用请求
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 仍需补全的接口
|
|||
|
|
|
|||
|
|
### P1 - 重要功能
|
|||
|
|
|
|||
|
|
#### 1. 成长档案接口（SchoolGrowthController, TeacherGrowthController）
|
|||
|
|
- `GET /api/v1/school/students/:studentId/growth-records` - 按学生查询成长档案
|
|||
|
|
- `GET /api/v1/school/classes/:classId/growth-records` - 按班级查询成长档案
|
|||
|
|
- `GET /api/v1/teacher/classes/:classId/growth-records` - 教师端按班级查询
|
|||
|
|
|
|||
|
|
#### 2. 教师端课时增强接口（TeacherLessonController）
|
|||
|
|
- `POST /api/v1/teacher/lessons/:id/finish` - 完成课时（带反馈数据）
|
|||
|
|
- `POST /api/v1/teacher/lessons/:id/students/:studentId/record` - 保存学生记录
|
|||
|
|
- `GET /api/v1/teacher/lessons/:id/student-records` - 获取学生记录
|
|||
|
|
- `POST /api/v1/teacher/lessons/:id/student-records/batch` - 批量保存学生记录
|
|||
|
|
- `POST /api/v1/teacher/lessons/:id/feedback` - 提交反馈
|
|||
|
|
- `GET /api/v1/teacher/lessons/:id/feedback` - 获取反馈
|
|||
|
|
|
|||
|
|
#### 3. 教师端课程增强接口（TeacherCourseController）
|
|||
|
|
- `GET /api/v1/teacher/courses/classes` - 获取班级列表
|
|||
|
|
- `GET /api/v1/teacher/students` - 获取所有学生
|
|||
|
|
- `GET /api/v1/teacher/classes/:id/students` - 获取班级学生
|
|||
|
|
- `GET /api/v1/teacher/classes/:id/teachers` - 获取班级教师
|
|||
|
|
- `GET /api/v1/teacher/schedules/timetable` - 获取课表
|
|||
|
|
- `GET /api/v1/teacher/schedules/today` - 获取今天排课
|
|||
|
|
- `POST /api/v1/teacher/schedules` - 创建排课
|
|||
|
|
- `PUT /api/v1/teacher/schedules/:id` - 更新排课
|
|||
|
|
- `DELETE /api/v1/teacher/schedules/:id` - 取消排课
|
|||
|
|
|
|||
|
|
#### 4. 班级管理接口（SchoolClassController）
|
|||
|
|
- `GET /api/v1/school/classes/:id/students` - 获取班级学生
|
|||
|
|
- `GET /api/v1/school/classes/:id/teachers` - 获取班级教师
|
|||
|
|
- `POST /api/v1/school/classes/:id/teachers` - 添加班级教师
|
|||
|
|
- `PUT /api/v1/school/classes/:id/teachers/:teacherId` - 更新班级教师
|
|||
|
|
- `DELETE /api/v1/school/classes/:id/teachers/:teacherId` - 移除班级教师
|
|||
|
|
- `POST /api/v1/school/students/:id/transfer` - 学生调班
|
|||
|
|
- `GET /api/v1/school/students/:id/history` - 学生调班历史
|
|||
|
|
- `POST /api/v1/school/students/import` - 批量导入学生
|
|||
|
|
- `GET /api/v1/school/students/import/template` - 获取导入模板
|
|||
|
|
|
|||
|
|
### P2 - 辅助功能
|
|||
|
|
|
|||
|
|
#### 1. 统计报告接口（SchoolStatsController）
|
|||
|
|
- `GET /api/v1/school/stats/teachers` - 活跃教师统计
|
|||
|
|
- `GET /api/v1/school/stats/courses` - 课程使用统计
|
|||
|
|
- `GET /api/v1/school/stats/activities` - 最近活动
|
|||
|
|
- `GET /api/v1/school/stats/lesson-trend` - 课时趋势
|
|||
|
|
- `GET /api/v1/school/stats/course-distribution` - 课程分布
|
|||
|
|
- `GET /api/v1/school/reports/overview` - 概览报告
|
|||
|
|
- `GET /api/v1/school/reports/teachers` - 教师报告
|
|||
|
|
- `GET /api/v1/school/reports/courses` - 课程报告
|
|||
|
|
- `GET /api/v1/school/reports/students` - 学生报告
|
|||
|
|
|
|||
|
|
#### 2. 导出接口增强（SchoolExportController）
|
|||
|
|
- `GET /api/v1/school/export/lessons?startDate=&endDate=` - 导出课时（带日期范围）
|
|||
|
|
- `GET /api/v1/school/export/teacher-stats?startDate=&endDate=` - 导出教师统计
|
|||
|
|
- `GET /api/v1/school/export/student-stats?classId=` - 导出学生统计（按班级）
|
|||
|
|
|
|||
|
|
#### 3. 课程包/套餐接口
|
|||
|
|
- `GET /api/v1/school/package` - 获取套餐信息
|
|||
|
|
- `GET /api/v1/school/package/usage` - 获取套餐使用情况
|
|||
|
|
|
|||
|
|
#### 4. 家长相关接口
|
|||
|
|
- `POST /api/v1/school/parents/:parentId/children/:studentId` - 添加孩子到家长
|
|||
|
|
- `DELETE /api/v1/school/parents/:parentId/children/:studentId` - 从家长移除孩子
|
|||
|
|
|
|||
|
|
#### 5. 管理员课程接口
|
|||
|
|
- `GET /api/v1/admin/courses/:id/stats` - 课程统计
|
|||
|
|
- `GET /api/v1/admin/courses/:id/validate` - 验证课程
|
|||
|
|
- `GET /api/v1/admin/courses/:id/versions` - 版本历史
|
|||
|
|
- `POST /api/v1/admin/courses/:id/submit` - 提交审核
|
|||
|
|
- `POST /api/v1/admin/courses/:id/withdraw` - 撤销审核
|
|||
|
|
- `POST /api/v1/admin/courses/:id/approve` - 审核通过
|
|||
|
|
- `POST /api/v1/admin/courses/:id/reject` - 审核驳回
|
|||
|
|
- `POST /api/v1/admin/courses/:id/direct-publish` - 直接发布
|
|||
|
|
- `POST /api/v1/admin/courses/:id/publish` - 发布
|
|||
|
|
- `POST /api/v1/admin/courses/:id/unpublish` - 下架
|
|||
|
|
- `POST /api/v1/admin/courses/:id/republish` - 重新发布
|
|||
|
|
|
|||
|
|
#### 6. 资源接口增强
|
|||
|
|
- `POST /api/v1/admin/resources/items/batch-delete` - 批量删除资源项
|
|||
|
|
- `GET /api/v1/admin/resources/stats` - 资源统计
|
|||
|
|
|
|||
|
|
#### 7. 反馈接口
|
|||
|
|
- `GET /api/v1/teacher/feedbacks` - 获取反馈列表
|
|||
|
|
- `GET /api/v1/teacher/feedbacks/stats` - 获取反馈统计
|
|||
|
|
- `GET /api/v1/school/feedbacks` - 获取反馈列表（学校端）
|
|||
|
|
- `GET /api/v1/school/feedbacks/stats` - 获取反馈统计（学校端）
|
|||
|
|
|
|||
|
|
#### 8. 认证接口
|
|||
|
|
- `GET /api/v1/auth/profile` - 获取用户信息
|
|||
|
|
- `POST /api/v1/auth/logout` - 登出
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 总结
|
|||
|
|
|
|||
|
|
本次补全了以下主要功能：
|
|||
|
|
1. 任务管理：统计、模板、完成情况更新
|
|||
|
|
2. 通知：学校管理员通知接口
|
|||
|
|
3. 排课：课表模板、批量创建、应用模板
|
|||
|
|
|
|||
|
|
下一步建议优先补全：
|
|||
|
|
1. 成长档案按学生/班级查询接口
|
|||
|
|
2. 教师端课时反馈接口
|
|||
|
|
3. 班级管理相关接口
|
|||
|
|
4. 学生调班和批量导入接口
|