kindergarten_java/docs/design/reading-task-design-v2.md

阅读任务模块 - 详细设计文档

版本：v2.0 日期：2026-03-20 状态：待开发

---

目录

1. 需求背景与目标
2. 用户角色与权限
3. 核心业务流程
4. 功能需求详解
5. 数据模型设计
6. API 接口设计
7. UI/UX 设计规范
8. 代码重构计划
9. 开发任务清单
10. 验收标准

---

一、需求背景与目标

1.1 业务背景

幼儿园教师在完成绘本课后，需要给学生布置家庭阅读任务，建议孩子回家自主阅读相关绘本。本模块旨在实现：

• 教师端：创建/管理阅读任务，查看家长提交，给出评价反馈
• 家长端：接收任务通知，提交完成证明（照片/视频/心得），查看教师评价
• 学校端：查看全校阅读任务数据，统计分析，监督教学质量

1.2 产品目标

目标	指标	优先级
简化任务发布流程	教师发布任务时间 < 2分钟	P0
提升家长参与度	任务完成率 > 80%	P0
增强家校互动	教师反馈率 > 90%	P0
数据可追溯	学校可查看所有历史记录	P1

1.3 本期范围

包含	不包含（后续迭代）
✅ 教师端任务管理	❌ 家长端绘本阅读功能
✅ 家长端任务查看/提交（照片/视频/心得）	❌ 绘本付费订阅
✅ 教师端评价反馈（评语/评分）	❌ 学生端独立 App
✅ 学校端数据查看（只读）	❌ 绘本库/自动推荐
✅ 关联绘本名称（手动填写）	❌

1.4 核心设计原则

1. 学校端只读：学校端不创建/编辑任务，仅查看和统计
2. 教师端闭环：创建 → 查看 → 评价 → 推送反馈
3. 家长端简洁：查看 → 提交 → 接收反馈

---

二、用户角色与权限

2.1 角色定义

角色	使用端	职责描述
教师	教师端 (Web)	创建和管理阅读任务，查看提交内容，评价反馈
家长	家长端 (H5)	接收任务，提交完成证明，查看教师评价
学校管理员	学校端 (Web)	查看全校数据，统计分析，导出报表（只读）
学生	-	任务执行对象，通过家长端操作

2.2 权限矩阵

功能	教师	家长	学校
创建/编辑/删除任务	✅	❌	❌
查看自己创建的任务	✅	-	-
查看孩子的任务	-	✅	-
查看全校所有任务	-	-	✅
提交完成证明	-	✅	❌
查看提交内容	✅	自己的	✅
评价反馈	✅	❌	❌
查看评价内容	-	✅	✅
发送提醒	✅	-	❌
导出报表	-	-	✅

---

三、核心业务流程

3.1 主流程图

┌─────────────────────────────────────────────────────────────────────────┐
│                           阅读任务完整流程                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐                                                       │
│  │ 1. 教师创建任务│                                                      │
│  └──────┬───────┘                                                       │
│         │                                                               │
│         ▼                                                               │
│  ┌──────────────┐      ┌──────────────┐                                │
│  │ 2. 系统推送   │─────►│ 3. 家长接收   │                                │
│  │    通知家长   │      │    任务通知   │                                │
│  └──────────────┘      └──────┬───────┘                                │
│                               │                                         │
│                               ▼                                         │
│                        ┌──────────────┐                                 │
│                        │ 4. 家长陪伴   │                                 │
│                        │    孩子阅读   │                                 │
│                        └──────┬───────┘                                 │
│                               │                                         │
│                               ▼                                         │
│                        ┌──────────────┐                                 │
│                        │ 5. 家长提交   │                                 │
│                        │ 照片/视频/心得│                                 │
│                        └──────┬───────┘                                 │
│                               │                                         │
│         ┌─────────────────────┴─────────────────────┐                   │
│         ▼                                           ▼                   │
│  ┌──────────────┐                          ┌──────────────┐              │
│  │ 6a. 教师收到  │                          │ 6b. 学校可查看│              │
│  │    提交通知   │                          │    提交记录   │              │
│  └──────┬───────┘                          └──────────────┘              │
│         │                                                               │
│         ▼                                                               │
│  ┌──────────────┐                                                       │
│  │ 7. 教师评价   │                                                       │
│  │ 优秀/通过/需改进│                                                      │
│  │ + 评语 + 评分 │                                                       │
│  └──────┬───────┘                                                       │
│         │                                                               │
│         ▼                                                               │
│  ┌──────────────┐                                                       │
│  │ 8. 系统推送   │                                                       │
│  │    评价通知   │                                                       │
│  └──────┬───────┘                                                       │
│         │                                                               │
│         ▼                                                               │
│  ┌──────────────┐                                                       │
│  │ 9. 家长查看   │                                                       │
│  │    教师评价   │                                                       │
│  └──────────────┘                                                       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

