docs/technical_debt_audit_08052026.md

Audit de la Dette Technique - Xamlé Studio (Mai 2026)

Ce document dresse un état des lieux de la dette technique accumulée sur la plateforme et propose des axes d'amélioration prioritaires pour garantir la scalabilité et la maintenabilité du système.

📊 Résumé de l'État Actuel

Domaine	État	Priorité
Architecture Frontend	🟠 Moyen (Standardisation Admin en cours)	Élevée
Architecture Backend	🟡 Correct (Standardisation API nécessaire)	Moyenne
Intégrité des Données	🟢 Bon (Schéma Prisma robuste)	Faible
Tests & QA	🔴 Critique (Quasiment inexistant)	Maximale
DevOps & CI/CD	🟠 Moyen (Manque de staging/prod clair)	Moyenne

---

1. Architecture Frontend & Communication API

🛠️ Points de Dette

• Fragmentation des Clients API : L'application admin utilise désormais un client api.ts standardisé, mais l'application web (portail étudiant) utilise toujours des appels fetch() manuels dispersés dans App.tsx.
• Typage Faible (any) : Trop de réponses API sont typées en any dans le frontend, ce qui annule les bénéfices de TypeScript et augmente les risques de régressions lors des changements de schéma backend.
• Gestion Multipart/Upload : Les uploads de fichiers (contacts, KB) utilisent encore des fetch() manuels avec l'utilitaire ah, au lieu d'être intégrés proprement dans le client api (ex: api.postMultipart).

💡 Recommandations

• Mutualiser le client api.ts dans un package shared pour qu'il soit utilisé par toutes les applications frontend.
• Implémenter des interfaces de réponse Zod ou TypeScript pour chaque endpoint.

---

2. Architecture Backend & Worker

🛠️ Points de Dette

• Incohérence des Requêtes Sortantes : Le whatsapp-worker et certains services API utilisent fetch ou axios de manière ad-hoc. Un utilitaire HTTP partagé avec logging intégré et gestion des retries (backoff exponentiel) est manquant.
• Monolithisation des Routes : Le fichier index.ts de l'API commence à accumuler beaucoup de logique de middleware.
• Gestion des Secrets : Bien que le middleware injectTenantConfig ait été ajouté, il existe encore des services qui effectuent des decryptSecrets manuels de manière redondante.

💡 Recommandations

• Extraire la logique de communication WhatsApp dans un package dédié ou un service HTTP unifié.
• Finaliser la migration vers le middleware pour toute résolution de configuration d'organisation.

---

3. Données & Schéma Prisma

🛠️ Points de Dette

• Modèle Message Hybride : Le modèle Message supporte à la fois userId (EdTech) et contactId (CRM). Bien que fonctionnel, cela crée une ambiguïté sur la source de vérité pour le tracking conversationnel.
• Dépendance Vectorielle : L'utilisation de Unsupported("vector") lie directement le projet à l'extension pgvector de Postgres, ce qui peut compliquer les migrations vers certains services managés sans support natif.

💡 Recommandations

• Évaluer une séparation plus nette ou une polymorphisation des relations pour les messages.
• Prévoir une couche d'abstraction pour la recherche vectorielle (Vector Store).

---

4. Tests, Qualité & DevOps

🛠️ Points de Dette

• Absence de Tests Automatisés : Il n'y a pas de suite de tests (Unitaires, E2E) visible. Les changements sont validés manuellement, ce qui est risqué pour une application multi-tenant.
• Conflits de Verrouillage de Paquets : Présence simultanée de package-lock.json et pnpm-lock.yaml. Cela peut causer des versions de dépendances divergentes entre les environnements de développement et de CI.
• Pipeline CI/CD : Manque d'automatisation pour le linting, le typage et le déploiement sur des environnements de staging isolés.

💡 Recommandations

• Supprimer le package-lock.json et forcer l'usage exclusif de pnpm.
• Mettre en place un framework de test (ex: Vitest pour le backend, Playwright pour le frontend).
• Configurer des GitHub Actions pour valider les PR.

---

📅 Plan d'Action Prioritaire (Sprint de Stabilisation)

1. Phase 1 (Urgent) : Supprimer package-lock.json, unifier sur pnpm et ajouter un premier test d'intégration sur l'API de base.
2. Phase 2 : Migrer l'application web vers le client API standardisé.
3. Phase 3 : Centraliser les appels WhatsApp sortants du worker vers un utilitaire HTTP robuste.