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

# 训练计划项目管理 API 文档

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

## 数据模型

### ScheduleExercise (训练项目)

```typescript
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`

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

或者添加休息项目：
```json
{
  "name": "组间休息",
  "durationSec": 90,
  "itemType": "rest"
}
```

或者添加提醒项目：
```json
{
  "name": "安全提醒",
  "note": "如感到不适请立即停止",
  "itemType": "note"
}
```

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

**GET** `/training-plans/:id/exercises`

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

```json
[
  {
    "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`

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

### 5. 删除训练项目

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

### 6. 更新训练项目排序

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

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

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

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

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

```json
{
  "completed": true
}
```

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

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

```json
{
  "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. 数据安全与验证
- 用户权限验证，确保数据安全
- 动作存在性验证，防止无效关联
- 软删除机制，数据可恢复

## 使用示例

### 创建完整的训练流程

```javascript
// 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
- **数据一致性**: 动作存在性验证
- **查询优化**: 左连接获取动作详情

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

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