Z8 — Onboarding & First Use Experience¶

Cold start · Recovery premier upload · Confiance parent Day 1

L'onboarding est le moment de vérité : un parent qui télécharge l'app un mardi soir et ne voit rien d'utilisable dans les 3 premières minutes désinstalle. Un élève dont le premier OCR échoue sans guidance pense que « ça ne marche pas ». Un parent qui rejoint et attend 6 jours son premier signal ne revient pas. Cette zone couvre les 3 gaps critiques d'adoption qui ne sont pas adressés par les zones existantes.

NOTE : Les zones Z6 (engagement) et Z7 (routine de soirée) couvrent le comportement du système une fois que l'élève a du contenu actif. Z8 couvre spécifiquement la transition entre « l'app est installée » et « l'élève a sa première session réussie + le parent a compris la valeur ». Sans Z8, les 163 AC précédents décrivent un produit excellent… auquel personne n'arrive.

Z8-AC01 — Chapitre démo pré-chargé (cold start)¶


Lot 0	P1
GIVEN	L'élève vient de créer son compte (email/OAuth). Il n'a encore uploadé aucun chapitre. L'app est vide.
WHEN	L'élève arrive sur le dashboard pour la première fois.
THEN	Un chapitre démo est automatiquement présent dans l'app : matière « Physique-Chimie », titre « Densité et masse volumique (démo) ». Ce chapitre contient 8 items pré-générés (2 MCQ, 2 CLOZE, 2 SHORT, 1 NUMERIC, 1 DEFINITION), tous en état UNKNOWN, difficulté 1. Le dashboard affiche un bandeau contextuel : « Essaie une session de révision avec ce chapitre d'exemple — 3 min ». L'élève peut lancer une `evening_first` sur le chapitre démo exactement comme sur un vrai chapitre (même moteur de session Z6-AC04/AC05, même débrief Z1-AC15, mêmes micro-célébrations Z1-AC14). Le chapitre démo est marqué `is_demo = true` dans la base. Il est exclu de la progression globale, du digest parent, du pool de composition des sessions `daily`/`pre_class`, et de l'`EveningPlan` (Z7-AC01). Seule la session `evening_first` initiale est proposée sur le chapitre démo. Quand le pipeline J0 du premier vrai chapitre se termine avec ≥ 1 item valide, le chapitre démo est automatiquement archivé (ne pollue plus le dashboard). L'élève peut le supprimer manuellement à tout moment. Si l'élève n'interagit pas avec le chapitre démo et uploade directement un vrai chapitre, aucune friction — le chapitre démo est archivé silencieusement.

NOTE : Le chapitre démo résout le problème #1 d'adoption : le cold start. Un parent qui télécharge l'app à 22h un mardi peut voir son enfant faire un quiz en 3 minutes, sans cahier, sans photo, sans attente OCR. Le contenu « Densité et masse volumique » est volontairement un sujet de 5e/4e accessible, sans prérequis. Le coût technique est quasi nul : 8 items statiques injectés à la création du compte, traités par le même moteur. L'archivage automatique évite que le chapitre démo ne devienne du bruit une fois que l'élève a du vrai contenu.

Z8-AC02 — Empty state guidé avant premier upload¶


Lot 0	P1
GIVEN	L'élève a créé son compte. Le chapitre démo est visible (Z8-AC01) mais l'élève n'a encore uploadé aucun vrai chapitre.
WHEN	L'élève ouvre le dashboard (après la session démo ou sans l'avoir faite).
THEN	Le dashboard affiche un empty state structuré en 3 étapes visuelles : (1) « ✓ Compte créé » (coché, vert). (2) « Photographie ton premier cours » avec un bouton « Capturer » proéminent + indication « 30 secondes ». (3) « Ta première session de révision » (grisé, avec « ~5 min après la capture »). Chaque étape a une icône, un texte court, et un état (fait / à faire / à venir). L'empty state disparaît dès que le premier chapitre est uploadé avec succès (pipeline J0 terminé avec ≥ 1 item valide). Si l'élève a fait la session démo, l'étape (1) devient « ✓ Session démo réussie — maintenant avec ton vrai cours ! ».

