# 阅读任务模块设计文档

> 创建时间：2026-02-23
> 最后更新：2026-02-23

---

## 一、模块概述

### 1.1 设计目标

阅读任务是**连接课堂教学与家庭阅读**的桥梁，实现：
- 教师：布置、跟踪、评估学生的课后阅读任务
- 学校：监督全校阅读任务执行，查看统计数据
- 家长：接收任务、陪伴阅读、提交反馈

### 1.2 业务流程

```
┌─────────────────┐
│   课堂授课      │ ← 教师端
│   (教师端)      │
└────────┬────────┘
         ↓ 布置任务
┌─────────────────┐
│   阅读任务系统   │
│  (学校端+教师端) │
└────────┬────────┘
         ↓ 推送给家长
┌─────────────────┐
│   亲子共读      │ ← 家长端
│   (家长端)      │
└────────┬────────┘
         ↓ 提交反馈
┌─────────────────┐
│   完成情况      │ ← 教师端/学校端
│   (两端可见)    │
└─────────────────┘
```

---

## 二、角色分工

### 2.1 教师端 - 执行层

**核心理念**：让老师"傻瓜式"完成高质量阅读教学

**功能定位**：
```
├── 阅读任务
│   ├── 布置任务      ← 日常操作，可选班级/学生
│   ├── 任务模板      ← 快速创建（待开发）
│   ├── 完成情况      ← 跟踪进度，查看详情
│   └── 家长反馈      ← 接收并查看家长提交的反馈
```

**使用场景**：
- 场景3：上完课，记录孩子表现，**布置任务**
- 跟踪班级学生的任务完成情况
- 与家长进行阅读互动

### 2.2 学校端 - 管理层

**核心理念**：回答"孩子们有什么收获？"

**功能定位**：
- 管理全校的阅读任务（创建、编辑、删除）
- 监督任务执行情况
- 查看统计数据和报告
- 制定任务模板供教师使用（待开发）

### 2.3 家长端 - 参与层

**功能定位**：
- 接收教师布置的阅读任务
- 陪伴孩子完成任务
- 提交完成反馈（文字、图片）

---

## 三、数据模型

### 3.1 核心表结构

#### tasks 表
```prisma
model Task {
  id              Int       @id @default(autoincrement())
  tenantId        Int       @map("tenant_id")
  title           String
  description     String?
  taskType        String    @map("task_type")     // READING, ACTIVITY, HOMEWORK
  targetType      String    @map("target_type")   // CLASS, STUDENT
  status          String    @default("DRAFT")     // DRAFT, PUBLISHED, ARCHIVED
  relatedCourseId Int?      @map("related_course_id")
  startDate       DateTime? @map("start_date")
  endDate         DateTime? @map("end_date")
  createdBy       Int       @map("created_by")
  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt

  tenant          Tenant    @relation(fields: [tenantId], references: [id])
  course          Course?   @relation(fields: [relatedCourseId], references: [id])
  targets         TaskTarget[]
  completions     TaskCompletion[]

  @@map("tasks")
}
```

#### task_targets 表（任务目标关联）
```prisma
model TaskTarget {
  id         Int       @id @default(autoincrement())
  taskId     Int       @map("task_id")
  classId    Int?      @map("class_id")
  studentId  Int?      @map("student_id")

  task       Task      @relation(fields: [taskId], references: [id])
  class      Class?    @relation(fields: [classId], references: [id])
  student    Student?  @relation(fields: [studentId], references: [id])

  @@map("task_targets")
}
```

#### task_completions 表（完成记录）
```prisma
model TaskCompletion {
  id              Int       @id @default(autoincrement())
  taskId          Int       @map("task_id")
  studentId       Int       @map("student_id")
  status          String    @default("PENDING")  // PENDING, IN_PROGRESS, COMPLETED
  completedAt     DateTime? @map("completed_at")
  studentFeedback String?   @map("student_feedback")
  parentFeedback  String?   @map("parent_feedback")
  images          String?   // JSON array
  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt

  task            Task      @relation(fields: [taskId], references: [id])
  student         Student   @relation(fields: [studentId], references: [id])

  @@map("task_completions")
}
```

### 3.2 实体关系图

```
Tenant (1) ←→ (N) Tasks
    ↓
Tasks (1) ←→ (N) TaskTargets
    ↓              ↓
TaskTargets (1) ←→ (1) Class OR Student
    ↓
TaskTargets (1) ←→ (N) TaskCompletions
    ↓
TaskCompletions (1) ←→ (1) Student
```

---

## 四、API 接口

### 4.1 学校端接口

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | /school/tasks | 任务列表（分页、筛选） |
| GET | /school/tasks/stats | 任务统计 |
| GET | /school/tasks/:id | 任务详情 |
| GET | /school/tasks/:id/completions | 完成情况列表 |
| POST | /school/tasks | 创建任务 |
| PUT | /school/tasks/:id | 更新任务 |
| DELETE | /school/tasks/:id | 删除任务 |
| PUT | /school/tasks/:taskId/completions/:studentId | 更新学生完成状态 |

