# 任务管理模块需求分析

**版本**: 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 实体字段

```java
// 基础字段
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 | 模板任务标记 |