# 目标管理 API 文档

## 概述

目标管理功能允许用户创建、管理和跟踪个人目标。每个目标包含标题、重复周期、频率等属性，支持完整的增删改查操作。

## 数据模型

### 目标 (Goal)

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| id | UUID | 是 | 目标唯一标识 |
| userId | String | 是 | 用户ID |
| title | String | 是 | 目标标题 |
| description | Text | 否 | 目标描述 |
| repeatType | Enum | 是 | 重复周期类型：daily/weekly/monthly/custom |
| frequency | Integer | 是 | 频率（每天/每周/每月多少次） |
| customRepeatRule | JSON | 否 | 自定义重复规则 |
| startDate | Date | 是 | 目标开始日期 |
| endDate | Date | 否 | 目标结束日期 |
| status | Enum | 是 | 目标状态：active/paused/completed/cancelled |
| completedCount | Integer | 是 | 已完成次数 |
| targetCount | Integer | 否 | 目标总次数 |
| category | String | 否 | 目标分类标签 |
| priority | Integer | 是 | 优先级（0-10） |
| hasReminder | Boolean | 是 | 是否提醒 |
| reminderTime | Time | 否 | 提醒时间 |
| reminderSettings | JSON | 否 | 提醒设置 |

### 目标完成记录 (GoalCompletion)

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| id | UUID | 是 | 完成记录唯一标识 |
| goalId | UUID | 是 | 目标ID |
| userId | String | 是 | 用户ID |
| completedAt | DateTime | 是 | 完成日期 |
| completionCount | Integer | 是 | 完成次数 |
| notes | Text | 否 | 完成备注 |
| metadata | JSON | 否 | 额外数据 |

## API 接口

### 1. 创建目标

**POST** `/goals`

**请求体：**
```json
{
  "title": "每天跑步30分钟",
  "description": "提高心肺功能，增强体质",
  "repeatType": "daily",
  "frequency": 1,
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "targetCount": 365,
  "category": "运动",
  "priority": 5,
  "hasReminder": true,
  "reminderTime": "07:00",
  "reminderSettings": {
    "weekdays": [1, 2, 3, 4, 5, 6, 0],
    "enabled": true
  }
}
```

**响应：**
```json
{
  "code": 0,
  "message": "目标创建成功",
  "data": {
    "id": "uuid",
    "title": "每天跑步30分钟",
    "status": "active",
    "completedCount": 0,
    "progressPercentage": 0,
    "daysRemaining": 365
  }
}
```

### 2. 获取目标列表

**GET** `/goals?page=1&pageSize=20&status=active&category=运动&search=跑步`

**查询参数：**
- `page`: 页码（默认1）
- `pageSize`: 每页数量（默认20，最大100）
- `status`: 目标状态筛选
- `repeatType`: 重复类型筛选
- `category`: 分类筛选
- `search`: 搜索标题和描述
- `startDate`: 开始日期范围
- `endDate`: 结束日期范围
- `sortBy`: 排序字段（createdAt/updatedAt/priority/title/startDate）
- `sortOrder`: 排序方向（asc/desc）

**响应：**
```json
{
  "code": 0,
  "message": "获取目标列表成功",
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 5,
    "items": [
      {
        "id": "uuid",
        "title": "每天跑步30分钟",
        "status": "active",
        "completedCount": 15,
        "targetCount": 365,
        "progressPercentage": 4,
        "daysRemaining": 350
      }
    ]
  }
}
```

### 3. 获取目标详情

**GET** `/goals/{id}`

**响应：**
```json
{
  "code": 0,
  "message": "获取目标详情成功",
  "data": {
    "id": "uuid",
    "title": "每天跑步30分钟",
    "description": "提高心肺功能，增强体质",
    "repeatType": "daily",
    "frequency": 1,
    "status": "active",
    "completedCount": 15,
    "targetCount": 365,
    "progressPercentage": 4,
    "daysRemaining": 350,
    "completions": [
      {
        "id": "completion-uuid",
        "completedAt": "2024-01-15T07:00:00Z",
        "completionCount": 1,
        "notes": "今天感觉很好"
      }
    ]
  }
}
```

### 4. 更新目标

**PUT** `/goals/{id}`

**请求体：**
```json
{
  "title": "每天跑步45分钟",
  "frequency": 1,
  "priority": 7
}
```

