plates-server/docs/goals-api-guide.md

目标管理 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

请求体：

{
  "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
  }
}

响应：

{
  "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）

响应：

{
  "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}

响应：

{
  "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}

请求体：

{
  "title": "每天跑步45分钟",
  "frequency": 1,
  "priority": 7
}

响应：

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

5. 删除目标

DELETE /goals/{id}

响应：

{
  "code": 0,
  "message": "目标删除成功",
  "data": true
}

6. 记录目标完成

POST /goals/{id}/complete

请求体：

{
  "completionCount": 1,
  "notes": "今天完成了跑步目标",
  "completedAt": "2024-01-15T07:30:00Z"
}

响应：

{
  "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

响应：

{
  "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

响应：

{
  "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

请求体：

{
  "goalIds": ["uuid1", "uuid2", "uuid3"],
  "action": "pause"
}

支持的操作：

• pause: 暂停目标
• resume: 恢复目标
• complete: 完成目标
• delete: 删除目标

响应：

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

使用示例

创建每日运动目标

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"
  }'

创建每周学习目标

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
  }'

记录目标完成

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

错误处理

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

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

常见错误：

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

注意事项

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