# 健康数据查询使用指南

## 概述

健康数据查询系统提供了便捷的命令行工具来查看和分析你的Garmin健康数据。

## 安装依赖

确保已安装 `click` 库：
```bash
pip install click
```

## 可用命令

### 1. 查看可用的指标类型

```bash
python -m health.cli.query types
```

**输出示例：**
- steps - 步数、距离、卡路里
- sleep - 睡眠阶段、时长、质量评分
- heart_rate - 心率数据（最小、最大、静息）
- hrv - 心率变异性
- stress - 压力水平
- body_battery - Body Battery充放电
- weight - 体重测量
- activities - 运动活动和锻炼

### 2. 查看某天的健康数据汇总

```bash
# 查看今天的数据
python -m health.cli.query daily

# 查看指定日期的数据
python -m health.cli.query daily 2026-01-19
```

**显示内容：**
- 🚶 步数（总步数、距离、卡路里）
- 😴 睡眠（总睡眠时长、深睡眠、浅睡眠、REM睡眠、睡眠评分）
- 💓 心率（静息心率、最小、最大、平均）
- 📈 HRV（心率变异性）
- 😰 压力（平均压力水平、最大压力）
- 🔋 Body Battery（充电、放电、最高、最低）
- ⚖️ 体重（体重、BMI、体脂率）
- 🏃 活动（运动类型、时长、距离、心率、卡路里）

### 3. 查看某个指标在时间区间内的数据

```bash
# 查看睡眠数据
python -m health.cli.query range sleep 2026-01-14 2026-01-19

# 查看步数数据
python -m health.cli.query range steps 2026-01-01 2026-01-07

# 查看心率数据
python -m health.cli.query range heart_rate 2026-01-14 2026-01-19
```

**以表格形式显示：**
- 日期
- 关键指标数值
- 每个指标类型都有预定义的显示字段

### 4. 查看指标统计数据

```bash
python -m health.cli.query range sleep 2026-01-14 2026-01-19 --stats
```

**统计数据包括：**
- Min（最小值）
- Max（最大值）
- Avg（平均值）
- Count（数据天数）

### 5. 查看时间区间内的活动

```bash
# 查看所有活动
python -m health.cli.query activities 2026-01-14 2026-01-19

# 按类型筛选（例如：只看跑步）
python -m health.cli.query activities 2026-01-01 2026-01-31 --type running
```

**显示内容：**
- 活动日期和类型
- 持续时间
- 距离（如果有）
- 平均心率和最大心率
- 消耗卡路里

## 编程接口（Python API）

你也可以在Python代码中直接使用查询服务：

```python
from datetime import date, timedelta
from health.services.query import HealthDataQuery

# 创建查询服务
query = HealthDataQuery()

# 1. 获取某天的健康数据汇总
today = date.today()
summary = query.get_daily_summary(today)
print(f"今天有 {len(summary['metrics'])} 个指标")
print(f"今天有 {len(summary['activities'])} 个活动")

# 2. 获取最近7天的睡眠数据
end_date = date.today()
start_date = end_date - timedelta(days=6)
sleep_data = query.get_metric_range("sleep", start_date, end_date)
for record in sleep_data:
    print(f"{record['date']}: 睡眠时长 {record.get('total_sleep_seconds', 0) / 3600:.1f}小时")

# 3. 计算统计数据
stats = query.get_metric_statistics(
    metric_type="steps",
    start_date=start_date,
    end_date=end_date,
    fields=["total_steps", "total_distance_meters"]
)
print(f"平均步数: {stats['total_steps']['avg']:.0f}")
print(f"最大步数: {stats['total_steps']['max']}")

# 4. 获取活动数据
activities = query.get_activities_range(start_date, end_date)
for activity in activities:
    print(f"{activity['date']}: {activity['activity_type']}")

# 5. 获取最近N天的数据
recent_sleep = query.get_latest_data("sleep", days=7)
print(f"最近7天有 {len(recent_sleep)} 条睡眠记录")
```

## 示例脚本

运行示例脚本查看所有功能演示：

```bash
python scripts/query_examples.py
```

## 常见用例

### 分析睡眠质量趋势
```bash
python -m health.cli.query range sleep 2026-01-01 2026-01-31 --stats
```

### 查看本周运动情况
```bash
# 假设今天是周日，查看本周的活动
python -m health.cli.query activities 2026-01-13 2026-01-19
```

### 检查昨天的健康数据
```bash
python -m health.cli.query daily 2026-01-19
```

### 对比不同时期的步数
```bash
# 这个月
python -m health.cli.query range steps 2026-01-01 2026-01-20 --stats

# 上个月
python -m health.cli.query range steps 2025-12-01 2025-12-31 --stats
```

## 数据存储位置

所有健康数据存储在：
- 📁 `/Users/lili/workspace/bulter/data/health/`
  - `daily_metrics/` - 每日指标（步数、睡眠、心率等）
  - `activities/` - 运动活动
  - `body_metrics/` - 身体指标（体重等）
  - `health.db` - SQLite索引数据库

## 故障排查

### 问题：没有数据显示
**解决方法：**
1. 确认已同步数据：`python -m skills.health_sync`
2. 检查数据目录是否存在数据文件
3. 使用 `types` 命令查看支持的指标类型

### 问题：日期格式错误
**解决方法：**
确保使用 YYYY-MM-DD 格式，例如：`2026-01-19`

### 问题：指标类型不存在
**解决方法：**
运行 `python -m health.cli.query types` 查看所有可用的指标类型

## 未来增强

计划中的功能：
- [ ] 数据可视化（图表）
- [ ] 导出为CSV/Excel
- [ ] 自定义报告模板
- [ ] 健康趋势预测
- [ ] 异常检测和提醒