**响应：**
```json
{
  "code": 0,
  "message": "目标更新成功",
  "data": {
    "id": "uuid",
    "title": "每天跑步45分钟",
    "priority": 7
  }
}
```

### 5. 删除目标

**DELETE** `/goals/{id}`

**响应：**
```json
{
  "code": 0,
  "message": "目标删除成功",
  "data": true
}
```

### 6. 记录目标完成

**POST** `/goals/{id}/complete`

**请求体：**
```json
{
  "completionCount": 1,
  "notes": "今天完成了跑步目标",
  "completedAt": "2024-01-15T07:30:00Z"
}
```

**响应：**
```json
{
  "code": 0,
  "message": "目标完成记录成功",
  "data": {
    "id": "completion-uuid",
    "goalId": "goal-uuid",
    "completedAt": "2024-01-15T07:30:00Z",
    "completionCount": 1,
    "notes": "今天完成了跑步目标"
  }
}
```

### 7. 获取目标完成记录

**GET** `/goals/{id}/completions?page=1&pageSize=20&startDate=2024-01-01&endDate=2024-01-31`

**响应：**
```json
{
  "code": 0,
  "message": "获取目标完成记录成功",
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 15,
    "items": [
      {
        "id": "completion-uuid",
        "completedAt": "2024-01-15T07:30:00Z",
        "completionCount": 1,
        "notes": "今天完成了跑步目标",
        "goal": {
          "id": "goal-uuid",
          "title": "每天跑步30分钟"
        }
      }
    ]
  }
}
```

### 8. 获取目标统计信息

**GET** `/goals/stats/overview`

**响应：**
```json
{
  "code": 0,
  "message": "获取目标统计成功",
  "data": {
    "total": 10,
    "active": 7,
    "completed": 2,
    "paused": 1,
    "cancelled": 0,
    "byCategory": {
      "运动": 5,
      "学习": 3,
      "健康": 2
    },
    "byRepeatType": {
      "daily": 6,
      "weekly": 3,
      "monthly": 1
    },
    "totalCompletions": 150,
    "thisWeekCompletions": 25,
    "thisMonthCompletions": 100
  }
}
```

### 9. 批量操作目标

**POST** `/goals/batch`

**请求体：**
```json
{
  "goalIds": ["uuid1", "uuid2", "uuid3"],
  "action": "pause"
}
```

**支持的操作：**
- `pause`: 暂停目标
- `resume`: 恢复目标
- `complete`: 完成目标
- `delete`: 删除目标

**响应：**
```json
{
  "code": 0,
  "message": "批量操作完成",
  "data": [
    {
      "goalId": "uuid1",
      "success": true
    },
    {
      "goalId": "uuid2",
      "success": true
    },
    {
      "goalId": "uuid3",
      "success": false,
      "error": "目标不存在"
    }
  ]
}
```

## 使用示例

### 创建每日运动目标
```bash
curl -X POST http://localhost:3000/goals \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "每日普拉提练习",
    "description": "每天进行30分钟的普拉提练习，提高核心力量",
    "repeatType": "daily",
    "frequency": 1,
    "startDate": "2024-01-01",
    "category": "运动",
    "priority": 8,
    "hasReminder": true,
    "reminderTime": "18:00"
  }'
```

### 创建每周学习目标
```bash
curl -X POST http://localhost:3000/goals \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "每周阅读一本书",
    "description": "每周至少阅读一本专业书籍",
    "repeatType": "weekly",
    "frequency": 1,
    "startDate": "2024-01-01",
    "targetCount": 52,
    "category": "学习",
    "priority": 6
  }'
```

### 记录目标完成
```bash
curl -X POST http://localhost:3000/goals/GOAL_ID/complete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "今天完成了30分钟的普拉提练习，感觉很好"
  }'
```

## 错误处理

所有接口都遵循统一的错误响应格式：

```json
{
  "code": 1,
  "message": "错误描述",
  "data": null
}
```

常见错误：
- `目标不存在`: 404
- `参数验证失败`: 400
- `权限不足`: 403
- `服务器内部错误`: 500

## 注意事项

1. 所有接口都需要JWT认证
2. 用户只能操作自己的目标
3. 已完成的目标不能修改状态
4. 删除操作采用软删除，不会真正删除数据
5. 目标完成记录会自动更新目标的完成次数
6. 达到目标总次数时，目标状态会自动变为已完成