3.2 状态流转

任务状态

DRAFT（草稿）→ PUBLISHED（已发布）→ ARCHIVED（已归档）

完成记录状态

PENDING（待提交）→ SUBMITTED（已提交）→ REVIEWED（已评价）

评价结果

EXCELLENT（优秀） / PASSED（通过） / NEEDS_WORK（需改进）

---

四、功能需求详解

4.1 教师端

4.1.1 任务列表页

页面路径：/teacher/tasks

功能点：

功能	描述	优先级
任务列表	卡片式展示，显示标题、类型、状态、时间、完成率	P0
状态筛选	进行中/草稿/已归档	P0
类型筛选	阅读/活动/作业	P0
关键字搜索	按标题搜索	P0
新建任务	打开创建弹窗	P0
编辑任务	修改任务内容（未截止前）	P0
删除任务	确认后删除	P0
归档任务	将进行中任务归档	P1
发送提醒	向未完成家长发送提醒	P1
查看完成情况	打开完成情况弹窗	P0

数据字段：

interface TeacherTask {
  id: number;
  title: string;
  description?: string;
  taskType: 'READING' | 'ACTIVITY' | 'HOMEWORK';
  relatedBookName?: string;  // 关联绘本名称
  relatedCourseId?: number;
  relatedCourseName?: string;
  targetType: 'CLASS' | 'STUDENT';
  targetIds: number[];
  targetNames?: string[];    // 班级或学生名称
  targetCount: number;       // 目标人数
  completionCount: number;   // 已提交人数
  feedbackCount: number;     // 已评价人数
  startDate: string;
  endDate: string;
  status: 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
  createdAt: string;
}

4.1.2 创建/编辑任务弹窗

功能点：

字段	类型	必填	描述
任务标题	文本	✅	最多50字
任务描述	文本域	❌	最多500字
任务类型	下拉	✅	阅读/活动/作业
关联绘本	文本	❌	新增，手动填写绘本名称
目标类型	单选	✅	班级/学生
选择目标	多选	✅	根据类型显示班级或学生列表
关联课程	下拉	❌	可选，关联课程包
任务时间	日期范围	✅	开始日期-截止日期

4.1.3 完成情况弹窗（重点改造）

功能点：

功能	描述	优先级
状态统计	待完成/已提交/已评价 数量	P0
状态筛选	按提交状态筛选	P0
学生列表	显示学生姓名、班级、提交状态	P0
查看提交内容	点击查看照片/视频/心得详情	P0
快捷评价	一键标记 优秀/通过/需改进	P0
详细评价	弹窗填写评语和评分	P0

学生完成记录数据：

interface TaskCompletion {
  id: number;
  taskId: number;
  studentId: number;
  student: {
    id: number;
    name: string;
    avatar?: string;
    gender: 'MALE' | 'FEMALE';
    class: {
      id: number;
      name: string;
    };
  };
  status: 'PENDING' | 'SUBMITTED' | 'REVIEWED';
  photos: string[];          // 照片URL数组
  videoUrl?: string;         // 视频URL
  audioUrl?: string;         // 语音URL
  content?: string;          // 文字心得
  submittedAt?: string;      // 提交时间
  reviewedAt?: string;       // 评价时间
  feedback?: TaskFeedback;   // 教师评价
}

interface TaskFeedback {
  id: number;
  completionId: number;
  teacherId: number;
  teacherName: string;
  result: 'EXCELLENT' | 'PASSED' | 'NEEDS_WORK';
  rating?: number;           // 1-5星，可选
  comment?: string;          // 评语
  createdAt: string;
}

