# Plan d'implémentation — Admin UX/UI Non-Tech

**Créé le :** 2026-05-13  
**Objectif :** Rendre l'interface admin utilisable par des non-développeurs, en s'appuyant sur l'IA conversationnelle pour guider chaque action clé.

---

## Statut global

| Phase | Description | Statut |
|-------|-------------|--------|
| Phase 1 | Gains immédiats — corrections sans refonte | ✅ Terminé |
| Phase 2 | Chat IA global toutes les pages | ✅ Terminé |
| Phase 3 | Onboarding WhatsApp guidé | ✅ Terminé |
| Phase 4 | Templates assistés par IA | ✅ Terminé |
| Phase 5 | Agent IA — setup guidé | ✅ Terminé |

---

## Phase 1 — Gains immédiats (sans refonte)

> Objectif : corriger les points de friction les plus bloquants en touchant un minimum de code.

### 1.1 — Masquer Flow Config JSON (SettingsPage)
- **Fichier :** `apps/admin/src/pages/SettingsPage.tsx`
- **Action :** Enrober le textarea `flowConfig` dans un `<details>` collapsé par défaut avec le label "⚙️ Configuration avancée (développeurs)"
- **Statut :** ✅ Terminé

### 1.2 — Remplacer "X chunks" (AIAgentSetup)
- **Fichier :** `apps/admin/src/pages/AIAgentSetup.tsx`
- **Action :** Indicateur de couverture qualitative (Excellente/Bonne/Insuffisante) + texte humain "X passages analysés" + conseil si volume insuffisant
- **Statut :** ✅ Terminé

### 1.3 — Placeholder guidé pour le champ Rôle (AIAgentSetup)
- **Fichier :** `apps/admin/src/pages/AIAgentSetup.tsx`
- **Action :** Placeholder exemple concret + texte d'aide sous le champ
- **Statut :** ✅ Terminé

### 1.4 — Bloc d'aide contextuel — Connexion WhatsApp (OnboardingWizard)
- **Fichier :** `apps/admin/src/pages/OnboardingWizard.tsx`
- **Action :** `<details>` collapsable expliquant WABA ID, Business ID, Token système avec liens directs Meta + conseil de basculer vers Facebook Signup si nouveau
- **Statut :** ✅ Terminé

### 1.5 — Labels humains pour les clés API (SettingsPage)
- **Fichier :** `apps/admin/src/pages/SettingsPage.tsx`
- **Action :** Texte explicatif enrichi : état locked (ce que SCALE débloque) + état unlocked (clés chiffrées, impact sur les crédits)
- **Statut :** ✅ Terminé

---

## Phase 2 — Chat IA global (toutes les pages)

> Objectif : étendre le chat billing à toute l'interface, avec un contexte qui change selon la page.

### 2.1 — Extraire AdminChat en composant générique
- **Fichier :** `apps/admin/src/components/AdminChat.tsx` (nouveau)
- **Action :** Widget flottant (bouton 💬 + panneau) avec prop `page: AdminChatPage`, questions rapides contextuelles par page, reset automatique au changement de page
- **Statut :** ✅ Terminé

### 2.2 — Endpoint API contextualisé
- **Fichier :** `apps/api/src/routes/billing.ts`
- **Action :** Param `page` ajouté au body du POST `/chat`. Si `page === 'billing'` → contexte complet (wallet + usage). Sinon → contexte léger (org + mode + aide contextuelle par page : settings, templates, agent, onboarding)
- **Statut :** ✅ Terminé

### 2.3 — Intégrer AdminChat dans MainLayout
- **Fichier :** `apps/admin/src/components/layouts/MainLayout.tsx`
- **Action :** Hook `useAdminChatPage()` mappe la route courante vers la page de chat. Widget masqué sur `/billing` (qui a son propre chat inline). Affiché uniquement si une organisation est sélectionnée.
- **Statut :** ✅ Terminé

---

## Phase 3 — Onboarding WhatsApp guidé

> Objectif : zéro abandon sur l'étape de connexion WhatsApp.

### 3.1 — Stepper visuel dans l'étape WhatsApp
- **Fichier :** `apps/admin/src/pages/OnboardingWizard.tsx`
- **Action :** Badges numérotés ①②③ devant chaque champ (WABA ID → Business ID → Token) avec lien direct Meta pour chacun
- **Statut :** ✅ Terminé

