kindergarten_java/docs/前后端接口对齐分析报告.md

前后端接口对齐分析报告

分析日期: 2026-03-11 分析范围: 旧后端 (NestJS) vs 新后端 (Spring Boot)

---

执行摘要

接口总体状态

角色	旧后端接口数	新后端接口数	已实现	缺失	完成率
教师端	~35	~32	30	5	86%
学校端	~60	~55	50	10	83%
家长端	6	6	6	0	100%
管理员端	~20	~18	16	4	80%
总计	~121	~111	102	19	84%

---

更新说明 (2026-03-11)

经过全面检查，发现新后端已经实现了绝大部分接口，原分析报告中的"缺失"接口实际上大多已经实现。

已实现但原报告标记为缺失的接口：

教师端：

• ✅ 成长档案 (TeacherGrowthController) - 已实现
• ✅ 通知管理 (TeacherNotificationController) - 已实现
• ✅ 课表管理 (TeacherScheduleController) - 已实现
• ✅ 任务统计 - 已实现
• ✅ 任务模板 - 已实现

学校端：

• ✅ 成长档案 (SchoolGrowthController) - 已实现
• ✅ 通知管理 (SchoolNotificationController) - 已实现
• ✅ 操作日志 (SchoolOperationLogController) - 已实现
• ✅ 统计接口 (SchoolStatsController) - 已实现
• ✅ 导出功能 (SchoolExportController) - 已实现
• ✅ 课表模板 - 已实现

家长端：

• ✅ 成长档案 (ParentGrowthController) - 已实现
• ✅ 通知管理 (ParentNotificationController) - 已实现

管理员端：

• ✅ 租户管理 (AdminTenantController) - 已实现
• ✅ 课程管理 (AdminCourseController) - 已实现
• ✅ 课程包管理 (AdminCoursePackageController) - 已实现
• ✅ 资源管理 (AdminResourceController) - 已实现
• ✅ 主题管理 (AdminThemeController) - 已实现
• ✅ 统计接口 (AdminStatsController) - 已实现

---

详细接口对比

一、教师端接口对比

✅ 已实现接口 (20 个)

接口路径	方法	功能	状态
/api/v1/teacher/dashboard	GET	仪表盘概览	✅
/api/v1/teacher/dashboard/today	GET	今日课表	✅
/api/v1/teacher/dashboard/weekly	GET	本周课时	✅
/api/v1/teacher/courses	GET	课程列表	✅
/api/v1/teacher/courses/{id}	GET	课程详情	✅
/api/v1/teacher/courses/classes	GET	教师的班级	✅
/api/v1/teacher/courses/students	GET	教师所有学生	✅
/api/v1/teacher/lessons	GET	课时列表	✅
/api/v1/teacher/lessons/{id}	GET/PUT	课时详情/更新	✅
/api/v1/teacher/lessons/{id}/start	POST	开始课时	✅
/api/v1/teacher/lessons/{id}/finish	POST	结束课时	✅
/api/v1/teacher/lessons/{id}/cancel	POST	取消课时	✅
/api/v1/teacher/lessons/{lessonId}/students/{studentId}/record	POST	保存学生评价	✅
/api/v1/teacher/lessons/{lessonId}/student-records	GET	获取学生评价	✅
/api/v1/teacher/lessons/{lessonId}/student-records/batch	POST	批量保存评价	✅
/api/v1/teacher/lessons/{lessonId}/feedback	GET/POST	课程反馈	✅
/api/v1/teacher/tasks	GET/POST	任务列表/创建	✅
/api/v1/teacher/tasks/{id}	GET/PUT/DELETE	任务详情/更新/删除	✅
/api/v1/teacher/tasks/{taskId}/completions/{studentId}	PUT	更新任务完成状态	✅
/api/v1/teacher/tasks/stats	GET	任务统计	✅
/api/v1/teacher/tasks/stats/by-type	GET	按类型统计	✅
/api/v1/teacher/tasks/stats/by-class	GET	按班级统计	✅
/api/v1/teacher/tasks/stats/monthly	GET	月度统计	✅
/api/v1/teacher/tasks/{id}/completions	GET	任务完成记录	✅
/api/v1/teacher/tasks/task-templates	GET	任务模板列表	✅
/api/v1/teacher/tasks/task-templates/{id}	GET	模板详情	✅
/api/v1/teacher/tasks/task-templates/default/{taskType}	GET	默认模板	✅
/api/v1/teacher/tasks/from-template	POST	从模板创建任务	✅

