# 任务管理模块需求分析

**版本**: 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)
- **可选值**: `学习类` / `生活类` / `运动类` / `小游戏类` / `其他`
- **说明**: 小游戏类是一种任务类型，孩子通过完成在线小游戏获得积分奖励
- **小游戏列表**:
  - 舒尔特方格 - 专注力训练
  - 猜数字 (1a2b) - 逻辑推理训练
  - 数独 - 策略与数学思维训练

---

### 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-017A~C）

> 说明：小游戏是任务分类的一种形式，属于"小游戏类"任务。孩子完成小游戏后获得积分奖励，与普通任务采用相同的积分计算逻辑。

#### TASK-017A: 小游戏任务-舒尔特方格
- **描述**: 专注力训练游戏，在方格中按顺序点击数字
- **游戏代码**: `schulte`
- **游戏参数**: gridSize (5x5, 6x6等)
- **积分规则**: 根据完成时间计算，参考 `MiniGameService.completeGame()`
- **状态**: ✅ 已实现
- **API**:
  - `POST /api/mini-game/list` - 获取小游戏列表
  - `POST /api/mini-game/complete` - 完成任务获得积分

#### TASK-017B: 小游戏任务-猜数字(1a2b)
- **描述**: 逻辑推理游戏，猜测4位数字并获取A、B提示
- **游戏代码**: `1a2b`
- **积分规则**: 用时越短分数越高，120秒内完成得满分
- **状态**: ✅ 已实现
- **特殊逻辑**: 用时判断（不是次数判断）

#### TASK-017C: 小游戏任务-数独
- **描述**: 策略与数学思维训练游戏，完成9x9数独
- **游戏代码**: `sudoku`
- **难度等级**: easy, medium, hard
- **积分规则**: 根据完成时间和难度计算
- **验证逻辑**: 行、列、3x3宫格都必须正确

#### 小游戏任务与普通任务的关系

| 特性 | 普通任务 | 小游戏任务 |
|------|---------|-----------|
| 任务分类 | 学习类/生活类/运动类/其他 | 小游戏类 |
| 完成方式 | 打卡/文本/图片/视频 | 游戏完成回调 |
| 积分计算 | 基础分+超额分 | 按游戏规则计算 |
| 审核流程 | 可选需审核 | 直接完成即时获积分 |
| 历史记录 | 任务历史 | 统一记录在任务历史中 |

---