4.1.4 提交详情+评价弹窗（新增）

┌─────────────────────────────────────────────────────────────────┐
│  张小明的提交 - 《好饿的毛毛虫》                         [返回]  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  📷 阅读照片                                                    │
│  ┌─────┐ ┌─────┐ ┌─────┐                                       │
│  │ 📸  │ │ 📸  │ │ 📸  │  点击查看大图                          │
│  └─────┘ └─────┘ └─────┘                                       │
│                                                                 │
│  🎬 阅读视频（如有）                                            │
│  ┌───────────────────────────────────────────────────────┐     │
│  │                    ▶️ 播放视频                         │     │
│  └───────────────────────────────────────────────────────┘     │
│                                                                 │
│  📝 阅读心得                                                    │
│  "孩子很喜欢这本书，读了好几遍..."                               │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  教师评价                                                       │
│                                                                 │
│  评价结果:                                                      │
│  [⭐ 优秀] [✓ 通过] [⚠ 需改进]                                  │
│                                                                 │
│  评分(可选): ⭐ ⭐ ⭐ ⭐ ⭐                                        │
│                                                                 │
│  评语:                                                          │
│  ┌───────────────────────────────────────────────────────┐     │
│  │ 阅读很认真，能够复述故事内容，继续保持！               │     │
│  └───────────────────────────────────────────────────────┘     │
│                                                                 │
│                              [取消]  [保存并发送给家长]          │
└─────────────────────────────────────────────────────────────────┘

---

4.2 家长端（H5）

4.2.1 任务列表页

页面路径：/parent/tasks

功能点：

功能	描述	优先级
任务列表	卡片式展示，按截止时间排序	P0
状态显示	待完成/已提交/已评价	P0
截止倒计时	显示剩余时间，即将截止标红	P1
孩子切换	多孩子家庭切换查看	P0
点击进入详情	跳转任务详情页	P0

任务卡片显示：

┌───────────────────────────────────────────────┐
│ ⏰ 明天截止                           [待完成] │
│                                               │
│ 《好饿的毛毛虫》阅读任务                        │
│ 李老师 | 大一班                                │
│                                               │
│                          [去完成 →]            │
└───────────────────────────────────────────────┘

┌───────────────────────────────────────────────┐
│ ✅ 已完成                          优秀 ⭐⭐⭐⭐⭐ │
│                                               │
│ 《小蝌蚪找妈妈》阅读任务                        │
│ 王老师 | 大一班                                │
│                                               │
│                          [查看反馈 →]          │
└───────────────────────────────────────────────┘

4.2.2 任务提交页（重写）

页面路径：/parent/tasks/:id/submit

功能点：

功能	描述	优先级
任务信息展示	标题、描述、绘本名称、截止时间	P0
拍照上传	支持拍照或从相册选择，最多9张	P0
视频上传	录制或选择视频，限60秒	P0
语音上传	录制语音，限60秒（P1）	P1
文字心得	文本输入，最多500字	P0
预览已上传内容	显示已上传的照片/视频缩略图	P0
删除已上传内容	可删除已上传的照片/视频	P0
提交按钮	校验后提交	P0
重新提交	截止前可修改	P0

提交表单数据：

interface TaskSubmitRequest {
  photos: string[];      // OSS URL数组
  videoUrl?: string;     // OSS URL
  audioUrl?: string;     // OSS URL
  content?: string;      // 文字心得
}

4.2.3 评价查看页（新增）

页面路径：/parent/tasks/:id/feedback

显示内容：

• 教师评价结果（优秀/通过/需改进）
• 评分（如有）
• 教师评语
• 评价时间

---

4.3 学校端- 只读

重要：学校端不能创建/编辑/删除任务，仅查看数据

4.3.1 任务列表页（重写）

页面路径：/school/reading-tasks

筛选功能（核心）：

筛选项	类型	说明
时间范围	快捷+自定义	今日/本周/本月/本学期/自定义日期
班级	多选下拉	支持选择多个班级
教师	多选下拉	支持选择多个教师
任务类型	单选下拉	阅读/活动/作业/全部
任务状态	单选下拉	进行中/已截止/已归档/全部
完成率	单选下拉	高(>80%)/中(50-80%)/低(<50%)/全部
搜索	文本框	按标题搜索