NOTE : L'empty state transforme le vide anxiogène (« cette app est cassée ? ») en checklist rassurante. Les 3 étapes numérotées créent un sentiment de progression immédiat. Le « 30 secondes » pour la capture et le « ~5 min » pour la session posent des attentes réalistes et désamorcent le « j'ai pas le temps ».

Z8-AC03 — UX de recovery si le premier OCR échoue¶


Lot 0	P2
GIVEN	L'élève vient de photographier son premier cours (1 à 5 pages). Le pipeline J0 échoue : OCR illisible (confidence < 0.3 sur toutes les pages) OU timeout (> 60s sans réponse) OU 0 items valides générés.
WHEN	Le pipeline J0 retourne un statut d'échec ou un résultat vide (0 items).
THEN	L'élève voit un écran de recovery (pas une erreur technique) : (1) Message empathique : « Les photos sont un peu difficiles à lire. Pas de panique, ça arrive souvent au début ! » (2) Conseils visuels : 3 mini-illustrations montrant (a) bonne luminosité vs ombre, (b) page bien cadrée vs coupée, (c) écriture lisible vs trop petite. (3) Bouton primaire : « Reprendre les photos » → rouvre la caméra avec les pages déjà prises visibles comme vignettes (pas de perte du travail précédent, l'élève peut re-photographier uniquement les pages problématiques). (4) Bouton secondaire : « Essayer quand même » → si le pipeline a produit au moins 1 item malgré la faible confidence, permettre de continuer en mode dégradé (les items générés sont marqués `validation_required = true`, Z3). (5) Fallback chapitre démo : si 0 items et c'est le tout premier upload, le message ajoute : « En attendant, tu peux t'entraîner sur le chapitre d'exemple ». Le nombre de retries n'est pas limité. Chaque retry relance le pipeline J0 normalement. L'écran de recovery est loggé (`event = 'j0_first_upload_recovery'`) pour monitorer le taux d'échec premier upload.

