99 lines
2.9 KiB
Markdown
99 lines
2.9 KiB
Markdown
# 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.
|