plates-server/docs/goal-tasks-api-guide.md

目标子任务API使用指南

概述

目标子任务系统是对目标管理功能的扩展，它支持用户为每个目标自动生成对应的子任务，用户可以根据目标的频率设置（每天、每周、每月）来完成这些子任务。系统采用惰性加载的方式，每次获取任务列表时才生成新的任务。

核心功能

1. 惰性任务生成

• 触发时机: 当用户调用获取任务列表API时
• 生成策略:
  • 每日任务：提前生成7天的任务
  • 每周任务：提前生成4周的任务
  • 每月任务：提前生成3个月的任务
  • 自定义任务：根据自定义规则生成

2. 任务状态管理

• pending: 待开始
• in_progress: 进行中（部分完成）
• completed: 已完成
• overdue: 已过期
• skipped: 已跳过

3. 进度追踪

• 支持分步完成（如一天要喝8杯水，可以分8次上报）
• 自动计算完成进度百分比
• 当完成次数达到目标次数时自动标记为完成

API接口详解

1. 获取任务列表

请求方式: GET /goals/tasks

查询参数:

{
  goalId?: string;        // 目标ID（可选）
  status?: TaskStatus;    // 任务状态（可选）
  startDate?: string;     // 开始日期（可选）
  endDate?: string;       // 结束日期（可选）
  page?: number;          // 页码，默认1
  pageSize?: number;      // 每页数量，默认20
}

响应示例:

{
  "code": 200,
  "message": "获取任务列表成功",
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 5,
    "list": [
      {
        "id": "task-uuid",
        "goalId": "goal-uuid",
        "userId": "user-123",
        "title": "每日喝水 - 2024年01月15日",
        "description": "每日目标：完成8次",
        "startDate": "2024-01-15",
        "endDate": "2024-01-15",
        "targetCount": 8,
        "currentCount": 3,
        "status": "in_progress",
        "progressPercentage": 37,
        "completedAt": null,
        "notes": null,
        "metadata": null,
        "daysRemaining": 0,
        "isToday": true,
        "goal": {
          "id": "goal-uuid",
          "title": "每日喝水",
          "repeatType": "daily",
          "frequency": 8,
          "category": "健康"
        }
      }
    ]
  }
}

2. 完成任务

请求方式: POST /goals/tasks/:taskId/complete

请求体:

{
  count?: number;         // 完成次数，默认1
  notes?: string;         // 备注（可选）
  completedAt?: string;   // 完成时间（可选）
}

使用示例:

# 喝水1次
curl -X POST "http://localhost:3000/goals/tasks/task-uuid/complete" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"count": 1, "notes": "午饭后喝水"}'

# 一次性完成多次
curl -X POST "http://localhost:3000/goals/tasks/task-uuid/complete" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"count": 3, "notes": "连续喝了3杯水"}'

响应示例:

{
  "code": 200,
  "message": "任务完成成功",
  "data": {
    "id": "task-uuid",
    "currentCount": 4,
    "progressPercentage": 50,
    "status": "in_progress",
    "notes": "午饭后喝水"
  }
}

3. 获取特定目标的任务列表

请求方式: GET /goals/:goalId/tasks

使用示例:

curl -X GET "http://localhost:3000/goals/goal-uuid/tasks?page=1&pageSize=10" \
  -H "Authorization: Bearer your-token"

4. 跳过任务

请求方式: POST /goals/tasks/:taskId/skip

请求体:

{
  reason?: string;  // 跳过原因（可选）
}

使用示例:

curl -X POST "http://localhost:3000/goals/tasks/task-uuid/skip" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"reason": "今天身体不舒服"}'

5. 获取任务统计

请求方式: GET /goals/tasks/stats/overview

查询参数:

{
  goalId?: string;  // 目标ID（可选，不传则统计所有目标的任务）
}

响应示例:

{
  "code": 200,
  "message": "获取任务统计成功",
  "data": {
    "total": 15,
    "pending": 5,
    "inProgress": 3,
    "completed": 6,
    "overdue": 1,
    "skipped": 0,
    "totalProgress": 68,
    "todayTasks": 3,
    "weekTasks": 8,
    "monthTasks": 15
  }
}

典型使用场景

场景1：每日喝水目标

1. 创建目标:

{
  "title": "每日喝水",
  "description": "每天喝8杯水保持健康",
  "repeatType": "daily",
  "frequency": 8,
  "category": "健康",
  "startDate": "2024-01-01"
}

2. 系统自动生成任务: 当用户第一次获取任务列表时，系统会自动生成当天及未来7天的每日任务

3. 用户完成任务: 每次喝水后调用完成API，直到当天任务完成

场景2：每周运动目标

1. 创建目标:

{
  "title": "每周运动",
  "description": "每周运动3次",
  "repeatType": "weekly",
  "frequency": 3,
  "category": "运动",
  "startDate": "2024-01-01"
}

2. 系统生成周任务: 按周生成任务，每个任务的开始时间是周一，结束时间是周日

3. 灵活完成: 用户可以在一周内的任何时间完成3次运动，每次完成后调用API更新进度

场景3：自定义周期目标

1. 创建目标:

{
  "title": "周末阅读",
  "description": "每个周末阅读1小时",
  "repeatType": "custom",
  "frequency": 1,
  "customRepeatRule": {
    "weekdays": [0, 6]  // 周日和周六
  },
  "category": "学习"
}

2. 系统按规则生成: 只在周六和周日生成任务

最佳实践

1. 任务列表获取

• 建议按日期范围获取任务，避免一次性加载过多数据
• 可以按状态筛选任务，如只显示今天的待完成任务

2. 进度上报

• 鼓励用户及时上报完成情况，保持任务状态的实时性
• 对于可分步完成的目标，支持分次上报更有利于习惯养成

3. 错误处理

• 当任务不存在或已完成时，API会返回相应错误信息
• 客户端应该处理网络异常情况，支持离线记录后同步

4. 性能优化

• 惰性生成机制确保只在需要时生成任务
• 建议客户端缓存任务列表，减少不必要的API调用

数据库表结构

t_goal_tasks 表字段说明

字段名	类型	说明
id	CHAR(36)	任务ID，主键
goal_id	CHAR(36)	关联的目标ID
user_id	VARCHAR(255)	用户ID
title	VARCHAR(255)	任务标题
description	TEXT	任务描述
start_date	DATE	任务开始日期
end_date	DATE	任务结束日期
target_count	INT	目标完成次数
current_count	INT	当前完成次数
status	ENUM	任务状态
progress_percentage	INT	完成进度(0-100)
completed_at	DATETIME	完成时间
notes	TEXT	备注
metadata	JSON	扩展数据

注意事项

1. 时区处理: 所有日期时间都使用服务器时区，客户端需要进行相应转换
2. 并发安全: 多次快速调用完成API可能导致计数不准确，建议客户端控制调用频率
3. 数据一致性: 目标删除时会级联删除相关任务
4. 性能考虑: 大量历史任务可能影响查询性能，建议定期清理过期数据

常见问题

Q: 如何修改已生成的任务？ A: 可以使用更新任务API (PUT /goals/tasks/:taskId) 修改任务的基本信息，但不建议频繁修改以保持数据一致性。

Q: 任务过期后还能完成吗？ A: 过期任务状态会自动更新为'overdue'，但仍然可以完成，完成后状态会变为'completed'。

Q: 如何处理用户时区问题？ A: 客户端应该将用户本地时间转换为服务器时区后发送请求，显示时再转换回用户时区。

Q: 能否批量完成多个任务？ A: 目前API设计为单个任务操作，如需批量操作可以在客户端并发调用多个API。