❌ 缺失接口 (11 个)

接口路径	方法	功能	优先级
/api/v1/teacher/dashboard/recommend	GET	推荐课程	中
/api/v1/teacher/dashboard/lesson-trend	GET	课时趋势	中
/api/v1/teacher/dashboard/course-usage	GET	课程使用情况	中
/api/v1/teacher/lessons/{id}/complete	POST	完成课时 (alternative)	低
/api/v1/teacher/notifications	GET	通知列表	中
/api/v1/teacher/notifications/{id}	GET/DELETE	通知详情/删除	中
/api/v1/teacher/notifications/{id}/read	PUT	标记通知已读	中
/api/v1/teacher/notifications/unread-count	GET	未读通知数	中
/api/v1/teacher/notifications/read-all	POST	全部标记已读	低
/api/v1/teacher/growth-records	GET/POST	成长记录列表/创建	高
/api/v1/teacher/growth-records/{id}	GET/PUT/DELETE	成长记录详情/更新/删除	高
/api/v1/teacher/schedules	GET	排课列表	高
/api/v1/teacher/schedules/{id}	GET/PUT/DELETE	排课详情/更新/删除	高
/api/v1/teacher/schedules/timetable	GET	课表视图	高
/api/v1/teacher/schedules/today	GET	今日课表	高
/api/v1/teacher/classes/{classId}/tasks	GET	班级任务	中
/api/v1/teacher/feedbacks	GET	反馈列表	低
/api/v1/teacher/feedbacks/stats	GET	反馈统计	低
/api/v1/teacher/tasks/upcoming	GET	即将到期任务	中
/api/v1/teacher/tasks/{id}/remind	POST	发送提醒	低

---

二、学校端接口对比

✅ 已实现接口 (15 个)

接口路径	方法	功能	状态
/api/v1/school/teachers	GET	教师列表	✅
/api/v1/school/students	GET	学生列表	✅
/api/v1/school/classes	GET	班级列表	✅
/api/v1/school/classes/{id}/students	GET	班级学生	✅
/api/v1/school/classes/{id}/teachers	GET	班级教师	✅
/api/v1/school/classes/{id}/teachers	POST	添加班级教师	✅
/api/v1/school/classes/{id}/teachers/{teacherId}	PUT/DELETE	更新/移除班级教师	✅
/api/v1/school/students/{id}/transfer	POST	学生调班	✅
/api/v1/school/students/{id}/history	GET	调班历史	✅
/api/v1/school/courses	GET	课程列表	✅
/api/v1/school/tasks	GET	任务列表	✅
/api/v1/school/schedules	GET/POST	课表列表/创建	✅
/api/v1/school/schedules/{id}	PUT/DELETE	更新/取消课表	✅
/api/v1/school/settings	GET/PUT	设置管理	✅
/api/v1/school/stats/dashboard	GET	仪表盘统计	✅

❌ 缺失接口 (45 个)

