# Audit de la Dette Technique v2.0 - Plateforme EdTech (XAMLÉ)

Cet audit fait suite au grand refactoring (Phases 1-3) et à la migration SQL. La base est désormais saine, mais de nouveaux défis "Product-Ready" émergent.

---

## 1. Score État de Santé (Post-Refactoring)
- **Typage (TS)** : 🟢 **85%** (Strict activé, builds validés).
- **Architecture Frontend** : 🟢 **90%** (Modulaire, Vite).
- **Observabilité** : 🟡 **70%** (Pino injecté, mais manque de centralisation/Sentry).
- **Persistence** : 🟢 **95%** (SQL pur, Cascade Delete activé).

---

## 2. Défis de Conception Majeurs (Nouvelle Priorité)

### A. Logicielle : Le "God Object" WhatsAppLogic
Le fichier [whatsapp-logic.ts](file:///Volumes/sms/Edtech/apps/whatsapp-worker/src/services/whatsapp-logic.ts) (422 lignes) gère trop de responsabilités :
- Routing des commandes (INSCRIPTION, SEED, SUITE...).
- Gestion du Time-Travel.
- Logique de Branchement (Langue, Secteur).
- Analyse Pédagogique.
- Interaction Multi-modale.
> [!WARNING]
> **Risque de Régression** : Chaque modification d'un mot-clé peut casser tout le flux.
> **Solution** : Migrer vers un **Command Pattern** (un fichier par intention : `InscribeCommand`, `SuiteCommand`, `ImageAnalysisHandler`).

### B. AI Service : Centralisation vs Spécialisation
Le service [ai/index.ts](file:///Volumes/sms/Edtech/apps/api/src/services/ai/index.ts) (556 lignes) est devenu le point de passage de tout le savoir métier :
- Prompts "Feedback" (très complexes).
- Prompts "One-Pager" et "PitchDeck".
- Prompts "Lesson Personalization".
> [!IMPORTANT]
> **Dette de Prompting** : Les prompts sont codés en dur dans le TypeScript. Toute modification de "ton" ou de "règle" nécessite un déploiement complet.
> **Solution** : Extraire les prompts dans des fichiers Markdown ou un Prompt CMS (type LangSmith/Weights & Biases).

### C. Gestion des Médias & Stockage
Le système télécharge les audios et images localement dans un dossier temporaire avant de les transformer.
- **Dette** : Pas de mécanisme de nettoyage automatique (Garbage Collection) des fichiers téléchargés.
- **Risque** : Saturation du disque sur le serveur API/Worker (plusieurs Go de voix par jour).
- **Solution** : Utiliser un stockage objet (S3/Azure Blob) avec TTL de 7 jours.

---

## 3. Revue de Securité & Infrastructure

### D. Authentification & API Keys
L'API utilise une `ADMIN_API_KEY` globale passée en en-tête.
- **Dette** : Pas de gestion d'utilisateurs Admin individuels (RBAC). On ne sait pas qui (quel admin) a envoyé un message manuel ou modifié un parcours.
- **Solution** : Implémenter une authentification JWT/OIDC pour les admins.

### E. Circuit de Time-Travel
Le Time-Travel repose sur une clé `Redis` avec un TTL.
- **Dette** : Si Redis est indisponible, l'utilisateur est bloqué ou fait l'exercice du jour réel sans prévenir.
- **Solution** : Un fallback permettant de lire le "Context" directement dans la table `Message` via un scan rapide si Redis échoue.

---

## 4. Plan de Remédiation Prioritaire (Phase 4)

1. **[ORCHESTRATION]** Refactoring de `whatsapp-logic.ts` en Handlers modulaires.
2. **[PROMPTS]** Isolation des prompts dans un dossier `packages/prompts` pour versionnage distinct.
3. **[STORAGE]** Mise en place d'un Garbage Collector pour les médias temporaires.
4. **[QUALITY]** Introduction de **Tests de Régression AI** (Vérifier que le coach ne devient pas "méchant" ou "incompréhensible" après un changement de prompt).

---
**Lead Fullstack Architect**  
*Date : 7 Avril 2026*