feat(training-plans): 添加训练项目管理功能
- 新增训练项目模型、DTO和服务，支持创建、更新、删除和批量操作训练项目 - 在控制器中实现训练项目的相关API，包括添加、批量添加、获取、更新、删除和标记完成状态 - 提供训练项目的完成统计功能，支持获取训练计划下所有项目的完成情况 - 更新训练计划模块以集成训练项目管理功能
This commit is contained in:
richarjiang
240
src/training-plans/README.md
Normal file
240
src/training-plans/README.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 训练计划项目管理 API 文档
|
||||
|
||||
这个功能实现了对训练计划下具体训练项目的完整管理，支持增删改查、排序、批量操作和完成状态跟踪。
|
||||
|
||||
## 数据模型
|
||||
|
||||
### ScheduleExercise (训练项目)
|
||||
|
||||
```typescript
|
||||
interface ScheduleExercise {
|
||||
id: string; // 项目ID
|
||||
trainingPlanId: string; // 所属训练计划ID
|
||||
userId: string; // 用户ID
|
||||
key: string; // 项目标识key (唯一)
|
||||
name: string; // 项目名称
|
||||
category?: 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; // 是否已删除
|
||||
}
|
||||
```
|
||||
|
||||
## API 端点
|
||||
|
||||
### 1. 添加训练项目
|
||||
|
||||
**POST** `/training-plans/:id/exercises`
|
||||
|
||||
```json
|
||||
{
|
||||
"key": "warm_up_1",
|
||||
"name": "热身运动",
|
||||
"category": "热身",
|
||||
"sets": 1,
|
||||
"durationSec": 300,
|
||||
"itemType": "exercise"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 批量添加训练项目
|
||||
|
||||
**POST** `/training-plans/:id/exercises/batch`
|
||||
|
||||
```json
|
||||
{
|
||||
"exercises": [
|
||||
{
|
||||
"key": "exercise_1",
|
||||
"name": "深蹲",
|
||||
"category": "力量训练",
|
||||
"sets": 3,
|
||||
"reps": 15,
|
||||
"itemType": "exercise"
|
||||
},
|
||||
{
|
||||
"key": "rest_1",
|
||||
"name": "休息",
|
||||
"itemType": "rest",
|
||||
"durationSec": 60
|
||||
},
|
||||
{
|
||||
"key": "note_1",
|
||||
"name": "注意事项",
|
||||
"note": "保持呼吸平稳",
|
||||
"itemType": "note"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取训练计划的所有项目
|
||||
|
||||
**GET** `/training-plans/:id/exercises`
|
||||
|
||||
返回按排序顺序排列的所有训练项目。
|
||||
|
||||
### 4. 获取训练项目详情
|
||||
|
||||
**GET** `/training-plans/:id/exercises/:exerciseId`
|
||||
|
||||
### 5. 更新训练项目
|
||||
|
||||
**PUT** `/training-plans/:id/exercises/:exerciseId`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "修改后的名称",
|
||||
"sets": 4,
|
||||
"reps": 12,
|
||||
"completed": true
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 批量更新训练项目
|
||||
|
||||
**PUT** `/training-plans/:id/exercises/batch`
|
||||
|
||||
```json
|
||||
{
|
||||
"exercises": [
|
||||
{
|
||||
"id": "exercise_id_1",
|
||||
"sets": 4,
|
||||
"completed": true
|
||||
},
|
||||
{
|
||||
"id": "exercise_id_2",
|
||||
"reps": 20
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 7. 删除训练项目
|
||||
|
||||
**DELETE** `/training-plans/:id/exercises/:exerciseId`
|
||||
|
||||
### 8. 批量删除训练项目
|
||||
|
||||
**DELETE** `/training-plans/:id/exercises`
|
||||
|
||||
```json
|
||||
["exercise_id_1", "exercise_id_2", "exercise_id_3"]
|
||||
```
|
||||
|
||||
### 9. 更新训练项目排序
|
||||
|
||||
**PUT** `/training-plans/:id/exercises/order`
|
||||
|
||||
```json
|
||||
{
|
||||
"exerciseIds": ["id3", "id1", "id2"]
|
||||
}
|
||||
```
|
||||
|
||||
重新排列项目顺序，数组中的顺序即为新的排序。
|
||||
|
||||
### 10. 标记训练项目完成状态
|
||||
|
||||
**PUT** `/training-plans/:id/exercises/:exerciseId/complete`
|
||||
|
||||
```json
|
||||
{
|
||||
"completed": true
|
||||
}
|
||||
```
|
||||
|
||||
### 11. 获取训练计划完成统计
|
||||
|
||||
**GET** `/training-plans/:id/exercises/stats/completion`
|
||||
|
||||
```json
|
||||
{
|
||||
"total": 10,
|
||||
"completed": 6,
|
||||
"percentage": 60
|
||||
}
|
||||
```
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. 智能排序
|
||||
- 新增项目自动添加到列表末尾
|
||||
- 支持拖拽重新排序
|
||||
- 批量操作时保持排序逻辑
|
||||
|
||||
### 2. 项目类型支持
|
||||
- **exercise**: 运动项目 (支持组数、次数、时长等)
|
||||
- **rest**: 休息项目 (主要设置休息时长)
|
||||
- **note**: 提示项目 (主要用于注意事项)
|
||||
|
||||
### 3. 灵活的参数配置
|
||||
- `sets`: 组数
|
||||
- `reps`: 每组重复次数
|
||||
- `durationSec`: 持续时长(秒)，适用于有氧运动或休息
|
||||
- `restSec`: 组间休息时长
|
||||
- `note`: 备注信息
|
||||
|
||||
### 4. 完成状态跟踪
|
||||
- 每个项目都有完成状态
|
||||
- 支持统计整体完成进度
|
||||
- 只有运动类型项目计入统计
|
||||
|
||||
### 5. 批量操作
|
||||
- 批量创建：一次性添加多个项目
|
||||
- 批量更新：同时修改多个项目
|
||||
- 批量删除：一次性删除多个项目
|
||||
|
||||
### 6. 数据安全
|
||||
- 所有操作都验证用户权限
|
||||
- 项目key在同一训练计划内唯一
|
||||
- 支持软删除，数据可恢复
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 创建完整的训练流程
|
||||
|
||||
```javascript
|
||||
// 1. 先创建训练计划
|
||||
const plan = await createTrainingPlan({...});
|
||||
|
||||
// 2. 批量添加训练项目
|
||||
await batchCreateExercises(plan.id, {
|
||||
exercises: [
|
||||
// 热身阶段
|
||||
{ key: "warmup", name: "热身", category: "热身", durationSec: 300, itemType: "exercise" },
|
||||
|
||||
// 主要训练
|
||||
{ key: "squat", name: "深蹲", category: "力量", sets: 3, reps: 15, itemType: "exercise" },
|
||||
{ key: "rest_1", name: "休息", itemType: "rest", durationSec: 60 },
|
||||
|
||||
{ key: "pushup", name: "俯卧撑", category: "力量", sets: 3, reps: 12, itemType: "exercise" },
|
||||
{ key: "rest_2", name: "休息", itemType: "rest", durationSec: 60 },
|
||||
|
||||
// 注意事项
|
||||
{ key: "note_form", name: "注意动作标准", note: "保持核心紧张，动作缓慢控制", itemType: "note" },
|
||||
|
||||
// 放松阶段
|
||||
{ key: "cooldown", name: "拉伸放松", category: "拉伸", durationSec: 300, itemType: "exercise" }
|
||||
]
|
||||
});
|
||||
|
||||
// 3. 用户完成训练项目
|
||||
await markExerciseComplete(plan.id, "squat", { completed: true });
|
||||
await markExerciseComplete(plan.id, "pushup", { completed: true });
|
||||
|
||||
// 4. 查看完成进度
|
||||
const stats = await getCompletionStats(plan.id);
|
||||
// { total: 4, completed: 2, percentage: 50 }
|
||||
```
|
||||
|
||||
这个实现提供了与前端 `ScheduleExercise` 接口完全匹配的后端支持，用户可以灵活地管理训练计划的具体内容。
|
||||
Reference in New Issue
Block a user