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.