# StreakFit — Modèle de domaine (spec OSDD)

App de cross-training / suivi muscu. **Concept central = le _streak_** (régularité : jours d'entraînement
consécutifs, gamification à la Duolingo). Stack : Laravel 13 + OSDD (`xefi/laravel-osdd`) + Octane/FrankenPHP,
Filament 5 (admin), Sanctum (auth cookie SPA), lomkit REST API + access-control, MySQL (mysql-shared), RustFS/S3 (médias).

## Règles d'architecture (NON négociables)
- **Le front ne contient AUCUNE logique métier, même l'auth.** Tout est calculé/validé côté back ; l'API renvoie
  du prêt-à-afficher (streak courant, PR, progression, prochaine séance, instructions dans la locale). Auth = cookie
  de session Sanctum, flow OIDC piloté 100% par le back.
- **OSDD** : une couche = un package `type: layer` sous `functional/` (métier) ou `technical/` (infra), autonome
  (`src/`, `database/migrations|factories|seeders`, `routes/`, provider `extends LayerServiceProvider`). Placer chaque
  fichier via `php artisan osdd:<gen> --layer=<functional|technical>/<nom>`.
- **i18n** : fr, pt-BR, en. Instructions d'exos = en+fr (dataset), pt-BR retombe sur en/fr.
- FK toujours vers `users(id)` (table possédée par `functional/users`). Ne pas recréer la table users.
- Pattern de référence = `functional/exercises` (déjà fait : model + migration + config + import command).

## Couches & schéma

### functional/users  (existe — auth)
- `users` : + `locale` (string, def 'fr'), `units` enum('metric','imperial') def 'metric', `timezone` (string, nullable),
  `avatar_path` (nullable), `oidc_sub` (string nullable, unique). Profil léger sur le user.

### functional/exercises  (FAIT — lecture seule, catalogue)
- `exercises` : external_id(unique), name, slug, category, body_part, equipment, target, muscle_group,
  secondary_muscles(json), instructions(json {en:[],fr:[]}), image_path, gif_path, attribution.

### functional/routines
Une routine = liste ordonnée d'exercices avec séries/reps/repos.
- `routines` : user_id(fk), name, slug, description(text null), is_public(bool def false), estimated_minutes(int null).
- `routine_exercises` (pivot enrichi) : routine_id(fk), exercise_id(fk), position(int), sets(int), target_reps(string, ex "8-12"),
  rest_seconds(int null), tempo(string null), target_weight(decimal 8,2 null), notes(text null).
- Relations : Routine belongsTo User ; Routine hasMany RoutineExercise (ordered by position) ; RoutineExercise belongsTo Exercise.

### functional/programs
Un programme = planning de routines sur plusieurs semaines.
- `programs` : user_id(fk), name, slug, description(text null), duration_weeks(int), days_per_week(int null), is_public(bool def false).
- `program_slots` : program_id(fk), week(int, 1..duration_weeks), weekday(tinyint 1..7), routine_id(fk null), label(string null).
- Relations : Program belongsTo User ; Program hasMany ProgramSlot ; ProgramSlot belongsTo Routine.

### functional/tracking
Séances réalisées + sets loggés + records + mensurations.
- `workout_sessions` : user_id(fk), routine_id(fk null), program_id(fk null), title(string null), started_at(datetime),
  ended_at(datetime null), status enum('active','completed','abandoned') def 'active', notes(text null), total_volume(decimal 10,2 null).
- `set_logs` : workout_session_id(fk), exercise_id(fk), set_number(int), reps(int null), weight(decimal 8,2 null),
  rpe(decimal 3,1 null), duration_seconds(int null), distance_meters(decimal 8,2 null), is_warmup(bool def false),
  is_completed(bool def true), logged_at(datetime).
- `personal_records` : user_id(fk), exercise_id(fk), type enum('1rm','max_weight','max_reps','max_volume','best_time'),
  value(decimal 10,2), unit(string), achieved_at(datetime), workout_session_id(fk null). unique(user_id,exercise_id,type).
- `body_metrics` : user_id(fk), measured_on(date), weight(decimal 6,2 null), body_fat(decimal 5,2 null), notes(text null). unique(user_id,measured_on).
- **Événement** : à la complétion d'une WorkoutSession, dispatch `WorkoutCompleted(session)` (listener côté streaks).

### functional/streaks  (LE CONCEPT)
- `streaks` (1 par user) : user_id(fk, unique), current_count(int def 0), longest_count(int def 0),
  last_active_date(date null), freezes_available(int def 0), freeze_last_granted_on(date null).
- `streak_days` : user_id(fk), date(date), source enum('workout','manual','freeze','rest'),
  workout_session_id(fk null). unique(user_id,date).
- `goals` : user_id(fk), type enum('weekly_sessions','weekly_minutes','weekly_volume'), target(int),
  period enum('week') def 'week', is_active(bool def true).
- `achievements` (badges) : user_id(fk), key(string, ex 'streak_7','streak_30','first_workout'), earned_at(datetime),
  meta(json null). unique(user_id,key).
- **Logique (service `StreakService`, côté back)** : listener sur `WorkoutCompleted` → enregistre un `streak_day`
  (source=workout) pour la date → recalcule : si last_active_date == veille → current++ ; == aujourd'hui → no-op ;
  sinon si un freeze couvre le trou → consomme ; sinon reset à 1. Met à jour longest. Débloque les achievements aux paliers.

### technical/integrations  (EXTENSIBILITÉ Garmin/Strava)
Générique : aucune référence en dur à un provider. Garmin/Strava = futures couches `functional/strava`, `functional/garmin`
qui implémentent le contrat et s'enregistrent dans le registre.
- `integrations` (comptes connectés) : user_id(fk), provider(string), external_user_id(string null),
  access_token(text null, cast encrypted), refresh_token(text null, cast encrypted), token_expires_at(datetime null),
  scopes(json null), status enum('connected','revoked','error') def 'connected', connected_at(datetime), last_synced_at(datetime null), meta(json null). unique(user_id,provider).
- `external_activities` : integration_id(fk), user_id(fk), provider(string), external_id(string), type(string),
  started_at(datetime), duration_seconds(int null), distance_meters(decimal 10,2 null), calories(int null), raw(json null). unique(provider,external_id).
- **Contrats** (`src/Contracts/`) : interface `ActivityProvider` { key():string; label():string; connectUrl(User):string;
  handleCallback(User,array):Integration; fetchActivities(Integration, ?Carbon $since):iterable; } — et un singleton
  `ProviderRegistry` { register(ActivityProvider), get(string):?ActivityProvider, all():array }. Enregistré dans le provider de la couche.

## API (lomkit REST) — fait plus tard, couche par couche
Resources lomkit sous `src/Rest/Resources`, contrôlées par access-control (chaque user ne voit que ses données ;
exercises = public en lecture). Endpoints REST search/mutate. Vues "prêtes à afficher" (dashboard streak, séance courante)
exposées via contrôleurs dédiés quand un simple CRUD ne suffit pas.