Add initial project

2026-07-30 23:25:20 -04:00
commit cff6aa8289
164 changed files with 26672 additions and 0 deletions
@@ -0,0 +1,98 @@
+# 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.