expria-frontend/docs/ROADMAP.md

# ROADMAP.md — Expria Frontend

> Source de vérité de l'ordre d'implémentation des sprints.
> Ne pas modifier sans validation de Hermann.

---

## Sprint 0 — Fondations ✅

1. Scaffold Vite + TypeScript + Tailwind + shadcn/ui
2. Structure de dossiers complète
3. docs/ copiés depuis backend + adaptations
4. ONBOARDING.md rédigé

## Sprint 0.5 — Design System ✅

- Direction artistique Boréal validée
- Tokens CSS dans index.css
- DESIGN_SYSTEM.md rédigé

## Sprint 1 — Auth + API layer ✅

5. auth-client.ts
6. api-client.ts
7. query-client.ts
8. entities/user/\*
9. features/auth (Login, Register, ProtectedRoute)

## Sprint 2 — Dashboard conditionnel ✅

10. usePlan hook
11. shared/components/PaywallModal
12. features/dashboard (Free / Standard / Premium)

## Sprint 3 — Simulations EE ✅

13. entities/production/_ + entities/report/_
14. features/simulations (EE T1/T2/T3)
15. Affichage rapport avec floutage conditionnel

## Sprint 3.5 — Clean

- Factorisation des fichiers modifiés Sprint 3
- Tests manuels Groupe B + C rejoués
- Commit refactor(simulation-ee)

## Sprint 3.6a — Qualité correction — Backend ✅

- Remplacement prompt maître (docs/Prompt_maître.md) + intégration taxonomie erreurs (docs/TAXONOMIE_ERREURS.md)
- Remplacement prompt production modèle (docs/Prompt_production_modèle.md) — cible fixe NCLC 9
- Génération parallèle correction + exercices + modèle (await correction, fire-and-forget sur les deux autres)
- Nouveaux champs DB : revelation, diagnostic, conseil_nclc, erreurs_codes, exercices_status, modele_status, nclc_cible
- Mise à jour GET /simulations/:id
- Migration SQL : `supabase/migrations/004_sprint_3_6a_qualite_correction.sql` (à exécuter manuellement)
- Tests : 173 tests verts (+18 vs baseline)

## Sprint 3.6b — Qualité correction — Frontend ✅

- Sélecteur NCLC cible dans SimulationForm (9 ou 10, défaut 9) — NclcCibleSelector
- RapportPage réécrite : ScoreHero (jauge + seuil NCLC cible + écart), RevelationCards, DiagnosticCallout, CritereCard enrichie (exemple/suggestion/astuce + codes taxonomie), ConseilNclcCallout
- ExerciceInteractive : badge difficulté, zone texte, bouton Indice (une fois), bouton Voir la correction (activé après saisie), explication
- ProductionModeleSection : texte final + notes pédagogiques + transformations original/amélioré + message
- JobStatusFallback : gère exercices_status / modele_status (pending / error) — refresh manuel, polling tracé en FTD-24
- Gating plan conforme PLANS_TARIFAIRES.md : revelation/diagnostic/conseil_nclc tous plans ; criteres/exercices/modele Standard+
- Tests : 84 verts (+8 vs baseline — floutage + helpers lib + ExerciceInteractive)

## Sprint 3.7 — Historique ✅

- Backend : `GET /simulations` — liste paginée des productions de l'utilisateur connecté (page/limit, tri `created_at DESC`, projection légère). 186 tests backend verts.
- Frontend : page `/historique` (route sous AppLayout), liste d'items (date relative, tâche, score /20, NCLC, badge Examen / En cours), pagination Précédent/Suivant, clic → `/rapport/:id`.
- Gating plan : Free → aperçu flouté + CTA « Passer en Standard » (`hasAccess(plan, 'dashboard')`) ; Standard + Premium → liste complète.
- État vide : CTA « Démarrer une simulation ».
- Hook `useSimulationsList(page, limit)` — TanStack Query, `staleTime: 30s`, `keepPreviousData` pour transitions fluides.
- Helper `formatRelativeDate` (Intl.RelativeTimeFormat, zéro dépendance).
- 102 tests frontend verts (+18 vs baseline 84).

## Sprint 3.6c — Analyse patterns (Premium) ✅

