plates-server/src/training-plans/README.md

训练计划项目管理 API 文档

这个功能实现了对训练计划下具体训练项目的完整管理，支持增删改查、排序和完成状态跟踪。项目与系统动作库智能关联，提供了训练、休息、提醒三种类型的灵活支持。

数据模型

ScheduleExercise (训练项目)

interface ScheduleExercise {
  id: string;                    // 项目ID
  trainingPlanId: string;        // 所属训练计划ID
  userId: string;                // 用户ID
  exerciseKey?: string;          // 关联的动作key（仅exercise类型）
  name: string;                  // 项目名称
  sets?: number;                 // 组数
  reps?: number;                 // 重复次数
  durationSec?: number;          // 持续时长(秒)
  restSec?: number;              // 休息时长(秒)
  note?: string;                 // 备注
  itemType: 'exercise' | 'rest' | 'note';  // 项目类型
  completed: boolean;            // 是否已完成
  sortOrder: number;             // 排序顺序
  createdAt: Date;              // 创建时间
  updatedAt: Date;              // 更新时间
  deleted: boolean;             // 是否已删除
  
  // 关联的动作信息（仅exercise类型时存在）
  exercise?: {
    key: string;                 // 动作key
    name: string;                // 动作名称
    description: string;         // 动作描述
    categoryKey: string;         // 分类key
    categoryName: string;        // 分类名称
  };
}

API 端点

1. 添加训练项目

POST /training-plans/:id/exercises

{
  "exerciseKey": "squat",          // 关联到动作库中的深蹲
  "name": "深蹲训练",
  "sets": 3,
  "reps": 15,
  "restSec": 60,
  "itemType": "exercise",
  "note": "注意膝盖不要超过脚尖"
}

或者添加休息项目：

{
  "name": "组间休息",
  "durationSec": 90,
  "itemType": "rest"
}

或者添加提醒项目：

{
  "name": "安全提醒",
  "note": "如感到不适请立即停止",
  "itemType": "note"
}

2. 获取训练计划的所有项目

GET /training-plans/:id/exercises

返回按排序顺序排列的所有训练项目，包含关联的动作信息：

[
  {
    "id": "ex_123",
    "trainingPlanId": "plan_456",
    "exerciseKey": "squat",
    "name": "深蹲训练",
    "sets": 3,
    "reps": 15,
    "restSec": 60,
    "itemType": "exercise",
    "completed": false,
    "sortOrder": 1,
    "exercise": {
      "key": "squat",
      "name": "深蹲",
      "description": "下肢力量训练的基础动作",
      "categoryKey": "strength",
      "categoryName": "力量训练"
    }
  },
  {
    "id": "ex_124",
    "name": "组间休息",
    "durationSec": 90,
    "itemType": "rest",
    "completed": false,
    "sortOrder": 2
  }
]

3. 获取训练项目详情

GET /training-plans/:id/exercises/:exerciseId

4. 更新训练项目

PUT /training-plans/:id/exercises/:exerciseId

{
  "exerciseKey": "pushup",     // 更换为俯卧撑
  "name": "俯卧撑训练",
  "sets": 4,
  "reps": 12,
  "completed": true
}

5. 删除训练项目

DELETE /training-plans/:id/exercises/:exerciseId

6. 更新训练项目排序

PUT /training-plans/:id/exercises/order

{
  "exerciseIds": ["id3", "id1", "id2"]
}

重新排列项目顺序，数组中的顺序即为新的排序。

7. 标记训练项目完成状态

PUT /training-plans/:id/exercises/:exerciseId/complete

{
  "completed": true
}

8. 获取训练计划完成统计

GET /training-plans/:id/exercises/stats/completion

{
  "total": 5,        // 总共5个运动项目(不包括休息和提醒)
  "completed": 3,    // 已完成3个
  "percentage": 60   // 完成率60%
}

功能特性

1. 动作库集成

• 智能关联: exercise类型自动关联系统动作库
• 标准化: 确保动作的准确性和专业性
• 分类管理: 通过动作分类快速筛选和组织

2. 灵活的项目类型

• exercise: 运动项目 (关联动作库，支持组数、次数、时长等)
• rest: 休息项目 (设置休息时长)
• note: 提醒项目 (添加注意事项和指导)

3. 智能排序和管理

• 新增项目自动添加到列表末尾
• 支持拖拽重新排序
• 简洁的单项操作设计

4. 参数配置丰富

• exerciseKey: 关联系统动作库
• sets: 训练组数
• reps: 每组重复次数
• durationSec: 持续时长(秒)，适用于有氧运动或休息
• restSec: 组间休息时长
• note: 个性化备注信息

5. 完成状态跟踪

• 实时跟踪每个项目的完成状态
• 智能统计整体完成进度
• 只有运动类型项目计入完成率统计

6. 数据安全与验证

• 用户权限验证，确保数据安全
• 动作存在性验证，防止无效关联
• 软删除机制，数据可恢复

使用示例

创建完整的训练流程

// 1. 先创建训练计划
const plan = await createTrainingPlan({...});

// 2. 逐个添加训练项目（关联动作库）
// 热身阶段
await createExercise(plan.id, {
  exerciseKey: "dynamic_warmup",
  name: "动态热身",
  durationSec: 300,
  itemType: "exercise"
});

// 主要训练 - 深蹲
await createExercise(plan.id, {
  exerciseKey: "squat",
  name: "深蹲训练",
  sets: 3,
  reps: 15,
  restSec: 60,
  itemType: "exercise",
  note: "保持膝盖不超过脚尖"
});

// 休息
await createExercise(plan.id, {
  name: "组间休息",
  durationSec: 90,
  itemType: "rest"
});

// 俯卧撑
await createExercise(plan.id, {
  exerciseKey: "pushup",
  name: "俯卧撑训练",
  sets: 3,
  reps: 12,
  restSec: 60,
  itemType: "exercise"
});

// 安全提醒
await createExercise(plan.id, {
  name: "注意动作标准",
  note: "保持核心紧张，动作缓慢控制",
  itemType: "note"
});

// 3. 用户完成训练项目
await markExerciseComplete(plan.id, squatId, { completed: true });
await markExerciseComplete(plan.id, pushupId, { completed: true });

// 4. 查看完成进度
const stats = await getCompletionStats(plan.id);
// { total: 3, completed: 2, percentage: 67 }

// 5. 获取包含动作详情的训练列表
const exercises = await listExercises(plan.id);
// 返回的数据包含关联的动作库信息

关键优化

数据库设计优化

• 外键关联: ScheduleExercise.exerciseKey → Exercise.key
• 数据一致性: 动作存在性验证
• 查询优化: 左连接获取动作详情

接口设计简化

• 去除批量操作: 专注单项操作，降低复杂度
• 智能关联: 自动验证和获取动作信息
• 类型安全: 强类型验证确保数据准确性

这个优化后的实现确保了训练计划项目与系统动作库的正确关联，提供了更加专业和标准化的训练管理体验。