tasks/lessons.md

🎓 Infrastructure Lessons (La Plomberie)

Ce fichier archive les échecs et solutions liées à la stabilité technique du système. Les règles ici doivent être respectées lors de toute modification structurelle.

• [ARCHI] Détachement Gateway : Ne JAMAIS laisser une gateway (Hugging Face / Meta) attendre > 20s. Répondre 200 OK immédiatement et déléguer au worker.

• [DB] Séquençage des Opérations : Ne JAMAIS envoyer de message WhatsApp avant d'avoir persisté la progression dans Prisma. La DB est la seule source de vérité.

• [CACHING] Verrous d'Idempotence : Utiliser des locks Redis avec un TTL minimal de 300s (5 min) pour protéger les appels LLM longs et éviter les retries en boucle.

• [MEDIA] Vision Base64 : Gemini échoue par URL ; toujours convertir les photos d'utilisateurs en Base64.

• [STT] Whisper Auto-Validation : Si l'indice de confiance est <= 80%, intercepter le flux et basculer en PENDING_REVIEW pour validation humaine sans crash.

• [NON-BLOQUANT] Processus FFMPEG : Les conversions audio doivent tourner dans des sous-processus.

• [AI] OpenAI Zod Schemas : Pour les Structured Outputs, OpenAI exige que TOUS les champs d'un schéma soient obligatoires OU explicitement .nullable().optional(). Les .optional() seuls sur les sous-objets provoquent une erreur.

• [QUEUES] Payload Sync : S'assurer que les noms de champs dans whatsappQueue.add (producteur) matchent exactement le destructuring dans le worker (consommateur). Préférer currentDay partout pour la consistance.

• [DB] Enrollment ID : Toujours passer l'ID d'inscription (enrollmentId) au job de feedback pour permettre la persistance des réponses sans crash Prisma.

• [JSON] Null Safety & Expansion : Toujours vérifier la présence de données (Null Safety) lors de l'extension des schémas JSON, sous peine de briser le pipeline des jours précédents (Utiliser des guards currentDay >= X).

• [FLOW] Re-validation Window : Ne jamais bloquer une analyse entrante sous prétexte que le statut est COMPLETED si le délai depuis la dernière validation est inférieur à 5 minutes (cas de correction immédiate par l'utilisateur) ou si un nouvel élément multimédia est présent.

• [FLOW] Day 7 Card Blockage : Risque de blocage lors du choix de carte. Toujours valider que l'entrée textuelle courte (ex: "WhatsApp") déclenche la même logique que l'audio en baissant le seuil de minWordCount.

• [UX] Card Interaction (Hook) : L'interaction par cartes/boutons ne doit jamais être bloquante. Elle doit servir de "hook" : le Coach valide le choix et relance immédiatement sur le "pourquoi" pour enrichir l'analyse.

• [UX] Anti-False Validation (Card Click) : Un clic sur une carte/bouton ne doit JAMAIS valider une étape (COMPLETED). Il doit servir de point d'entrée ("hook") pour une explication riche. Forcer le statut à PENDING après un choix par bouton pour obliger l'utilisateur à donner son explication audio/texte.

• [FLOW] Validation Subordonnée : Le passage en COMPLETED est strictement réservé au feedback positif de l'IA sur une réponse de fond. L'UI d'attente ("Analyse de votre réponse...") doit être envoyée, mais le statut ne doit bouger que sur confirmation IA.

🛡️ Règle d'Or de l'Intégrité

Les correctifs techniques ne doivent JAMAIS impacter la logique de personnalisation du prompt generatePersonalizedLesson ou des feedbacks. Toute simplification technique qui réduit la spécificité de l'IA est un échec.

📅 Historique des Apprentissages

• [24/03/2026] | Gemini 404 | Utiliser gemini-1.5-pro-latest au lieu de gemini-1.5-pro sur l'API v1beta.
• [24/03/2026] | Missing dayNumber | currentDay vs dayNumber mismatch dans le job payload. Toujours vérifier le destructuring.
• [30/04/2026] | tsx en production | Ne jamais utiliser --import tsx en PM2 pour production. tsx est une devDependency. Compiler tous les packages/apps avec tsc et pointer PM2 vers dist/index.js.
• [30/04/2026] | @repo/database non compilé | Tout package workspace consommé en production doit : (1) avoir noEmit: false dans son tsconfig, (2) pointer main vers ./dist/index.js, (3) être compilé dans le Dockerfile avant les apps qui en dépendent.
• [30/04/2026] | Imports .js dans tsconfig node | Les imports './foo.js' dans un fichier .ts requièrent moduleResolution: node16. Avec moduleResolution: node, utiliser des imports sans extension : './foo'.
• [30/04/2026] | Fastify plugin versioning | Avant de modifier la version de Fastify ou d'un plugin @fastify, auditer TOUS les plugins avec grep "fastify:.*\.x" dans leur index.js. Le numéro de version majeur varie par plugin — ne pas supposer que X.x = Fastify v4 ou v5.
• [30/04/2026] | addContentTypeParser Fastify v5 | La signature callback (req, body, done) => void est remplacée par async (req: FastifyRequest, body: Buffer) => unknown. Retourner la valeur parsée, ne pas appeler done().
• [30/04/2026] | Fire-and-forget Fastify v5 | Pattern correct : setImmediate(async () => { ... }) D'ABORD, puis return reply.code(200).send(...). Ne jamais laisser reply.send() sans return dans un handler async Fastify v5.