Pièges connus

Le limiteur de débit d'authentification

Les endpoints d’authentification sont limités à 100 requêtes / 60 s en fenêtre glissante. Saturé, le service répond 400 avec un corps vide — sans message. Cesser toute requête une minute, puis reprendre.

Ce que vous lisez à l’écran : « Une erreur est survenue. Veuillez réessayer. » — le message générique. Rien ne nomme le limiteur, et vos identifiants sont bons.

Quand il frappe : quand on enchaîne inscriptions, connexions et acceptations d’invitation pour monter un jeu de test ou préparer une démonstration.

Comportement attendu. Ne changez pas de mot de passe, ne réinstallez rien : attendez une minute de silence complet, puis reprenez où vous en étiez.

Ce qui suit fait perdre du temps sans être un défaut. Chaque entrée dit le symptôme d’abord, puis la cause, puis ce qu’on fait — et si c’est un comportement attendu ou une limitation connue. La différence compte : confondre les deux fait remonter de faux défauts, ou pire, fait passer de vrais défauts pour normaux.

Un piège propre à un domaine reste dans son scénario. Ceux d’ici sont transverses.

Environnement

Symptôme	Cause	Ce qu’on fait	Nature
Rien ne répond sur http://localhost:5173	ce port n’a jamais été celui du produit — c’est l’ancien défaut de l’outil de développement, resté dans les habitudes	ouvrir http://localhost:3000 ; la table complète est sur le gabarit	attendu
L’application se charge mais tout est vide, chaque écran affiche son erreur	PostgreSQL n’est pas démarré	docker compose up -d postgres, puis recharger	attendu
Les notifications, les imports et les rappels ne partent pas, alors que le reste fonctionne	Redis n’est pas démarré : la file d’attente est indisponible	docker compose up -d redis ; vérifier avec docker compose ps	attendu
La cloche ne bouge pas mais les réservations se créent	même cause — les lignes de notification peuvent être posées, l’acheminement échoue proprement	idem ; l’action métier n’est jamais cassée par un incident de notification	attendu
« Le calcul a échoué : … » dès le lancement d’une optimisation	le solveur n’est pas démarré, ou pas encore prêt	docker compose up -d solver, puis curl http://localhost:8082/q/health/ready — il met une trentaine de secondes au premier démarrage	attendu
Des écrans plantent avec des erreurs de colonne inconnue	les migrations ne sont pas appliquées	cd packages/db && bun run db:migrate	attendu
La grille est vide, aucun cours nulle part, sur le tenant de démonstration	le seed n’a pas été rejoué, ou a échoué en cours de route	bun run demo:seed ; le récapitulatif des quatre scénarios doit s’afficher à la fin	attendu
Un import reste bloqué à « Vérification… »	la file d’attente ne tourne pas	vérifier Redis	attendu

Authentification et session

Symptôme	Cause	Ce qu’on fait	Nature
Des inscriptions enchaînées échouent sans message	le limiteur de débit — voir en tête de page	attendre une minute de silence complet	attendu
Vous arrivez sur l’écran de connexion sans l’avoir demandé	la session a expiré ou manquait ; l’adresse porte alors ?redirect=	se reconnecter : vous serez ramené où vous alliez	attendu
Les deux sessions d’un test à deux comptes n’en font qu’une	deux onglets d’un même profil partagent la session	deux navigateurs différents, ou un navigateur plus une fenêtre privée	attendu
Un changement de mot de passe vous déconnecte partout	c’est écrit sur l’écran : « Par sécurité, changer votre mot de passe déconnecte vos autres appareils. »	se reconnecter	attendu
Le lien de changement d’adresse n’arrive jamais dans la nouvelle boîte	sur une adresse vérifiée, il part vers l’ancienne adresse	regarder l’ancienne boîte ; le détail est sur Mon compte	attendu, et contre-intuitif
Une invitation créée ne parvient jamais à son destinataire	sur une installation sans service d’envoi, aucun e-mail ne part — et l’écran affiche toujours le message de repli, même quand un envoi a lieu	copier le lien affiché et le transmettre à la main, systématiquement	limitation connue — le message de l’écran est trompeur

Fraîcheur des données