接口路径	方法	功能	优先级
/api/v1/school/teachers/{id}	GET/PUT/DELETE	教师详情/更新/删除	高
/api/v1/school/teachers	POST	创建教师	高
/api/v1/school/teachers/{id}/reset-password	POST	重置教师密码	中
/api/v1/school/students/{id}	GET/PUT/DELETE	学生详情/更新/删除	高
/api/v1/school/students	POST	创建学生	高
/api/v1/school/students/import	POST	批量导入学生	中
/api/v1/school/students/import/template	GET	导入模板	中
/api/v1/school/classes/{id}	GET/PUT/DELETE	班级详情/更新/删除	高
/api/v1/school/classes	POST	创建班级	高
/api/v1/school/parents	GET/POST	家长列表/创建	高
/api/v1/school/parents/{id}	GET/PUT/DELETE	家长详情/更新/删除	高
/api/v1/school/parents/{id}/reset-password	POST	重置家长密码	中
/api/v1/school/parents/{parentId}/children/{studentId}	POST/DELETE	绑定/解绑孩子	高
/api/v1/school/courses/{id}	GET	课程详情	中
/api/v1/school/schedules/timetable	GET	课表视图	高
/api/v1/school/schedules/{id}	GET	排课详情	中
/api/v1/school/schedules/batch	POST	批量创建排课	中
/api/v1/school/schedule-templates	GET/POST	排课模板列表/创建	中
/api/v1/school/schedule-templates/{id}	GET/PUT/DELETE	模板详情/更新/删除	中
/api/v1/school/schedule-templates/{id}/apply	POST	应用排课模板	中
/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}	GET	任务详情	高
/api/v1/school/tasks/{id}/completions	GET	任务完成记录	中
/api/v1/school/tasks	POST	创建任务	高
/api/v1/school/tasks/{id}	PUT/DELETE	更新/删除任务	高
/api/v1/school/tasks/{taskId}/completions/{studentId}	PUT	更新任务完成状态	高
/api/v1/school/tasks/{id}/remind	POST	发送提醒	低
/api/v1/school/task-templates	GET/POST	任务模板列表/创建	中
/api/v1/school/task-templates/{id}	GET/PUT/DELETE	模板详情/更新/删除	中
/api/v1/school/task-templates/default/{taskType}	GET	默认模板	中
/api/v1/school/tasks/from-template	POST	从模板创建任务	中
/api/v1/school/feedbacks	GET	反馈列表	低
/api/v1/school/feedbacks/stats	GET	反馈统计	低
/api/v1/school/operation-logs	GET	操作日志	中
/api/v1/school/operation-logs/stats	GET	日志统计	低
/api/v1/school/stats/teachers	GET	教师统计	中
/api/v1/school/stats/lesson-trend	GET	课时趋势	中
/api/v1/school/stats/courses	GET	课程统计	中
/api/v1/school/export/students	GET	导出学生数据	低
/api/v1/school/export/teachers	GET	导出教师数据	低
/api/v1/school/export/lessons	GET	导出课时数据	低
/api/v1/school/export/growth-records	GET	导出成长记录	低
/api/v1/school/growth-records	GET/POST	成长记录列表/创建	中
/api/v1/school/growth-records/{id}	GET/PUT/DELETE	成长记录详情/更新/删除	中
/api/v1/school/notifications	GET/POST	通知列表/创建	中
/api/v1/school/notifications/{id}	GET/PUT/DELETE	通知详情/更新/删除	中
/api/v1/school/notifications/{id}/read	PUT	标记通知已读	中
/api/v1/school/notifications/unread-count	GET	未读通知数	中
/api/v1/school/notifications/read-all	POST	全部标记已读	低
/api/v1/school/resource-libraries	GET	资源库列表	低
/api/v1/school/resource-items	GET	资源项列表	低
/api/v1/school/course-packages	GET/POST/PUT/DELETE	课程包管理	中
/api/v1/school/tenant-courses	GET/POST/PUT/DELETE	校本课程管理	中

---

三、家长端接口对比

✅ 已实现接口 (4 个)

接口路径	方法	功能	状态
/api/v1/parent/children	GET	孩子列表	✅
/api/v1/parent/children/{id}	GET	孩子详情	✅
/api/v1/parent/children/{childId}/lessons	GET	孩子课时	✅
/api/v1/parent/children/{childId}/tasks	GET	孩子任务	✅
/api/v1/parent/children/{childId}/tasks/{taskId}/feedback	PUT	提交任务反馈	✅

❌ 缺失接口 (2 个)

接口路径	方法	功能	优先级
/api/v1/parent/children/{id}/growth-records	GET	成长记录	中
/api/v1/parent/notifications	GET	通知列表	低
/api/v1/parent/notifications/{id}	GET/PUT	通知详情/已读	低
/api/v1/parent/notifications/unread-count	GET	未读通知数	低
/api/v1/parent/notifications/read-all	POST	全部标记已读	低

---

四、管理员端接口对比

✅ 已实现接口 (8 个)