NOTE : L'échec du premier OCR est le moment le plus dangereux du funnel : l'élève n'a aucune tolérance à l'erreur car il n'a pas encore construit de confiance dans l'app. Le ton empathique (« ça arrive souvent ») + les conseils visuels (pas un message d'erreur technique) + le fallback vers le chapitre démo (Z8-AC01) garantissent que l'élève n'est jamais dans un cul-de-sac. Le logging du recovery permet d'identifier si le problème est systémique (OCR défaillant) ou ponctuel (mauvaises photos).

Z8-AC04 — Écran de progression pendant le traitement J0¶


Lot 0	P1
GIVEN	L'élève vient de soumettre ses photos (premier upload ou upload suivant). Le pipeline J0 est en cours de traitement.
WHEN	Le traitement dure plus de 3 secondes.
THEN	Un écran de progression s'affiche avec : (1) Animation de chargement engageante (pas un spinner technique — ex : une page qui se « scanne » visuellement). (2) Message contextuel en 3 phases : phase 1 (0-5s) « Lecture de tes pages… », phase 2 (5-15s) « Création des questions… », phase 3 (15s+) « Presque fini… ». (3) Si le traitement dépasse 30s, un message additionnel : « C'est un peu plus long que d'habitude. Tu peux fermer l'app — on te préviendra quand c'est prêt. » + l'app envoie une notification push quand le pipeline J0 termine (succès ou échec). L'élève peut quitter l'écran de progression à tout moment sans interrompre le pipeline. S'il revient dans l'app, l'écran de progression se réaffiche si le pipeline est toujours en cours, ou le résultat (session proposée ou recovery Z8-AC03) s'affiche si le pipeline est terminé.

NOTE : Le silence pendant le traitement est anxiogène — l'élève ne sait pas si l'app a planté ou si elle travaille. Les messages en phases donnent une illusion de progression même si le backend est asynchrone. Le seuil de 30s pour le message « tu peux fermer » est basé sur les standards UX mobile : au-delà de 30s d'attente, le taux d'abandon dépasse 50%. La notification push de fin transforme l'attente passive en promesse active.

Z8-AC05 — Onboarding parent : premiers écrans + digest anticipé¶


Lot 0	—
GIVEN	Le parent vient de créer son compte et de le lier à l'élève via le code 6 caractères (Z6-AC44).
WHEN	Le parent accède au dashboard pour la première fois.
THEN	Avant d'afficher le dashboard, le parent voit un mini-onboarding en 3 écrans (swipeable, skippable) : (Écran 1) « Voici ce que fait [Prénom] » : résumé visuel du principe (photo → questions → révision espacée → maîtrise). Durée de lecture : 10s. (Écran 2) « Votre tableau de bord » : aperçu annoté du dashboard avec 3 flèches : progression globale, matières actives, lien vers le script 3 minutes (Z1-AC17). (Écran 3) « Restez informé sans effort » : explication des notifications (routine terminée, digest hebdo, alerte inactivité) + bouton « Gérer mes préférences » (Z6-AC20). Après le 3e écran ou le skip, le parent arrive sur le dashboard réel. Si aucune session n'a été faite, l'Écran 1 utilise le futur (« Voici ce que fera [Prénom] ») et le dashboard affiche « [Prénom] n'a pas encore commencé — vous serez notifié dès sa première session. »

NOTE : 3 écrans = 30 secondes. C'est le minimum pour que le parent comprenne (1) ce que fait l'app, (2) ce qu'il voit, (3) ce qu'il recevra. Sans ça, le parent voit un dashboard avec des % qu'il ne comprend pas et des boutons qu'il n'ose pas toucher.

Z8-AC06 — Digest parent anticipé (J+2 après liaison)¶


Lot 0	—
GIVEN	Le parent a lié son compte à l'élève (Z6-AC44). Le prochain digest standard est dimanche 9h (Z6-AC27).
WHEN	(48h se sont écoulées depuis la liaison OU l'élève a complété 3 sessions, ce qui arrive en premier) ET l'élève a fait au moins 1 session depuis la liaison. Si 0 sessions à 48h, le digest anticipé est reporté jusqu'à la première session complétée.
THEN	Le parent reçoit un digest anticipé (notification push + email si activé) avec : (1) Nombre de sessions complétées depuis la liaison. (2) Temps total de révision. (3) Matières actives et nombre de chapitres. (4) Progression mastery globale (% FRAGILE → OK ou mieux). (5) Message d'encouragement contextualisé : « [Prénom] a révisé [X] min en [N] sessions depuis [jour]. Les premiers résultats arrivent vite — voici ce qu'on observe déjà. » Ce digest anticipé est unique — il n'est envoyé qu'une fois, après la première liaison. Les digests suivants reprennent le rythme hebdomadaire standard (dimanche 9h, Z6-AC27). Si le parent lie le compte un samedi, le digest anticipé est envoyé lundi (48h), et le digest standard dimanche suivant — pas de doublon si < 3 jours d'écart (le digest standard de ce dimanche est sauté, le prochain est le dimanche d'après). Le digest anticipé est également dédupliqué avec le digest pré-contrôle (Z6-AC25) : si les deux sont programmés dans un intervalle de 48h, ils sont fusionnés en un seul envoi. Le champ `parent.first_digest_sent_at` empêche les envois multiples.

NOTE : Attendre 6 jours (mercredi → dimanche) pour le premier signal parent est un churn silencieux. Le parent oublie l'app, l'enfant perd son allié. Le digest anticipé dit « l'app marche, votre enfant l'utilise, voici les preuves ». Le trigger dual (48h OU 3 sessions) couvre les deux cas : l'enfant actif (3 sessions en 24h = digest dès le lendemain) et l'enfant occasionnel (digest à 48h même avec 2 sessions). Le coût technique est un cron conditionnel sur parent.linked_at + 48h — trivial.

Z8-AC07 — Invitation parent : timing optimal dans l'onboarding¶


Lot 0	—
GIVEN	L'élève a terminé sa première session `evening_first` sur un vrai chapitre (`is_demo = false`, cf. Z6-AC05). La session démo ne déclenche pas l'invitation. L'élève n'a pas encore invité de parent (aucun compte parent lié).
WHEN	L'écran de débrief de la première session (Z1-AC15) est affiché.
THEN	Après le débrief standard, un écran d'invitation parent s'affiche : « Bravo pour ta première session ! Invite un parent pour qu'il suive ta progression. » Avec deux boutons : (1) « Inviter maintenant » → déclenche le flow Z6-AC44 (génération code 6 caractères + partage). (2) « Plus tard » → ferme l'écran, l'invitation reste accessible dans les paramètres. L'écran d'invitation n'est montré qu'une seule fois (après la 1re session). Si l'élève tape « Plus tard », un rappel discret apparaît dans les paramètres (badge notification sur l'icône settings) mais aucune notification push ni pop-up de relance. Le timing « après la 1re session » est intentionnel : l'élève a vécu le produit, il peut expliquer à son parent « c'est une app qui me pose des questions sur mes cours ». Avant la 1re session, l'élève ne sait pas ce que fait l'app et ne peut pas la recommander.

NOTE : Z6-AC44 spécifie le mécanisme de liaison mais pas le quand. Proposer l'invitation à la création du compte (avant toute session) est prématuré : l'élève ne sait pas encore ce qu'il recommande. Après la 1re session, l'élève vient de vivre le « moment magique » (ses propres questions de cours transformées en quiz) et a un pitch naturel. C'est aussi le moment où le parent voit son enfant excité par une app éducative — fenêtre d'opportunité maximale.

Z8-AC08 — Séquence d'onboarding déterministe (orchestration Day 0)¶


Lot 0	P2
GIVEN	L'élève vient de créer son compte. Les composants d'onboarding sont répartis entre Z6 (schedule), Z7 (tutoriel soirée), et Z8 (démo, empty state, recovery, parent invite).
WHEN	L'élève interagit avec l'app pour la première fois.
THEN	La séquence d'onboarding est déterministe et suit cet ordre : (1) Création de compte → (2) Chapitre démo apparaît (Z8-AC01) + Empty state visible (Z8-AC02) → (3) Session démo optionnelle (evening_first sur le chapitre démo, ~3 min) → (4) Première soirée dans la fenêtre de soirée : tutoriel Z7-AC16 (overlay guidé vers capture du vrai cours) → (5) Premier upload : saisie emploi du temps contextuelle (Z6-AC01) → pipeline J0 avec écran de progression (Z8-AC04) → si échec : recovery (Z8-AC03) → (6) evening_first sur vrai chapitre (Z6-AC04/AC05) → (7) Débrief (Z1-AC15) → Invitation parent (Z8-AC07). Les étapes (3), (5), (6), (7) sont des transitions event-driven, pas des timers. Si l'élève fait les étapes hors ordre (ex : upload avant la fenêtre de soirée), le tutoriel Z7-AC16 s'adapte en sautant les étapes déjà complétées. À aucun moment deux overlays/écrans modaux ne sont affichés simultanément.

NOTE : Cet AC est un orchéstrateur : il ne définit pas de nouveau comportement mais impose un ordre de priorité quand plusieurs composants veulent s'afficher en même temps. Sans lui, un développeur implémentant Z7-AC16 et Z8-AC02 indépendamment pourrait superposer le tutoriel sur l'empty state. La règle est simple : un seul écran modal à la fois, dans l'ordre défini ci-dessus.

Ces 171 AC couvrent les zones à risque identifiées pour le vibe coding. Ils sont conçus pour être directement transformés en tests (Jest / Pytest / Playwright). Chaque session de génération de code doit recevoir les AC de la zone concernée comme contexte système, avec l'instruction explicite de générer les tests correspondants avant le code d'implémentation (TDD-first).

Fin du document — Révise Mieux AC