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)` - 获取任务完成记录

## 数据库迁移需求

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

```sql
-- 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. 教师端的班级、学生过滤逻辑需要根据实际业务场景优化