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

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

> 版本：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<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

```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` | `<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): 完整需求分析和设计文档