| # 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 : |
| - [x] **Build local** : `pnpm turbo run build` exécuté avec succès (8/8 packages). |
| - [x] **Installation** : `pnpm install` a correctement mis à jour le `pnpm-lock.yaml` avec les versions v4. |
| - [x] **Monitoring** : Les deux files d'attente (`whatsappQueue` et `notificationQueue`) sont désormais visibles. |
| - [x] **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`. |
|
|
| > [!TIP] |
| > 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. |
|
|