### 4.2 教师端接口

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | /teacher/tasks | 我的任务列表 |
| GET | /teacher/tasks/upcoming | 即将截止的任务 |
| GET | /teacher/tasks/:id | 任务详情 |
| GET | /teacher/tasks/:id/completions | 完成情况列表 |
| POST | /teacher/tasks | 创建任务 |
| PUT | /teacher/tasks/:id | 更新任务 |
| DELETE | /teacher/tasks/:id | 删除任务 |
| POST | /teacher/tasks/:id/remind | 发送提醒 |

### 4.3 家长端接口

| 方法 | 路径 | 说明 |
|-----|------|------|
| GET | /parent/tasks | 孩子的任务列表 |
| GET | /parent/tasks/:id | 任务详情 |
| PUT | /parent/tasks/:id/complete | 提交完成情况 |

---

## 五、功能实现状态

### 5.1 已完成功能

| 功能 | 学校端 | 教师端 | 家长端 | 后端 |
|-----|-------|-------|-------|-----|
| 任务列表 | ✅ | ✅ | ✅ | ✅ |
| 创建任务 | ✅ | ✅ | - | ✅ |
| 编辑任务 | ✅ | ✅ | - | ✅ |
| 删除任务 | ✅ | ✅ | - | ✅ |
| 任务类型 | ✅ | ✅ | - | ✅ |
| 目标选择 | ✅ | ✅ | - | ✅ |
| API接口 | - | - | - | ✅ |
| 完成情况详情页 | ✅ | ✅ | - | ✅ |
| 家长提交反馈 | - | - | ✅ | ✅ |
| 家长反馈展示 | ✅ | ✅ | - | ✅ |
| 课后记录→布置任务 | - | ✅ | - | ✅ |
| 任务模板 | ✅ | ✅ | - | ✅ |
| 提醒通知 | ✅ | ✅ | - | ✅ |
| 统计报表 | ✅ | ✅ | - | ✅ |

### 5.2 所有功能已完成 ✅

阅读任务模块的核心功能已全部实现。

---

## 六、开发计划

### 6.1 阶段一：完善现有功能（P0）✅ 已完成

1. **测试家长端任务功能** ✅
   - 验证任务列表展示 - 通过
   - 验证任务详情 - 通过
   - 验证完成提交 - 通过
   - 验证家长反馈可见性 - 通过

2. **实现完成情况详情页** ✅
   - 学生完成状态列表 - 完成
   - 批量更新状态 - 完成
   - 家长反馈展示 - 完成
   - 文件：`src/views/teacher/tasks/TaskListView.vue`

3. **打通课后记录→布置任务** ✅
   - 在课后记录页面添加"布置阅读任务"按钮
   - 自动关联当前课程和班级
   - 预设任务时间（默认7天）
   - 文件：`src/views/teacher/lessons/LessonRecordsView.vue`

### 6.2 阶段二：功能增强（P1-P2）✅ 已完成

4. **任务模板功能** ✅
   - 数据库：新增 TaskTemplate 模型
   - 后端：模板 CRUD API
   - 学校端：模板管理页面 (`/school/task-templates`)
   - 教师端：任务创建时使用模板

5. **提醒通知系统** ✅
   - 定时任务：每天早上9点检查即将截止任务
   - 手动提醒：教师可发送提醒给家长
   - 通知记录：通过 Notification 模型存储

### 6.3 阶段三：数据分析（P3）✅ 已完成

6. **统计报表增强** ✅
   - 基本统计：任务数、完成数、完成率
   - 按类型统计：阅读/活动/作业完成率
   - 按班级统计：各班级完成情况
   - 月度趋势：任务数量和完成率趋势

---

## 七、技术实现建议

### 7.1 前端组件复用

建议创建共享组件：
- `TaskCard.vue` - 任务卡片（学校端/教师端复用）
- `TaskForm.vue` - 任务表单（学校端/教师端复用）
- `CompletionList.vue` - 完成情况列表
- `FeedbackDisplay.vue` - 反馈展示组件

### 7.2 状态管理

任务数据涉及多端，建议：
- 使用 Pinia 统一管理任务状态
- 缓存任务列表减少请求
- 使用 WebSocket 实时推送完成状态

### 7.3 数据一致性

- 任务创建后自动创建 TaskCompletion 记录
- 学生调班时更新 TaskTarget
- 任务删除时级联删除关联数据

---

## 八、变更记录

| 日期 | 变更内容 |
|-----|---------|
| 2026-02-23 | 完成 P2/P3 功能：任务模板、提醒通知、统计报表 |
| 2026-02-23 | 完成 P0 功能：测试家长端任务功能、实现教师端完成情况详情页、打通课后记录→布置任务流程 |
| 2026-02-23 | 创建文档，分析现状，制定开发计划 |