cfc/docs/task-requirements.md

任务管理模块需求分析

版本: V1.2 更新时间: 2026-04-13

---

一、需求清单总览

需求ID	描述	优先级	状态
TASK-001	家长可创建任务，设置任务名称	P0	✅ 已实现
TASK-002	设置任务积分值（1-10分，默认2分）	P0	✅ 已实现
TASK-003	设置任务截止时间（精确到分钟）	P0	✅ 已实现
TASK-004	设置任务重复（每日/每周）	P0	✅ 已实现
TASK-005	设置任务分类（学习类/生活类/运动类/其他）	P0	✅ 已实现
TASK-006	任务模板功能	P1	⚠️ 部分实现
TASK-007	设置审核方式	P1	⚠️ 部分实现
TASK-008	孩子可查看今日任务列表	P0	✅ 已实现
TASK-009	孩子点击"完成"按钮提交任务	P0	✅ 已实现
TASK-010	任务完成方式设置	P2	⚠️ 待完善
TASK-011	任务时长设置	P2	⚠️ 待完善
TASK-012A	打卡支持照片上传	P0	✅ 已实现
TASK-012B	打卡支持视频上传	P0	✅ 已实现
TASK-012C	打卡支持录音上传	P0	✅ 已实现
TASK-012D	打卡支持文字描述	P0	✅ 已实现
TASK-012E	打卡支持倒计时功能	P0	✅ 已实现
TASK-012F	倒计时结束时语音提醒	P0	✅ 已实现
TASK-013	任务提醒通知	P1	✅ 已实现
TASK-014	任务历史记录查询	P1	✅ 已实现
TASK-015	任务统计分析报表	P1	✅ 已实现
TASK-016	批量操作任务	P2	❌ 未实现

---

二、需求详细说明

2.1 任务创建（TASK-001~005）

TASK-001: 创建任务，设置任务名称

• 描述: 家长可以创建任务，设置任务名称
• 必填: 是
• 字段: title (String, 最大100字符)
• 验证: 不能为空
• 实现位置: TaskService.createTask()

TASK-002: 设置任务积分值

• 描述: 积分值范围1-10分，默认2分
• 必填: 是
• 字段: points (Integer)
• 默认值: 2
• 验证: 1-10分

TASK-003: 设置任务截止时间

• 描述: 精确到分钟，支持多孩子任务和家长任务
• 必填: 是
• 字段: deadline (DateTime)
• 前端: 多级日期时间选择器（年/月/日/时/分）

TASK-004: 设置任务重复

• 描述: 支持每日重复、每周重复
• 字段: repeatType (String)
• 可选值: none / daily / weekly
• 定时任务: RepeatTaskGenerator 每天05:00执行

TASK-005: 设置任务分类

• 描述: 学习类/生活类/运动类/其他
• 字段: category (String)
• 可选值: 学习类 / 生活类 / 运动类 / 其他

---

2.2 任务模板和审核（TASK-006~007）

TASK-006: 任务模板功能

• 描述: 使用任务模板快速创建
• 状态: ⚠️ 部分实现
• 待完善: 模板库管理、模板选择UI

TASK-007: 设置审核方式

• 描述: 选择审核人类型
• 字段: reviewType (String)
• 可选值:
  • creator - 创建者审核
  • parent - 家长审核
  • teacher - 指导师审核
  • ai - AI自动审核

---

2.3 任务查看和完成（TASK-008~011）

TASK-008: 孩子查看今日任务

• 描述: 孩子可以查看今日需要完成的任务列表
• 实现: GET /api/tasks/today?childId={id}
• 返回: 当日所有pending/completed状态的任务

TASK-009: 孩子完成任务

• 描述: 孩子点击完成按钮提交任务
• 实现: POST /api/tasks/{id}/complete
• 参数: childId, photoUrl(可选)

TASK-010: 任务完成方式设置

• 描述: 支持多种完成方式
• 字段: completeTypes (JSON数组)
• 可选值:
  • checkin - 打卡
  • text - 文本
  • audio - 语音
  • image - 图片
  • video - 视频

TASK-011: 任务时长设置

• 字段: duration (Integer, 分钟)
• 描述: 任务预计耗时

---

2.4 打卡功能（TASK-012A~F）

