docs: Add detailed audio pipeline investigation report

docs/audio_pipeline_investigation.md

@@ -0,0 +1,140 @@
+# Rapport d'Audit & Investigation Pipeline Audio (WhatsApp STT/TTS)
+
+## 📌 Contexte de l'Architecture
+
+Le système (EdTech) repose sur une architecture distribuée gérant les webhooks WhatsApp :
+1.  **HuggingFace Space (`safetrack-edtech`)** : Agit comme une passerelle publique pour recevoir les événements de l'API Meta WhatsApp Cloud. Il filtre et enfile les requêtes dans une file de messages (BullMQ / Redis).
+2.  **Railway / Vercel (`whatsapp-worker-production...`)** : Héberge le véritable moteur applicatif. Il contient un serveur API Fastify (`apps/api`) et un Worker (`apps/whatsapp-worker`) qui consomme les queues BullMQ pour le routage des messages, la sauvegarde DB, et les appels aux services IA (via `apps/api/src/services/ai`).
+3.  **Fournisseurs Tiers** :
+    *   **OpenAI** : `gpt-4o-mini` (Génération/Feedback), `whisper-1` (STT Inbound), `tts-1` (TTS Outbound).
+    *   **Cloudflare R2** : Stockage tampon des objets audios (Bucket S3 API).
+    *   **WhatsApp Graph API** : Pour les webhooks et l'envoi (`sendAudioMessage`, `sendTextMessage`).
+
+---
+
+## 🛑 Problèmes Initiaux Identifiés & Causes Réelles (Avant Patch)
+
+### 1. Rejet Silentieux de l'Audio Entrant (STT/Whisper)
+*   **Symptôme** : L'utilisateur envoie une note vocale. Le bot répond le fallback : *"Je n'ai pas pu lire l'audio. Envoie ta réponse en texte !"* ou affiche le log `Job completed!` sans retranscrire.
+*   **Cause structurelle (Format)** : WhatsApp compresse ses notes vocales natives en conteneurs `OGG` encodés en `OPUS` (`audio/ogg; codecs=opus`). L'API Whisper d'OpenAI est extrêmement capricieuse avec les headers de fichiers `OGG` provenant des serveurs Meta. Sans un transcodage propre, la requête part mais OpenAI rejette le blob silencieusement ou le traite de travers.
+*   **Cause Config** : Si l'API Key OpenAI manquait *du côté Railway*, ou si la connexion au S3 R2 échouait `(Missing R2 Credentials)`, le worker de téléchargement attrapait l'erreur et interrompait le flux d'analyse AI de la réponse.
+
+### 2. Plantage des Fetch (AI_API_BASE_URL sans Schéma)
+*   **Symptôme** : Logs crachant `Failed to parse URL ... input: 'whatsapp-worker-production-0bc0.up.railway.app/v1/ai/tts'`
+*   **Cause** : La variable d'environnement `API_URL` (ou `AI_API_BASE_URL`) fournie dans le dashboard d'hébergement omettait le préfixe HTTPS. La fonction `fetch` de Node.js lève une exception TypeError immédiate lorsqu'on tente une requête HTTP sans schéma valide (`http://` ou `https://`). Ceci crashait *tous* les workers qui tentaient d'appeler localement le module AI (TTS, Personalize, Transcribe).
+
+### 3. Audio Sortant (TTS) Invisible
+*   **Symptôme** : Les logs affichent `[PEDAGOGY] Generating TTS Audio...` et `[TTS] Audio generated`, mais WhatsApp n'envoie aucun message vocal natif `[🎙️]`.
+*   **Cause** :
+    *   L'appel à `sendAudioMessage(phone, url)` exige une URL directe publique (Cloudflare R2) téléchargeable par les serveurs proxy de Meta, avec un `Content-Type` valide (`audio/mpeg`). Si R2 configurait un accès privé, ou si l'API TTS d'OpenAI plantait en arrière-plan à cause de l'erreur d'URL évoquée au point 2, la variable `audioUrl` restait vide. Le Worker traitait un string vide, donc `sendAudioMessage` ne partait pas.
+
+---
+
+## 🛠️ Fichiers Impactés & Solutions Implémentées
+
+Afin qu'un développeur expert puisse tracer ou étendre la solution, voici les modifications fondamentales apportées.
+
+### A) Rigidité de l'URL Applicative (`apps/whatsapp-worker/src/config.ts`)
+On interdit purement et simplement le lancement de l'application si l'URL IA est mal formée, et on auto-corrige les erreurs de saisie courantes.
+
+```typescript
+// Extrait de apps/whatsapp-worker/src/config.ts
+export function requireHttpUrl(url: string | undefined, keyName: string): string {
+    if (!url) throw new Error(`[CONFIG] Missing environment variable: ${keyName}`);
+    let normalized = url.trim();
+    // Auto-prefix with https://
+    if (!normalized.startsWith('http')) {
+        normalized = `https://${normalized}`;
+        console.warn(`[CONFIG] Warning: Auto-prefixed ${keyName} with https://`);
+    }
+    // Formellement interdire HTTP en production
+    if (normalized.startsWith('http://') && !normalized.includes('localhost')) {
+         throw new Error(`[CONFIG] ❌ CRITICAL: ${keyName} MUST use https:// (got ${normalized})`);
+    }
+    return normalized.replace(/\/$/, ""); // Supression des trailing slashes
+}
+```
+
+### B) FFMPEG Middleware pour l'Audio Entrant (`apps/api/src/services/ai/ffmpeg.ts` & `nixpacks.toml`)
+Pour contrer le rejet OPUS/OGG de WhatsApp par Whisper, un adaptateur qui intercepte le buffer, écrit un fichier temp `/tmp`, compile avec FFmpeg (`1 channel`, `64k`), et renvoie le buffer MP3.
+
+```toml
+# Extrait de nixpacks.toml (Déclaration dépendance serveur)
+providers = ["node"]
+
+[phases.setup]
+nixPkgs = ["...", "ffmpeg"]
+```
+
+```typescript
+// Extrait de apps/api/src/services/ai/ffmpeg.ts
+export async function convertToMp3IfNeeded(inputBuffer: Buffer, filename: string) {
+    if (!filename.toLowerCase().endsWith('.ogg') && !filename.toLowerCase().endsWith('.opus')) {
+        return { buffer: inputBuffer, format: filename.split('.').pop()! }; 
+    }
+    // ...
+    // Exécution de sous-processus FFMPEG robuste pour transformer l'OGG en MP3 propre
+    await execAsync(`ffmpeg -y -i "${inputPath}" -vn -ar 44100 -ac 1 -b:a 64k "${outputPath}"`);
+    const mp3Buffer = await readFile(outputPath);
+    // ...
+}
+```
+
+### C) Workflow "Inbound Audio" Tracé (`apps/whatsapp-worker/src/index.ts`)
+Le Worker logge méticuleusement la réception du Payload Meta, la conversion, et le ping OpenAI STT pour ne plus *jamais* silencier une panne.
+
+```typescript
+// Extrait de index.ts (Worker BullMQ - job 'download-media')
+const { buffer } = await downloadMedia(mediaId, accessToken);
+console.log(`[MEDIA] downloaded file size=${buffer.length} contentType=${mimeType}`);
+
+// Envoi asynchrone pour la Transcription + FFMPEG
+console.log(`[STT] transcribe start calling ${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/transcribe`);
+const transcribeRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/transcribe`, {
+    method: 'POST',
+    body: JSON.stringify({ audioBase64: buffer.toString('base64'), filename: `msg.ogg` })
+    // -> Cet appel intercepte l'audio avec ffmpeg.ts avant de l'envoyer à Whisper
+});
+
+// Réponse UX
+console.log(`[STT] transcribe result="${transcribedText.substring(0, 80)}"`);
+const confirmationText = `J'ai compris :\n"${transcribedText}"`;
+await sendTextMessage(phone, confirmationText);
+```
+
+### D) Workflow "Outbound Audio" (`apps/whatsapp-worker/src/pedagogy.ts`)
+On requiert l'audio (TTS), on log l'URL R2 générée, et on *protège* l'envoi. Si Meta rejette l'envoi de l'audio `type: 'audio'`, un bloc `catch` permet un Fallback élégant en envoyant quand même le cours en texte.
+
+```typescript
+// Extrait de pedagogy.ts (Génération & Envoi de la leçon/Exercice)
+const AI_API_BASE_URL = requireHttpUrl(process.env.AI_API_BASE_URL, 'AI_API_BASE_URL');
+const ttsRes = await fetch(`${AI_API_BASE_URL.replace(/\/$/, "")}/v1/ai/tts`, { ... });
+
+if (finalAudioUrl) {
+    try {
+        console.log(`[TTS] audioUrl=${finalAudioUrl} sending to WhatsApp...`);
+        // WhatsApp API exigeant un lien HTTP direct pour le Content-Type: audio
+        await sendAudioMessage(user.phone, finalAudioUrl);
+        console.log(`[WhatsApp] ✅ Audio message sent to ${user.phone}`);
+    } catch (err) {
+         console.error(`[PEDAGOGY] Failed to send native audio, falling back to text. Error:`, err);
+         await sendTextMessage(user.phone, lessonText); // Ne jamais bloquer l'étudiant
+    }
+}
+```
+
+---
+
+## 🔎 Guide de Dépannage pour Développeur (Si l'audio bloque encore)
+
+Si l'audio ne fonctionne toujours pas après avoir vérifié que le code ci-dessus est déployé sur `main` :
+
+1.  **Vérifier le `[CONFIG] AI_API_BASE_URL effective: ...` au démarrage du Worker.**
+    *   S'il y a un warning HTTP, corrigez l'environnement sur Railway.
+2.  **L'audio STT plante silencieusement sans logs ?**
+    *   L'erreur vient de `nixpacks.toml` : le serveur (Railway/Vercel) n'a pas pris en compte l'installation asynchrone de `ffmpeg`. Regardez dans les logs de **Build / Deploy** si `ffmpeg` est bien `apt-get install`. S'il manque, le wrapper `ffmpeg.ts` échouera et enverra le `.ogg` corrompu à Whisper.
+3.  **L'audio TTS ne part pas côté WhatsApp ?**
+    *   Vérifiez le cloudflare R2 Bucket. Cliquez sur l'URL `[TTS] audioUrl=https://pub-xxx.r2.dev/fichier.mp3` générée.
+    *   Si le navigateur dit "Access Denied" (403), c'est que le bucket `R2_PUBLIC_URL` n'est pas configuré en accès `Public Routing` chez Cloudflare. WhatsApp ne peut pas télécharger et jouer de fichiers protégés derrière une permission Auth (S3).
+4.  **L'erreur 429 Quota ?**
+    *   Regardez les logs : `[WORKER] 429 Error during generate-feedback`. C'est l'API OpenAI qui est à sec (Limites de taux Free Tier ou facturation bloquée). Heureusement, le fallback affichera le mode texte grâce au bloc try/catch résilient ajouté.