kindergarten_java/docs/dev-logs/2026-03-20.md

开发日志 - 2026-03-20

阅读任务模块重写 Phase 1 - 后端基础改造

完成的工作

1. 数据库迁移脚本

• 文件: V43__add_reading_task_features.sql
• 创建 task_feedback 表（评价表）
• 为 task 表添加 related_book_name 字段
• 为 task_completion 表添加 video_url, audio_url 字段

2. 实体类

• TaskFeedback.java - 新增评价实体
• Task.java - 添加 relatedBookName 字段（已存在）
• TaskCompletion.java - 添加新字段（已存在）

3. DTO

• TaskFeedbackRequest.java - 评价请求 DTO
• TaskFeedbackResponse.java - 评价响应 DTO
• TaskCompletionDetailResponse.java - 完成详情响应 DTO
• TaskSubmitRequest.java - 家长提交请求 DTO

4. Service 层

新增:

• TaskFeedbackService.java - 评价服务接口
• TaskFeedbackServiceImpl.java - 评价服务实现

扩展:

• TaskService.java - 添加以下方法:

  • getTaskCompletions() - 获取任务完成情况列表
  • getCompletionDetail() - 获取提交详情
  • submitTaskCompletion() - 家长提交任务完成
  • getSchoolTaskList() - 学校端任务列表（多维度筛选）
  • getTaskDetailForSchool() - 学校端任务详情

• ClassService.java - 添加:

  • getPrimaryClassByStudentId() - 获取学生当前所在班级

5. Controller 层

教师端 (TeacherTaskController.java):

• GET /api/v1/teacher/tasks/{taskId}/completions - 完成情况列表
• GET /api/v1/teacher/tasks/completions/{completionId} - 提交详情
• POST /api/v1/teacher/tasks/completions/{completionId}/feedback - 提交评价
• PUT /api/v1/teacher/tasks/completions/{completionId}/feedback - 修改评价

家长端 (ParentTaskController.java):

• POST /api/v1/parent/tasks/{taskId}/submit - 提交任务完成
• PUT /api/v1/parent/tasks/{taskId}/submit - 修改提交
• GET /api/v1/parent/tasks/completions/{completionId}/feedback - 获取评价
• GET /api/v1/parent/tasks/completions/{completionId} - 获取提交详情

学校端 (SchoolTaskController.java) - 完全重写为只读:

• GET /api/v1/school/reading-tasks - 任务列表（多维度筛选）
• GET /api/v1/school/reading-tasks/{taskId} - 任务详情
• GET /api/v1/school/reading-tasks/{taskId}/completions - 完成情况列表
• GET /api/v1/school/reading-tasks/completions/{completionId} - 学生提交详情
• GET /api/v1/school/reading-tasks/statistics - 统计数据（TODO）

移除的学校端 API:

• POST 创建任务
• PUT 更新任务
• DELETE 删除任务

关键设计决策

1. 学校端只读: 学校端 API 路径从 /api/v1/school/tasks 改为 /api/v1/school/reading-tasks，完全只读

2. 评价结果枚举: EXCELLENT（优秀）/ PASSED（通过）/ NEEDS_WORK（需改进）

3. 完成状态: PENDING（待提交）/ SUBMITTED（已提交）/ REVIEWED（已评价）

4. 文件存储: 继续使用现有 OSS，照片以 JSON 数组存储

---

阅读任务模块重写 Phase 2 - 教师端前端改造 ✅

完成的工作

1. API 类型更新 (src/api/teacher.ts)

• 更新 TaskCompletion 接口添加新字段:
  • photos: string[] - 照片列表
  • videoUrl: string - 视频链接
  • audioUrl: string - 音频链接
  • content: string - 提交内容
  • submittedAt: string - 提交时间
  • reviewedAt: string - 评价时间
  • feedback: TaskFeedback - 关联评价
• 添加 TaskFeedbackDto 接口（评价请求）
• 添加新 API 函数:
  • getTeacherTaskCompletions() - 获取完成情况列表
  • getCompletionDetail() - 获取提交详情
  • submitCompletionFeedback() - 提交评价
  • updateCompletionFeedback() - 修改评价

2. TaskListView.vue 改造

创建任务弹窗:

• 添加 relatedBookName（关联绘本名称）字段
• 编辑任务时加载已有绘本名称

完成情况弹窗改造:

• 状态筛选改为新状态值（PENDING/SUBMITTED/REVIEWED）
• 显示提交内容预览（照片数量、视频、文字内容）
• 统计标签更新为：待提交/已提交/已评价

评价弹窗组件:

• 新增评价弹窗 UI
• 提交内容预览区域（照片、视频、音频、文字）
• 评价结果选择（优秀/通过/需改进）
• 评分组件（1-5 星）
• 评语输入框
• 支持新建和编辑评价

状态显示逻辑:

• getCompletionStatusColor() - 新状态颜色映射
• getCompletionStatusText() - 新状态文本映射
• completionStats computed 使用新状态值

文件变更清单

修改文件:

• src/api/teacher.ts - API 类型和函数
• src/views/teacher/tasks/TaskListView.vue - 教师任务管理页面

TypeScript 编译验证

• src/views/teacher/tasks/TaskListView.vue ✅ 无错误

---

下一步

Phase 3: 家长端前端改造

• 改造提交功能
• 新增查看评价页面

Phase 4: 学校端前端重写

• 重写任务列表页（只读+多维度筛选）
• 新增任务详情页
• 新增学生提交详情页