### 3.2 — Validation token WhatsApp en temps réel
- **Fichiers :** `OnboardingWizard.tsx` + `apps/api/src/routes/organizations.ts`
- **Action :** Endpoint `POST /v1/organizations/whatsapp-validate-token` (ping `graph.facebook.com/me`). Feedback visuel sur le champ : `✓ vert` / `✗ rouge` / `… checking` + message explicatif sous le champ
- **Statut :** ✅ Terminé

### 3.3 — Détection d'expiration du token (SettingsPage)
- **Fichiers :** `SettingsPage.tsx` + `apps/api/src/routes/organizations.ts`
- **Action :** Endpoint `GET /v1/organizations/:id/whatsapp-status` (déchiffre le token + ping Meta). SettingsPage charge le statut au mount. Bannière rouge avec instructions si token invalide/expiré.
- **Statut :** ✅ Terminé

---

## Phase 4 — Création de templates assistée par IA

> Objectif : un non-tech peut créer un template WhatsApp correct du premier coup.

### 4.1 — Générateur de template via IA
- **Fichiers :** `TemplatesPage.tsx` + `apps/api/src/routes/billing.ts`
- **Action :** Endpoint `POST /v1/billing/template-generate` (gpt-4o-mini, response_format JSON). Dans la modal : champ description + bouton "Générer" → auto-remplit nom, corps, catégorie.
- **Statut :** ✅ Terminé

### 4.2 — Validation en temps réel des variables
- **Fichier :** `apps/admin/src/pages/TemplatesPage.tsx`
- **Action :** Regex `{{...}}` sur le body en temps réel. Badges colorés pour chaque variable : bleu si `{{1}}` (valide), amber si `{{texte}}` (invalide). Bouton Submit bloqué si variables invalides.
- **Statut :** ✅ Terminé

### 4.3 — Prévisualisation rendu WhatsApp
- **Fichier :** `apps/admin/src/pages/TemplatesPage.tsx`
- **Action :** Bulle WhatsApp (fond `#ECE5DD`, bulle blanche) avec `{{1}}` → exemples réels (Jean Dupont, 3 000 FCFA…). Apparaît dès que le corps n'est pas vide.
- **Statut :** ✅ Terminé

### 4.4 — Explication politique d'approbation Meta
- **Fichier :** `apps/admin/src/pages/TemplatesPage.tsx`
- **Action :** Texte contextuel sous le sélecteur Catégorie : Marketing → "24-48h, évitez les mots trop commerciaux" / Utilitaire → "approbation plus rapide, confirmations/rappels".
- **Statut :** ✅ Terminé

---

## Phase 5 — Agent IA — Setup guidé

> Objectif : configurer un agent opérationnel sans comprendre ce qu'est un LLM.

### 5.1 — Feedback post-upload enrichi
- **Fichier :** `apps/admin/src/pages/AIAgentSetup.tsx`
- **Action :** Après upload succès → card "✨ Que se passe-t-il maintenant ?" expliquant le délai d'indexing et invitant à tester dans le panneau de droite
- **Statut :** ✅ Terminé

### 5.2 — Suggestion de ton selon le secteur
- **Fichier :** `apps/admin/src/pages/AIAgentSetup.tsx`
- **Action :** Fetch org mode au chargement → pré-sélection automatique (EDTECH→Pédagogue, CRM→Amical, AI_AGENT→Professionnel, CUSTOMER_SERVICE→Direct). Badge `✦` sur le ton recommandé. Description contexuelle + "recommandé pour votre secteur" sous les boutons.
- **Statut :** ✅ Terminé

### 5.3 — Blocage activation si KB vide
- **Fichier :** `apps/admin/src/pages/AIAgentSetup.tsx`
- **Action :** Bannière amber en haut de page si KB vide + mode AI_AGENT. Bouton Save désactivé avec message explicatif.
- **Statut :** ✅ Terminé

### 5.4 — Test de l'agent en direct (chat preview)
- **Fichiers :** `AIAgentSetup.tsx` + `apps/api/src/routes/billing.ts`
- **Action :** Endpoint `POST /v1/billing/agent-test` (personalityConfig → system prompt → gpt-4o-mini). Panneau de droite remplacé par un chat interactif avec input + bulles. Indicateur de chargement animé.
- **Statut :** ✅ Terminé

---

## Ordre d'exécution recommandé

```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
```

Les phases 1 sont indépendantes et peuvent être faites en parallèle.  
Les phases 3–5 dépendent de la Phase 2 (AdminChat générique).

---

## Légende

| Symbole | Signification |
|---------|--------------|
| ✅ | Terminé |
| ⏳ | En cours |
| 🔲 | À faire |
| ❌ | Bloqué |