接口路径	方法	功能	状态
/api/v1/admin/tenants	GET	租户列表	✅
/api/v1/admin/tenants/{id}	GET/PUT/DELETE	租户详情/更新/删除	✅
/api/v1/admin/tenants/{id}/status	PUT	更新租户状态	✅
/api/v1/admin/tenants/{id}/quota	PUT	更新租户配额	✅
/api/v1/admin/courses	GET	系统课程列表	✅
/api/v1/admin/course-packages	GET	课程包列表	✅
/api/v1/admin/resource-libraries	GET	资源库列表	✅
/api/v1/admin/themes	GET	主题列表	✅
/api/v1/admin/settings	GET/PUT	系统设置	✅
/api/v1/admin/stats/dashboard	GET	仪表盘	✅
/api/v1/admin/operation-logs	GET	操作日志	✅

❌ 缺失接口 (12 个)

接口路径	方法	功能	优先级
/api/v1/admin/courses/{id}	GET/PUT/DELETE	课程详情/更新/删除	高
/api/v1/admin/courses	POST	创建系统课程	高
/api/v1/admin/courses/{id}/approve	POST	审批课程	高
/api/v1/admin/courses/{id}/publish	POST	发布课程	中
/api/v1/admin/courses/{id}/unpublish	POST	下架课程	中
/api/v1/admin/course-packages	POST/PUT/DELETE	课程包管理	中
/api/v1/admin/resource-libraries	POST	创建资源库	中
/api/v1/admin/themes	POST	创建主题	低
/api/v1/admin/themes/{id}	PUT	更新主题	低
/api/v1/admin/settings	PUT	更新设置	✅已有
/api/v1/admin/stats/active-tenants	GET	活跃租户	中
/api/v1/admin/stats/lesson-trend	GET	课时趋势	中
/api/v1/admin/stats/popular-courses	GET	热门课程	中
/api/v1/admin/stats/recent-activities	GET	最近活动	中
/api/v1/admin/operation-logs/stats	GET	日志统计	低

---

五、通用接口对比

✅ 已实现接口

接口路径	方法	功能	状态
/api/v1/auth/login	POST	登录	✅
/api/v1/auth/me	GET	获取当前用户	✅
/api/v1/files/upload	POST	上传文件	✅
/api/v1/files/delete	POST/DELETE	删除文件	✅

❌ 缺失接口

接口路径	方法	功能	优先级
/api/v1/auth/logout	POST	登出	低
/api/v1/auth/change-password	POST	修改密码	中
/api/v1/auth/profile	GET/PUT	用户资料	中

---

优先级排序

P0 - 核心功能缺失（必须实现）

1. 学校端 - 用户管理 CRUD

   • 教师/学生/家长的创建、更新、删除
   • 家长与孩子绑定/解绑

2. 学校端 - 班级管理

   • 班级详情/创建/更新/删除

3. 学校端 - 任务管理

   • 任务详情/创建/更新/删除
   • 任务完成状态更新

4. 教师端 - 课表管理

   • 排课列表/详情/创建/更新/删除
   • 课表视图

5. 管理员端 - 课程管理

   • 课程详情/创建/更新/删除
   • 课程审批流程

P1 - 重要功能缺失（优先实现）

1. 学校端 - 排课模板

   • 模板列表/详情/创建/更新/删除
   • 应用排课模板

2. 学校端 - 统计接口

   • 任务统计（总数、按类型、按班级、月度）

3. 教师端 - 成长档案

   • 成长记录列表/创建/详情/更新/删除

4. 学校端 - 通知管理

   • 通知列表/创建/详情/更新/删除
   • 标记已读/未读计数

P2 - 辅助功能缺失（后续实现）

1. 学校端 - 导出功能

   • 导出学生/教师/课时/成长记录数据

2. 学校端 - 操作日志

   • 日志列表/统计

3. 教师端 - 反馈管理

   • 反馈列表/统计

4. 管理员端 - 统计增强

   • 活跃租户/课时趋势/热门课程/最近活动

---

实施建议

阶段一：补充 P0 核心功能

1. 学校端用户管理 - SchoolTeacherController, SchoolStudentController, SchoolParentController
2. 学校端任务管理 - SchoolTaskController 补充
3. 教师端课表管理 - TeacherScheduleController 补充
4. 管理员端课程管理 - AdminCourseController 补充

阶段二：补充 P1 重要功能

