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`

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

**响应示例**:
```json
{
  "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`

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

**使用示例**:
```bash
# 喝水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杯水"}'
```

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

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

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

**使用示例**:
```bash
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`

**请求体**:
```typescript
{
  reason?: string;  // 跳过原因（可选）
}
```

**使用示例**:
```bash
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`

**查询参数**:
```typescript
{
  goalId?: string;  // 目标ID（可选，不传则统计所有目标的任务）
}
```

**响应示例**:
```json
{
  "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. **创建目标**:
```json
{
  "title": "每日喝水",
  "description": "每天喝8杯水保持健康",
  "repeatType": "daily",
  "frequency": 8,
  "category": "健康",
  "startDate": "2024-01-01"
}
```

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

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

### 场景2：每周运动目标

1. **创建目标**:
```json
{
  "title": "每周运动",
  "description": "每周运动3次",
  "repeatType": "weekly",
  "frequency": 3,
  "category": "运动",
  "startDate": "2024-01-01"
}
```

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

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

### 场景3：自定义周期目标

1. **创建目标**:
```json
{
  "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。