# Garmin Health Data Sync System

完整的 Garmin Connect China（中国区）健康数据同步系统，支持历史数据回填和每日自动更新。

## 功能特性

- ✅ 支持 Garmin Connect China（connect.garmin.cn）
- ✅ 多种健康数据类型：步数、心率、睡眠、压力、Body Battery、血氧、运动活动等
- ✅ 增量同步（仅同步新数据）
- ✅ 历史数据回填
- ✅ 数据存储：JSON 文件 + SQLite 索引
- ✅ 命令行工具（CLI）
- ✅ Claude Code Skill 集成
- ✅ 自动化调度支持（Cron / LaunchAgent）

## 快速开始

### 1. 系统验证

首先验证所有组件已正确安装：

```bash
python scripts/verify_system.py
```

### 2. 初始化设置

运行设置脚本，创建 .env 文件和初始化数据库：

```bash
python scripts/setup_health.py
```

### 3. 配置 Garmin 凭证

编辑 `.env` 文件，添加你的 Garmin China 账号：

```bash
GARMIN_EMAIL=your_email@example.com
GARMIN_PASSWORD=your_password
```

⚠️ **重要**: 确保使用的是 **connect.garmin.cn**（中国区）的账号，不是国际版。

### 4. 测试同步

同步最近几天的数据进行测试：

```bash
python -m health.cli.sync sync --days 3
```

### 5. 查看同步状态

```bash
python -m health.cli.sync status
```

## 使用指南

### CLI 命令

#### 查看状态
```bash
python -m health.cli.sync status
```

#### 同步最近几天
```bash
# 同步昨天的数据
python -m health.cli.sync sync --days 1

# 同步最近 7 天
python -m health.cli.sync sync --days 7

# 强制重新同步（覆盖已有数据）
python -m health.cli.sync sync --days 7 --force
```

#### 增量同步（推荐）
```bash
# 自动同步自上次同步以来的所有新数据
python -m health.cli.sync sync-incremental
```

#### 历史数据回填
```bash
# 从指定日期开始回填所有数据
python -m health.cli.sync backfill --start-date 2024-01-01

# 指定结束日期
python -m health.cli.sync backfill --start-date 2024-01-01 --end-date 2024-12-31

# 自定义批次大小（默认 30 天）
python -m health.cli.sync backfill --start-date 2024-01-01 --batch-size 15

# 只同步特定指标
python -m health.cli.sync backfill --start-date 2024-01-01 --metrics steps --metrics sleep
```

### Claude Code Skill

在 Claude Code 中可以直接执行同步：

```bash
# 运行 skill
python skills/health_sync.py
```

或在 Claude Code 对话中说：
- "sync my health data"
- "update garmin data"

### 每日自动同步

#### 选项 1: Cron Job（推荐）

编辑 crontab：
```bash
crontab -e
```

添加以下行（每天早上 8:00 执行）：
```
0 8 * * * cd /Users/lili/workspace/butler && /Users/lili/workspace/butler/venv/bin/python /Users/lili/workspace/butler/scripts/daily_sync.py >> /Users/lili/workspace/butler/logs/cron.log 2>&1
```

#### 选项 2: macOS LaunchAgent

详细配置请参考：`docs/CRON_SETUP.md`

## 数据存储

### 目录结构
```
./data/health/
├── daily_metrics/           # 每日健康指标
│   ├── steps/              # 步数数据
│   │   └── 2024/
│   │       └── 01/
│   │           └── 2024-01-15.json
│   ├── heart_rate/         # 心率数据
│   ├── sleep/              # 睡眠数据
│   ├── stress/             # 压力数据
│   ├── body_battery/       # Body Battery
│   └── ...
├── activities/             # 运动活动
│   └── 2024/
│       └── 01/
│           └── {activity_id}.json
├── body_metrics/           # 体重和身体成分
│   └── weight/
└── health.db               # SQLite 数据库（索引和元数据）
```

