feat: 新增目标子任务管理功能模块
- 实现目标子任务的完整功能，包括数据库表设计、API接口、业务逻辑和文档说明。 - 支持用户创建、管理和跟踪目标子任务，提供增删改查操作及任务完成记录功能。 - 引入惰性任务生成机制，优化任务管理体验，提升系统性能和用户交互。
This commit is contained in:
richarjiang
304
docs/goal-tasks-api-guide.md
Normal file
304
docs/goal-tasks-api-guide.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 目标子任务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。
|
||||
Reference in New Issue
Block a user