expria-backend/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 réutilisant ws-client + audio worklet + state machine T2 ; phase préparation ; gestion interruption / reprise du flux audio dans la state machine ; gating Premium.

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 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.

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