更新训练会话API文档和服务逻辑

- 修改训练会话文档,增加三种训练创建方式的详细说明,包括自动获取、基于计划手动创建和完全自定义创建。
- 在控制器中新增创建训练会话和向训练会话添加自定义动作的API,支持基于训练计划或自定义动作创建训练会话。
- 更新服务逻辑,支持创建自定义训练会话并添加自定义动作,增强训练会话管理的灵活性和用户体验。
This commit is contained in:
richarjiang
2025-08-15 16:12:27 +08:00
parent 0edcfdcae9
commit 4257449f76
4 changed files with 283 additions and 98 deletions

View File

@@ -45,17 +45,69 @@ POST /training-plans/{planId}/exercises
POST /training-plans/{planId}/activate
```
### 第二步:开始每日训练
### 第二步:开始训练(三种方式)
#### 方式一:自动获取今日训练(推荐)
```bash
# 1. 获取今日训练会话(如不存在则自动创建)
# 获取今日训练会话(如不存在则自动创建)
GET /workouts/today
# 系统会自动基于激活的训练计划创建今日训练会话
```
# 2. 开始训练会话(可选)
POST /workouts/sessions/{sessionId}/start
#### 方式二:基于训练计划手动创建
```bash
POST /workouts/sessions
{
"startedAt": "2024-01-15T09:00:00.000Z"
"trainingPlanId": "{planId}",
"name": "晚间训练",
"scheduledDate": "2024-01-15T19:00:00.000Z"
}
```
#### 方式三:创建完全自定义训练
```bash
POST /workouts/sessions
{
"name": "自定义核心训练",
"scheduledDate": "2024-01-15T15:00:00.000Z",
"customExercises": [
{
"exerciseKey": "plank",
"name": "平板支撑",
"plannedDurationSec": 60,
"itemType": "exercise",
"sortOrder": 1
},
{
"name": "休息",
"plannedDurationSec": 30,
"itemType": "rest",
"sortOrder": 2
},
{
"name": "自定义深蹲变式",
"plannedSets": 3,
"plannedReps": 20,
"note": "脚距离肩膀更宽",
"itemType": "exercise",
"sortOrder": 3
}
]
}
```
### 第三步:执行训练
```bash
# 1. 开始训练会话(可选)
POST /workouts/sessions/{sessionId}/start
# 2. 动态添加动作(如果需要)
POST /workouts/sessions/{sessionId}/exercises
{
"name": "额外的拉伸",
"plannedDurationSec": 120,
"itemType": "exercise"
}
# 3. 开始特定动作
@@ -87,25 +139,27 @@ POST /workouts/sessions/{sessionId}/exercises/{exerciseId}/complete
- 每日训练是独立的实例
- 修改计划不影响历史训练记录
### 2. 自动化管理
- 客户端直接获取今日训练,系统自动创建
- 所有动作完成后自动完成训练会话
- 无需手动管理会话生命周期
### 2. 灵活的创建方式
- 自动创建:基于激活计划的今日训练
- 计划创建:基于指定训练计划创建
- 自定义创建:完全自定义的训练动作
### 3. 进度追踪
- 每个训练会话都有完整的状态跟踪
- 支持详细的性能数据记录
- 可以分析训练趋势和进步情况
### 4. 灵活性
- 支持训练中的临时调整
### 4. 动态调整能力
- 支持训练中动态添加动作
- 支持跳过或修改特定动作
- 自动完成会话管理
- 自动计算训练统计数据
## API 端点总览
### 训练会话管理
- `GET /workouts/today` - 获取/自动创建今日训练会话 ⭐
- `POST /workouts/sessions` - 手动创建训练会话(支持基于计划或自定义动作)
- `GET /workouts/sessions` - 获取训练会话列表
- `GET /workouts/sessions/{id}` - 获取训练会话详情
- `POST /workouts/sessions/{id}/start` - 开始训练(可选)
@@ -113,6 +167,7 @@ POST /workouts/sessions/{sessionId}/exercises/{exerciseId}/complete
- 注意:训练会话在所有动作完成后自动完成
### 训练动作管理
- `POST /workouts/sessions/{id}/exercises` - 向训练会话添加自定义动作 ⭐
- `GET /workouts/sessions/{id}/exercises` - 获取训练动作列表
- `GET /workouts/sessions/{id}/exercises/{exerciseId}` - 获取动作详情
- `POST /workouts/sessions/{id}/exercises/{exerciseId}/start` - 开始动作