- Backend : `GET /users/patterns` — agrégation des `erreurs_codes` sur les 5 dernières productions corrigées, seuil 3/5, tri DESC, cache `pattern_analyses` avec invalidation si nouvelle production plus récente que la dernière analyse.
- Backend : exercices long terme générés par DeepSeek sur patterns confirmés — format `{ consigne, exemple, correction, astuce }` avec prompt dédié (température 0.4, timeout 20 s). Dégradation gracieuse si DeepSeek échoue.
- Backend : indice de préparation 0→100 — formule 60 % score moyen + 20 % régularité + 20 % tendance, messages figés (`<40`, `40-70`, `>70`).
- Backend : migration SQL `005_sprint_3_6c_pattern_analyses.sql` (RLS SELECT par user_id, index composite, CHECK constraints).
- Backend : 205 tests verts (+19 vs baseline 186).
- Frontend : page `/progression` — orchestration hero (indice + jauge), liste patterns, cartes exercices long terme, footer « il y a X » ; gate plan via `hasAccess('pattern_analysis')` (Free/Standard → aperçu flouté + upgrade).
- Frontend : `PatternExerciceCard` — composant lesson-style dédié (non interactif, UX distincte de `ExerciceInteractive`) avec encart astuce proéminent.
- Frontend : Dashboard Premium — section compacte `MonProfilPreparation` (MetricCard indice + nb patterns + CTA vers `/progression`). Absente pour Free/Standard.
- Frontend : hook `usePatterns` (staleTime 60 s, cache partagé entre page et dashboard, `enabled` conditionné par feature).
- Frontend : 115 tests verts (+13 vs baseline 102).

## Sprint DA Charcoal — Reskin ✅

- Remplacement palette Boréal par Charcoal (dark default, light override)
- Sidebar navy permanent, layout radial-gradient, anti-FOUC
- Renommage tokens sur ~45 composants + inversion dark:/light: shadcn
- ADR 006 mis à jour

## Sprint UI Polish — Sidebar + Topbar + Dashboard ✅

- Sidebar : icônes lucide, cadenas gating, badge upgrade, user footer, logo "EX|PRIA"
- Topbar : sticky backdrop-blur, breadcrumb centralisé, recherche placeholder
- Dashboard : split Free/Standard/Premium, NclcHero + StatCards + RecentSimulations + NextStepCard + PaywallBanner refonte
- MobileHeader supprimé (remplacé par Topbar)

## Sprint 4 — Simulations EO (audio) ✅

- MediaRecorder + Gemini batch transcription (EO T1/T3)
- Questionnaire T1 + génération présentation IA (POST /presentations/generate)
- Auto-submit à expiration de la durée recommandée
- Rapport EO format 3.6a (4 critères officiels TCF Canada)

## Sprint 4.5 — Clean

- Factorisation des fichiers modifiés Sprint 4
- Tests manuels Groupe B + D rejoués
- Commit refactor(simulation-eo)

## Sprint 4.6 — UI EO (waveform + timeline)

- Waveform visualizer pendant l'enregistrement (barres audio animées)
- Barre timeline colorée : verte → orange (75%) → rouge (dernières 15s)
- Applicable à toutes les tâches EO (T1 et T3)

## Sprint 4.7 — Historique refonte

- Stats en haut : Total simulations, Score moyen, Meilleur score
- Filtre par tâche (EE T1/T2/T3, EO T1/T3, Examen blanc)
- Filtre par période (Ce mois, 3 mois, Tout)
- Design conforme aux captures de référence

## Sprint 4.8 — Phonologie EO

- Affichage note_phonologie dans RapportPage (déjà stocké en base)
- Analyse phonologique réelle via Gemini audio (TD-08 backend)
- Score phonologie dans les 4 critères EO (actuellement fixé à 0)

## Sprint 5 — Billing ✅

- **5a (backend)** : TD-13 webhook idempotency (table `stripe_webhook_events` + helpers + 10 tests) ; route `POST /stripe/customer-portal` + `createBillingPortalSession` ; doc cleanup `ARCHITECTURE-backend.md` (`POST /plans/upgrade` retiré, duplication doc) ; tests backend 261 → 278.
- **5b (frontend)** : `PricingPage` `/plan` (3 colonnes Découverte/Standard/Premium) + `useStripeCheckout` initial + uniformisation CTA upgrade « Voir les plans » sur 5 emplacements ; env vars `VITE_STRIPE_PRICE_*` ; tests 198 → 203.
- **5c (frontend + cross-repo backend fix)** : `useStripeCheckout` hook isolé + `useUpgradeSuccessHandler` (détection `?upgrade=success` + invalidation cache plan + URL clean) + `UpgradeSuccessBanner` ; migration `PricingPage` + injection banner `DashboardPage` ; fix backend `cancel_url /tarifs → /plan` ; tests 203 → 212.
- **5d (frontend)** : `useCustomerPortal` hook + `AccountBillingSection` + `ParametresPage` `/parametres` (Abonnement + Session/déconnexion) ; **Standard→Premium routé via Customer Portal** (prorata natif Stripe) ; tests 212 → 219.

