docs/technical_debt_audit.md

Audit de la Dette Technique — Infrastructure PaaS (v3.0)

Dernière Mise à Jour : 25 Avril 2026 Statut global : 🏗️ Transition PaaS (Architecture Stable, Optimisations Requises)

🚦 Résumé des Risques Actuels

Priorité	Sujet	État	Impact
🔴 Critique	Performance du Bridge (Requêtes Prisma)	⚠️ À RISQUE	Latence accrue à chaque message reçu
🟠 Haute	Duplication d'Extraction WhatsApp	🔄 DUPLIQUÉ	Risque d'incohérence entre Gateway et Worker
🟠 Haute	Résilience des Webhooks Clients	❌ MANQUANT	Perte de messages si le client est offline
🟡 Moyenne	Validation JSON FlowConfig	✅ FIXED	Sécurisé côté API, à renforcer côté Worker
🟡 Moyenne	Gestion des Secrets (Shared Keys)	🔐 STATIQUE	Risque de compromission sur le long terme

---

1. Performance & Évolutivité (Scalability)

• Problème : Chaque message entrant dans le bridge du Worker (index.ts) déclenche une requête SQL synchrone pour récupérer le mode de l'organisation.
• Risque : Saturation de la pool de connexions Prisma lors de pics de trafic.
• Action requise : Implémenter un cache Redis pour les métadonnées des organisations (TTL: 1h).
• Statut : ⚠️ À surveiller.

2. Maintenabilité : Duplication de Logique

• Problème : La logique d'extraction du phone et du text depuis le payload Meta est copiée entre apps/api et apps/whatsapp-worker.
• Risque : Un changement dans l'API WhatsApp (ex: nouveau type de bouton) doit être reporté à deux endroits, multipliant les chances d'erreur.
• Action requise : Créer un helper extractWhatsAppPayload dans packages/shared-types ou un nouveau package @repo/whatsapp-utils.
• Statut : 🔄 Dette active.

3. Fiabilité des Webhooks (Phase 2)

• Problème : Le routage vers les clients externes en mode WEBHOOK utilise un simple fetch avec un log d'erreur en cas d'échec.
• Risque : Aucun mécanisme de retry (tentatives de renvoi). Si le serveur du client redémarre, le message est définitivement perdu.
• Action requise : Utiliser une file d'attente BullMQ dédiée (webhook-retry-queue) pour garantir la livraison avec exponential backoff.
• Statut : ❌ Manquant.

4. Intégrité des Données (Zod)

• Problème : Le Worker lit le champ flowConfig (JSON) et le parse sans re-validation.
• Risque : Si un administrateur injecte un JSON corrompu via un script direct (hors API), le Worker peut crasher en tentant de lire des propriétés inexistantes.
• Action effectuée : ✅ Validation Zod ajoutée sur la route PUT /organizations.
• Action restante : Re-valider le schéma lors de la lecture dans OnboardingHandler.ts.
• Statut : 🟡 Partiellement résolu.

5. Intelligence Artificielle (RAG)

• Problème : Le champ knowledgeBaseUrl n'est qu'un lien vers un fichier. L'AIAgentHandler simule l'injection.
• Risque : Pour des fichiers volumineux (> 10 pages), l'injection directe dans le prompt va exploser les limites de tokens et les coûts.
• Action requise : Implémenter une pipeline d'indexation vectorielle (Vector DB) pour les clients en mode AI_AGENT.
• Statut : 🏗️ En cours de conception.

---

📅 Historique des Corrections (v2.x)

• ✅ [FIXED] Sécurisation du bridge interne via ADMIN_API_KEY.
• ✅ [FIXED] Dé-hardcodage des secteurs EdTech.
• ✅ [FIXED] Isolation des tenants via runWithTenant (Context API).
• ✅ [FIXED] Centralisation des logs Pino.