# 阅读任务模块 - 详细设计文档 > 版本：v2.0 > 日期：2026-03-20 > 状态：待开发 --- ## 目录 1. [需求背景与目标](#一需求背景与目标) 2. [用户角色与权限](#二用户角色与权限) 3. [核心业务流程](#三核心业务流程) 4. [功能需求详解](#四功能需求详解) 5. [数据模型设计](#五数据模型设计) 6. [API 接口设计](#六api-接口设计) 7. [UI/UX 设计规范](#七uiux-设计规范) 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 | **数据字段**： ```typescript 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 | **学生完成记录数据**： ```typescript 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 | **提交表单数据**： ```typescript 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 表 - 新增字段 ```sql ALTER TABLE task ADD COLUMN related_book_name VARCHAR(200) COMMENT '关联绘本名称'; ``` #### 5.1.2 TaskCompletion 表 - 扩展字段 ```sql -- 修改 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 表 - 新建 ```sql 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（变更） ```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（变更） ```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（新增） ```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 ```java @Data @Builder public class TaskCompletionResponse { private Long id; private Long taskId; private StudentInfo student; private String status; private List 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 ```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 ```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` | 修改评价 | **新增** | #### 请求/响应示例 **创建任务请求**： ```json { "title": "《好饿的毛毛虫》亲子阅读", "description": "和孩子一起阅读这本经典绘本...", "taskType": "READING", "relatedBookName": "《好饿的毛毛虫》", "targetType": "CLASS", "targetIds": [1, 2], "relatedCourseId": 10, "startDate": "2026-03-20", "endDate": "2026-03-27" } ``` **提交评价请求**： ```json { "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` | 查看评价 | **新增** | #### 请求示例 **提交完成请求**： ```json { "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` | 导出报表 | **新增** | #### 学校端筛选参数 ```typescript 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` | `` | | PASSED（通过） | 蓝色 `#1890ff` | `` | | NEEDS_WORK（需改进） | 橙色 `#fa8c16` | `` | ### 7.2 评分星星 - 使用 Ant Design 的 `` 组件 - 默认禁用（仅展示），在评价时可编辑 - 颜色：金色 `#fadb14` ### 7.3 照片上传组件 - 使用 Ant Design 的 `` 组件 - 列表模式：`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): 完整需求分析和设计文档