tonytech/kindergarten_java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5d96c832f6
kindergarten_java/API 对比分析.md
En 583b47c430 feat: 新增学校通知、任务模板和日程管理功能 
- 新增学校通知控制器 (SchoolNotificationController)
- 新增任务模板创建/更新请求 DTO
- 新增日程计划创建和模板应用请求 DTO
- 新增 TokenService 服务实现
- 新增多个服务实现类 (AdminStats, CourseLesson, CoursePackage 等)
- 添加数据库迁移脚本 V7__fix_schedule_plans.sql
- 更新配置文件和依赖

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-10 01:06:03 +08:00

7.2 KiB
Raw Blame History

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