## Sprint 5.5 — Clean

- Factorisation des fichiers modifiés Sprint 5
- Tests manuels Groupe E rejoués
- Commit refactor(billing)

## Sprint 6 — T2 Live ✅

18. features/t2-live (ws-client + audio worklet + state machine)

- **6b (frontend)** : capture micro (AudioWorklet 16 kHz uplink) + playback IA + helpers audio purs.
- **6c (frontend)** : state machine T2 (9 états), `useT2LiveSession` (WebSocket + audio + format Gemini natif), pages Sujets / Préparation / Dialogue + routes ; carte EO T2 Live déverrouillée Premium.
- **6d (backend)** : prompt T2 durci (anti-relance, interdiction du `?`, règles dures Gemini — TD-22), VAD `realtimeInputConfig` réintégré, `@google/genai` retiré. Validé Groupe D en conditions réelles. Commits `94387a7` (code) + `5f7e52d` (docs), poussés sur `forgejo`.
- **6e (frontend)** : architecture audio « Voie A » — un seul AudioContext au rate natif partagé (capture + playback + enregistrement), mix temps réel via tap worklet, WAV mono single-track aligné, indicateur de prise de parole (VAD), correction des blancs EO, nettoyage `[BISECT]`. Tests 269/37 ; validation audio à l'oreille.

## Sprint 6.5 — Clean

- Factorisation des fichiers modifiés Sprint 6
- Tests manuels Groupe D rejoués
- Commit refactor(t2-live)

## Sprint 7 — T1 Live (interruption aléatoire)

- **7a (backend) ✅** : extension du proxy WebSocket Gemini Live (`gemini-3.1-flash-live-preview`, ws brut, pas de SDK) au mode T1 — system prompt « examinateur », décision d'interruption probabiliste, génération de la question de relance sur transcription partielle (DeepSeek). Réutilise l'infra T2 Live. Scoring EO 5 critères × /4. Phonologie live = 0 (TD-08, gelé). Contraintes héritées : pas de `speechConfig`. Livré : commits `868bd09` (code) + `3722e2a` (docs) ; dettes tracées TD-23/24/25 (cf. `TECH_DEBT-backend.md`).
- **7b (frontend) ✅** : UI T1 Live — machine d'état T1 (8 états, `interrupted ⇄ presenting`), `useT1LiveSession` (WS `/t1/live`, sans message `context` post-Patch 7a, uplink coupé par ref pendant interruption), `T1PreparationPage` / `T1DialoguePage` / `T1SpeakingIndicator`, carte `EO_T1_LIVE` gatée Premium (`oral_t2_live`). Parcours simplifié carte → prépa → dialogue. `T1LiveQuestionnairePage` + `T1LiveContext` retirés. Réutilise les hooks audio T2 (FTD-44 gelée). **Bugs amont observés au test manuel** (hors contrôle frontend) : **FTD-45** (relances Gemini hors-sujet, extension TD-23) et **FTD-46** (transcription Gemini Live hasardeuse).

## Sprint 7.5 — Clean

- Factorisation des fichiers modifiés Sprint 7
- Tests manuels Groupe D étendu (T1 Live) rejoués
- Commit refactor(t1-live)

## Sprint 7c — Migration audio EO Live : Gemini Live → Deepgram (T1 + T2)

