kindergarten_java/docs/后端接口补全总结.md

后端接口补全总结

本文档总结了为匹配前端 API 调用而补全的后端接口。

已完成的工作

1. 学校端 (/api/v1/school/*)

班级管理 (/classes)

• GET /list - 获取班级列表（无分页）
• GET /{id}/students - 获取班级学生分页
• GET /{id}/teachers - 获取班级教师列表
• POST /{id}/teachers - 添加班级教师
• PUT /{id}/teachers/{teacherId} - 更新班级教师角色
• DELETE /{id}/teachers/{teacherId} - 移除班级教师

学生管理 (/students)

• POST /{id}/transfer - 学生调班
• GET /{id}/history - 获取学生调班历史

2. 教师端 (/api/v1/teacher/*)

课程管理 (/courses)

• GET /classes - 获取教师的班级列表
• GET /students - 获取教师所有学生分页
• GET /classes/{classId}/students - 获取班级学生分页
• GET /classes/{classId}/teachers - 获取班级教师列表

课时管理 (/lessons)

• POST /{id}/finish - 结束课时（包含实际时长、评分等）
• POST /{lessonId}/students/{studentId}/record - 保存学生评价记录
• GET /{lessonId}/student-records - 获取课程所有学生记录
• POST /{lessonId}/student-records/batch - 批量保存学生评价记录
• POST /{lessonId}/feedback - 提交课程反馈
• GET /{lessonId}/feedback - 获取课程反馈

课表管理 (/schedules)

• GET /timetable - 获取课表（按日期范围）
• GET /today - 获取今日课表
• POST / - 创建课表计划
• PUT /{id} - 更新课表计划
• DELETE /{id} - 取消课表计划

3. 家长端 (/api/v1/parent/*)

孩子信息 (/children)

• GET / - 获取我的孩子（增强返回格式）
• GET /{id} - 获取孩子详情（增强返回格式）
• GET /{childId}/lessons - 获取孩子的课时记录
• GET /{childId}/tasks - 获取孩子的任务（带完成状态）

任务管理 (/tasks)

• PUT /{childId}/tasks/{taskId}/feedback - 提交任务家长反馈

4. 管理员端 (/api/v1/admin/*)

管理员端接口大部分已存在，以下接口需要在未来补充：

• PUT /themes/reorder - 主题重新排序
• PUT /packages/{packageId}/courses - 设置套餐课程
• POST /packages/{packageId}/courses - 添加课程到套餐
• DELETE /packages/{packageId}/courses/{courseId} - 从套餐移除课程
• POST /packages/{id}/submit - 提交审核
• POST /packages/{id}/review - 审核套餐
• POST /packages/{id}/publish - 发布套餐
• POST /packages/{id}/offline - 下架套餐

实体类更新

StudentRecord

新增字段：

• focus - 专注力评分 (1-5)
• participation - 参与度评分 (1-5)
• interest - 兴趣评分 (1-5)
• understanding - 理解度评分 (1-5)

LessonFeedback

新增字段：

• designQuality - 设计质量评分 (1-5)
• participation - 参与度评分 (1-5)
• goalAchievement - 目标达成度评分 (1-5)
• stepFeedbacks - 环节反馈 JSON
• pros - 优点
• suggestions - 建议
• activitiesDone - 完成的活动 JSON

Service 方法更新

ClassService

• getClassList(Long tenantId) - 获取班级列表
• getClassStudents(Long classId, ...) - 获取班级学生分页
• getClassTeachers(Long classId) - 获取班级教师列表
• addClassTeacher(...) - 添加班级教师
• updateClassTeacher(...) - 更新班级教师角色
• removeClassTeacher(...) - 移除班级教师

LessonService

• finishLesson(...) - 结束课时
• saveStudentRecord(...) - 保存学生评价记录
• getStudentRecords(Long lessonId) - 获取课程所有学生记录
• batchSaveStudentRecords(...) - 批量保存学生评价记录
• saveLessonFeedback(...) - 提交课程反馈
• getLessonFeedback(Long lessonId) - 获取课程反馈

StudentService

• transferStudent(...) - 学生调班
• getStudentClassHistory(Long studentId) - 获取学生调班历史

TaskService

• getTaskCompletion(Long taskId, Long studentId) - 获取任务完成记录

数据库迁移需求

需要创建数据库迁移脚本，添加以下字段：

-- student_records 表新增字段
ALTER TABLE student_records ADD COLUMN focus INT COMMENT '专注力评分 (1-5)';
ALTER TABLE student_records ADD COLUMN participation INT COMMENT '参与度评分 (1-5)';
ALTER TABLE student_records ADD COLUMN interest INT COMMENT '兴趣评分 (1-5)';
ALTER TABLE student_records ADD COLUMN understanding INT COMMENT '理解度评分 (1-5)';

-- lesson_feedbacks 表新增字段
ALTER TABLE lesson_feedbacks ADD COLUMN design_quality INT COMMENT '设计质量评分 (1-5)';
ALTER TABLE lesson_feedbacks ADD COLUMN participation INT COMMENT '参与度评分 (1-5)';
ALTER TABLE lesson_feedbacks ADD COLUMN goal_achievement INT COMMENT '目标达成度评分 (1-5)';
ALTER TABLE lesson_feedbacks ADD COLUMN step_feedbacks TEXT COMMENT '环节反馈 JSON';
ALTER TABLE lesson_feedbacks ADD COLUMN pros TEXT COMMENT '优点';
ALTER TABLE lesson_feedbacks ADD COLUMN suggestions TEXT COMMENT '建议';
ALTER TABLE lesson_feedbacks ADD COLUMN activities_done TEXT COMMENT '完成的活动 JSON';

-- student_class_history 表新增字段
ALTER TABLE student_class_history ADD COLUMN reason VARCHAR(255) COMMENT '调班原因';

待补充的接口

学校端

• GET /stats/teachers/active - 获取活跃教师统计
• GET /stats/courses - 获取课程使用统计
• GET /stats/activities - 获取最近活动
• GET /stats/lesson-trend - 课时趋势
• GET /stats/course-distribution - 课程分布
• GET /reports/* - 数据报告接口

教师端

• POST /tasks/{taskId}/remind - 发送任务提醒
• GET /school-courses/* - 校本课程相关接口

家长端

• GET /growth-records/student/{studentId} - 获取孩子成长记录（已存在，路径不同）

注意事项

1. 所有新增的数据库字段需要创建 Flyway 迁移脚本
2. 部分接口的返回数据结构已调整以匹配前端需求
3. 部分 Service 方法需要进一步测试验证
4. 教师端的班级、学生过滤逻辑需要根据实际业务场景优化