CognxSafeTrack
chore: finalize Sprint P2 & P3 optimizations, baseline prisma migrations, and update technical audit docs
cfbb685 | # 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* | |