已选条件显示：

• 在筛选区下方显示已选条件的标签
• 点击标签可移除该条件
• 提供"清空全部"按钮

列表字段：

列	说明	排序
任务标题	点击可查看详情	✅
发布教师	教师姓名	✅
班级	目标班级（多个用逗号分隔）	-
类型	阅读/活动/作业	-
目标人数	学生总数	-
提交数	已提交/总人数	✅
完成率	进度条	✅
反馈率	教师已评价比例	✅
发布时间	yyyy-MM-dd	✅
截止时间	yyyy-MM-dd	✅
状态	进行中/已截止	-
操作	查看详情	-

4.3.2 任务详情页（新增）

页面路径：/school/reading-tasks/:id

显示内容：

1. 基本信息

   • 任务标题、描述
   • 发布教师、班级
   • 任务类型、关联绘本
   • 发布时间、截止时间

2. 完成统计

   • 目标人数、提交人数、完成率
   • 待完成/已提交/已评价 数量

3. 学生完成列表（可下钻查看）

   • 学生姓名、班级
   • 提交时间、提交状态
   • 评价结果（如有）
   • 操作：查看提交内容

4.3.3 学生提交详情页（新增）

页面路径：/school/reading-tasks/:taskId/completions/:completionId

显示内容：

• 提交的照片（可放大查看）
• 提交的视频（可播放）
• 提交的心得文字
• 教师评价（如有）

注意：学校端此页面为纯只读，不能进行任何编辑操作

---

五、数据模型设计

5.1 表结构变更

5.1.1 Task 表 - 新增字段

ALTER TABLE task ADD COLUMN related_book_name VARCHAR(200) COMMENT '关联绘本名称';

5.1.2 TaskCompletion 表 - 扩展字段

-- 修改 photos 字段类型（如果原来是 VARCHAR）
ALTER TABLE task_completion MODIFY COLUMN photos JSON COMMENT '照片URL数组(JSON)';

-- 新增字段
ALTER TABLE task_completion ADD COLUMN video_url VARCHAR(500) COMMENT '视频URL';
ALTER TABLE task_completion ADD COLUMN audio_url VARCHAR(500) COMMENT '语音URL';

5.1.3 TaskFeedback 表 - 新建

