Guide 📱 Scanneur — bénévole à la ligne d'arrivée

⚠️ Document généré automatiquement par les tests E2E (e2e/browser.test.ts). Toute modification manuelle sera écrasée au prochain run.

Tu es bénévole à la ligne d'arrivée. Ton job : scanner chaque dossard qui franchit la ligne. L'app range automatiquement les scans en retard au bon tour grâce au mode rattrapage.

Mot de passe : si la course est protégée, le directeur de course t'a transmis un mot de passe (généralement via le QR code « Scanneur arrivée » imprimé). Le mot de passe te sera demandé une seule fois dès ta première action (premier scan ou première correction), puis il est mémorisé sur ce téléphone pour toute la durée de la course. Cette protection empêche les coureurs ou les spectateurs ayant l'URL d'envoyer de faux scans qui pollueraient le classement.

Sommaire

• Démarrer une course
• Pendant la course
• Corriger un scan (à chaud ou à froid)
• Mode rattrapage
• Fin de course

Démarrer une course

3. Splash : à quel rôle es-tu ?

Quand un téléphone arrive sur une course sans préciser la vue (par exemple via un lien WhatsApp partagé), un écran d'orientation s'affiche : « Quel est ton rôle sur cette course ? ». Quatre cartes : 🎯 Directeur, 📱 Scanneur, 👀 Spectateur, ⚙️ Administrateur.

Le choix est mémorisé sur ce téléphone — la prochaine fois qu'on revient sur la course, on est redirigé directement vers la bonne vue (sans repasser par ce splash). Les QR codes générés depuis la page Configuration mènent quant à eux directement sur la bonne vue, sans passer par ce splash.

4. Page d'accueil — pitch & contact

La page d'accueil de ttt-chrono.juulieen.fr est une page de présentation publique du projet. Elle s'ouvre sur un hero avec le pitch (« Chronométrer ta backyard, par un coureur, pour des organisateurs ») et deux CTA : Je veux ce système pour ma course (qui scrolle vers le formulaire de contact) et Voir comment ça marche.

La page raconte ensuite la genèse du projet (un coup de fil du club Run Event 86, une backyard à organiser, pas de solution abordable sur le marché), puis explique en 3 cartes comment ça marche : bracelets NFC scannés par téléphone Android, multi-téléphone hors-ligne, résultats live sur web et grand écran TV. Quatre chiffres clés rappellent le bilan de la Tic Tac Trail 2026 (177 coureurs, 1 201 tours, 17h de course, 1 finisher). Sous ces chiffres, deux liens : les résultats live de la Tic Tac Trail 2026, toujours en ligne, et l'archive des courses passées (/races).

Une mosaïque photos du jour J (arche départ, vainqueur, ambiance nuit, podium) précède le formulaire de contact présenté comme un service sur mesure : un orga peut écrire pour présenter sa course (format, date prévue, ordre de grandeur du nombre de coureurs, message). Le bouton Envoyer ouvre le client mail prérempli pour caler un appel et discuter du périmètre et des conditions ; un bouton secondaire propose WhatsApp. Email et téléphone sont assemblés en JS pour ne pas être moissonnés par les bots.

En bas, un encart 🙏 Merci Run Event 86 rend hommage explicitement au club, sans qui le projet n'existerait pas. Deux boutons sociaux y sont affichés : Instagram (@run_event_86) et Facebook (Run Event 86), qui s'ouvrent dans un nouvel onglet.

Une zone repliable 📂 Mes courses (en bas, ouverte par défaut) regroupe les outils admin : bouton + Nouvelle course, lien 📖 Guide vers cette documentation, panneau persona (4 cartes Administrateur / Directeur / Scanneur / Spectateur), et la liste de toutes les courses créées avec leurs boutons d'accès rapide selon leur statut (Tags NFC, Contrôle, Arrivée, Résultats, 📊 Stats). Sur chaque fiche course, en plus des boutons d'action, des compteurs indiquent le nombre de dossards et de scans enregistrés. Pour une course en cours, le tour actuel est affiché en accent (ex : Tour 3 en cours).

