feat: 新增目标管理功能模块
实现目标管理的完整功能，包括数据库表设计、API接口、业务逻辑和文档说明。支持用户创建、管理和跟踪个人目标，提供增删改查操作及目标完成记录功能。
This commit is contained in:
399
docs/goals-api-guide.md
Normal file
399
docs/goals-api-guide.md
Normal file
@@ -0,0 +1,399 @@
|
||||
# 目标管理 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. 达到目标总次数时，目标状态会自动变为已完成
|
||||
Reference in New Issue
Block a user