Symptôme	Cause	Ce qu’on fait	Nature
« Des changements ont eu lieu depuis le dernier calcul — les scores peuvent être périmés. » sur la synthèse	une modification a touché le périmètre depuis le dernier calcul	cliquer « Recalculer » ; ce n’est pas une erreur — le détail est sur Époque de planification	attendu
La synthèse ne se périme pas après une publication	publier ne déplace rien, n’occupe rien : seules les mutations d’occupation périment une synthèse	rien à faire — c’est le comportement voulu	attendu
« Mon planning » n’a pas changé alors que la notification de publication est arrivée	la réponse est mise en cache 60 secondes côté serveur	attendre une minute et recharger. Ne republiez pas — vous notifieriez tout le monde une seconde fois	attendu, compromis assumé entre fraîcheur et charge
Les taux d’occupation ne bougent pas après une réservation ou une publication	l’analytique est un calcul figé, reconstruit périodiquement ou à la demande	cliquer « Rafraîchir » avant de lire, et noter la date de calcul avec la valeur	attendu
Deux relevés d’analytique se contredisent	ils n’ont pas la même date de calcul, ou pas les mêmes filtres — le rafraîchissement ne recalcule que la combinaison affichée	comparer les dates avant les chiffres	attendu
Un taux paraît anormalement bas	les taux sont calculés sur la plage d’ouverture complète, 7 jours sur 7 ; les brouillons et les demandes en attente ne comptent pas	lire les définitions sur Analytique d'occupation avant de conclure	attendu

Perception

Les pièges qui ne sont pas des dysfonctionnements du tout, mais des lectures fausses.

Symptôme	Cause	Ce qu’on fait	Nature
Une section a disparu du menu	le produit filtre la navigation : ce qui n’est pas permis n’existe pas à l’écran. Il n’y a ni entrée grisée, ni cadenas	ouvrir l’accueil et lire « Vos accès » — c’est la liste exhaustive de vos droits	attendu, et c’est la question de support n°1
Au tout premier affichage, le menu est plus court qu’il ne le sera	les permissions ne sont pas encore résolues ; seules les entrées sans permission s’affichent	attendre une seconde	attendu
La grille ne se rafraîchit pas sur certains écrans	le temps réel n’est pas branché partout : le calendrier, les nomenclatures, la pédagogie, les plans d’étage et l’analytique exigent un rechargement	recharger la page	limitation connue
On cherche un abonnement d’agenda pour synchroniser son planning	cette fonctionnalité n’existe pas — aucune route, aucun bouton, aucune adresse de ce type dans le produit	rien à chercher ; le détail est sur Mon planning	limitation connue
On cherche à activer les notifications Push	la colonne existe dans la matrice de préférences, mais aucun écran ne propose d’autoriser un appareil	compter sur « In-app » et « E-mail »	limitation connue
Le compteur de « Validations » a disparu	il n’affiche jamais « 0 » : à zéro, le badge s’efface	une entrée sans compteur veut dire « rien à traiter »	attendu
Une action échoue avec « L’action a échoué. Réessayez. » sans raison apparente	la file d’approbation est partagée : un collègue a traité la demande entre-temps	vérifier si la ligne est encore là avant de conclure	attendu
Une adresse directe donne « Salle introuvable. »	la ressource appartient à un autre établissement — le produit ne confirme pas l’existence de ce qu’il protège	c’est la garantie d’isolation qui fonctionne	attendu

Ce qui n’est pas ici

• Les refus légitimes — quota atteint, salle occupée, permission manquante — sont des garanties, pas des pièges. Ils sont sur Les chemins qui échouent.
• Les pièges propres à un domaine restent dans leur scénario : la case des lignes valides d’un import global, le mercredi d’un enseignant peint en vert, le poids d’une contrainte qui change la grille de tout le monde. Chaque scénario porte sa propre section « Pièges connus ».
• Les pièges propres à un écran sont dans la référence, au plus près de ce qu’ils décrivent.

Ajouter un piège ici

Trois conditions, et il les faut toutes :

1. il est transverse — il ne dépend pas d’un écran ni d’un domaine ;
2. il a été observé, pas supposé. Un piège écrit au futur — « il faudra penser à… » — n’est pas un piège ;
3. il n’est écrit nulle part ailleurs sur ce site. Si c’est le cas, renvoyez plutôt que de recopier.

Le format ne se négocie pas : symptôme observé → cause → ce qu’on fait → attendu ou limitation connue. C’est ce qui rend la page lisible en diagonale, et cette page se lit en panique.

Pages liées

• Les chemins qui échouent — les refus qui sont des garanties.
• Avant une démonstration — la checklist qui évite la moitié de ces pièges.
• La recette — les deux niveaux de parcours.
• Le gabarit d’un scénario — les ports, les comptes, le format.