CREATE TABLE task_feedback (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键',
    completion_id BIGINT NOT NULL COMMENT '完成记录ID',
    task_id BIGINT NOT NULL COMMENT '任务ID（冗余，方便查询）',
    student_id BIGINT NOT NULL COMMENT '学生ID（冗余）',
    teacher_id BIGINT NOT NULL COMMENT '教师ID',
    result VARCHAR(20) NOT NULL COMMENT '评价结果：EXCELLENT/PASSED/NEEDS_WORK',
    rating INT COMMENT '评分 1-5（可选）',
    comment TEXT COMMENT '评语',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    deleted_at DATETIME DEFAULT NULL COMMENT '删除时间',

    INDEX idx_completion_id (completion_id),
    INDEX idx_task_id (task_id),
    INDEX idx_teacher_id (teacher_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='任务评价表';

5.2 实体类定义

Task.java（变更）

@Data
@TableName("task")
public class Task extends BaseEntity {
    private Long tenantId;
    private String title;
    private String description;
    private String type;              // taskType
    private String relatedBookName;   // 【新增】关联绘本名称
    private Long courseId;
    private Long creatorId;
    private String creatorRole;
    private LocalDate startDate;
    private LocalDate dueDate;
    private String status;
    private String attachments;
}

TaskCompletion.java（变更）

@Data
@TableName("task_completion")
public class TaskCompletion extends BaseEntity {
    private Long taskId;
    private Long studentId;
    private String status;
    private String photos;      // JSON数组
    private String videoUrl;    // 【新增】
    private String audioUrl;    // 【新增】
    private String content;
    private LocalDateTime submittedAt;
    private LocalDateTime reviewedAt;
}

TaskFeedback.java（新增）

@Data
@TableName("task_feedback")
public class TaskFeedback extends BaseEntity {
    private Long completionId;
    private Long taskId;
    private Long studentId;
    private Long teacherId;
    private String result;      // EXCELLENT/PASSED/NEEDS_WORK
    private Integer rating;     // 1-5，可选
    private String comment;
}

5.3 DTO 定义

TaskCompletionResponse.java

@Data
@Builder
public class TaskCompletionResponse {
    private Long id;
    private Long taskId;
    private StudentInfo student;
    private String status;
    private List<String> photos;
    private String videoUrl;
    private String audioUrl;
    private String content;
    private LocalDateTime submittedAt;
    private LocalDateTime reviewedAt;
    private TaskFeedbackResponse feedback;

    @Data
    public static class StudentInfo {
        private Long id;
        private String name;
        private String avatar;
        private String gender;
        private ClassInfo classInfo;

        @Data
        public static class ClassInfo {
            private Long id;
            private String name;
        }
    }
}

TaskFeedbackRequest.java

@Data
public class TaskFeedbackRequest {
    @NotBlank(message = "评价结果不能为空")
    private String result;  // EXCELLENT/PASSED/NEEDS_WORK

    @Min(1) @Max(5)
    private Integer rating;

    @Size(max = 500, message = "评语最多500字")
    private String comment;
}

TaskFeedbackResponse.java

@Data
@Builder
public class TaskFeedbackResponse {
    private Long id;
    private String result;
    private String resultText;  // 优秀/通过/需改进
    private Integer rating;
    private String comment;
    private Long teacherId;
    private String teacherName;
    private LocalDateTime createdAt;
}

---

六、API 接口设计

6.1 教师端 API

6.1.1 任务管理

方法	路径	说明	变更
GET	/api/v1/teacher/tasks	任务列表	无变更
POST	/api/v1/teacher/tasks	创建任务	新增 relatedBookName
GET	/api/v1/teacher/tasks/{id}	任务详情	无变更
PUT	/api/v1/teacher/tasks/{id}	更新任务	新增 relatedBookName
DELETE	/api/v1/teacher/tasks/{id}	删除任务	无变更
POST	/api/v1/teacher/tasks/{id}/archive	归档任务	新增
POST	/api/v1/teacher/tasks/{id}/remind	发送提醒	无变更

6.1.2 完成情况与评价（重点变更）

方法	路径	说明	变更
GET	/api/v1/teacher/tasks/{id}/completions	完成情况列表	返回内容扩展
GET	/api/v1/teacher/completions/{id}	提交详情	新增
POST	/api/v1/teacher/completions/{id}/feedback	提交评价	新增
PUT	/api/v1/teacher/completions/{id}/feedback	修改评价	新增

请求/响应示例

创建任务请求：

{
  "title": "《好饿的毛毛虫》亲子阅读",
  "description": "和孩子一起阅读这本经典绘本...",
  "taskType": "READING",
  "relatedBookName": "《好饿的毛毛虫》",
  "targetType": "CLASS",
  "targetIds": [1, 2],
  "relatedCourseId": 10,
  "startDate": "2026-03-20",
  "endDate": "2026-03-27"
}

提交评价请求：

{
  "result": "EXCELLENT",
  "rating": 5,
  "comment": "阅读很认真，能够完整复述故事内容，继续保持！"
}

6.2 家长端 API

方法	路径	说明	变更
GET	/api/v1/parent/tasks	孩子的任务列表	无变更
GET	/api/v1/parent/tasks/{id}	任务详情	无变更
POST	/api/v1/parent/tasks/{id}/submit	提交完成	重写，支持文件
PUT	/api/v1/parent/tasks/{id}/submit	修改提交	新增
GET	/api/v1/parent/completions/{id}/feedback	查看评价	新增

请求示例

提交完成请求：

{
  "photos": [
    "https://oss.example.com/photo1.jpg",
    "https://oss.example.com/photo2.jpg"
  ],
  "videoUrl": "https://oss.example.com/video.mp4",
  "content": "孩子很喜欢这本书，读了好几遍..."
}

6.3 学校端 API

方法	路径	说明	变更
GET	/api/v1/school/reading-tasks	任务列表（支持多维度筛选）	重写
GET	/api/v1/school/reading-tasks/{id}	任务详情	新增
GET	/api/v1/school/reading-tasks/{id}/completions	完成情况列表	新增
GET	/api/v1/school/completions/{id}	学生提交详情	新增
GET	/api/v1/school/reading-tasks/statistics	统计数据	新增
GET	/api/v1/school/reading-tasks/export	导出报表	新增

学校端筛选参数

interface SchoolTaskQueryParams {
  // 分页
  pageNum?: number;
  pageSize?: number;

  // 时间筛选
  dateType?: 'today' | 'week' | 'month' | 'semester' | 'custom';
  startDate?: string;  // 自定义开始日期
  endDate?: string;    // 自定义结束日期

  // 组织筛选
  classIds?: number[];   // 班级ID数组
  teacherIds?: number[]; // 教师ID数组

  // 状态筛选
  taskType?: 'READING' | 'ACTIVITY' | 'HOMEWORK';
  taskStatus?: 'PUBLISHED' | 'ARCHIVED';
  completionRate?: 'high' | 'medium' | 'low';

  // 搜索
  keyword?: string;

  // 排序
  sortBy?: 'createdAt' | 'completionRate' | 'feedbackRate';
  sortOrder?: 'asc' | 'desc';
}

---

七、UI/UX 设计规范

7.1 评价结果颜色规范

结果	颜色	标签样式
EXCELLENT（优秀）	绿色 #52c41a	<a-tag color="success">
PASSED（通过）	蓝色 #1890ff	<a-tag color="blue">
NEEDS_WORK（需改进）	橙色 #fa8c16	<a-tag color="warning">

7.2 评分星星

• 使用 Ant Design 的 <a-rate> 组件
• 默认禁用（仅展示），在评价时可编辑
• 颜色：金色 #fadb14

7.3 照片上传组件

• 使用 Ant Design 的 <a-upload> 组件
• 列表模式：list-type="picture-card"
• 最大数量：9张
• 支持预览和删除

7.4 视频上传

• 限制时长：60秒
• 支持格式：mp4, mov
• 文件大小：不超过 50MB

7.5 筛选组件规范

时间快捷选择：
┌─────────────────────────────────────────────────────┐
│  [今日] [本周 ✓] [本月] [本学期] [自定义 ▼]        │
└─────────────────────────────────────────────────────┘

多选下拉：
┌─────────────────────────────────────────────────────┐
│  班级 ▼                                             │
│  ┌───────────────────────────────────────────────┐ │
│  │ ☑ 全选                                         │ │
│  │ ☑ 大一班                                       │ │
│  │ ☑ 大二班                                       │ │
│  │ ☐ 中一班                                       │ │
│  └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

已选条件标签：
┌─────────────────────────────────────────────────────┐
│  已选条件:                                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │ 本周  ✕  │ │ 大一班 ✕ │ │ 李老师 ✕ │            │
│  └──────────┘ └──────────┘ └──────────┘  [清空全部] │
└─────────────────────────────────────────────────────┘

---

八、代码重构计划

8.1 需要删除的文件/代码

文件	原因
school/TaskListView.vue	完全重写，改为只读模式
api/school.ts 中的 createSchoolTask, updateSchoolTask, deleteSchoolTask	学校端不再需要这些API

8.2 需要修改的文件

文件	修改内容
entity/Task.java	新增 relatedBookName 字段
entity/TaskCompletion.java	新增 videoUrl, audioUrl 字段
dto/request/TaskCreateRequest.java	新增 relatedBookName 字段
dto/response/TaskResponse.java	新增 relatedBookName 字段
service/TaskService.java	新增评价相关方法
service/impl/TaskServiceImpl.java	实现评价相关方法
controller/teacher/TeacherTaskController.java	新增评价API
controller/parent/ParentTaskController.java	重写提交API，新增查看评价API
controller/school/SchoolTaskController.java	重写为只读API
views/teacher/tasks/TaskListView.vue	新增关联绘本字段，改造评价功能
views/parent/tasks/TaskListView.vue	改造提交功能

8.3 需要新增的文件

文件	用途
entity/TaskFeedback.java	评价实体类
mapper/TaskFeedbackMapper.java	评价Mapper
service/TaskFeedbackService.java	评价服务接口
service/impl/TaskFeedbackServiceImpl.java	评价服务实现
dto/request/TaskFeedbackRequest.java	评价请求DTO
dto/response/TaskFeedbackResponse.java	评价响应DTO
dto/response/TaskCompletionResponse.java	完成记录响应DTO（扩展）
common/mapper/TaskFeedbackMapper.java	MapStruct Mapper
views/school/reading-tasks/TaskListView.vue	学校端任务列表（重写）
views/school/reading-tasks/TaskDetailView.vue	学校端任务详情（新增）
views/school/reading-tasks/CompletionDetailView.vue	学校端提交详情（新增）
views/parent/tasks/TaskSubmitView.vue	家长端提交页面（重写）
views/parent/tasks/TaskFeedbackView.vue	家长端查看评价（新增）
views/teacher/tasks/components/CompletionDetailModal.vue	教师端提交详情弹窗（新增）
views/teacher/tasks/components/FeedbackModal.vue	教师端评价弹窗（新增）
api/reading-task.ts	阅读任务API（新模块，独立于原task）
components/TaskFilterPanel.vue	通用筛选面板组件

---

九、开发任务清单

Phase 1：后端基础改造（2-3天）

任务	预估时间	依赖
数据库迁移脚本（TaskFeedback表、字段扩展）	0.5天	无
TaskFeedback 实体类和 Mapper	0.5天	数据库
TaskFeedbackService 接口和实现	1天	实体类
扩展 TaskService（评价相关方法）	0.5天	TaskFeedback
教师端评价 API	0.5天	Service
家长端提交 API（支持文件）	0.5天	Service
学校端只读 API（多维度筛选）	1天	Service

Phase 2：教师端改造（2天）

任务	预估时间	依赖
创建任务弹窗添加绘本字段	0.5天	无
完成情况弹窗改造（显示提交内容）	0.5天	无
新增提交详情弹窗组件	0.5天	无
新增评价弹窗组件	0.5天	后端API

Phase 3：家长端改造（2天）

任务	预估时间	依赖
重写任务提交页面（照片/视频上传）	1天	后端API
新增查看评价页面	0.5天	后端API
完善任务列表页	0.5天	无

Phase 4：学校端重写（2天）

任务	预估时间	依赖
多维度筛选组件	0.5天	无
任务列表页（只读）	0.5天	筛选组件
任务详情页	0.5天	后端API
学生提交详情页	0.5天	后端API

Phase 5：测试与优化（1-2天）

任务	预估时间
三端联调测试	0.5天
Bug修复	0.5天
性能优化	0.5天

---

十、验收标准

10.1 功能验收

教师端

• 可以创建任务，填写关联绘本名称
• 可以查看所有学生的提交情况
• 可以查看学生提交的照片和视频
• 可以给学生评价（优秀/通过/需改进）
• 可以填写评语和评分
• 评价后家长端能收到通知

家长端

• 可以查看孩子的任务列表
• 可以上传照片（最多9张）
• 可以上传视频
• 可以填写文字心得
• 可以查看教师的评价

学校端

• 不能创建/编辑/删除任务
• 可以按时间范围筛选
• 可以按班级筛选（多选）
• 可以按教师筛选（多选）
• 可以按任务类型/状态筛选
• 可以按完成率筛选
• 可以搜索任务标题
• 可以查看任务详情
• 可以查看学生提交内容
• 可以查看教师评价

10.2 技术验收

• 所有 API 有 Swagger 文档
• 前端代码有 TypeScript 类型定义
• 数据库迁移脚本可重复执行
• 无 console.log 残留
• 无未使用的导入和变量

10.3 UI/UX 验收

• 符合 Ant Design 设计规范
• 移动端响应式适配
• 加载状态有 loading 提示
• 操作有成功/失败反馈
• 表单有必填校验

---

附录：关键决策记录

决策	原因	日期
学校端只读，不创建任务	学校是管理监督角色，不是执行角色	2026-03-20
关联绘本手动填写而非选择	绘本库功能复杂，先简化实现	2026-03-20
评价结果用三档而非五档	简化教师操作，符合实际场景	2026-03-20
评分设为可选	避免过度评价压力	2026-03-20
学校端筛选参数用数组	支持多选，更灵活	2026-03-20

---

文档版本历史：

• v2.0 (2026-03-20): 完整需求分析和设计文档