# 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. 学生调班和批量导入接口