### 数据格式

所有数据以 JSON 格式存储，便于查看和分析。数据库仅用于索引和追踪同步状态。

## 支持的数据类型

| 数据类型 | 描述 | 状态 |
|---------|------|------|
| `steps` | 步数、距离、卡路里 | ✅ 支持 |
| `heart_rate` | 心率数据（最小/最大/静息） | ✅ 支持 |
| `sleep` | 睡眠阶段、时长、分数 | ✅ 支持 |
| `stress` | 压力水平 | ✅ 支持 |
| `body_battery` | Body Battery 充电/消耗 | ✅ 支持 |
| `rhr` | 静息心率 | ✅ 支持 |
| `activities` | 运动活动 | ✅ 支持 |
| `weight` | 体重测量 | ✅ 支持 |
| `spo2` | 血氧饱和度 | 🚧 API 可能不可用 |
| `respiration` | 呼吸频率 | 🚧 API 可能不可用 |
| `hydration` | 水分摄入 | 🚧 API 可能不可用 |
| `floors` | 爬楼层数 | 🚧 API 可能不可用 |
| `intensity_minutes` | 活动强度时长 | 🚧 API 可能不可用 |
| `hrv` | 心率变异性 | 🚧 API 可能不可用 |

⚠️ 部分数据类型的 API 端点可能在 garminconnect 库中不可用或需要特殊权限。

## 健康偏好配置

编辑 `health.md` 文件记录你的健康信息、目标和偏好。该文件将用于：
- 个性化健康建议（未来功能）
- 数据分析和洞察（未来功能）
- LLM 驱动的健康助手（未来功能）

## 日志

所有日志存储在 `./logs/` 目录：
- `daily_sync.log` - 每日同步日志
- `cron.log` - Cron job 输出
- `launchd.log` - LaunchAgent 输出

查看最近的日志：
```bash
tail -f logs/daily_sync.log
```

## 故障排除

### 认证失败

确保：
1. 使用的是 connect.garmin.cn（中国区）账号
2. 账号和密码正确
3. `.env` 文件格式正确（无多余空格）

### API 限流

如果遇到 429 错误（限流），系统会自动重试。建议：
- 减小批次大小（`--batch-size 15`）
- 在非高峰时段同步
- 避免频繁执行全量同步

### 数据缺失

某些数据类型可能在你的 Garmin 设备上不可用，或 API 不支持。检查日志了解详情。

## 项目结构

```
butler/
├── health/                 # 主模块
│   ├── cli/               # CLI 工具
│   ├── db/                # 数据库层
│   ├── models/            # Pydantic 数据模型
│   ├── services/          # 业务逻辑
│   └── utils/             # 工具函数
├── scripts/               # 自动化脚本
│   ├── setup_health.py    # 初始化脚本
│   ├── daily_sync.py      # 每日同步脚本
│   └── verify_system.py   # 系统验证脚本
├── skills/                # Claude Code skills
│   └── health_sync.py     # 手动同步 skill
├── docs/                  # 文档
│   └── CRON_SETUP.md      # Cron 配置指南
├── data/                  # 数据存储
│   └── health/
├── logs/                  # 日志文件
├── health.md              # 健康偏好配置
└── .env                   # 环境变量（需要创建）
```

## 未来扩展

计划中的功能：
- 📊 数据分析和可视化
- 💡 健康趋势分析和异常检测
- 🤖 基于 LLM 的个性化健康建议
- 📈 数据导出和报告生成
- 🔍 高级查询接口

## 技术栈

- **Python 3.12+**
- **Pydantic** - 数据验证
- **garminconnect** - Garmin API 客户端
- **Click** - CLI 框架
- **SQLite** - 数据库
- **pathlib** - 路径处理

## 许可证

个人项目，供内部使用。

---

**注意**: 此项目遵守 Garmin API 使用条款，仅用于个人健康数据管理。请勿用于商业用途或大规模数据采集。