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 使用流程

第一步：创建训练计划模板

# 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

第二步：开始训练（三种方式）

方式一：自动获取今日训练（推荐）

# 获取今日训练会话（如不存在则自动创建）
GET /workouts/today
# 系统会自动基于激活的训练计划创建今日训练会话

方式二：基于训练计划手动创建

POST /workouts/sessions
{
  "trainingPlanId": "{planId}",
  "name": "晚间训练",
  "scheduledDate": "2024-01-15T19:00:00.000Z"
}

方式三：创建完全自定义训练

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
    }
  ]
}

第三步：执行训练

# 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 (训练会话)

{
  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 (训练动作实例)

{
  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. 原有的训练计划数据保持不变，作为模板使用

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