需求ID	描述	实现
TASK-012A	照片上传	✅ 文件上传API
TASK-012B	视频上传	✅ 文件上传API
TASK-012C	录音上传	✅ 文件上传API
TASK-012D	文字描述	✅ CompleteTaskDTO.text
TASK-012E	倒计时功能	✅ 前端组件
TASK-012F	语音提醒	✅ 前端TTS

---

2.5 任务提醒和统计（TASK-013~016）

TASK-013: 任务提醒通知

• 描述: 任务截止前发送提醒
• API:
  • GET /api/tasks/reminder/{childId} - 30分钟内到期
  • GET /api/tasks/upcoming/{childId}?minutes=60 - 自定义时间
  • GET /api/tasks/overdue/{childId} - 已超时任务

TASK-014: 任务历史记录查询

• 描述: 查看历史任务，支持筛选
• API: GET /api/tasks/history/filter/{childId}
• 筛选条件: 状态、时间范围

TASK-015: 任务统计分析报表

• 描述: 统计任务完成情况
• API:
  • GET /api/tasks/statistics/{childId} - 概览统计
  • GET /api/tasks/statistics/category/{childId} - 分类统计
  • GET /api/tasks/statistics/date/{childId}?days=7 - 日期统计
  • GET /api/tasks/statistics/family/{familyId} - 家庭统计

TASK-016: 批量操作任务

• 描述: 批量删除、批量审核
• 状态: ❌ 未实现

---

三、任务数据模型

3.1 Task 实体字段

// 基础字段
private Long id;
private Long familyId;       // 家庭ID
private Long creatorId;      // 创建者ID
private String title;        // 任务名称
private String description;  // 任务描述

// 执行者
private String executorType; // child/parent
private Long executorId;     // 执行者ID
private Long childId;        // 孩子ID（兼容）

// 积分和时间
private Integer points;      // 积分值
private Date deadline;      // 截止时间

// 分类和审核
private String category;     // 分类
private Integer needReview; // 是否需要审核
private String reviewType;   // 审核人类型
private String status;       // 任务状态
private Date completedAt;    // 完成时间

// 重复设置 (TASK-004)
private String repeatType;  // none/daily/weekly
private Long templateId;    // 模板ID
private Integer isTemplate; // 是否模板

// POINT-002: 超额积分
private String bonusRule;   // JSON格式规则

// POINT-009: 积分有效期
private Integer pointsExpireDays; // 有效期天数

// 扩展字段
private String taskType;    // onetime/recurring
private String frequency;   // daily/weekly/monthly
private Integer maxFrequency; // 周期内最多次数
private String completeTypes; // 完成方式JSON
private Date earliestStart;  // 最早开始
private Date latestEnd;      // 最晚结束

3.2 状态流转

pending → completed (孩子完成)
pending → completed (审核通过)
completed → pending (审核拒绝)
pending → cancelled (创建者删除)

---

四、API接口汇总

4.1 任务管理

方法	路径	功能	权限
POST	/api/tasks	创建任务	家长/指导师
GET	/api/tasks/today	今日任务	孩子
POST	/api/tasks/{id}/complete	完成任务	孩子
POST	/api/tasks/{id}/review	审核任务	家长/指导师
GET	/api/tasks/history	历史记录	孩子/家长
GET	/api/tasks/pending-review	待审核任务	家长/指导师
DELETE	/api/tasks/{id}	删除任务	创建者

4.2 任务提醒统计

方法	路径	功能
GET	/api/tasks/reminder/{childId}	需要提醒的任务
GET	/api/tasks/upcoming/{childId}	即将到期任务
GET	/api/tasks/overdue/{childId}	已超时任务
GET	/api/tasks/history/filter/{childId}	带筛选历史
GET	/api/tasks/statistics/{childId}	统计概览
GET	/api/tasks/statistics/category/{childId}	分类统计
GET	/api/tasks/statistics/date/{childId}	日期统计
GET	/api/tasks/statistics/family/{familyId}	家庭统计

---

五、前端页面

页面	路径	功能
创建任务	/pages/tasks/create-task	任务表单
任务列表	/pages/tasks/tasks	任务查看/管理
今日任务	首页嵌入	孩子查看任务

---

六、待完善功能

功能	优先级	说明
任务模板管理	P1	模板库CRUD
批量操作	P2	批量删除/审核
任务时长显示	P2	前端展示
AI审核	P1	调用AI服务自动审核
消息推送	P1	微信模板消息提醒

---

七、数据库迁移

迁移	字段	说明
迁移20	template_id	重复任务模板追踪
迁移21	is_template	模板任务标记