docs/business/backlog.md

# 📋 Backlog XAMLÉ — État complet au 2026-05-12

Audit exhaustif de ce qui est **implémenté**, **incomplet**, ou **manquant**.
Toutes les sections "À faire" sont classées par priorité business.

---

## ✅ CE QUI EST ENTIÈREMENT IMPLÉMENTÉ

### Infrastructure & Core
- Architecture async-first (réponse 200 OK immédiate, BullMQ)
- Multi-tenancy Prisma via AsyncLocalStorage
- JWT + API Key auth, org isolation middleware
- Encryption/décryption des secrets org (clés API, tokens)
- Rate limiting, CORS, error handler global
- Logs structurés (Pino + Logtail), Sentry
- Redis locks idempotence (300s) sur tous les jobs LLM

### Worker — Handlers (20/20 opérationnels)
- OnboardingHandler — langue, secteur, activité, flow config
- ExerciseHandler — évaluation + grading IA
- FeedbackHandler — feedback IA + deep-dive + tracking usage ✅
- MediaHandler — transcription Whisper + vision Base64 + tracking audio ✅
- MessageHandler — envoi texte/boutons/listes + tracking WA ✅
- ContentHandler — envoi contenu jour
- NavigationHandler — navigation jours/leçons
- CommandHandler — SEED, MENU_HISTORIQUE, DAY_X
- BroadcastHandler — diffusion campagnes
- CampaignHandler — traitement campagnes
- AIAgentHandler — mode agent IA (RAG + KB)
- NudgeHandler — relances planifiées
- AdminHandler — override audio admin
- EnrollHandler — enrollment utilisateur
- KBProcessor — indexation knowledge base
- WebhookHandler — forward webhook avec retries
- DirectMessageHandler — message direct
- EmailHandler — welcome(1), reset pwd(2), alerte quota(3), rapport mensuel(4) ✅

### API Routes (12/12 implémentées)
- Auth, Admin, Organizations, AI, Analytics, Billing, Campaigns, Notifications, Payments, Student, WhatsApp, Internal

### Admin UI (21/21 pages fonctionnelles)
- Dashboard, Analytics, Conversations (CRM + EdTech), Contacts, Content (tracks/jours), LiveFeed, TrainingLab, KnowledgeBase, CampaignHistory, Templates, AIAgentSetup, ClientsManagement, Billing, Settings, Users, Onboarding, ResetPassword

### Système de Facturation (terminé session actuelle)
- Migration Gemini 2.0 Flash → 2.5 Flash
- Modèles DB : `UsageEvent`, `SubscriptionPlan`, compteurs `aiCreditsUsed`/`whatsappMessagesSent`
- Capture tokens réels : OpenAI (`completion.usage`) + Gemini (`usageMetadata`)
- `usage-tracker.ts` fire-and-forget (ne bloque jamais le flux pédagogique)
- Routes API : `/v1/billing/summary`, `/history`, `/breakdown`, `/chat`
- BillingPage UI : carte crédits IA + barre de progression, carte WhatsApp, graphe 30j, répartition features, chat IA facturation
- Plan gating : clés API propres verrouillées STARTER/GROWTH, actives SCALE/ENTERPRISE
- Sélecteur plan dans ClientsManagementView (super-admin)
- Guard backend : `PUT /v1/organizations/:id` rejette clés API si plan < SCALE

### Paiements
- Orange Money : initiation + webhook de confirmation
- Wave : initiation session checkout + webhook
- Auto-enrollment après paiement réussi

---

## ✅ PRIORITÉ HAUTE — Tous les items critiques fermés

### 1. ~~Usage tracking incomplet~~ — ✅ DONE
`pedagogy.ts` + `ai-pedagogy.ts` + `InboundHandler.ts` audio — tracking complet via fire-and-forget `trackAiUsage` / `trackAudioUsage`.

### 2. ~~Clé `nav.billing` manquante dans i18n~~ — ✅ DONE
Ajouté dans fr/en/es/pt. `MainLayout.tsx` utilise `t('nav.billing')`.

### 3. ~~BillingPage spinner infini sans orgId~~ — ✅ DONE
Guard `if (!orgId)` affiche un message "Sélectionnez une organisation".

### 4. ~~EmailHandler stub~~ — ✅ DONE
`EmailService` : templates 1 (welcome), 2 (reset pwd), 3 (alerte quota), 4 (rapport mensuel). `EmailHandler.ts` : switch complet sur les 4 cas.

### 5. ~~Alerte email quota IA~~ — ✅ DONE
`maybeQueueQuotaAlert()` dans `usage-tracker.ts` — détecte le crossing 85% de manière atomique via la valeur retournée par `prisma.organization.update`, sans champ DB supplémentaire.

---

## 🟡 PRIORITÉ MOYENNE — État

### 6. ~~Push Notifications — envoi non implémenté~~ — ✅ DONE
- `apps/whatsapp-worker/src/services/push.ts` — `sendPushToUser` + `sendPushToOrganization` via `web-push`
- `apps/whatsapp-worker/src/handlers/PushHandler.ts` — handler `send-push` dans `notification-queue`
- `apps/api/src/services/push.ts` — `sendToUser()` ajouté
- `apps/api/src/routes/notifications.ts` — `POST /v1/notifications/push`
- `usage-tracker.ts` — quota alert enqueue `send-push` en plus du `send-email`

