Training API

API培训

一个自我托管的锻炼跟踪API与苹果手表培训队列。存储锻炼历史记录、查询分析和队列结构化锻炼，以便通过workout Kit交付给Apple Watch。

使用FastAPI、PostgreSQL和SQLAlchemy构建。包括用于AI助手集成的可选MCP（模型上下文协议）服务器。

特性

• 锻炼存储 -CRUD API，用于包含活动类型、距离、持续时间、心率、拆分和任意JSONB数据的训练
• 分析 --按周、月或年汇总终点
• 培训队列 --通过iOS配套应用程序将结构化锻炼（间歇训练、热身/冷却、速度提醒）排队同步到Apple Watch
• 锻炼动作 --编辑或删除已通过待处理操作队列同步到Apple Watch的训练
• 设备清单 --追踪用户Apple Watch上当前正在进行的锻炼
• 错过的锻炼反馈 --当用户错过预定的锻炼时，记录和查询反馈，并进行模式检测以进行指导
• 培训计划 --创建和管理训练计划，将目标、护栏、阶段和运动员上下文存储为灵活的JSONB元数据
• 健康指标 --批量更新每日HealthKit指标（睡眠、心率、心率变异性、体重、最大摄氧量、步数、身体成分），并基于日期进行更新
• 计划锻炼链接 --将排队的训练链接到计划(plan_id)并将训练记录到计划中的对应部分(plan_workout_id)计划与实际分析
• 仪表盘 --内置网络仪表板 /dashboard 包含概览统计数据、计划进度、运行状况指标和API密钥管理
• MCP服务器 --让AI助手查询您的训练数据，创建锻炼和计划，并通过自然语言关联健康指标

快速开始

先决条件

• Docker和Docker Compose

1.克隆和配置

git clone https://github.com/YOUR_USERNAME/training-api.git
cd training-api
cp backend/config/.env.example backend/config/.env

编辑 backend/config/.env 并设置一个随机 API_KEY:

DATABASE_URL=postgresql+psycopg://training-api:training-api@db:5432/training-api
API_KEY=your-secret-api-key-here
ENVIRONMENT=LOCAL

2.开始

make up        # or: docker compose up -d

API将于 http://localhost:8001数据库迁移在启动时自动运行。网络仪表板可在 http://localhost:8001/dashboard.

3.验证

curl http://localhost:8001/api/health

API

所有端点（健康状况除外）都需要 Bearer 令牌在 Authorization 标题匹配 API_KEY 您已配置。

锻炼

训练队列

锻炼动作

设备清单

错过的锻炼反馈

培训计划

健康指标

仪表盘

MCP服务器（可选）

这 mcp/ 目录包含 FastMCP 将训练数据暴露给AI助手（例如Claude）的服务器。

设置

cd mcp
cp config/.env.example config/.env

编辑 mcp/config/.env --set TRAINING_API_KEY 以匹配后端 API_KEY:

TRAINING_API_URL=http://localhost:8001
TRAINING_API_KEY=your-secret-api-key-here

跑

uv run start

或者在MCP客户端（例如Claude Desktop）中将其配置为stdio传输。

发展

make up       # Start containers
make down     # Stop containers
make build    # Rebuild images
make logs     # Tail container logs
make migrate  # Run database migrations manually

# Create a new migration after changing models
make create_migration m="add new column"

项目结构

├── docker-compose.yml          # PostgreSQL + API orchestration
├── Makefile                    # Dev shortcuts
├── backend/
│   ├── Dockerfile              # Multi-stage Python 3.13 build
│   ├── pyproject.toml          # Dependencies (uv/hatch)
│   ├── config/.env.example     # Environment template
│   ├── app/
│   │   ├── main.py             # FastAPI app
│   │   ├── config.py           # Settings (pydantic-settings)
│   │   ├── auth.py             # Bearer token auth
│   │   ├── database.py         # SQLAlchemy setup
│   │   ├── models/             # ORM models
│   │   ├── routes/             # API endpoints
│   │   ├── schemas/            # Pydantic request/response models
│   │   └── templates/          # Jinja2 dashboard templates
│   └── migrations/             # Alembic migrations
└── mcp/
    ├── pyproject.toml          # MCP dependencies
    ├── config/.env.example     # MCP environment template
    └── app/
        ├── main.py             # FastMCP server
        ├── tools/              # MCP tool definitions
        └── services/           # API client

许可证

麻省理工学院