# Workout Timer App 集成说明

> Created: 2026-04-12 | Updated: 2026-06-09
> 项目地址: gitee.com/kaiji1126/workout-timer
> 技术栈: Flutter (Dart), SQLite

## 概述

Workout Timer 是一款健身计时+训练记录App（Android/iOS）。用户通过两种方式与AI交互：

1. **AI训练分析**：从训练记录生成数据报告，复制prompt发送给AI，AI返回JSON计划后通过「导入分析」导入
2. **AI计划生成器**：在App内填个人资料→生成prompt→粘贴AI返回的JSON→预览导入

**⚠️ 兼容性原则**：本技能同时服务使用和不使用此App的用户。仅在用户发送的数据包含App特征时，才按此文档处理。

## 如何识别App生成的数据

用户从App「AI分析」功能复制的数据报告通常包含以下特征：
- 开头为「你是一位专业的健身教练。根据我的训练数据报告...」
- 包含 `## 训练数据报告` 段落
- 包含「训练密度」「肌肉容量分布」「每肌群组数」「估算1RM」「恢复状态」等指标
- 包含 `## 用户画像` 段落（目标、经验、频率、设备）
- 结尾要求 `Output ONLY valid JSON`

## App数据体系

### 训练容量（Volume）
- 计算公式: **组 × 次 × 重量**（sets × reps × weight）
- 这是所有分析的基石指标
- 等长收缩动作（如Plank）无法计算容量，不建议安排在计划中

### 肌肉分类
- **6大主肌群**: chest, back, shoulders, arms, legs, core
- 主肌群使用 `PrimaryMuscleGroup` 枚举，`displayName` 为中文显示名

### 统计指标说明

| 指标 | 含义 | 用途 |
|------|------|------|
| 总训练量 | 所有动作组×次×重量之和 | 衡量整体训练负荷 |
| 训练密度 | 组数/训练时长(分钟) | 衡量训练效率 |
| 肌群容量分布 | 各肌群训练量绝对值+占比%，按量降序 | 发现不平衡 |
| **每肌群组数** | 各主肌群本周/本月总组数 + MEV参考状态标记 | 判断训练量是否达标 |
| **估算1RM** | Mayhew公式，取本周期最佳，TOP10 | 力量评估（替代旧的PR记录） |
| 恢复状态 | 各肌群距上次训练天数 + ✅/⚠️/🔴 标记 | 判断是否可训练 |
| 趋势变化 | vs上周/上月的总量和各肌群变化（百分比+箭头） | 判断进步/退步 |

### MEV参考（重要）

App使用 Schoenfeld 2017 的最小有效容量（MEV）作为基准：
- **周MEV**: 10组/周/肌群
- **月MEV**: 40组/月/肌群（10×4）

状态标记规则（ratio = 实际组数/MEV）：
- `ratio >= 1.0` → ✅ 充足
- `ratio >= 0.5` → ⚠️ 偏低
- `ratio < 0.5` → 🔴 不足

### 数据报告段落结构

1. **基本信息**: 周期（周/月）、日期范围、训练次数/天数、总训练量、训练密度
2. **趋势变化**: 总训练量vs上周、训练频率、各肌群变化百分比（≥10%才显示）
3. **肌肉容量分布**: 各肌群训练量kg + 占比%，按量降序
4. **每肌群组数**: 各主肌群总组数 + MEV状态标记（✅/⚠️/🔴）
5. **估算1RM**: Mayhew公式 TOP10，格式 `~XX kg (基于 XXkg×X)`
6. **1RM进步趋势**（仅月度）: 跨周期对比，显示变化%和周数
7. **恢复状态**: 各主肌群已休息天数 + ✅可训练/⚠️建议再休息N天/🔴今日刚训练
8. **用户画像**: 训练目标、经验水平、每周频率、可用设备、重点加强肌群
9. **动作命名规范**: 标准英文动作名示例（杠铃/哑铃/器械/徒手）
10. **输出格式**: 纯JSON模板 + "生成我的训练计划。JSON only:"

## 基于App数据的计划生成

当收到App数据报告时，生成计划应：

1. **分析趋势**：重点关注容量下降的肌群（需要调整）和持续增长的肌群（保持）
2. **参考估算1RM**：用1RM数据判断力量水平，确保渐进超负荷
3. **检查每肌群组数**：🔴不足的肌群优先补量，⚠️偏低的关注
4. **尊重恢复状态**：🔴今日刚训练的肌群不要安排在当天，⚠️的肌群考虑排后面
5. **遵循用户画像中的规则**：目标、经验、频率、设备限制
6. **训练日动态排序**：恢复最久的肌群优先安排

### 输出格式

- **App数据报告要求JSON时**：只输出纯JSON，不加markdown包裹或额外解释
- **JSON中的exerciseName**：使用标准英文动作名（与free-exercise-db一致）
- **targetMuscles**：使用App的6大主肌群英文名（chest, back, shoulders, arms, legs, core）

## JSON导入格式（App专用）

**以 `assets/plan-template.json` 为唯一标准**，与App源码 `weekly_plan_import.dart` 解析逻辑一致：

```json
{
  "name": "计划名称",
  "days": [
    {
      "dayOfWeek": 1,
      "targetMuscles": ["chest", "shoulders", "triceps"],
      "exercises": [
        {"exerciseName": "Incline Dumbbell Press", "targetSets": 4}
      ]
    }
  ]
}
```

字段说明：
- `name`: 计划名称（如 "Week 13 — 增肌期"）
- `days[]`: 训练日数组
  - `dayOfWeek`: 星期几（1=周一 ... 7=周日），App会clamp到1-7范围
  - `targetMuscles[]`: 该日目标肌群（英文标准名数组）
  - `exercises[]`: 动作列表
    - `exerciseName`: 动作英文名（与 free-exercise-db 一致），缺失默认空字符串
    - `targetSets`: 目标组数，缺失默认3组

**App解析特点**：缺失字段会用默认值（dayOfWeek默认1，targetSets默认3，name默认空），容错性强。

## 没有App的用户

对于不使用App的用户：
- 通过对话收集训练信息（频率、动作、感受）
- 用自然语言描述计划，Markdown表格格式
- 不需要生成JSON
- 手动追踪进度，通过对话了解训练情况