Hugging Face's logo

Spaces:
safetrack
/
edtech
Running

App Files Community
edtech / docs /technical_debt_audit_v2.md
CognxSafeTrack
chore: finalize Sprint P2 & P3 optimizations, baseline prisma migrations, and update technical audit docs
cfbb685
preview code
|
raw
history blame contribute delete
3.57 kB

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 (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.

    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 (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".

    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