---

阅读任务模块重写 Phase 3 - 家长端前端改造 ✅

完成的工作

1. API 类型更新 (src/api/parent.ts)

• 添加新的类型定义:
  • TaskCompletionStatus - 完成状态类型
  • FeedbackResult - 评价结果类型
  • TeacherFeedback - 教师评价接口
  • TaskCompletion - 任务完成记录接口
  • TaskSubmitRequest - 提交请求接口
• 更新 TaskWithCompletion 接口添加新字段:
  • photos: string[] - 照片列表
  • videoUrl: string - 视频链接
  • audioUrl: string - 音频链接
  • content: string - 提交内容
  • submittedAt: string - 提交时间
  • reviewedAt: string - 评价时间
  • teacherFeedback: TeacherFeedback - 教师评价
• 添加新 API 函数:
  • submitTaskCompletion() - 提交任务完成
  • updateTaskCompletion() - 修改提交
  • getCompletionDetail() - 获取提交详情
  • getCompletionFeedback() - 获取教师评价

2. TaskListView.vue 完全重写

任务卡片展示:

• 显示关联绘本名称
• 状态标签更新为新状态（待提交/已提交/已评价）
• 已提交内容预览（照片数量、视频、音频、文字）
• 教师评价显示区域（评价结果、评分、评语）

提交功能改造:

• 照片上传（最多9张）
• 视频链接输入
• 音频链接输入
• 阅读心得文字输入
• 支持新建和修改提交

查看评价功能:

• 评价详情弹窗
• 评价结果展示（优秀/通过/需改进）
• 评分显示（1-5星）
• 教师评语展示
• 提交内容回顾（照片网格、链接、文字）
• 图片预览功能

状态驱动操作:

• 待提交状态 → 显示"提交完成"按钮
• 已提交状态 → 显示"修改提交"按钮
• 已评价状态 → 显示"查看评价详情"按钮

文件变更清单

修改文件:

• src/api/parent.ts - API 类型和函数
• src/views/parent/tasks/TaskListView.vue - 家长任务管理页面

TypeScript 编译验证

• src/api/parent.ts ✅ 无错误
• src/views/parent/tasks/TaskListView.vue ✅ 无错误

---

阅读任务模块重写 Phase 4 - 学校端前端重写 ✅

完成的工作

1. API 层更新 (src/api/school.ts)

新增只读接口类型:

• TaskCompletionStatus - 完成状态（PENDING/SUBMITTED/REVIEWED）
• FeedbackResult - 评价结果（EXCELLENT/PASSED/NEEDS_WORK）
• TaskTeacherFeedback - 教师评价接口
• TaskCompletionRecord - 任务完成记录（新设计）
• SchoolTaskQueryParams - 多维度筛选参数

新增 API 函数:

• getReadingTaskList() - 获取任务列表（多维度筛选）
• getReadingTaskDetail() - 获取任务详情
• getReadingTaskCompletions() - 获取完成情况列表
• getCompletionDetail() - 获取提交详情

保留旧接口: 保留 create/update/delete 函数以保持向后兼容

2. TaskListView.vue 完全重写（只读模式）

移除的功能:

• ❌ 创建任务
• ❌ 编辑任务
• ❌ 删除任务
• ❌ 发布任务按钮

新增/改进的功能:

统计卡片:

• 全部任务数
• 进行中任务数
• 已提交数量
• 已评价数量

多维度筛选:

• 关键字搜索
• 任务类型筛选（阅读/活动/作业）
• 任务状态筛选（进行中/草稿/已归档）
• 日期范围筛选
• 排序方式选择

任务列表:

• 卡片式展示
• 显示关联绘本名称
• 显示创建人
• 完成情况统计（待提交/已提交/已评价）
• 完成率进度条
• 点击查看详情

任务详情弹窗:

• 基本信息（类型、状态、时间等）
• 关联绘本
• 完成情况统计
• 查看完成列表入口

完成情况列表弹窗:

• 学生信息（姓名、班级、头像）
• 状态标签
• 提交内容预览（照片数量、视频、音频）
• 教师评价显示
• 筛选和分页
• 查看详情按钮

提交详情弹窗:

• 学生信息卡片
• 提交状态显示
• 照片网格展示（支持预览）
• 视频/音频链接
• 阅读心得文字
• 提交时间
• 教师评价详情（结果、评分、评语）
• 评价时间

文件变更清单

修改文件:

• src/api/school.ts - 新增只读接口类型和函数
• src/views/school/tasks/TaskListView.vue - 完全重写为只读模式

TypeScript 编译验证

• src/api/school.ts ✅ 无错误
• src/views/school/tasks/TaskListView.vue ✅ 无错误

---

总结

阅读任务模块重写全部完成 ✅

Phase	端	状态
Phase 1	后端基础改造	✅ 完成
Phase 2	教师端前端	✅ 完成
Phase 3	家长端前端	✅ 完成
Phase 4	学校端前端	✅ 完成

关键设计决策

1. 学校端只读: 学校端 API 路径改为 /api/v1/school/reading-tasks，完全只读
2. 新状态值: PENDING → SUBMITTED → REVIEWED
3. 评价结果: EXCELLENT（优秀）/ PASSED（通过）/ NEEDS_WORK（需改进）
4. 多维度筛选: 支持关键字、类型、状态、日期范围、排序等筛选条件

---

Last updated: 2026-03-20 19:30