### 2.6 任务提醒与统计（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 (创建者删除)
```

### 3.3 任务属性分组与职责边界

> 说明：以下内容从业务视角定义任务对象的完整属性。前端展示时，应按角色和阶段裁剪字段；后端存储时，宜将“任务定义”和“执行记录”分开管理。

#### A. 基础信息

| 字段 | 含义 | 创建时 | 执行时 | 审核时 | 完成后 |
|------|------|--------|--------|--------|--------|
| title | 任务标题 | 必填，可编辑 | 只读 | 只读 | 只读 |
| description | 任务描述 | 可选，可编辑 | 只读 | 只读 | 只读 |
| category | 任务分类 | 必填，可编辑 | 只读 | 只读 | 只读 |
| taskType | 任务类型（一次性/重复） | 必填，可编辑 | 只读 | 只读 | 只读 |
| templateId | 模板来源 | 选择模板时自动带入 | 只读 | 只读 | 只读 |

#### B. 执行对象

| 字段 | 含义 | 创建时 | 执行时 | 审核时 | 完成后 |
|------|------|--------|--------|--------|--------|
| creatorId | 创建人 | 系统生成 | 只读 | 只读 | 只读 |
| familyId | 所属家庭 | 系统生成 | 只读 | 只读 | 只读 |
| executorType | 执行者类型 | 必填，可编辑 | 只读 | 只读 | 只读 |
| executorId / childId | 执行者ID/孩子ID | 必填，可编辑 | 只读 | 只读 | 只读 |

#### C. 规则信息

| 字段 | 含义 | 创建时 | 执行时 | 审核时 | 完成后 |
|------|------|--------|--------|--------|--------|
| points | 奖励积分 | 必填，可编辑 | 只读 | 只读 | 只读 |
| deadline | 截止时间 | 必填，可编辑 | 只读 | 只读 | 只读 |
| earliestStart | 最早开始时间 | 可选，可编辑 | 只读 | 只读 | 只读 |
| latestEnd | 最晚结束时间 | 可选，可编辑 | 只读 | 只读 | 只读 |
| duration | 预计时长 | 可选，可编辑 | 只读 | 只读 | 只读 |
| completeTypes | 完成方式 | 必填，可编辑 | 只读 | 只读 | 只读 |
| needReview | 是否需要审核 | 必填，可编辑 | 只读 | 只读 | 只读 |
| reviewType | 审核方式 | 需要审核时可选 | 只读 | 只读 | 只读 |
| repeatType | 重复规则 | 选择重复任务时可选 | 只读 | 只读 | 只读 |
| bonusRule | 超额积分规则 | 可选，可编辑 | 只读 | 只读 | 只读 |
| pointsExpireDays | 积分有效期 | 可选，可编辑 | 只读 | 只读 | 只读 |

#### D. 执行与提交信息

| 字段 | 含义 | 创建时 | 执行时 | 审核时 | 完成后 |
|------|------|--------|--------|--------|--------|
| status | 当前状态 | 系统初始化 | 可随流程变化 | 可随流程变化 | 归档只读 |
| completedAt | 完成时间 | 为空 | 记录提交或完成时间 | 可查看 | 只读 |
| completedBy | 实际完成人 | 为空 | 孩子提交时生成 | 可查看 | 只读 |
| completeContent | 完成说明/文本 | 为空 | 孩子填写 | 可查看 | 只读 |
| completeMedia | 完成附件（图/音/视频） | 为空 | 孩子上传 | 可查看 | 只读 |
| overtimeFlag | 超时标记 | 系统计算 | 可刷新 | 可查看 | 只读 |

#### E. 审核信息

| 字段 | 含义 | 创建时 | 执行时 | 审核时 | 完成后 |
|------|------|--------|--------|--------|--------|
| reviewerId | 审核人ID | 为空 | 只读 | 家长/指导师填写 | 只读 |
| reviewTime | 审核时间 | 为空 | 只读 | 审核通过时生成 | 只读 |
| reviewResult | 审核结果 | 为空 | 只读 | 通过/驳回/退回补充 | 只读 |
| reviewComment | 审核意见 | 为空 | 只读 | 可填写 | 只读 |

#### F. 系统信息

| 字段 | 含义 | 创建时 | 执行时 | 审核时 | 完成后 |
|------|------|--------|--------|--------|--------|
| id | 任务ID | 系统生成 | 只读 | 只读 | 只读 |
| createdAt | 创建时间 | 系统生成 | 只读 | 只读 | 只读 |
| updatedAt | 更新时间 | 系统生成 | 系统更新 | 系统更新 | 只读 |
| isTemplate | 是否模板任务 | 可选 | 只读 | 只读 | 只读 |
| templateId | 模板关联 | 可选 | 只读 | 只读 | 只读 |

### 3.4 阶段展示、角色与字段变更规则

#### 3.4.1 创建阶段

- **可见角色**: 家长、管理员、指导师
- **可编辑角色**: 任务创建人
- **主要内容**: 标题、描述、分类、执行对象、积分、截止时间、时长、完成方式、是否审核、审核方式、重复规则、提醒规则、模板来源
- **字段规则**:
  - 发布前允许修改全部业务字段
  - 发布后建议锁定积分、截止时间、执行对象、审核方式、重复规则，避免任务含义被改变

#### 3.4.2 执行阶段

- **可见角色**: 孩子、家长、指导师（按家庭权限）
- **可编辑角色**: 孩子仅可填写提交内容；家长不可直接修改孩子的提交结果
- **主要内容**: 任务标题、任务说明、剩余时间、奖励积分、完成要求、附件上传入口、提醒信息
- **字段规则**:
  - 任务定义字段只读
  - 孩子可更新提交内容、补充说明、附件
  - 系统记录实际开始时间、提交时间、超时标记

#### 3.4.3 提交阶段

- **可见角色**: 孩子、家长
- **可编辑角色**: 孩子
- **主要内容**: 提交说明、图片/视频/录音/文字、计时结果、是否完成
- **字段规则**:
  - 允许在审核前补充材料的，提交内容可再次编辑
  - 审核提交后，提交内容进入只读，避免争议

#### 3.4.4 审核阶段

- **可见角色**: 家长、指导师
- **可编辑角色**: 审核人
- **主要内容**: 孩子的提交内容、完成时间、是否超时、历史修改记录、审核意见
- **字段规则**:
  - 审核人可填写审核结果与意见
  - 审核通过后，任务结果和积分流水应固定，不再覆盖原记录
  - 审核驳回时，应保留原提交内容和驳回原因

#### 3.4.5 完成阶段

- **可见角色**: 全部相关角色
- **可编辑角色**: 原则上无；仅保留申诉或补审入口
- **主要内容**: 最终状态、实际完成时间、获得积分、审核结果、审核意见、附件证据、历史记录
- **字段规则**:
  - 任务主体只读
  - 若发生积分回滚或补审，必须保留操作流水

### 3.5 推荐的状态流转说明

为便于前端和接口统一理解，建议将业务流程描述为：

```
草稿 → 待执行 → 执行中 → 待提交 → 待审核 → 已完成
                         ↘ 已驳回 / 已过期 / 已取消
