kindergarten_java/补全接口修复总结.md

# API 接口补全修复总结

## 修复日期
2026-03-09

## 问题修复

### Bug 修复
修复了 `TaskServiceImpl.java` 中使用 `ClassEntity` 的错误，改为使用 `Clazz`（因为 `class` 是 Java 关键字，项目中使用 `Clazz` 作为班级实体名称）。

**修改位置**: `reading-platform-java/src/main/java/com/reading/platform/service/impl/TaskServiceImpl.java`
- 第 284 行：`List<ClassEntity> classes` → `List<Clazz> classes`
- 第 288 行：`for (ClassEntity cls : classes)` → `for (Clazz cls : classes)`

### 数据库迁移
新增数据库迁移脚本 `V7__fix_schedule_plans.sql`，为 `schedule_plans` 表添加以下字段：
- `course_id` - 课程 ID
- `teacher_id` - 教师 ID
- `day_of_week` - 星期几 (1-7)
- `period` - 节次
- `start_time` - 开始时间
- `end_time` - 结束时间
- `location` - 教室/地点
- `note` - 备注

---

## 已补全的 API 接口

### 1. 任务管理接口

#### 新增 Service 方法 (TaskService)
```java
// 任务统计
Map<String, Object> getTaskStats(Long tenantId);
Map<String, Object> getStatsByType(Long tenantId);
List<Map<String, Object>> getStatsByClass(Long tenantId);
List<Map<String, Object>> getMonthlyStats(Long tenantId, Integer months);

// 任务完成情况
Page<TaskCompletion> getTaskCompletions(Long tenantId, Long taskId, Integer pageNum, Integer pageSize, String status);
TaskCompletion updateTaskCompletion(Long tenantId, Long taskId, Long studentId, String status, String feedback);

// 任务模板
Page<TaskTemplate> getTemplatePage(Long tenantId, Integer pageNum, Integer pageSize, String keyword, String type);
TaskTemplate getTemplateById(Long tenantId, Long id);
TaskTemplate getDefaultTemplate(Long tenantId, String taskType);
TaskTemplate createTemplate(Long tenantId, Long creatorId, TaskTemplateCreateRequest request);
TaskTemplate updateTemplate(Long tenantId, Long id, TaskTemplateUpdateRequest request);
void deleteTemplate(Long tenantId, Long id);
Task createTaskFromTemplate(Long tenantId, Long creatorId, String creatorRole, CreateTaskFromTemplateRequest request);
```

#### 新增 Controller 端点

**SchoolTaskController** (学校管理员 - 任务管理):
- `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` - 从模板创建任务

**TeacherTaskController** (教师端 - 任务管理):
- `GET /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` - 获取任务完成情况分页
- `PUT /api/v1/teacher/tasks/:taskId/completions/:studentId` - 更新任务完成状态
- `GET /api/v1/teacher/task-templates` - 获取任务模板列表
- `GET /api/v1/teacher/task-templates/:id` - 获取单个模板
- `GET /api/v1/teacher/task-templates/default/:taskType` - 获取默认模板
- `POST /api/v1/teacher/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. 排课和课表接口

#### 新增 Service 方法 (ScheduleService)
```java
Page<SchedulePlan> getSchedulePlans(int pageNum, int pageSize, Long tenantId, Long classId, LocalDate startDate, LocalDate endDate);
List<Map<String, Object>> getTimetable(Long tenantId, LocalDate startDate, LocalDate endDate, Long classId);
List<SchedulePlan> batchCreateSchedules(Long tenantId, Long userId, List<SchedulePlanCreateRequest> requests);
ScheduleTemplate updateScheduleTemplate(Long id, ScheduleTemplate template);
List<SchedulePlan> applyScheduleTemplate(Long tenantId, Long templateId, ScheduleTemplateApplyRequest request);
```

#### 新增 Controller 端点 (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. 实体类增强

**SchedulePlan** (新增字段):
- `courseId` - 课程 ID
- `teacherId` - 教师 ID
- `dayOfWeek` - 星期几 (1-7)
- `period` - 节次
- `startTime` - 开始时间
- `endTime` - 结束时间
- `location` - 教室/地点
- `note` - 备注

---

### 5. 新增 DTO

**TaskTemplateCreateRequest** - 任务模板创建请求
```java
- name: 模板名称
- description: 模板描述
- type: 任务类型
- content: 任务内容模板
- isPublic: 是否公共模板
```

**TaskTemplateUpdateRequest** - 任务模板更新请求

**CreateTaskFromTemplateRequest** - 从模板创建任务请求
```java
- templateId: 模板 ID
- targetIds: 目标 ID 列表
- targetType: 目标类型 (CLASS/STUDENT)
- startDate: 开始日期
- endDate: 截止日期
```

**SchedulePlanCreateRequest** - 课表计划创建请求
```java
- classId: 班级 ID
- courseId: 课程 ID
- teacherId: 授课教师 ID
- dayOfWeek: 星期几
- period: 节次
- startTime: 开始时间
- endTime: 结束时间
- location: 教室/地点
- note: 备注
- startDate: 开始日期
- endDate: 结束日期
```

**ScheduleTemplateApplyRequest** - 课表模板应用请求
```java
- classId: 班级 ID
- startDate: 应用开始日期
- weeks: 应用周数
```

---

## 文件变更列表

### 新增文件 (7 个)
1. `dto/request/TaskTemplateCreateRequest.java`
2. `dto/request/TaskTemplateUpdateRequest.java`
3. `dto/request/CreateTaskFromTemplateRequest.java`
4. `dto/request/SchedulePlanCreateRequest.java`
5. `dto/request/ScheduleTemplateApplyRequest.java`
6. `controller/school/SchoolNotificationController.java`
7. `resources/db/migration/V7__fix_schedule_plans.sql`

### 修改文件 (7 个)
1. `service/TaskService.java` - 添加统计和模板方法接口
2. `service/impl/TaskServiceImpl.java` - 实现统计和模板逻辑 + 修复 ClassEntity bug
3. `service/ScheduleService.java` - 添加课表相关方法
4. `entity/SchedulePlan.java` - 添加课程、教师等字段
5. `controller/school/SchoolTaskController.java` - 添加统计和模板端点
6. `controller/teacher/TeacherTaskController.java` - 添加统计和模板端点
7. `controller/school/SchoolScheduleController.java` - 添加课表和模板端点

---

## 仍需补全的接口（下一步建议）

### 高优先级
1. **成长档案接口** - 按学生/班级查询
2. **教师端课时反馈** - 完成课时、学生记录、反馈接口
3. **班级管理** - 班级教师/学生管理、学生调班

### 中优先级
1. **统计报告** - 学校统计、报告导出
2. **导出接口增强** - 带日期范围参数
3. **管理员课程审核** - 提交、审核、发布流程

---

## 使用说明

1. 运行数据库迁移：
```bash
# Flyway 会在应用启动时自动运行 V7 迁移脚本
```

2. 编译项目：
```bash
cd reading-platform-java
mvn clean compile
```

3. 启动应用后，访问 API 文档：
```
http://localhost:8080/doc.html
```