- Décision actée (**ADR-007**) de migrer l'architecture audio de Gemini Live natif vers une architecture découplée Deepgram (STT nova-3 + DeepSeek LLM + TTS Aura-2), suite à un POC concluant : transcription quasi parfaite à débit lent (vs confusions de langue/omissions Gemini), relances ancrées sur le discours réel du candidat, coût 4-5x inférieur.
- Implémentation en deux temps : (1) construction du module Deepgram en parallèle de Gemini Live derrière un flag `EO_STT_PROVIDER=gemini|deepgram` pour comparaison en conditions réelles, (2) bascule complète + retrait du code Gemini Live (`geminiLive.ts`, usages `t1live.ts`/`t2live.ts`).
- Résout FTD-45, FTD-46 (frontend, gelées avec renvoi vers cet ADR — cf. `TECH_DEBT.md`) et TD-22/TD-23 (backend, hors scope frontend — dépôt séparé).
- Découpage fin (sous-sprints backend/frontend) à définir dans une session de planification dédiée avant exécution — non détaillé ici.

## Sprint 7e — Transcription live à l'écran (T2 + T1)

- Affichage incrémental temps réel des prises de parole pendant le dialogue : router `inputTranscription` + `outputTranscription` (déjà produits côté backend pour l'évaluation) jusqu'au frontend via le WebSocket, puis rendu progressif à l'écran.
- Placé après le T1 Live pour couvrir **les deux modes live** d'un seul chantier.
- **Chantier non trivial** (flux WS + affichage incrémental) — à décomposer en sous-étapes ; pas « cosmétique ».
- **MAJ post-7a** : source backend de la transcription déjà disponible (confirmé par 7a).
- **Caveat TD-23** : en VAD manuel, `inputTranscription` candidat n'est flushé qu'à `activityEnd` (pas token par token) → l'affichage incrémental temps réel n'est possible que pour `outputTranscription` (examinateur) ; l'incrémental côté candidat est à reconcevoir.
- **Note (ajoutée 2026-07-02)** : à réévaluer/simplifier une fois la migration **Sprint 7c** (Deepgram, ADR-007) effectuée — le caveat TD-23 ci-dessus disparaît avec un provider nativement streaming. Ce sprint pourrait devenir substantiellement plus simple, voire trivial, une fois 7c terminé.

## Sprint 8 — Mode Examen

- Timer inarrêtable + readOnly à T=0

## Sprint 8.5 — Clean

- Factorisation des fichiers modifiés Sprint 8
- Tests manuels Groupe D rejoués
- Commit refactor(exam-mode)

## Sprint 9 — Page Admin (outillage opérationnel)

- **9a (backend)** : middleware auth admin (modèle de sécurité à trancher — cf. SECURITY.md) ; endpoint agrégation chiffres clés (inscrits, corrections jour/mois, abonnements actifs, waitlist) ; endpoint waitlist (liste + export CSV).
- **9b (backend)** : CRUD sujets (liste + filtres mode·tâche·statut, create, update, toggle actif, delete) — réutilise le modèle de sujets existant, service role.
- **9c (frontend)** : route admin protégée (hors navigation publique) + Dashboard chiffres clés (compteurs cliquables, refresh périodique).
- **9d (frontend)** : module Gestion des sujets + module Waitlist (tableau + bouton Export CSV).

## Sprint 9.5 — Clean

- Factorisation des fichiers modifiés Sprint 9
- Tests manuels Groupe H (admin) joués
- Commit refactor(admin)

## Sprint 10 — Paiement Orange Money (semi-manuel)

- **10a (backend)** : migration Supabase `commandes_om` (RLS, accès service role) ; endpoint création de commande (code unique + insertion) ; job d'expiration via scheduler Render (pas de cron Vercel).
- **10b (backend)** : endpoint d'activation → écrit le plan via le même chemin que le webhook Stripe (planController / source de vérité unique, ADR 005) — jamais d'écriture SQL directe du plan ; email de confirmation client.
- **10c (frontend)** : page client `/paiement-om` (depuis `/plan`, lien WhatsApp pré-rempli) + ajout de l'option « Payer via Orange Money » sur la page plans.
- **10d (frontend)** : module Commandes OM dans l'admin (onglets en attente / activées / expirées, bouton Activer, countdown, note interne).

## Sprint 10.5 — Clean

- Factorisation des fichiers modifiés Sprint 10
- Tests manuels Groupe H étendu (flux OM complet) joués
- Commit refactor(paiement-om)

## Sprint 11 — Pré-lancement

- MAINTENANCE_MODE implémenté ✅ (2026-04-19)
- Sentry configuré
- /ultrareview avant bascule
- Smoke test Groupe Z complet
- Procédure DEPLOYMENT.md exécutée