---

### 7. Paiements — credentials non configurés en production
**Situation** : Le code Orange Money + Wave est complet. Les variables d'env sont commentées dans `.env.example`.

**Ce qu'il faut faire** :
- Obtenir les credentials Orange Money (API Key + Merchant ID) et les ajouter sur Railway
- Obtenir le WAVE_API_KEY et l'ajouter sur Railway
- Tester le flow complet (initiation → webhook → enrollment)
- Variables : `ORANGE_MONEY_API_KEY`, `ORANGE_MONEY_MERCHANT_ID`, `WAVE_API_KEY`

---

### 8. ~~Page Facturation — aucun bouton "Recharger les crédits"~~ — ✅ DONE
Bouton "Recharger" dans le header + modale avec 3 packs (500 / 2 000 / 5 000 crédits → contact WhatsApp). L'alerte rouge quota > 85% est désormais cliquable et ouvre la même modale.

---

### 9. ~~BillingPage inaccessible sans `selectedOrgId`~~ — ✅ DONE
Guard `if (!orgId)` en place, affiche "Sélectionnez une organisation pour voir la facturation."

---

### 10. docker-compose.yml incomplet pour le dev local
**Situation** : Le `docker-compose.yml` ne contient que Postgres et Redis. Pour lancer l'ensemble du stack en local, il faut démarrer manuellement l'API et le worker.

**Ce qu'il faut faire** :
- Ajouter les services `api` et `whatsapp-worker` dans `docker-compose.yml`
- Ajouter un service `admin` (optionnel, pour demo)
- Documenter la commande `docker-compose up --build` dans le README

---

### 11. Tests — couverture critique
**Situation actuelle** : 7 fichiers de test pour ~10 000+ lignes de code de production.

**Déjà écrits** :
- ✅ `test/billing.test.ts` — 10 tests (summary, plan guard, quota threshold, history grouping)
- ✅ `test/payments.test.ts` — 13 tests (webhook Wave + OM, state machine, auto-enrollment, provider validation)

**Flows encore sans tests** :
- Campaigns routes (création, broadcast)
- Analytics routes
- Admin routes (stats, users, enrollments)
- Notification routes
- WhatsApp worker dispatcher (inbound/media routing)
- FeedbackHandler + MediaHandler (les plus critiques pédagogiquement)

---

## 🟢 PRIORITÉ BASSE — Nice to have

### 12. Rapport mensuel automatique
Envoyer un email récapitulatif en fin de mois (coût total, features les plus utilisées, crédits restants) à l'admin de chaque org.

### 13. Export CSV de l'historique facturation
Permettre depuis la BillingPage de télécharger l'historique des UsageEvents en CSV pour comptabilité.

### 14. Webhook de facturation sortant
Permettre aux clients SCALE/ENTERPRISE de recevoir un webhook sur leur endpoint quand leur quota dépasse 80%.

### 15. Dashboard super-admin agrégé
Vue globale de toutes les orgs : revenus totaux, crédits consommés par org, les 3 plus gros consommateurs. Actuellement chaque org est vue séparément.

### 16. Branding non utilisé dans Settings
Les champs `brandingData.logoUrl` et `brandingData.primaryColor` sont dans le schéma et dans i18n (`settings.branding`, `settings.logo_url`) mais le formulaire Settings ne les expose pas encore.

---

## 📊 TABLEAU DE SYNTHÈSE

| Domaine | Complet | En cours | Manquant |
|---------|---------|----------|----------|
| API Routes (12) | 12/12 | — | — |
| Admin Pages (21) | 21/21 | — | — |
| Worker Handlers (20) | ✅ 20/20 | — | — |
| Usage Tracking | ✅ 7/7 handlers | — | — |
| Système facturation | ✅ complet | — | — |
| Paiements (code) | ✅ complet | — | Credentials prod manquants |
| i18n | ✅ 100% | — | — |
| Push Notifications | ✅ Subscribe + Send | — | — |
| Tests | 7 fichiers | — | Campaigns, handlers, analytics |
| Docker dev | DB+Redis ✅ | — | API + Worker |

---

## 🔢 ORDRE D'EXÉCUTION RECOMMANDÉ

```
✅ 1. Usage tracking — pedagogy.ts + InboundHandler + BroadcastHandler
✅ 2. i18n nav.billing dans les 4 locales + MainLayout
✅ 3. BillingPage guard orgId null
✅ 4. EmailHandler templates 2/3/4 + alerte quota > 85%
✅ 5. Tests billing.test.ts (10 tests) + payments.test.ts (13 tests)
✅ 6. Push notifications — PushHandler + send-push job + quota alert push
✅ 7. BillingPage — modal recharge crédits (3 packs → WhatsApp contact)
   8. Payment credentials Railway                       [external — ops]
```

**Tous les gaps dev fermés.** Reste uniquement la configuration des credentials de paiement en production (action externe).