plates-server/docs/workout-sessions-api-guide.md

# 训练会话 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
# 获取今日训练会话（如不存在则自动创建）
GET /workouts/today
# 系统会自动基于激活的训练计划创建今日训练会话
```

#### 方式二：基于训练计划手动创建
```bash
POST /workouts/sessions
{
  "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. 开始特定动作
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` - 获取/自动创建今日训练会话 ⭐
- `POST /workouts/sessions` - 手动创建训练会话（支持基于计划或自定义动作）
- `GET /workouts/sessions` - 获取训练会话列表
- `GET /workouts/sessions/{id}` - 获取训练会话详情
- `POST /workouts/sessions/{id}/start` - 开始训练（可选）
- `DELETE /workouts/sessions/{id}` - 删除训练会话
- 注意：训练会话在所有动作完成后自动完成

### 训练动作管理
- `POST /workouts/sessions/{id}/exercises` - 向训练会话添加自定义动作 ⭐
- `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. 原有的训练计划数据保持不变，作为模板使用

这样的架构分离使得系统更加清晰、可维护，也更符合健身应用的实际使用场景。