cfc/docs/backup/root/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)
• 可选值: 学习类 / 生活类 / 运动类 / 小游戏类 / 其他
• 说明: 小游戏类是一种任务类型，孩子通过完成在线小游戏获得积分奖励
• 小游戏列表:
  • 舒尔特方格 - 专注力训练
  • 猜数字 (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 实体字段

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