coach-ios/HANDOFF-LIVE-BACKEND.md

Handoff — Backend /live (Mac → session Linux coach_sportif)

De : Claude Code Mac mini, 2026-05-25 (chantier watchOS Live Workout). Pour : session Claude Code sur le repo coach_sportif (backend FastAPI + templates). Objet : finir le point 1 — la page /live doit s'afficher dans l'app et recevoir les samples temps réel poussés par la Watch.

Contexte : le natif est TERMINÉ et PROUVÉ

Phases 1-3 (target watchOS CoachWatch + 4 fichiers Swift + plugin Capacitor CoachLiveBridge) livrées sur coach-ios (commits 5d60a40 → 678b5a4).

Pont watch → iPhone validé end-to-end sur simulateur (paire iPhone+Watch) : les logs montrent chaque sample envoyé par la Watch reçu à l'identique par le plugin iPhone (HR 130.69 → 148.32, latence ~300 ms). Donc dès que /live s'affiche dans l'app et écoute l'event, les chiffres défileront.

Un mode Test (FC simulée) existe dans l'app watch (bouton sous les activités) : il envoie des samples synthétiques sans HealthKit. → tu peux valider /live sans dépendre de la vraie FC (la Santé de la Watch physique de Sylvain a un bug système séparé, hors scope ici).

Le problème observé

En ouvrant /live dans l'app, la page renvoie « token invalide ». → La route /live ne reconnaît pas la session authentifiée de l'app.

Rappel : l'app (wrapper Capacitor) s'authentifie via injection de cookie de session dans AppDelegate (coach-ios). Toutes les pages authentifiées marchent via ce cookie. La route /live (Phase 4) avait été écrite avec check_auth(request, token) où token venait d'un ?token= — ce qui ne matche pas le flux cookie de l'app.

À faire côté coach_sportif

1. Auth de /live = même mécanisme que les autres pages authentifiées

Faire en sorte que /live accepte la session/cookie de l'app (comme les autres routes protégées), ?token= restant un fallback optionnel. Concrètement : utiliser le même Depends/helper d'auth que les autres pages, au lieu d'exiger le token en query. Objectif : ouvrir /live dans l'app authentifiée → 200, pas « token invalide ».

2. Un accès à /live depuis l'UI web

Ajouter un lien/bouton vers /live dans la nav de l'app (là où c'est pertinent — ex. page séance / accueil), pour que l'utilisateur y arrive sans taper d'URL.

3. JS du template live_workout.html — contrat EXACT du plugin natif

Le plugin iPhone émet l'event liveSample (jsName du plugin : CoachLiveBridge). Champs d'un sample :

champ	type	sens
heartRate	number	FC en bpm
activeEnergyKcal	number	calories actives cumulées
distanceMeters	number	distance cumulée en mètres
elapsedSec	number	durée écoulée en secondes
ts	number	timestamp epoch (secondes, fractionnaire)
sim	bool	présent (=true) uniquement en mode Test

JS à mettre dans le template (page chargée DANS l'app Capacitor) :

<script type="module">
import { registerPlugin } from '/static/vendor/capacitor-core.js';
const CoachLiveBridge = registerPlugin('CoachLiveBridge');
let lastTs = 0;
CoachLiveBridge.addListener('liveSample', (s) => {
  document.getElementById('live-hr').textContent      = Math.round(s.heartRate || 0);
  document.getElementById('live-kcal').textContent    = Math.round(s.activeEnergyKcal || 0);
  document.getElementById('live-dist').textContent    = ((s.distanceMeters || 0) / 1000).toFixed(2);
  document.getElementById('live-elapsed').textContent = fmtMS(s.elapsedSec || 0);
  document.getElementById('live-status').textContent  = 'En direct';
  lastTs = Date.now();
});
function fmtMS(sec){const h=Math.floor(sec/3600),m=Math.floor((sec%3600)/60),x=Math.floor(sec%60);
  return h?`${h}h${String(m).padStart(2,'0')}`:`${m}:${String(x).padStart(2,'0')}`;}
setInterval(()=>{ if (Date.now()-lastTs>8000)
  document.getElementById('live-status').textContent='Connexion perdue avec la Watch'; },1000);
</script>

Vérifier que /static/vendor/capacitor-core.js (ou équivalent) expose bien registerPlugin. En navigateur pur (hors app) il n'y a aucun WCSession donc 0 sample — c'est normal, la page n'est utile que dans le wrapper iOS.

Test d'acceptation (sans device, sur simulateur)

1. App iOS (sim ou device) sur /live, page au premier plan.
2. App watch → bouton Test (FC simulée).
3. /live doit afficher FC/calories/distance/durée qui défilent (~ toutes les 2 s) et le statut « En direct ».

Côté natif c'est déjà prouvé (plugin CoachLiveBridge logue liveSample reçu de la Watch hr=…). Si /live ne bouge pas alors que ce log apparaît, c'est le JS/registerPlugin du template à corriger.

État du fix + déploiement (VPS)

Fix point 1 déjà écrit : branche feat/live-nav-tab sur coach_sportif (ajout d'un onglet nav « Live workout » → /live dans NAV_ITEMS, car la route existait mais n'était liée nulle part → page inatteignable → « token invalide » sur redirect /login). Commit ecf334a. PAS mergé sur main (pas de deploy prod à l'aveugle).

Infra (depuis Makefile / deploy.sh) :

• VPS : ubuntu@83.228.246.229
• Prod : /home/ubuntu/coach_sportif, service systemd coach-web
• Staging : /home/ubuntu/coach_sportif_staging, service coach-web-staging
• Auto-deploy : webhook Gitea sur push main → deploy.sh (git reset --hard origin/main + pip install -r requirements.txt + restart coach-web + healthcheck)
• Targets : make test, make deploy-staging (sans risque), make deploy (prod)

Pour finir : sur l'env Linux/VPS (Python ≥ 3.11, le venv ne se monte pas sur le Mac : anyio==4.13.0), lancer make test, valider via make deploy-staging, puis merger feat/live-nav-tab → main (auto-deploy prod).

Hors scope de ce handoff

• Vraie FC sur la Watch physique de Sylvain (bug système Santé de SA montre — NanoSettings crashe, à régler par désappairage/réappairage).
• TestFlight (signing/App Store Connect côté Sylvain).