En
0d4275b235
主要变更： 1. 所有 Entity/DTO/VO 添加 @Schema 注解，完善 API 文档 2. 新增前端 API 封装模块 (src/apis)，包含 fetch.ts 和 apis.ts 3. 生成完整的 TypeScript 类型定义（100+ 个模型） 4. pom.xml 添加 Maven 编译配置和 UTF-8 编码支持 5. 更新 CLAUDE.md 开发文档，新增接口规范和 Swagger 注解规范 6. 清理旧的文档文件和 Flyway 迁移脚本 技术细节： - 后端：27 个实体类 + 所有 DTO/Response 添加 Swagger 注解 - 前端：新增 orval 生成的 API 客户端类型 - 构建：配置 Maven compiler plugin 和 Spring Boot 插件的 JVM 参数 - 数据库：新增 schema 导出文件，删除旧 Flyway 迁移脚本 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
158 lines
6.0 KiB
Markdown
158 lines
6.0 KiB
Markdown
# 后端接口补全总结
|
|
|
|
本文档总结了为匹配前端 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. 教师端的班级、学生过滤逻辑需要根据实际业务场景优化
|