```

- **草稿**: 仅创建人可见，未发布
- **待执行**: 任务已发布，等待孩子开始
- **执行中**: 孩子已开始执行或已领取任务
- **待提交**: 已完成动作，等待提交结果
- **待审核**: 已提交，等待家长/指导师确认
- **已完成**: 审核通过或自动通过
- **已驳回**: 审核不通过，等待补充或重做
- **已过期**: 超过截止时间仍未完成
- **已取消**: 创建人主动撤销

### 3.6 Web端与小程序端字段展示矩阵

> 说明：Web端以管理与配置为主，小程序端以查看与执行为主。下表用于统一页面展示边界，避免前后端对同一字段理解不一致。

#### 3.6.1 任务主对象字段

| 字段 | Web端任务列表 `Tasks.vue` | Web端模板页 `TaskTemplates.vue` | 小程序任务列表 `tasks.vue` | 小程序创建页 `create-task.vue` | 创建后可改 |
|------|---------------------------|----------------------------------|-----------------------------|----------------------------------|-----------|
| title | 显示 | 显示 | 显示 | 填写 | 否（发布后锁定） |
| description | 不显示 | 编辑/显示 | 显示 | 填写 | 仅允许补充说明 |
| category | 显示 | 显示/筛选 | 显示 | 填写 | 否 |
| points | 显示 | 显示/编辑 | 显示 | 填写 | 不建议改 |
| deadline | 显示 | 不直接展示 | 显示 | 填写 | 否 |
| status | 显示 | 不展示 | 显示（完成/未完成） | 不展示 | 系统变更 |
| needReview | 显示 | 显示/编辑 | 创建页可设 | 创建页可设 | 否 |
| childId / childIds | 显示（childId） | 不展示 | 创建页选择孩子 | 创建页选择孩子 | 否 |
| repeatType | 不展示 | 编辑 | 不展示 | 创建页可设 | 否 |
| completeTypes | 不展示 | 编辑 | 创建页可设 | 创建页可设 | 否 |
| duration | 不展示 | 显示/编辑 | 创建页可设 | 创建页可设 | 仅补充说明类变更 |
| createdAt | 显示 | 显示 | 不展示 | 不展示 | 系统字段 |
| templateId | 不展示 | 不直接展示 | 模板选择后自动带入 | 模板选择后自动带入 | 系统字段 |

#### 3.6.2 Web端任务管理页显示重点

- **任务列表页**: `id`、`title`、`points`、`category`、`deadline`、`status`、`needReview`、`childId`、`createdAt`
- **筛选条件**: 任务标题、状态、家庭
- **统计信息**：总任务数、今日任务数
- **适用场景**：后台查看、检索、按家庭定位任务

#### 3.6.3 Web端任务模板页显示重点

- **列表字段**：模板名称、分类、积分、难度、推荐年龄、时长、任务性质、是否需要审核、启用状态、创建时间
- **编辑字段**：标题、描述、分类、积分、难度、推荐年龄、预计时长、完成方式、任务性质、频率、周期次数、是否审核、审核方式、按分类审核
- **适用场景**：统一模板配置，供任务创建复用

#### 3.6.4 小程序任务列表页显示重点

- **孩子视图**: 任务标题、积分、截止时间、完成按钮、已完成标识
- **家长视图**: 今日任务列表、添加任务入口、家长任务列表
- **适用场景**: 任务执行、快速完成、家庭日常管理

#### 3.6.5 小程序创建页显示重点

- **基础字段**: 任务名称、任务描述、选择孩子、积分、分类、截止时间、重复设置、是否需要审核
- **扩展字段**: 当任务模板可用时，可自动带入标题、描述、分类、积分、完成方式、审核设置等
- **适用场景**: 快速创建单次或重复任务

#### 3.6.6 字段展示规则建议

- **管理端可见更多配置项**，如模板、难度、审核细则、启用开关
- **小程序端优先展示执行所需信息**，避免把模板配置、规则细节全部暴露给孩子
- **创建后高敏感业务字段尽量只读**，包括积分、截止时间、审核方式、重复规则和执行对象

### 3.7 关键字段生命周期矩阵

> 说明：本节描述字段在各阶段的写入主体、锁定时机和只读边界。其粒度高于 3.6，适合用于约束前端表单和后端接口。

| 字段 | 创建阶段 | 执行阶段 | 提交阶段 | 审核阶段 | 完成阶段 |
|------|----------|----------|----------|----------|----------|
| title | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| description | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| category | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| points | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| deadline | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| childId / childIds | 创建人选择 | 只读 | 只读 | 只读 | 只读 |
| repeatType | 创建人选择 | 只读 | 只读 | 只读 | 只读 |
| completeTypes | 创建人选择 | 只读 | 只读 | 只读 | 只读 |
| needReview | 创建人选择 | 只读 | 只读 | 只读 | 只读 |
| reviewType | 创建人选择 | 只读 | 只读 | 只读 | 只读 |
| duration | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| earliestStart | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| latestEnd | 创建人填写 | 只读 | 只读 | 只读 | 只读 |
| status | 系统初始化 | 系统更新 | 系统更新 | 系统更新 | 归档只读 |
| completedAt | 为空 | 执行开始时可为空 | 孩子提交时写入 | 审核时可查看 | 只读 |
| completedBy | 为空 | 为空 | 孩子提交时写入 | 审核时可查看 | 只读 |
| completeContent | 为空 | 孩子可填写 | 孩子可补充 | 审核人可查看 | 只读 |
| completeMedia | 为空 | 孩子可上传 | 孩子可补充 | 审核人可查看 | 只读 |
| overtimeFlag | 系统计算 | 系统更新 | 系统更新 | 审核时可查看 | 只读 |
| reviewerId | 为空 | 只读 | 只读 | 审核人写入 | 只读 |
| reviewTime | 为空 | 只读 | 只读 | 审核通过或驳回时写入 | 只读 |
| reviewResult | 为空 | 只读 | 只读 | 审核人写入 | 只读 |
| reviewComment | 为空 | 只读 | 只读 | 审核人写入 | 只读 |

#### 3.7.1 生命周期规则

- **创建阶段**: 任务定义字段应一次性写入，默认仅允许在发布前修改。
- **执行阶段**: 任务定义应冻结，孩子仅执行任务，不得修改任务规则本身。
- **提交阶段**: 仅允许写入完成内容、附件和提交时间，不得覆盖任务定义。
- **审核阶段**: 仅允许写入审核人、审核结果和审核意见，提交内容应保留原始记录。
- **完成阶段**: 任务主体和审核记录均应只读，仅保留申诉、补审或积分回滚入口。

#### 3.7.2 推荐的写入边界

- **任务定义类字段**：title、description、category、points、deadline、childId / childIds、repeatType、completeTypes、needReview、reviewType、duration、earliestStart、latestEnd。
- **执行结果类字段**：status、completedAt、completedBy、completeContent、completeMedia、overtimeFlag。
- **审核结果类字段**：reviewerId、reviewTime、reviewResult、reviewComment。
- **系统字段**：id、createdAt、updatedAt、templateId、isTemplate。

### 3.8 字段总览汇总表

> 说明：本表适合用于评审、排期和页面对齐。它将“字段、含义、责任归属、端侧展示、可改阶段”合并呈现。

| 字段 | 含义 | 责任归属 | Web端 | 小程序端 | 创建后是否可改 | 归属阶段 |
|------|------|----------|------|---------|---------------|---------|
| title | 任务名称 | 家长/创建人 | 列表显示 / 模板编辑 | 列表显示 / 创建页填写 | 否 | 创建 |
| description | 任务描述 | 家长/创建人，孩子可补充 | 模板编辑 | 任务详情/创建页填写 | 仅补充说明 | 创建 / 提交 |
| category | 任务分类 | 家长/创建人 | 列表显示 / 模板编辑 | 列表显示 / 创建页填写 | 否 | 创建 |
| points | 奖励积分 | 家长/创建人 | 列表显示 / 模板编辑 | 列表显示 / 创建页填写 | 不建议改 | 创建 |
| deadline | 截止时间 | 家长/创建人 | 列表显示 | 创建页填写 | 否 | 创建 |
| childId / childIds | 执行孩子（单选/多选） | 家长/创建人 | 列表显示 childId | 创建页选择孩子 | 否 | 创建 |
| repeatType | 重复规则 | 家长/创建人 | 模板编辑 | 创建页可设 | 否 | 创建 |
| completeTypes | 完成方式 | 家长/创建人 | 模板编辑 | 创建页可设 | 否 | 创建 |
| needReview | 是否审核 | 家长/创建人 | 列表显示 / 模板编辑 | 创建页可设 | 否 | 创建 |
| reviewType | 审核方式 | 家长/创建人 | 模板编辑 | 创建页可设 | 否 | 创建 |
| duration | 预计时长 | 家长/创建人 | 模板显示 / 编辑 | 创建页可设 | 仅补充说明类调整 | 创建 |
| status | 当前状态 | 系统 | 列表显示 | 任务列表显示 | 系统变更 | 执行 / 审核 |
| completedAt | 完成时间 | 系统 | 历史/详情 | 完成结果展示 | 否 | 提交 / 审核 |
| completedBy | 完成人 | 孩子提交 | 历史/详情 | 完成结果展示 | 否 | 提交 |
| completeContent | 完成说明 | 孩子提交，家长审核 | 详情/审核页 | 提交页填写 | 可在审核前补充 | 提交 |
| completeMedia | 完成附件 | 孩子提交，家长审核 | 详情/审核页 | 提交页上传 | 可在审核前补充 | 提交 |
| overtimeFlag | 超时标记 | 系统 | 列表/详情 | 列表/结果提示 | 系统变更 | 执行 / 提交 |
| reviewerId | 审核人 | 审核人 | 审核页 | 不直接展示 | 否 | 审核 |
| reviewTime | 审核时间 | 系统记录 | 审核页 | 结果展示 | 否 | 审核 |
| reviewResult | 审核结果 | 审核人 | 审核页 | 结果展示 | 否 | 审核 |
| reviewComment | 审核意见 | 审核人 | 审核页 | 结果展示 | 否 | 审核 |
| templateId | 模板来源 | 系统 | 模板页关联 | 模板自动带入 | 否 | 创建 |
| isTemplate | 模板标记 | 系统 | 模板页状态 | 不直接展示 | 否 | 创建 |
| createdAt | 创建时间 | 系统 | 列表显示 | 不展示 | 否 | 系统 |
| updatedAt | 更新时间 | 系统 | 列表/详情 | 不展示 | 否 | 系统 |
| id | 任务ID | 系统 | 列表显示 | 不展示 | 否 | 系统 |

#### 3.8.1 责任边界补充说明

- **家长/创建人负责**: 任务定义字段的填写与首次发布，包括标题、描述、分类、积分、截止时间、执行孩子、重复规则、完成方式、审核方式和时长。
- **孩子负责**: 提交执行结果，包括完成说明、附件和实际完成状态。
- **审核人负责**: 输出审核结果、审核意见以及是否通过的最终判断。
- **系统负责**: 状态流转、时间戳、超时标记、模板关联、创建时间和更新时间。

### 3.9 阶段 × 角色 × 动作矩阵

> 说明：本表用于统一“谁在什么阶段做什么”，避免文档仅描述字段而忽略流程责任。

| 阶段 | 家长/创建人 | 孩子 | 审核人 | 系统 |
|------|------------|------|--------|------|
| 创建阶段 | 创建任务、选择孩子、设置积分/截止时间/完成方式/审核方式/重复规则、选择模板、发布任务 | 一般不参与；如有任务建议，仅提交申请不直接生效 | 可作为模板审核人或指定审核人，但不直接参与任务创建 | 校验必填项、生成任务ID、写入创建时间、初始化状态 |
| 执行阶段 | 查看任务进度、必要时调整未发布任务；发布后原则上不改规则 | 查看任务、领取/开始任务、阅读执行要求 | 查看待审核任务预览，不修改任务定义 | 记录任务状态变化、计算超时、发送提醒 |
| 提交阶段 | 查看孩子提交内容、等待审核 | 填写完成说明、上传图片/视频/录音、提交完成结果、必要时补充材料 | 查看提交内容，准备审核 | 记录提交时间、提交内容、附件信息、提交次数 |
| 审核阶段 | 根据需要参与审核或查看审核结果 | 根据审核意见补充材料或重新提交 | 审核通过/驳回/退回补充，填写审核意见 | 记录审核结果、审核时间、审核人，触发积分变更 |
| 完成阶段 | 查看最终结果、积分变更和历史记录 | 查看完成结果、获得积分或驳回原因 | 查看审核归档和历史记录 | 归档任务、保留流水、生成统计数据 |

#### 3.9.1 动作规则说明

- **创建阶段**: 仅家长/创建人可定义任务，孩子不直接参与任务生效。
- **执行阶段**: 孩子为主要执行者，家长负责监督，系统负责提醒与超时判断。
- **提交阶段**: 孩子负责提交，家长负责查看，系统负责记录提交证据。
- **审核阶段**: 审核人负责最终判断，孩子仅在需要时补充材料。
- **完成阶段**: 任务主体冻结，仅保留查看、统计和补审能力。

### 3.10 接口级字段清单

> 说明：本节按接口维度列出任务创建、任务完成与任务审核所需字段，并补充请求示例与返回语义。该清单用于前后端联调、接口文档和参数校验。

#### 3.10.1 创建任务接口

**接口**：`POST /api/tasks`
 
| 字段 | 是否必填 | 说明 | 责任主体 |
|------|----------|------|----------|
| title | 是 | 任务名称 | 家长/创建人 |
| childId / childIds | 是 | 执行孩子（单选/多选） | 家长/创建人 |
| points | 是 | 奖励积分 | 家长/创建人 |
| category | 是 | 任务分类 | 家长/创建人 |
| deadline | 是 | 截止时间 | 家长/创建人 |
| description | 否 | 任务描述 | 家长/创建人 |
| repeatType | 否 | 重复规则 | 家长/创建人 |
| completeTypes | 否 | 完成方式 | 家长/创建人 |
| needReview | 否 | 是否需要审核 | 家长/创建人 |
| reviewType | 否 | 审核方式 | 家长/创建人 |
| duration | 否 | 预计时长 | 家长/创建人 |
| earliestStart | 否 | 最早开始时间 | 家长/创建人 |
| latestEnd | 否 | 最晚结束时间 | 家长/创建人 |
| templateId | 否 | 模板来源 | 系统/家长 |
| bonusRule | 否 | 超额积分规则 | 家长/创建人 |
| pointsExpireDays | 否 | 积分有效期 | 家长/创建人 |

**校验要求**
- 必填项不得为空。
- `points` 应符合积分范围约束。
- `deadline` 应合法且不得早于当前时间。
- 若选择模板，系统可自动回填模板字段。

#### 3.10.2 完成任务接口

**接口**：`POST /api/tasks/{id}/complete`

| 字段 | 是否必填 | 说明 | 责任主体 |
|------|----------|------|----------|
| childId | 是 | 完成任务的孩子 | 孩子 |
| completeContent / text | 否 | 完成说明 | 孩子 |
| completeMedia | 否 | 完成附件 | 孩子 |
| photoUrl | 否 | 图片地址（如适用） | 孩子 |
| audioUrl | 否 | 语音地址（如适用） | 孩子 |
| videoUrl | 否 | 视频地址（如适用） | 孩子 |
| completedAt | 否 | 完成时间 | 系统/孩子 |

**校验要求**
- `childId` 应与任务执行对象一致。
- 提交内容应符合任务配置的完成方式。
- 系统应记录提交时间、提交内容和附件信息，并据规则判断是否进入待审核。

#### 3.10.3 审核任务接口

**接口**：`POST /api/tasks/{id}/review`

| 字段 | 是否必填 | 说明 | 责任主体 |
|------|----------|------|----------|
| reviewResult | 是 | 审核结果（通过/驳回/退回补充） | 审核人 |
| reviewerId | 是 | 审核人 | 审核人 |
| reviewComment | 否 | 审核意见 | 审核人 |
| reviewTime | 否 | 审核时间 | 系统/审核人 |

**校验要求**
- 审核人应具备该任务的审核权限。
- 任务状态应处于待审核阶段。
- 系统应在审核完成后更新任务状态，并触发积分发放或回滚逻辑。

#### 3.10.4 请求示例

**创建任务示例**

| 字段 | 示例值 | 说明 |
|------|--------|------|
| title | 整理书桌 | 任务名称 |
| description | 把书桌上的书本、文具和杂物整理干净 | 任务描述 |
| childId | 10001 | 执行孩子 |
| points | 5 | 奖励积分 |
| category | 生活类 | 任务分类 |
| deadline | 2026-04-20T20:00:00 | 截止时间 |
| repeatType | none | 重复规则 |
| completeTypes | ["checkin", "image"] | 完成方式 |
| needReview | 1 | 需要审核 |
| reviewType | parent | 审核方式 |
| duration | 20 | 预计时长 |

**完成任务示例**

| 字段 | 示例值 | 说明 |
|------|--------|------|
| childId | 10001 | 完成任务的孩子 |
| completeContent | 已经整理完毕，桌面已清空 | 完成说明 |
| completeMedia | ["https://example.com/upload/task/20260414/desk-1.jpg"] | 完成附件 |
| completedAt | 2026-04-14T19:30:00 | 完成时间 |

**审核任务示例**

| 字段 | 示例值 | 说明 |
|------|--------|------|
| reviewerId | 9001 | 审核人 |
| reviewResult | approved | 审核结果 |
| reviewComment | 整理得很整齐，符合要求 | 审核意见 |
| reviewTime | 2026-04-14T19:40:00 | 审核时间 |

#### 3.10.5 返回结果说明

| 场景 | 成功返回 | 失败原因 |
|------|----------|----------|
| 创建任务 | 任务ID、创建时间、初始状态 | 必填字段缺失、截止时间非法、积分超出范围、执行对象无效 |
| 完成任务 | 完成结果、积分变动信息、当前状态 | 任务不存在、任务状态不允许完成、孩子不匹配、提交内容不符合要求 |
| 审核任务 | 审核结果、审核时间、最终状态、积分处理结果 | 审核权限不足、任务未进入待审核状态、审核结果参数非法 |

#### 3.10.6 状态建议

| 场景 | 建议状态 | 说明 |
|------|----------|------|
| 创建任务成功 | 待执行 / 待发布 | 任务已创建，等待孩子执行或等待正式发布 |
| 完成任务成功且无需审核 | 已完成 | 系统可直接结算积分并结束流程 |
| 完成任务成功且需要审核 | 待审核 | 任务进入家长/审核人确认阶段 |
| 审核通过 | 已完成 | 任务正式完成，积分结算生效 |
| 审核驳回 | 已驳回 | 任务回到补充材料或重做流程 |
| 审核退回补充 | 待提交 | 孩子补充材料后再次提交 |

---

## 四、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} | 家庭统计 |

### 4.3 小游戏任务（任务类型为"小游戏类"）

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | /api/mini-game/list | 获取小游戏列表 |
| POST | /api/mini-game/{gameCode} | 获取游戏详情 |
| POST | /api/mini-game/all | 获取所有小游戏(管理端) |
| PUT | /api/mini-game/{id}/status | 更新游戏状态 |
| POST | /api/mini-game/complete | 完成任务获得积分 |

---

## 五、前端页面一览

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

---

## 六、待完善事项

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

---

## 七、数据库变更

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