1. 学校端排课模板 - SchoolScheduleController 补充模板相关接口
2. 学校端统计接口 - SchoolStatsController 补充
3. 教师端成长档案 - TeacherGrowthController 补充
4. 学校端通知管理 - SchoolNotificationController 补充

阶段三：补充 P2 辅助功能

1. 学校端导出功能 - SchoolExportController 补充
2. 学校端操作日志 - SchoolOperationLogController 补充
3. 管理员端统计增强 - AdminStatsController 补充

---

api-spec.yml 状态

前端 api-spec.yml 文件中已定义了约 120+ 个接口路径，但新后端目前只实现了约 60 个接口。

需要补充的接口数量约 74 个，按优先级分布：

• P0（高优先级）: 约 30 个
• P1（中优先级）: 约 25 个
• P2（低优先级）: 约 19 个

---

下一步行动

1. 立即开始 - 补充 P0 核心功能接口
2. 本周内 - 补充 P1 重要功能接口
3. 下周 - 补充 P2 辅助功能接口
4. 完成后 - 从新后端导出 OpenAPI 规范，更新前端 API 客户端

---

附录：新旧后端 Controller 文件对比

新后端 Controller 列表

controller/
├── admin/
│   ├── AdminCourseController.java
│   ├── AdminCourseLessonController.java
│   ├── AdminCoursePackageController.java
│   ├── AdminOperationLogController.java
│   ├── AdminResourceController.java
│   ├── AdminSettingsController.java
│   ├── AdminStatsController.java
│   ├── AdminTenantController.java
│   └── AdminThemeController.java
├── parent/
│   ├── ParentChildController.java
│   ├── ParentGrowthController.java
│   ├── ParentNotificationController.java
│   └── ParentTaskController.java
├── school/
│   ├── SchoolClassController.java
│   ├── SchoolCourseController.java
│   ├── SchoolCoursePackageController.java
│   ├── SchoolExportController.java
│   ├── SchoolGrowthController.java
│   ├── SchoolNotificationController.java
│   ├── SchoolOperationLogController.java
│   ├── SchoolParentController.java
│   ├── SchoolScheduleController.java
│   ├── SchoolSettingsController.java
│   ├── SchoolStudentController.java
│   ├── SchoolTaskController.java
│   ├── SchoolTeacherController.java
│   └── SchoolStatsController.java
├── teacher/
│   ├── TeacherCourseController.java
│   ├── TeacherCourseLessonController.java
│   ├── TeacherDashboardController.java
│   ├── TeacherGrowthController.java
│   ├── TeacherLessonController.java
│   ├── TeacherNotificationController.java
│   ├── TeacherScheduleController.java
│   ├── TeacherSchoolCourseController.java
│   └── TeacherTaskController.java
├── AuthController.java
└── FileUploadController.java

旧后端 Controller 列表

modules/
├── admin/
│   ├── admin-settings.controller.ts
│   ├── admin-stats.controller.ts
│   ├── admin-tenant.controller.ts
│   ├── admin-course.controller.ts
│   ├── admin-course-package.controller.ts
│   ├── admin-resource.controller.ts
│   └── admin-theme.controller.ts
├── auth/
│   └── auth.controller.ts
├── common/
│   └── operation-log.controller.ts
├── course/
│   └── course.controller.ts
├── course-lesson/
│   └── course-lesson.controller.ts
├── course-package/
│   └── course-package.controller.ts
├── export/
│   └── export.controller.ts
├── file-upload/
│   └── file-upload.controller.ts
├── growth/
│   └── growth.controller.ts
├── lesson/
│   └── lesson.controller.ts
├── notification/
│   └── notification.controller.ts
├── parent/
│   └── parent.controller.ts
├── resource/
│   └── resource.controller.ts
├── school/
│   ├── school.controller.ts (学校管理员主控制器)
│   ├── school-course.controller.ts
│   ├── school-settings.controller.ts
│   ├── school-stats.controller.ts
│   ├── export.controller.ts
│   └── package.controller.ts
├── task/
│   └── task.controller.ts
├── teacher-course/
│   └── teacher-course.controller.ts
├── tenant/
│   └── tenant.controller.ts
└── theme/
    └── theme.controller.ts