# HabitForge - Zepp Data Import

## Overview
This document explains how to import your Zepp/Mi Band/Amazfit health data into HabitForge.

## Prerequisites
- Zepp data export in `export-zepp/` directory (exported from Zepp app)
- HabitForge application running
- User account created in HabitForge

## Export Structure
Your Zepp export should be in the following structure:
```
export-zepp/
└── [ACCOUNT_ID_TIMESTAMP]/
    ├── ACTIVITY/         # Daily activity summaries (steps, distance, calories)
    ├── ACTIVITY_MINUTE/  # Minute-by-minute activity data
    ├── ACTIVITY_STAGE/   # Activity segments
    ├── BODY/             # Body measurements (weight, BMI, etc.)
    ├── HEALTH_DATA/      # Additional health metrics
    ├── HEARTRATE/        # Manual heart rate readings
    ├── HEARTRATE_AUTO/   # Automatic heart rate monitoring
    ├── SLEEP/            # Sleep summaries
    ├── SLEEP_MINUTE/     # Minute-by-minute sleep data
    ├── SPORT/            # Workout/sport sessions
    └── USER/             # User profile data
```

## Import Process

### Option 1: Using Docker (Recommended)
```bash
docker-compose -f docker-compose.dev.yml exec web python scripts/import_zepp_data.py
```

### Option 2: Local Environment
```bash
python scripts/import_zepp_data.py
```

### Specify User ID
If you need to import data for a specific user:
```bash
python scripts/import_zepp_data.py --user-id 2
```

## Data Imported

### Daily Health Metrics
- **Activity**: Steps, distance (meters), calories burned
- **Sleep**: Total sleep time, deep sleep, light sleep, REM sleep, awake duration
- **Heart Rate**: Average, minimum, maximum, resting heart rate
- **Body**: Weight measurements
- **PAI Score**: Calculated from activity and heart rate data

### Workout Sessions
- **Running** (type 1)
- **Walking** (type 6)
- **Cycling** (type 8)
- **Elliptical** (type 10)
- **Free Training** (type 16)
- **HIIT** (type 23)
- **Stretching** (type 52)
- **Yoga** (type 60)

Each workout includes:
- Start/end time
- Duration
- Distance
- Calories burned
- Pace metrics (avg, min, max)

## API Endpoints

After importing, you can access the data via these endpoints:

### Health Stats
```
GET /api/health/stats?period=week
GET /api/health/stats?period=month
GET /api/health/stats?period=year
```

### Workout Sessions
```
GET /api/health/workouts              # List workouts
GET /api/health/workouts/summary      # Workout statistics
```

## Notes
- The import will merge data with existing records (taking the imported values for conflicts)
- Default user ID is 1
- The script automatically finds the latest export directory
- All timestamps are converted to local dates for daily aggregation
- PAI scores are calculated automatically based on activity and heart rate data

## Re-importing Data
If you export new data from Zepp, simply replace the contents of `export-zepp/` and run the import script again. It will upsert (update or insert) all records.