Pastille de synchronisation (en haut à droite, visible sur toutes les vues) : indique l'état du téléphone d'un coup d'œil. 🟢 Sync = toutes les données sont synchronisées avec le serveur. 🟡 N en attente = N scans en file d'attente, qui partiront automatiquement à la reconnexion (mode hors-ligne) — y compris si la course s'est terminée entre-temps : un scan fait pendant la course est toujours compté. Un scan ne quitte la file qu'une fois confirmé par le serveur ; s'il est refusé (par exemple horodaté après la fin de course), un message rouge l'indique avec le numéro de dossard. 🔴 Hors ligne = pas de connexion. Plus besoin de mémoriser un code couleur — le libellé est lisible directement.

Pendant la course

8. Modale d'aide bénévole (1ère visite)

Au premier passage d'un téléphone sur Mode Arrivée, une modale d'aide s'ouvre automatiquement avec une checklist en 6 points :

1. Navigateur recommandé (Chrome Android)
2. NFC activé dans les paramètres Android
3. Permission NFC acceptée dans Chrome
4. Mot de passe de la course (saisie unique au premier scan si la course est protégée, transmis via le QR code « Scanneur arrivée »)
5. Position du tag sur le téléphone (zone variable selon les modèles)
6. Fallback saisie manuelle si le NFC ne marche pas

La modale affiche aussi l'état NFC actuel sous forme de pastille (✅ Actif / ⏳ Démarrage / ❌ Non supporté / 🔒 Permission refusée / ⚠️ Désactivé / Erreur).

Deux boutons en bas : 📖 Guide complet (ouvre /docs/scanneur dans un nouvel onglet) et J'ai compris (ferme et mémorise — elle ne se rouvrira plus automatiquement). On peut la rappeler à tout moment via le bouton ❓ Aide dans le header.

9. Vue Mode Arrivée

L'écran Mode Arrivée est utilisé sur les téléphones de scan. Il enregistre chaque coureur qui franchit la ligne via le scan NFC du dossard, ou via la saisie manuelle. Cet écran a deux états :

• Avant DÉPART : bandeau orange 🧪 Mode TEST — voir la section dédiée juste après. Tu peux scanner pour tester ton téléphone, rien n'est enregistré.
• Pendant la course : c'est ce qu'on voit ici. Le bandeau test est remplacé par les compteurs de tours et les arrivées s'enregistrent normalement.

Bandeau diagnostic NFC au-dessus de la zone de scan : indique d'un coup d'œil si le NFC est actif (✅), en démarrage (⏳), non supporté par le navigateur (ℹ️), désactivé sur le téléphone (⚠️), ou si la permission a été refusée (🔒) avec un bouton 📱 Réactiver NFC pour relancer la demande sans recharger la page.

Mot de passe de la course : si la course est protégée, le tout premier scan déclenche une popup native qui demande le mot de passe (transmis via le QR code « Scanneur arrivée »). Une fois saisi, il est mémorisé sur ce téléphone pour toute la course — cette protection empêche un spectateur ou un coureur ayant l'URL d'injecter de faux scans dans le classement.

Anti-rebond NFC (3 s par dossard) : un même dossard re-scanné en moins de 3 secondes est ignoré silencieusement (les puces NFC déclenchent parfois plusieurs lectures consécutives au contact prolongé). Les autres dossards passent normalement — il n'y a pas de cooldown global, tu peux scanner 3 puces différentes en 1 seconde sans souci. Pour rattraper plusieurs tours d'un même dossard, attends ~3 s entre chaque scan.

Bouton ❓ Aide dans le header : rouvre la checklist bénévole à tout moment.

12. Mode Arrivée pendant les scans

Au fur et à mesure que les coureurs franchissent la ligne, le dernier scan est mis en évidence en grand au centre de l'écran. La liste Arrivées récentes en bas conserve l'historique du tour en cours.

Chaque ligne affiche un badge Tx (numéro de tour). Les scans attribués automatiquement au tour précédent (mode rattrapage) sont marqués d'une bordure gauche orange et d'un Tx en orange, pour distinguer visuellement un retardataire d'un coureur en avance sur le tour courant.

Détection de doublon : si un coureur a déjà bouclé le tour courant (validé via completed_laps >= current_lap), un nouveau scan affiche le toast « Dossard #N a déjà bouclé ce tour » et n'est pas envoyé au serveur — la détection est basée sur les tours réellement validés du coureur (cohérent entre tous les téléphones), plus sur l'historique local du téléphone.

