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

第二步：开始每日训练

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

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

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