docs/audit_resolution_fastify_v4.md

Rapport d'Audit : Résolution du Conflit de Dépendances Fastify & Stabilisation du Worker

1. Description du Problème

Lors du déploiement sur Hugging Face Spaces, l'API et le Worker WhatsApp ne parvenaient pas à démarrer, provoquant une erreur critique de type FST_ERR_PLUGIN_VERSION_MISMATCH.

Symptômes :

• Logs de démarrage affichant : fastify-plugin: @fastify/multipart - expected '5.x' fastify version, '4.29.1' is installed.
• Le bot WhatsApp ne répondait plus aux interactions utilisateurs (boutons "Continuer" ou "Répondre").
• Le Worker échouait localement à cause de variables d'environnement manquantes (ENCRYPTION_SECRET).

---

2. Analyse de la Cause Racine

Conflit d'Écosystème (Fastify v4 vs v5)

Le projet utilisait initialement Fastify v4.29.1. Cependant, plusieurs plugins avaient été mis à jour vers leurs versions les plus récentes (v9+, v11+), qui font partie de l'écosystème Fastify v5. Fastify v5 a introduit des changements majeurs, et ses plugins associés refusent de s'enregistrer sur une instance Fastify v4 par mesure de sécurité (vérification stricte via fastify-plugin).

Dépendances Invisibles

Le plugin @fastify/view était tiré indirectement par @bull-board/fastify dans sa version 11 (v5 ecosystem), créant un blocage même s'il n'était pas explicitement déclaré dans le package.json de l'API.

---

3. Actions Correctives Entreprises

A. Harmonisation des Dépendances (Downgrade)

Nous avons choisi de stabiliser le projet sur la version 4.x de Fastify pour éviter une migration complexe et risquée de toute l'API vers la v5. Les paquets suivants ont été rétrogradés dans apps/api/package.json :

• fastify : ^4.29.1
• @fastify/multipart : ^8.3.0
• @fastify/cors : ^8.3.0
• @fastify/jwt : ^8.0.1
• @fastify/rate-limit : ^9.1.0
• @fastify/static : ^7.0.4
• @fastify/view : ^8.2.0 (ajouté explicitement pour forcer la version compatible)

B. Correction de la Logique Métier (Fix #1)

Dans apps/whatsapp-worker/src/handlers/CommandHandler.ts, nous avons ajouté les gestionnaires manquants pour les actions de boutons :

• CONTINUE : Déclenche l'envoi de la suite du contenu du cours via la queue send-content.
• PROMPT : Envoie une invitation à répondre (support multilingue Français/Wolof).

C. Configuration de l'Environnement

• Ajout de ENCRYPTION_SECRET dans le fichier .env pour satisfaire les validations de schéma du Worker au démarrage.

D. Amélioration du Monitoring (Fix #10)

• Enregistrement de notificationQueue dans le tableau de bord BullBoard (apps/api/src/routes/internal.ts) pour permettre le suivi en temps réel de l'envoi des emails transactionnels.

E. Nettoyage Frontend (Fix #16)

• Correction des liens morts (#) dans le footer de la Web App (apps/web/src/App.tsx) pour pointer vers des destinations valides (/ et mailto:).

---

4. État de la Résolution & Validation

Validation Technique :

• Build local : pnpm turbo run build exécuté avec succès (8/8 packages).
• Installation : pnpm install a correctement mis à jour le pnpm-lock.yaml avec les versions v4.
• Monitoring : Les deux files d'attente (whatsappQueue et notificationQueue) sont désormais visibles.
• Déploiement : Push effectué sur GitHub et Hugging Face.

Conclusion :

Le problème est entièrement résolu. La structure actuelle garantit que tous les plugins utilisent des versions compatibles avec le noyau Fastify v4 présent dans l'environnement Hugging Face. L'interactivité du bot WhatsApp est rétablie grâce à l'intégration des handlers CONTINUE et PROMPT.

Pour toute future mise à jour de dépendances, veillez à ne pas utiliser pnpm update de manière globale, car cela pourrait tenter de repasser les plugins Fastify en version v5, recréant ainsi le conflit.