Tape sur une ligne pour ouvrir un menu de correction (changer le tour, supprimer le scan).

32. Mode TEST — avant le DÉPART

Quand un bénévole ouvre Mode Arrivée avant que le directeur n'ait cliqué DÉPART, un bandeau orange 🧪 Mode TEST — la course n'a pas démarré s'affiche en haut.

Tu peux scanner ta puce NFC ou saisir un dossard pour vérifier que ton téléphone fonctionne (vibration + beep + affichage du dossard à l'écran), mais aucun scan n'est enregistré ni envoyé au serveur — un toast TEST · #N OK (course non démarrée — non comptabilisé) te le rappelle à chaque essai. C'est exactement le moment idéal pour valider que :

• ton NFC marche (le bandeau diagnostic NFC est visible juste en dessous)
• la saisie manuelle marche aussi (au cas où)
• ton téléphone vibre et bipe correctement
• le mot de passe est mémorisé (s'il a été demandé au join WS)

Le bandeau disparaît automatiquement dès que la course passe en started après le DÉPART. Côté serveur, l'API rejette aussi tout scan pré-départ en HTTP 409 (belt-and-suspenders contre un envoi direct hors UI).

Corriger un scan (à chaud ou à froid)

13. Menu de correction depuis le mode Arrivée

En tapant sur une ligne du log Arrivées récentes, un menu apparaît avec les actions disponibles : ← Changer pour Tour N-1, Changer pour Tour N+1 →, Supprimer ce scan…, ou Annuler. La suppression est protégée par un second modal qui exige de taper le numéro de dossard concerné.

Mode rattrapage

15. Bandeau orange « Coureurs en retard »

Lorsque le tour suivant commence (transition automatique selon les durées configurées) mais que des coureurs n'ont pas encore franchi la ligne du tour précédent, un bandeau orange apparaît avec la liste des dossards manquants.

Continue à scanner normalement : l'application range automatiquement chaque scan au prochain tour à valider du coureur (= son completed_laps + 1), pas systématiquement au tour précédent.

Rattrapage de plusieurs tours d'affilée : un coureur qui revient avec 2 ou 3 tours de retard peut tous les rattraper en re-scannant son dossard plusieurs fois — chaque scan lui crédite le tour suivant qu'il doit valider, dans l'ordre. Vu le cooldown de 3 secondes par dossard (anti-rebond NFC), attends ~3 s entre chaque re-scan du même dossard. Les autres dossards passent normalement.

Quand tu es certain que les retardataires ne reviendront pas, un bouton Tour N terminé (X abandons) en bas du bandeau permet de clôturer la fenêtre de rattrapage : les coureurs manquants sont alors marqués abandonnés.

16. Scan attribué automatiquement au tour précédent

Quand tu scannes un dossard qui figure dans la liste des coureurs en retard, la carte centrale affiche TOUR N (rattrapage) en orange. Une notification bleue confirme #X → Tour N (rattrapage) et l'entrée s'ajoute à Arrivées récentes au bon tour. Aucune action de l'opérateur n'est nécessaire — tout est automatique grâce à l'historique du coureur.

Si le coureur a 2 tours de retard ou plus, le toast précise aussi le nombre de tours à rattraper, par exemple #12 → Tour 3 (rattrapage, 2 tours de retard). Re-scanne pour le tour suivant (en respectant le cooldown 3 s par dossard).

21. Modal « Terminer le rattrapage du tour N »

Quand tu cliques Tour N terminé sur le bandeau orange, ce modal s'ouvre. Il liste les dossards manquants qui seront marqués ABANDONNÉS définitivement. Pour éviter les fausses manips, le bouton Confirmer ne s'active que si tu tapes le numéro du tour dans le champ de saisie. Cette protection est volontaire car l'action est destructrice.

Fin de course

24. Écran Arrivée — course terminée

Dès que le directeur termine la course, l'écran Arrivée de chaque scanneur affiche le bandeau 🏁 Course terminée avec la durée totale, sans recharger la page. Un bracelet scanné ensuite est lu (bip) mais non comptabilisé : la carte du dernier scan affiche NON COMPTABILISÉ au lieu du tour, et un message le précise.