新增普拉提训练系统的数据库结构和数据导入功能
- 创建普拉提分类和动作数据的SQL导入脚本，支持垫上普拉提和器械普拉提的分类管理 - 实现数据库结构迁移脚本，添加新字段以支持普拉提类型和器械名称 - 更新数据库升级总结文档，详细说明数据库结构变更和数据导入步骤 - 创建训练会话相关表，支持每日训练实例功能 - 引入训练会话管理模块，整合训练计划与实际训练会话的关系
This commit is contained in:
richarjiang
190
docs/workout-sessions-api-guide.md
Normal file
190
docs/workout-sessions-api-guide.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# 训练会话 API 使用指南
|
||||
|
||||
## 架构说明
|
||||
|
||||
新的训练系统采用了分离的架构设计，符合健身应用的最佳实践：
|
||||
|
||||
### 1. 训练计划模板 (Training Plans)
|
||||
- **用途**: 用户创建和管理的训练计划模板
|
||||
- **表**: `t_training_plans` + `t_schedule_exercises`
|
||||
- **特点**: 静态配置，不包含完成状态
|
||||
- **API**: `/training-plans`
|
||||
|
||||
### 2. 训练会话实例 (Workout Sessions)
|
||||
- **用途**: 每日实际训练，从训练计划模板复制而来
|
||||
- **表**: `t_workout_sessions` + `t_workout_exercises`
|
||||
- **特点**: 动态数据，包含完成状态、进度追踪
|
||||
- **API**: `/workouts`
|
||||
|
||||
## API 使用流程
|
||||
|
||||
### 第一步：创建训练计划模板
|
||||
|
||||
```bash
|
||||
# 1. 创建训练计划
|
||||
POST /training-plans
|
||||
{
|
||||
"name": "全身力量训练",
|
||||
"startDate": "2024-01-15T00:00:00.000Z",
|
||||
"mode": "daysOfWeek",
|
||||
"daysOfWeek": [1, 3, 5],
|
||||
"goal": "core_strength"
|
||||
}
|
||||
|
||||
# 2. 添加训练动作到计划
|
||||
POST /training-plans/{planId}/exercises
|
||||
{
|
||||
"exerciseKey": "squat",
|
||||
"name": "深蹲训练",
|
||||
"sets": 3,
|
||||
"reps": 15,
|
||||
"itemType": "exercise"
|
||||
}
|
||||
|
||||
# 3. 激活训练计划
|
||||
POST /training-plans/{planId}/activate
|
||||
```
|
||||
|
||||
### 第二步：开始每日训练
|
||||
|
||||
```bash
|
||||
# 1. 获取今日训练会话（如不存在则自动创建）
|
||||
GET /workouts/today
|
||||
# 系统会自动基于激活的训练计划创建今日训练会话
|
||||
|
||||
# 2. 开始训练会话（可选）
|
||||
POST /workouts/sessions/{sessionId}/start
|
||||
{
|
||||
"startedAt": "2024-01-15T09:00:00.000Z"
|
||||
}
|
||||
|
||||
# 3. 开始特定动作
|
||||
POST /workouts/sessions/{sessionId}/exercises/{exerciseId}/start
|
||||
|
||||
# 4. 完成动作
|
||||
POST /workouts/sessions/{sessionId}/exercises/{exerciseId}/complete
|
||||
{
|
||||
"completedSets": 3,
|
||||
"completedReps": 15,
|
||||
"actualDurationSec": 180,
|
||||
"performanceData": {
|
||||
"sets": [
|
||||
{ "reps": 15, "difficulty": 7 },
|
||||
{ "reps": 12, "difficulty": 8 },
|
||||
{ "reps": 10, "difficulty": 9 }
|
||||
],
|
||||
"perceivedExertion": 8
|
||||
}
|
||||
}
|
||||
|
||||
# 注意：当所有动作完成后，训练会话会自动标记为完成
|
||||
```
|
||||
|
||||
## 主要优势
|
||||
|
||||
### 1. 数据分离
|
||||
- 训练计划是可重用的模板
|
||||
- 每日训练是独立的实例
|
||||
- 修改计划不影响历史训练记录
|
||||
|
||||
### 2. 自动化管理
|
||||
- 客户端直接获取今日训练，系统自动创建
|
||||
- 所有动作完成后自动完成训练会话
|
||||
- 无需手动管理会话生命周期
|
||||
|
||||
### 3. 进度追踪
|
||||
- 每个训练会话都有完整的状态跟踪
|
||||
- 支持详细的性能数据记录
|
||||
- 可以分析训练趋势和进步情况
|
||||
|
||||
### 4. 灵活性
|
||||
- 支持训练中的临时调整
|
||||
- 支持跳过或修改特定动作
|
||||
- 自动计算训练统计数据
|
||||
|
||||
## API 端点总览
|
||||
|
||||
### 训练会话管理
|
||||
- `GET /workouts/today` - 获取/自动创建今日训练会话 ⭐
|
||||
- `GET /workouts/sessions` - 获取训练会话列表
|
||||
- `GET /workouts/sessions/{id}` - 获取训练会话详情
|
||||
- `POST /workouts/sessions/{id}/start` - 开始训练（可选）
|
||||
- `DELETE /workouts/sessions/{id}` - 删除训练会话
|
||||
- 注意：训练会话在所有动作完成后自动完成
|
||||
|
||||
### 训练动作管理
|
||||
- `GET /workouts/sessions/{id}/exercises` - 获取训练动作列表
|
||||
- `GET /workouts/sessions/{id}/exercises/{exerciseId}` - 获取动作详情
|
||||
- `POST /workouts/sessions/{id}/exercises/{exerciseId}/start` - 开始动作
|
||||
- `POST /workouts/sessions/{id}/exercises/{exerciseId}/complete` - 完成动作
|
||||
- `POST /workouts/sessions/{id}/exercises/{exerciseId}/skip` - 跳过动作
|
||||
- `PUT /workouts/sessions/{id}/exercises/{exerciseId}` - 更新动作信息
|
||||
|
||||
### 统计和快捷功能
|
||||
- `GET /workouts/sessions/{id}/stats` - 获取训练统计
|
||||
- `GET /workouts/recent` - 获取最近训练
|
||||
|
||||
## 数据模型
|
||||
|
||||
### WorkoutSession (训练会话)
|
||||
```typescript
|
||||
{
|
||||
id: string;
|
||||
userId: string;
|
||||
trainingPlanId: string; // 关联的训练计划模板
|
||||
name: string;
|
||||
scheduledDate: Date;
|
||||
startedAt?: Date;
|
||||
completedAt?: Date;
|
||||
status: 'planned' | 'in_progress' | 'completed' | 'skipped';
|
||||
totalDurationSec?: number;
|
||||
summary?: string;
|
||||
caloriesBurned?: number;
|
||||
stats?: {
|
||||
totalExercises: number;
|
||||
completedExercises: number;
|
||||
totalSets: number;
|
||||
completedSets: number;
|
||||
// ...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### WorkoutExercise (训练动作实例)
|
||||
```typescript
|
||||
{
|
||||
id: string;
|
||||
workoutSessionId: string;
|
||||
exerciseKey?: string; // 关联动作库
|
||||
name: string;
|
||||
plannedSets?: number; // 计划数值
|
||||
completedSets?: number; // 实际完成数值
|
||||
plannedReps?: number;
|
||||
completedReps?: number;
|
||||
plannedDurationSec?: number;
|
||||
actualDurationSec?: number;
|
||||
status: 'pending' | 'in_progress' | 'completed' | 'skipped';
|
||||
startedAt?: Date;
|
||||
completedAt?: Date;
|
||||
performanceData?: { // 详细性能数据
|
||||
sets: Array<{
|
||||
reps?: number;
|
||||
weight?: number;
|
||||
difficulty?: number;
|
||||
notes?: string;
|
||||
}>;
|
||||
heartRate?: { avg: number; max: number };
|
||||
perceivedExertion?: number; // RPE 1-10
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 迁移说明
|
||||
|
||||
如果您之前使用了 `training-plans` 的完成状态功能，现在需要：
|
||||
|
||||
1. 使用 `/workouts/sessions` 来创建每日训练
|
||||
2. 使用新的完成状态 API 来跟踪进度
|
||||
3. 原有的训练计划数据保持不变，作为模板使用
|
||||
|
||||
这样的架构分离使得系统更加清晰、可维护，也更符合健身应用的实际使用场景。
|
||||
Reference in New Issue
Block a user