# 训练计划项目管理 API 使用示例 ## 创建一个完整的训练计划项目 ### 1. 创建基础训练计划 ```bash POST /training-plans Authorization: Bearer {token} Content-Type: application/json { "name": "全身力量训练", "startDate": "2024-01-15T00:00:00.000Z", "mode": "daysOfWeek", "daysOfWeek": [1, 3, 5], "sessionsPerWeek": 3, "goal": "core_strength" } ``` 响应： ```json { "id": "plan_1705123456789_abc123", "name": "全身力量训练", "isActive": true, "userId": "user_123", "startDate": "2024-01-15T00:00:00.000Z", "mode": "daysOfWeek", "daysOfWeek": [1, 3, 5], "sessionsPerWeek": 3, "goal": "core_strength", "createdAt": "2024-01-10T10:30:00.000Z" } ``` ### 2. 批量添加训练项目 ```bash POST /training-plans/plan_1705123456789_abc123/exercises/batch Authorization: Bearer {token} Content-Type: application/json { "exercises": [ { "key": "warmup_dynamic", "name": "动态热身", "category": "热身", "durationSec": 300, "itemType": "exercise", "note": "轻松活动关节，准备训练" }, { "key": "note_safety", "name": "安全提醒", "note": "如感到不适请立即停止，保持正确呼吸", "itemType": "note" }, { "key": "squat_exercise", "name": "深蹲训练", "category": "下肢力量", "sets": 3, "reps": 15, "restSec": 60, "itemType": "exercise", "note": "下蹲时膝盖不超过脚尖" }, { "key": "rest_squat", "name": "组间休息", "durationSec": 90, "itemType": "rest" }, { "key": "pushup_exercise", "name": "俯卧撑", "category": "上肢力量", "sets": 3, "reps": 12, "restSec": 60, "itemType": "exercise", "note": "保持身体一条直线" }, { "key": "rest_pushup", "name": "组间休息", "durationSec": 90, "itemType": "rest" }, { "key": "plank_exercise", "name": "平板支撑", "category": "核心力量", "sets": 3, "durationSec": 60, "restSec": 45, "itemType": "exercise", "note": "腹部收紧，不要塌腰" }, { "key": "cooldown_stretch", "name": "拉伸放松", "category": "拉伸", "durationSec": 600, "itemType": "exercise", "note": "充分拉伸训练过的肌群" } ] } ``` 响应： ```json [ { "id": "ex_1705123456790_def456", "trainingPlanId": "plan_1705123456789_abc123", "key": "warmup_dynamic", "name": "动态热身", "category": "热身", "sets": 0, "durationSec": 300, "note": "轻松活动关节，准备训练", "itemType": "exercise", "completed": false, "sortOrder": 1, "createdAt": "2024-01-10T10:35:00.000Z", "updatedAt": "2024-01-10T10:35:00.000Z" }, // ... 其他项目 ] ``` ### 3. 获取训练项目列表 ```bash GET /training-plans/plan_1705123456789_abc123/exercises Authorization: Bearer {token} ``` 响应：按sortOrder排序的完整项目列表 ```json [ { "id": "ex_1705123456790_def456", "trainingPlanId": "plan_1705123456789_abc123", "key": "warmup_dynamic", "name": "动态热身", "category": "热身", "sets": 0, "durationSec": 300, "note": "轻松活动关节，准备训练", "itemType": "exercise", "completed": false, "sortOrder": 1 }, { "id": "ex_1705123456791_ghi789", "trainingPlanId": "plan_1705123456789_abc123", "key": "note_safety", "name": "安全提醒", "note": "如感到不适请立即停止，保持正确呼吸", "itemType": "note", "completed": false, "sortOrder": 2 } // ... 更多项目 ] ``` ### 4. 用户完成训练项目 ```bash PUT /training-plans/plan_1705123456789_abc123/exercises/ex_1705123456792_jkl012/complete Authorization: Bearer {token} Content-Type: application/json { "completed": true } ``` 响应： ```json { "id": "ex_1705123456792_jkl012", "trainingPlanId": "plan_1705123456789_abc123", "key": "squat_exercise", "name": "深蹲训练", "category": "下肢力量", "sets": 3, "reps": 15, "restSec": 60, "itemType": "exercise", "completed": true, "sortOrder": 3, "updatedAt": "2024-01-10T11:15:00.000Z" } ``` ### 5. 调整训练项目顺序 ```bash PUT /training-plans/plan_1705123456789_abc123/exercises/order Authorization: Bearer {token} Content-Type: application/json { "exerciseIds": [ "ex_1705123456790_def456", // 热身 "ex_1705123456792_jkl012", // 深蹲 (提前) "ex_1705123456791_ghi789", // 安全提醒 (延后) "ex_1705123456793_mno345", // 休息 "ex_1705123456794_pqr678" // 其他项目... ] } ``` 响应： ```json { "success": true } ``` ### 6. 批量更新训练强度 ```bash PUT /training-plans/plan_1705123456789_abc123/exercises/batch Authorization: Bearer {token} Content-Type: application/json { "exercises": [ { "id": "ex_1705123456792_jkl012", "sets": 4, // 增加组数 "reps": 18 // 增加次数 }, { "id": "ex_1705123456794_pqr678", "sets": 4, "reps": 15 }, { "id": "ex_1705123456795_stu901", "durationSec": 75 // 增加平板支撑时长 } ] } ``` ### 7. 查看训练完成统计 ```bash GET /training-plans/plan_1705123456789_abc123/exercises/stats/completion Authorization: Bearer {token} ``` 响应： ```json { "total": 5, // 总共5个运动项目(不包括休息和提醒) "completed": 3, // 已完成3个 "percentage": 60 // 完成率60% } ``` ### 8. 删除不需要的项目 ```bash DELETE /training-plans/plan_1705123456789_abc123/exercises Authorization: Bearer {token} Content-Type: application/json [ "ex_1705123456793_mno345", // 删除某个休息项目 "ex_1705123456796_vwx234" // 删除某个提醒项目 ] ``` 响应： ```json { "success": true, "deletedCount": 2 } ``` ## 错误处理示例 ### 重复的key错误 ```bash POST /training-plans/plan_1705123456789_abc123/exercises { "key": "squat_exercise", // 已存在的key "name": "新的深蹲" } ``` 响应： ```json { "statusCode": 400, "message": "项目key \"squat_exercise\" 已存在", "error": "Bad Request" } ``` ### 训练计划不存在 ```bash GET /training-plans/nonexistent_plan/exercises ``` 响应： ```json { "statusCode": 404, "message": "训练计划不存在或不属于当前用户", "error": "Not Found" } ``` ## 前端集成建议 ### 1. 训练项目组件状态管理 ```typescript interface TrainingSessionState { exercises: ScheduleExercise[]; currentExercise: number; completedCount: number; totalCount: number; } // 加载训练项目 const loadExercises = async (planId: string) => { const exercises = await api.get(`/training-plans/${planId}/exercises`); return exercises.filter(ex => ex.itemType === 'exercise'); }; // 标记完成 const markComplete = async (planId: string, exerciseId: string) => { await api.put(`/training-plans/${planId}/exercises/${exerciseId}/complete`, { completed: true }); }; ``` ### 2. 拖拽重新排序 ```typescript const handleDragEnd = async (result: DropResult) => { if (!result.destination) return; const newOrder = Array.from(exercises); const [reorderedItem] = newOrder.splice(result.source.index, 1); newOrder.splice(result.destination.index, 0, reorderedItem); const exerciseIds = newOrder.map(ex => ex.id); await api.put(`/training-plans/${planId}/exercises/order`, { exerciseIds }); setExercises(newOrder); }; ``` 这个API设计提供了完整的训练项目管理功能，支持用户创建个性化的训练流程，实时跟踪完成进度，并且具有良好的扩展性。