Merge pull request #194 from Dzarlax-AI/apple-health-xml-workout-import

[codex] Import Apple Health XML workouts

Author: dzarlax

README.md

@@ -225,6 +225,8 @@ The endpoint stores summary fields only (duration, distance, energy, average / m
 
 If `HEALTH_HR_ZONES_BPM` is configured, the ingest path also computes time-in-zone (Z1..Z5) from the per-minute HR samples in the payload and stores five integer columns per workout. Pick zone borders that match your physiology — the Karvonen (HR Reserve) method using observed MaxHR and resting HR is more accurate than the textbook `220 - age` formula.
 
+Apple Health XML imports (`cmd/import` and the Admin import UI) also ingest `<Workout>` summaries into the same `workouts` table. XML exports provide nested `WorkoutStatistics` for distance, energy, and aggregate heart-rate fields on some workouts, so imported rows may include `distance_km`, `energy_kcal`, `avg_hr_bpm`, and `max_hr_bpm`. GPX workout routes are deliberately not imported.
+
 The `/health` endpoint (no suffix) still accepts all metrics unfiltered for backward compatibility.
 
 > **Why two automations?** HealthKit redistributes cumulative metrics (steps, calories) across time buckets with fractional values. With minute-level grouping, the sum of these fractions exceeds the actual total by ~20-30%. Hourly grouping uses `HKStatisticsQuery` which returns correctly deduplicated totals. Instantaneous metrics (heart rate, SpO2) don't have this problem -- they are averaged, not summed -- so minute-level grouping preserves useful granularity.

cmd/import/main.go

@@ -23,7 +23,7 @@ import (
 
 func main() {
 	filePath := flag.String("file", "", "Apple Health export (.zip or export.xml) — required")
-	batchSize := flag.Int("batch", 500, "metric points per DB transaction")
+	batchSize := flag.Int("batch", 500, "metric points or workouts per DB transaction")
 	pauseDur := flag.Duration("pause", 150*time.Millisecond, "sleep between batches (rate-limits DB load)")
 	dryRun := flag.Bool("dry-run", false, "parse only — do not write to DB")
 	flag.Parse()
@@ -47,11 +47,16 @@ func main() {
 	}
 
 	var (
-		totalParsed   int
-		totalInserted int
-		batchN        int
-		pending       []storage.MetricPoint
-		startTime     = time.Now()
+		totalParsed         int
+		totalInserted       int
+		totalWorkoutsParsed int
+		totalWorkoutsUpsert int
+		totalWorkoutsFailed int
+		batchN              int
+		workoutBatchN       int
+		pending             []storage.MetricPoint
+		pendingWorkouts     []storage.Workout
+		startTime           = time.Now()
 	)
 
 	flush := func(pts []storage.MetricPoint) {
@@ -81,6 +86,36 @@ func main() {
 		}
 	}
 
+	flushWorkouts := func(workouts []storage.Workout) {
+		workoutBatchN++
+		totalWorkoutsParsed += len(workouts)
+
+		if *dryRun {
+			if totalWorkoutsParsed%100 == 0 || totalWorkoutsParsed < 20 {
+				log.Printf("[dry-run] parsed %d workouts so far…", totalWorkoutsParsed)
+			}
+			return
+		}
+
+		var failed int
+		for _, w := range workouts {
+			if err := db.UpsertWorkout(0, w); err != nil {
+				failed++
+				log.Printf("workout batch %d upsert %s error: %v", workoutBatchN, w.ExternalID, err)
+			}
+		}
+		totalWorkoutsFailed += failed
+		totalWorkoutsUpsert += len(workouts) - failed
+
+		elapsed := time.Since(startTime).Round(time.Second)
+		log.Printf("workout batch %d: %d parsed / %d upserted / %d failed (total %d upserted, %s elapsed)",
+			workoutBatchN, len(workouts), len(workouts)-failed, failed, totalWorkoutsUpsert, elapsed)
+
+		if *pauseDur > 0 {
+			time.Sleep(*pauseDur)
+		}
+	}
+
 	// Collect points up to batchSize, then flush.
 	emit := func(pts []storage.MetricPoint) {
 		pending = append(pending, pts...)
@@ -90,31 +125,43 @@ func main() {
 		}
 	}
 
+	emitWorkouts := func(workouts []storage.Workout) {
+		pendingWorkouts = append(pendingWorkouts, workouts...)
+		for len(pendingWorkouts) >= *batchSize {
+			flushWorkouts(pendingWorkouts[:*batchSize])
+			pendingWorkouts = pendingWorkouts[*batchSize:]
+		}
+	}
+
 	log.Printf("starting import from %s (batch=%d pause=%s dry-run=%v)",
 		*filePath, *batchSize, *pauseDur, *dryRun)
 
+	opts := applehealth.EmitOptions{Points: emit, Workouts: emitWorkouts}
 	var parseErr error
 	switch {
 	case len(*filePath) > 4 && (*filePath)[len(*filePath)-4:] == ".zip":
-		parseErr = applehealth.ParseZip(*filePath, emit, nil)
+		parseErr = applehealth.ParseZipWithOptions(*filePath, opts, nil)
 	default:
-		parseErr = applehealth.ParseXMLFile(*filePath, emit, nil)
+		parseErr = applehealth.ParseXMLFileWithOptions(*filePath, opts, nil)
 	}
 	if len(pending) > 0 {
 		flush(pending)
 	}
+	if len(pendingWorkouts) > 0 {
+		flushWorkouts(pendingWorkouts)
+	}
 
 	if parseErr != nil {
 		log.Printf("parse error (partial import may have succeeded): %v", parseErr)
 	}
 
 	elapsed := time.Since(startTime).Round(time.Second)
 	if *dryRun {
-		log.Printf("dry-run complete: %d points parsed in %s", totalParsed, elapsed)
+		log.Printf("dry-run complete: %d points and %d workouts parsed in %s", totalParsed, totalWorkoutsParsed, elapsed)
 		return
 	}
-	log.Printf("import complete: %d points parsed, %d inserted, %d duplicates skipped in %s",
-		totalParsed, totalInserted, totalParsed-totalInserted, elapsed)
+	log.Printf("import complete: %d points parsed, %d inserted, %d duplicates skipped; %d workouts parsed, %d upserted, %d failed in %s",
+		totalParsed, totalInserted, totalParsed-totalInserted, totalWorkoutsParsed, totalWorkoutsUpsert, totalWorkoutsFailed, elapsed)
 
 	// Trigger a full backfill so daily_scores and caches are up to date.
 	log.Println("running backfill (this may take a few minutes)…")