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

阅读任务模块设计文档

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

---

一、模块概述

1.1 设计目标

阅读任务是连接课堂教学与家庭阅读的桥梁，实现：

• 教师：布置、跟踪、评估学生的课后阅读任务
• 学校：监督全校阅读任务执行，查看统计数据
• 家长：接收任务、陪伴阅读、提交反馈

1.2 业务流程

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

---

二、角色分工

2.1 教师端 - 执行层

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

功能定位：

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

使用场景：

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

2.2 学校端 - 管理层

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

功能定位：

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

2.3 家长端 - 参与层

功能定位：

• 接收教师布置的阅读任务
• 陪伴孩子完成任务
• 提交完成反馈（文字、图片）

---

三、数据模型

3.1 核心表结构

tasks 表

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 表（任务目标关联）

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 表（完成记录）

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	创建文档，分析现状，制定开发计划