400 lines
8.1 KiB
Markdown
400 lines
8.1 KiB
Markdown
# 目标管理 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. 达到目标总次数时，目标状态会自动变为已完成
|