CognxSafeTrack commited on
Commit ·
7e22952
1
Parent(s): bc01171
docs(business): update economic model — wallet/ledger decision v2.0
Browse files- docs/business/MODELE-ECONOMIQUE.md +195 -220
docs/business/MODELE-ECONOMIQUE.md
CHANGED
|
@@ -1,289 +1,264 @@
|
|
| 1 |
-
# Modèle
|
| 2 |
|
| 3 |
-
**
|
| 4 |
-
**
|
| 5 |
|
| 6 |
---
|
| 7 |
|
| 8 |
-
##
|
| 9 |
|
| 10 |
-
|
| 11 |
-
|
| 12 |
-
|
| 13 |
-
|
| 14 |
-
|
| 15 |
-
|
| 16 |
-
|
| 17 |
-
### Les 4 types de conversations (tarifs différents)
|
| 18 |
-
|
| 19 |
-
| Type | Qui initie | Exemple concret | Tarif (Afrique) |
|
| 20 |
-
|------|-----------|-----------------|-----------------|
|
| 21 |
-
| **Service** | L'utilisateur envoie en premier | Élève envoie "inscription" | ~$0.013/conv |
|
| 22 |
-
| **Utility** | Le bot envoie en premier | Confirmation d'inscription | ~$0.020/conv |
|
| 23 |
-
| **Authentication** | Le bot envoie en premier | Code OTP | ~$0.020/conv |
|
| 24 |
-
| **Marketing** | Le bot envoie en premier | Campagne broadcast | ~$0.040/conv |
|
| 25 |
-
|
| 26 |
-
### Le quota gratuit
|
| 27 |
-
|
| 28 |
-
> **1 000 conversations Service gratuites par mois, par WABA.**
|
| 29 |
-
|
| 30 |
-
Pour XAMLÉ : quasiment tout le trafic est **Service** (l'élève envoie en premier). Jusqu'à 1 000 conversations/mois → **0 $ chez Meta**.
|
| 31 |
-
|
| 32 |
-
### Simulation coûts Meta pour un client typique
|
| 33 |
-
|
| 34 |
-
| Élèves actifs | Conv./mois | Gratuites | Payantes | Coût Meta |
|
| 35 |
-
|---------------|-----------|-----------|----------|-----------|
|
| 36 |
-
| 30 élèves | 900 | 900 | 0 | **0 $** |
|
| 37 |
-
| 50 élèves | 1 500 | 1 000 | 500 | **~6.50 $** |
|
| 38 |
-
| 150 élèves | 4 500 | 1 000 | 3 500 | **~45 $** |
|
| 39 |
-
| 300 élèves | 9 000 | 1 000 | 8 000 | **~104 $** |
|
| 40 |
-
| 500 élèves | 15 000 | 1 000 | 14 000 | **~182 $** |
|
| 41 |
-
|
| 42 |
-
> **Note importante :** Ces coûts sont payés **directement par le client à Meta** (Modèle A), ou par toi si tu gères le compte (Modèle B).
|
| 43 |
|
| 44 |
---
|
| 45 |
|
| 46 |
-
## PARTIE
|
| 47 |
-
|
| 48 |
-
### Infrastructure mensuelle actuelle
|
| 49 |
-
|
| 50 |
-
| Service | Usage | Coût estimé |
|
| 51 |
-
|---------|-------|------------|
|
| 52 |
-
| Railway | API + Worker (2 processus) | ~$20-35/mois |
|
| 53 |
-
| Neon PostgreSQL | Base de données | ~$19/mois |
|
| 54 |
-
| Hugging Face Space | Hébergement secondaire | ~$9/mois |
|
| 55 |
-
| Redis (inclus Railway) | Cache + BullMQ | $0 |
|
| 56 |
-
| Netlify | Admin dashboard | ~$0 (free tier) |
|
| 57 |
-
| **TOTAL FIXE** | | **~$48-63/mois** |
|
| 58 |
-
| | | **≈ 31 000-41 000 FCFA** |
|
| 59 |
|
| 60 |
-
###
|
| 61 |
-
|
| 62 |
-
C'est le seul coût qui **grandit avec le nombre d'élèves**. À chaque exercice soumis, ton système appelle GPT-4o ou Gemini pour évaluer la réponse.
|
| 63 |
-
|
| 64 |
-
**Coût IA par évaluation :**
|
| 65 |
```
|
| 66 |
-
|
| 67 |
-
Gemini Flash : ~$0.002-0.005 par évaluation (10x moins cher)
|
| 68 |
```
|
| 69 |
|
| 70 |
-
|
| 71 |
|
| 72 |
-
|
|
| 73 |
-
|----------
|
| 74 |
-
|
|
| 75 |
-
|
|
| 76 |
-
|
|
| 77 |
-
|
|
|
|
|
|
|
|
| 78 |
|
| 79 |
-
> **
|
|
|
|
| 80 |
|
| 81 |
---
|
| 82 |
|
| 83 |
-
## PARTIE
|
| 84 |
-
|
| 85 |
-
### Modèle A — SaaS Pur ✅ (ce que tu as aujourd'hui)
|
| 86 |
|
| 87 |
-
|
| 88 |
-
→ Meta facture **le client directement**.
|
| 89 |
-
→ Toi tu factures uniquement la **plateforme XAMLÉ**.
|
| 90 |
|
| 91 |
```
|
| 92 |
-
|
| 93 |
-
|
| 94 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 95 |
```
|
| 96 |
|
| 97 |
-
|
| 98 |
-
- Marge très élevée (85-92% à l'échelle)
|
| 99 |
-
- Aucun risque financier Meta pour toi
|
| 100 |
-
- Simple à expliquer et à vendre
|
| 101 |
-
|
| 102 |
-
**Inconvénients :**
|
| 103 |
-
- Le client doit créer et gérer son compte Meta
|
| 104 |
-
- Mauvaise surprise possible si le client ne comprend pas les coûts Meta
|
| 105 |
-
- Tu ne captures pas la marge Meta
|
| 106 |
-
|
| 107 |
-
---
|
| 108 |
-
|
| 109 |
-
### Modèle B — BSP (Business Solution Provider)
|
| 110 |
-
|
| 111 |
-
Tu gères **un seul compte Meta** et tu sous-loues l'accès à tes clients.
|
| 112 |
-
→ Tu paies Meta.
|
| 113 |
-
→ Tu factures tes clients Meta + ta marge.
|
| 114 |
|
| 115 |
```
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 119 |
```
|
| 120 |
|
| 121 |
-
**
|
| 122 |
-
- Revenu supplémentaire sur chaque conversation
|
| 123 |
-
- Expérience client plus simple (une seule facture)
|
| 124 |
-
- Contrôle total
|
| 125 |
-
|
| 126 |
-
**Inconvénients :**
|
| 127 |
-
- Tu portes le risque financier (tu paies Meta même si le client ne paie pas)
|
| 128 |
-
- Nécessite une certification BSP Meta pour faire ça officiellement à grande échelle
|
| 129 |
-
- Plus complexe à gérer
|
| 130 |
-
|
| 131 |
-
> **Recommandation :** Commencer par le Modèle A. Passer au Modèle B quand tu as 10+ clients et que les volumes justifient la complexité.
|
| 132 |
|
| 133 |
---
|
| 134 |
|
| 135 |
-
## PARTIE
|
|
|
|
|
|
|
|
|
|
| 136 |
|
| 137 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 138 |
|
| 139 |
-
|
| 140 |
|
| 141 |
-
|
|
| 142 |
-
|------|-----------|-----------|-----------|------|
|
| 143 |
-
|
|
| 144 |
-
|
|
| 145 |
-
|
|
|
|
|
| 146 |
|
| 147 |
-
|
| 148 |
-
✅ Prévisible pour le client
|
| 149 |
-
⚠️ Risque : gros clients avec beaucoup d'IA consomment tes crédits
|
| 150 |
|
| 151 |
---
|
| 152 |
|
| 153 |
-
##
|
| 154 |
-
|
| 155 |
-
Le client achète des crédits à l'avance. Chaque action consomme des crédits.
|
| 156 |
|
| 157 |
-
|
| 158 |
```
|
| 159 |
-
|
| 160 |
-
|
| 161 |
-
|
| 162 |
-
|
| 163 |
-
Envoi d'un broadcast = 5 crédits/destinataire
|
| 164 |
-
Jour de formation complet = 5 crédits/élève
|
| 165 |
-
|
| 166 |
-
Pack Démarrage : 5 000 crédits = 45 000 FCFA (marge ~55%)
|
| 167 |
-
Pack Standard : 15 000 crédits = 120 000 FCFA (marge ~60%)
|
| 168 |
-
Pack Pro : 50 000 crédits = 350 000 FCFA (marge ~65%)
|
| 169 |
```
|
| 170 |
|
| 171 |
-
|
| 172 |
-
|
| 173 |
-
|
| 174 |
-
|
| 175 |
-
|
| 176 |
-
|
| 177 |
-
|
| 178 |
-
|
| 179 |
|
| 180 |
-
|
| 181 |
|
|
|
|
| 182 |
```
|
| 183 |
-
|
| 184 |
-
|
| 185 |
-
|
|
|
|
| 186 |
```
|
| 187 |
|
| 188 |
-
✅ Entrée facile pour le client
|
| 189 |
-
✅ Capture la valeur des gros usages
|
| 190 |
-
⚠️ Facturation imprévisible pour le client
|
| 191 |
-
|
| 192 |
---
|
| 193 |
|
| 194 |
-
## PARTIE 5 —
|
| 195 |
-
|
| 196 |
-
###
|
| 197 |
-
|
| 198 |
-
|
| 199 |
-
|
| 200 |
-
|
|
| 201 |
-
|
|
| 202 |
-
|
|
| 203 |
-
|
|
| 204 |
-
|
|
| 205 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 206 |
|
| 207 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 208 |
|
| 209 |
---
|
| 210 |
|
| 211 |
-
## PARTIE 6 —
|
| 212 |
-
|
| 213 |
-
Actuellement : **"—"** dans Détails & Facturation.
|
| 214 |
-
|
| 215 |
-
Ce qu'on peut afficher si on intègre l'API Meta Analytics :
|
| 216 |
|
| 217 |
```
|
| 218 |
-
|
| 219 |
-
|
| 220 |
-
|
| 221 |
-
|
| 222 |
-
│
|
| 223 |
-
│
|
| 224 |
-
│
|
| 225 |
-
|
| 226 |
-
|
| 227 |
-
|
| 228 |
-
|
| 229 |
-
└──────────────────────────────────────────────────────┘
|
| 230 |
```
|
| 231 |
|
| 232 |
-
|
| 233 |
-
|
| 234 |
-
|
| 235 |
-
|
| 236 |
-
|
|
|
|
|
|
|
| 237 |
|
| 238 |
---
|
| 239 |
|
| 240 |
-
## PARTIE 7 —
|
| 241 |
-
|
| 242 |
-
Réponds à chacune pour qu'on sache exactement quoi construire :
|
| 243 |
|
| 244 |
-
###
|
| 245 |
-
|
| 246 |
-
|
| 247 |
-
|
| 248 |
|
| 249 |
-
###
|
| 250 |
-
|
| 251 |
-
|
| 252 |
-
|
| 253 |
-
|
|
|
|
|
|
|
| 254 |
|
| 255 |
-
###
|
| 256 |
-
|
| 257 |
-
|
| 258 |
-
|
| 259 |
-
- [ ] **XAMLÉ paie jusqu'à X élèves, clés client au-delà** (hybride)
|
| 260 |
|
| 261 |
-
###
|
| 262 |
-
|
| 263 |
-
|
| 264 |
-
|
| 265 |
-
|
| 266 |
-
### Q5 — Système de crédits interne
|
| 267 |
-
> Si tu choisis l'Option 2 (crédits), veux-tu un système de crédits dans la plateforme ?
|
| 268 |
-
- [ ] **Oui** (ledger en DB, déduction par action, dashboard solde)
|
| 269 |
-
- [ ] **Non** (facturation externe, Stripe ou manuel)
|
| 270 |
|
| 271 |
---
|
| 272 |
|
| 273 |
-
##
|
| 274 |
-
|
| 275 |
-
Si tu veux avancer vite avec le moins de risque :
|
| 276 |
-
|
| 277 |
-
```
|
| 278 |
-
✅ Modèle A (SaaS pur, client gère son Meta)
|
| 279 |
-
✅ Option 1 (Abonnement fixe, 3 tiers)
|
| 280 |
-
✅ IA : XAMLÉ paie jusqu'à 400 élèves, clés client au-delà
|
| 281 |
-
✅ Dashboard : stats internes d'abord, Meta Analytics en V2
|
| 282 |
-
✅ Pas de système de crédits pour l'instant
|
| 283 |
-
```
|
| 284 |
|
| 285 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 286 |
|
| 287 |
---
|
| 288 |
|
| 289 |
-
*
|
|
|
|
| 1 |
+
# Modèle Économique XAMLÉ — Décisions finales & Simulateur de rentabilité
|
| 2 |
|
| 3 |
+
**Version 2.0 — 2026-05-13**
|
| 4 |
+
**Statut : DÉCIDÉ — en attente de validation avant implémentation**
|
| 5 |
|
| 6 |
---
|
| 7 |
|
| 8 |
+
## DÉCISIONS PRISES
|
| 9 |
|
| 10 |
+
| Question | Décision |
|
| 11 |
+
|---|---|
|
| 12 |
+
| Modèle Meta | **BSP/Wallet interne** — XAMLÉ facture les conversations (client ne voit pas Meta) |
|
| 13 |
+
| Tarification | **Wallet prépayé** — crédits achetés à l'avance, déductés en temps réel |
|
| 14 |
+
| Coût IA | **BYOK ou crédits** — clé client → 0 crédit IA déduit ; clé XAMLÉ → crédits déduits |
|
| 15 |
+
| Dashboard | **Stats internes temps réel** — solde visible, consommation par action |
|
| 16 |
+
| Hard Stop | **Oui** — balance = 0 → tout s'arrête, message générique aux élèves |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 17 |
|
| 18 |
---
|
| 19 |
|
| 20 |
+
## PARTIE 1 — La table de conversion des crédits
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 21 |
|
| 22 |
+
### Unité de base
|
|
|
|
|
|
|
|
|
|
|
|
|
| 23 |
```
|
| 24 |
+
1 Crédit XAMLÉ = 10 FCFA
|
|
|
|
| 25 |
```
|
| 26 |
|
| 27 |
+
### Ce que coûte chaque action (notre coût réel vs. ce qu'on facture)
|
| 28 |
|
| 29 |
+
| Action | Coût réel XAMLÉ | Crédits facturés | Revenu FCFA | Marge brute |
|
| 30 |
+
|--------|----------------|-----------------|-------------|-------------|
|
| 31 |
+
| **Conversation WhatsApp Service** (élève écrit en premier) | ~7,8 FCFA ($0.013) | **1 crédit** = 10 FCFA | 10 FCFA | **22%** |
|
| 32 |
+
| **Conversation WhatsApp Marketing** (broadcast) | ~24 FCFA ($0.040) | **3 crédits** = 30 FCFA | 30 FCFA | **20%** |
|
| 33 |
+
| **Appel IA — Texte (Gemini Flash)** | ~2-3 FCFA ($0.003) | **3 crédits** = 30 FCFA | 30 FCFA | **90%** |
|
| 34 |
+
| **Appel IA — Texte (GPT-4o)** | ~18 FCFA ($0.030) | **3 crédits** = 30 FCFA | 30 FCFA | **40%** |
|
| 35 |
+
| **Transcription audio (Whisper)** | ~3 FCFA ($0.005) | **2 crédits** = 20 FCFA | 20 FCFA | **85%** |
|
| 36 |
+
| **Jour de formation complet** (leçon + feedback) | ~5-8 FCFA | **5 crédits** = 50 FCFA | 50 FCFA | **85%** |
|
| 37 |
|
| 38 |
+
> **Règle BYOK :** Si l'organisation a sa propre clé OpenAI ou Gemini → 0 crédit IA déduit.
|
| 39 |
+
> Seuls les crédits WhatsApp (conversations Meta) sont déduits dans tous les cas.
|
| 40 |
|
| 41 |
---
|
| 42 |
|
| 43 |
+
## PARTIE 2 — Ce que coûte un élève actif par mois
|
|
|
|
|
|
|
| 44 |
|
| 45 |
+
### Scénario sans BYOK (clé XAMLÉ — Gemini Flash)
|
|
|
|
|
|
|
| 46 |
|
| 47 |
```
|
| 48 |
+
Un élève actif sur 21 jours de formation :
|
| 49 |
+
- 21 jours × 1 conversation service = 21 crédits WhatsApp
|
| 50 |
+
- 21 jours × 1 appel IA leçon = 21 crédits IA
|
| 51 |
+
- 21 jours × 1 appel IA feedback = 21 crédits IA
|
| 52 |
+
─────────────────────────────────────────────────────
|
| 53 |
+
Total / élève / mois = 63 crédits = 630 FCFA
|
| 54 |
+
|
| 55 |
+
Coût réel XAMLÉ / élève :
|
| 56 |
+
- WhatsApp : 21 × 7,8 FCFA = 163 FCFA
|
| 57 |
+
- IA (Gemini) : 42 × 2,5 FCFA = 105 FCFA
|
| 58 |
+
─────────────────────────────────────────────────────
|
| 59 |
+
Coût réel = 268 FCFA
|
| 60 |
+
Revenu crédits = 630 FCFA
|
| 61 |
+
Marge par élève = 362 FCFA (57%)
|
| 62 |
```
|
| 63 |
|
| 64 |
+
### Scénario avec BYOK (clé client)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 65 |
|
| 66 |
```
|
| 67 |
+
Un élève actif sur 21 jours de formation :
|
| 68 |
+
- 21 conversations service = 21 crédits WhatsApp
|
| 69 |
+
- 0 crédit IA (BYOK)
|
| 70 |
+
─────────────────────────────────────────────────────
|
| 71 |
+
Total / élève / mois = 21 crédits = 210 FCFA
|
| 72 |
+
|
| 73 |
+
Coût réel XAMLÉ / élève :
|
| 74 |
+
- WhatsApp : 21 × 7,8 FCFA = 163 FCFA
|
| 75 |
+
- IA : 0 FCFA (client paie)
|
| 76 |
+
─────────────────────────────────────────────────────
|
| 77 |
+
Marge par élève = 47 FCFA (22%)
|
| 78 |
```
|
| 79 |
|
| 80 |
+
> **Conclusion :** BYOK est moins rentable sur la marge par élève, mais attire des clients tech qui apportent leurs propres volumes. À toi de décider si tu encourages ou décourages le BYOK.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 81 |
|
| 82 |
---
|
| 83 |
|
| 84 |
+
## PARTIE 3 — Les packs de recharge (prix de vente)
|
| 85 |
+
|
| 86 |
+
```
|
| 87 |
+
1 Crédit = 10 FCFA (prix de référence)
|
| 88 |
|
| 89 |
+
Pack Découverte : 1 000 crédits = 12 000 FCFA (bonus 20% → 1 200 crédits effectifs)
|
| 90 |
+
Pack Standard : 5 000 crédits = 55 000 FCFA (bonus 10% → 5 500 crédits effectifs)
|
| 91 |
+
Pack Pro : 20 000 crédits = 200 000 FCFA (bonus 15% → 23 000 crédits effectifs)
|
| 92 |
+
Pack Scale : 100 000 crédits : 900 000 FCFA (bonus 10% → 110 000 crédits effectifs)
|
| 93 |
+
```
|
| 94 |
|
| 95 |
+
### Simulation de rentabilité selon le pack acheté
|
| 96 |
|
| 97 |
+
| Pack | Crédits reçus | Revenu XAMLÉ | Coût si 100% conversations | Coût si 50% IA + 50% WA | Marge mini | Marge maxi |
|
| 98 |
+
|------|--------------|--------------|---------------------------|------------------------|-----------|-----------|
|
| 99 |
+
| Découverte | 1 200 | 12 000 FCFA | 9 360 FCFA (78% coût) | 3 120 FCFA (26% coût) | 22% | 74% |
|
| 100 |
+
| Standard | 5 500 | 55 000 FCFA | 42 900 FCFA | 14 300 FCFA | 22% | 74% |
|
| 101 |
+
| Pro | 23 000 | 200 000 FCFA | 179 400 FCFA | 59 800 FCFA | 10% | 70% |
|
| 102 |
+
| Scale | 110 000 | 900 000 FCFA | 858 000 FCFA | 286 000 FCFA | 5% | 68% |
|
| 103 |
|
| 104 |
+
> **Lecture :** La marge dépend du mix d'usage. Un client qui fait surtout de l'IA est très rentable. Un client qui fait du broadcast pur est moins rentable.
|
|
|
|
|
|
|
| 105 |
|
| 106 |
---
|
| 107 |
|
| 108 |
+
## PARTIE 4 — Simulation par profil client
|
|
|
|
|
|
|
| 109 |
|
| 110 |
+
### Profil A — École de formation (30 élèves, Gemini)
|
| 111 |
```
|
| 112 |
+
30 élèves × 63 crédits/mois = 1 890 crédits/mois
|
| 113 |
+
Recharge mensuelle estimée = 2 000 crédits = 20 000 FCFA
|
| 114 |
+
Coût réel XAMLÉ = 8 040 FCFA
|
| 115 |
+
Marge mensuelle par client = 11 960 FCFA (60%)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 116 |
```
|
| 117 |
|
| 118 |
+
### Profil B — PME CRM WhatsApp (500 contacts, 1 broadcast/semaine)
|
| 119 |
+
```
|
| 120 |
+
4 broadcasts × 500 contacts × 3 crédits = 6 000 crédits/mois
|
| 121 |
+
+ Conversations entrantes (200) = 200 crédits
|
| 122 |
+
Total = 6 200 crédits = 62 000 FCFA
|
| 123 |
+
Coût réel XAMLÉ (Meta) = 52 900 FCFA
|
| 124 |
+
Marge mensuelle par client = 9 100 FCFA (15%)
|
| 125 |
+
```
|
| 126 |
|
| 127 |
+
> **Alerte :** Les clients CRM broadcast pur sont peu rentables. À compenser avec le volume ou monter le prix des crédits Marketing.
|
| 128 |
|
| 129 |
+
### Profil C — Agent IA (réponses automatiques, 1 000 messages/mois)
|
| 130 |
```
|
| 131 |
+
1 000 messages × (1 WA + 3 IA) = 4 000 crédits/mois
|
| 132 |
+
Recharge estimée = 4 500 crédits = 45 000 FCFA
|
| 133 |
+
Coût réel XAMLÉ (Gemini) = 10 800 FCFA
|
| 134 |
+
Marge mensuelle par client = 34 200 FCFA (76%)
|
| 135 |
```
|
| 136 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 137 |
---
|
| 138 |
|
| 139 |
+
## PARTIE 5 — Architecture Wallet : ce qui existe vs. ce qu'il faut ajouter
|
| 140 |
+
|
| 141 |
+
### Ce qui existe dans la base de données (ne pas casser)
|
| 142 |
+
| Champ/Table | Utilisation actuelle | Évolution |
|
| 143 |
+
|---|---|---|
|
| 144 |
+
| `Organization.aiCreditsUsed` | Compteur IA mensuel | Garder pour analytics |
|
| 145 |
+
| `Organization.aiCreditsLimit` | Quota mensuel IA | Remplacer par `walletBalance` |
|
| 146 |
+
| `Organization.openAiApiKey` | BYOK OpenAI | Déjà là ✅ |
|
| 147 |
+
| `Organization.googleAiApiKey` | BYOK Gemini | Déjà là ✅ |
|
| 148 |
+
| `UsageEvent` | Ledger IA (coût USD) | Garder, enrichir |
|
| 149 |
+
| `AuditLog` | Logs d'actions admin | Déjà là ✅ |
|
| 150 |
+
| `Organization.whatsappMessagesSent` | Compteur WA | Garder pour analytics |
|
| 151 |
+
|
| 152 |
+
### Ce qu'il faut ajouter (migration Prisma nécessaire)
|
| 153 |
+
|
| 154 |
+
```prisma
|
| 155 |
+
model Organization {
|
| 156 |
+
// À AJOUTER :
|
| 157 |
+
walletBalance Int @default(0) // solde en crédits (temps réel)
|
| 158 |
+
isHardStopped Boolean @default(false) // flag coupure explicite
|
| 159 |
+
walletTransactions WalletTransaction[]
|
| 160 |
+
}
|
| 161 |
+
|
| 162 |
+
model WalletTransaction {
|
| 163 |
+
id String @id @default(uuid())
|
| 164 |
+
organizationId String
|
| 165 |
+
amount Int // positif = recharge, négatif = débit
|
| 166 |
+
balanceAfter Int // snapshot après transaction
|
| 167 |
+
type WalletTransactionType
|
| 168 |
+
description String? // ex: "Leçon Jour 3 — Aminata Diallo"
|
| 169 |
+
actorId String? // admin qui a fait un ajustement manuel
|
| 170 |
+
metadata Json? // { feature, provider, tokensIn, userId... }
|
| 171 |
+
createdAt DateTime @default(now())
|
| 172 |
+
organization Organization @relation(fields: [organizationId], references: [id])
|
| 173 |
+
|
| 174 |
+
@@index([organizationId, createdAt])
|
| 175 |
+
@@index([type])
|
| 176 |
+
}
|
| 177 |
+
|
| 178 |
+
enum WalletTransactionType {
|
| 179 |
+
TOP_UP_MANUAL // admin alloue des crédits (hors ligne)
|
| 180 |
+
TOP_UP_PAYMENT // paiement validé automatiquement
|
| 181 |
+
DEBIT_WHATSAPP // conversation WhatsApp déduite
|
| 182 |
+
DEBIT_AI // appel IA (si pas BYOK)
|
| 183 |
+
DEBIT_BROADCAST // envoi broadcast
|
| 184 |
+
ADJUSTMENT // correction / crédit de bienvenue
|
| 185 |
+
}
|
| 186 |
+
```
|
| 187 |
|
| 188 |
+
### Ce qui NE change PAS dans le code
|
| 189 |
+
- Handler chain (AIAgentHandler, ExerciseHandler, etc.)
|
| 190 |
+
- `trackAiUsage()` — garde pour analytics coût USD
|
| 191 |
+
- `AuditLog` — on l'utilise déjà pour tracer les ajustements admin
|
| 192 |
+
- Routes `/v1/billing/*` — on les enrichit, pas on les remplace
|
| 193 |
|
| 194 |
---
|
| 195 |
|
| 196 |
+
## PARTIE 6 — Le flux Hard Stop
|
|
|
|
|
|
|
|
|
|
|
|
|
| 197 |
|
| 198 |
```
|
| 199 |
+
Inbound WhatsApp message
|
| 200 |
+
└─ checkWalletBalance(organizationId)
|
| 201 |
+
├─ balance > 0
|
| 202 |
+
│ └─ traiter normalement
|
| 203 |
+
│ └─ après traitement : debitWallet(-N credits)
|
| 204 |
+
│ └─ si balance tombe < seuil alerté (20%) → email + push
|
| 205 |
+
│ └─ si balance = 0 → setHardStopped(true) + notifier admin
|
| 206 |
+
└─ balance = 0 ou isHardStopped
|
| 207 |
+
└─ message générique à l'élève :
|
| 208 |
+
"Le service est temporairement indisponible. Veuillez réessayer plus tard."
|
| 209 |
+
└─ NE PAS traiter, NE PAS consommer de crédits
|
|
|
|
| 210 |
```
|
| 211 |
|
| 212 |
+
### Seuils d'alerte
|
| 213 |
+
| Seuil | Action |
|
| 214 |
+
|---|---|
|
| 215 |
+
| 20% restants | Email + push notification à l'admin |
|
| 216 |
+
| 10% restants | Deuxième alerte (urgence) |
|
| 217 |
+
| 0% | Hard stop + notification "service suspendu" |
|
| 218 |
+
| Recharge → solde > 0 | Réactivation automatique + notification "service rétabli" |
|
| 219 |
|
| 220 |
---
|
| 221 |
|
| 222 |
+
## PARTIE 7 — Plan de développement
|
|
|
|
|
|
|
| 223 |
|
| 224 |
+
### Phase 1 — Migration DB (1 jour)
|
| 225 |
+
1. Ajouter `walletBalance` et `isHardStopped` sur `Organization`
|
| 226 |
+
2. Créer le modèle `WalletTransaction` et l'enum `WalletTransactionType`
|
| 227 |
+
3. Migration Prisma + script de remplissage (`walletBalance = aiCreditsLimit - aiCreditsUsed` pour les orgs existantes)
|
| 228 |
|
| 229 |
+
### Phase 2 — Backend (2 jours)
|
| 230 |
+
4. Remplacer `assertCredits()` par `checkWalletBalance()` — vérifie `walletBalance` ET `isHardStopped`
|
| 231 |
+
5. Créer `debitWallet(organizationId, amount, type, metadata)` — atomique avec snapshot
|
| 232 |
+
6. Intégrer la déduction WhatsApp dans le flow inbound (actuellement 0 déduction WA)
|
| 233 |
+
7. Intégrer la déduction IA avec détection BYOK automatique
|
| 234 |
+
8. Route `POST /v1/billing/admin/allocate` → écrire une `WalletTransaction` type `TOP_UP_MANUAL` + log `AuditLog`
|
| 235 |
+
9. Route `GET /v1/billing/wallet` → solde + dernières transactions
|
| 236 |
|
| 237 |
+
### Phase 3 — Dashboard (1 jour)
|
| 238 |
+
10. BillingPage : afficher `walletBalance` + jauge + dernières 10 transactions
|
| 239 |
+
11. ClientsManagementView : modal allocation → montrer le solde actuel + écrire en `WalletTransaction`
|
| 240 |
+
12. Bannière hard stop si `isHardStopped = true`
|
|
|
|
| 241 |
|
| 242 |
+
### Phase 4 — Alertes (0.5 jour)
|
| 243 |
+
13. Déclencher email + push à 20% et 10% restants
|
| 244 |
+
14. Notification "service suspendu" quand balance = 0
|
| 245 |
+
15. Notification "service rétabli" quand recharge reçue
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 246 |
|
| 247 |
---
|
| 248 |
|
| 249 |
+
## RÉSUMÉ EXÉCUTIF
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 250 |
|
| 251 |
+
| | Valeur |
|
| 252 |
+
|---|---|
|
| 253 |
+
| Unité | 1 crédit = 10 FCFA |
|
| 254 |
+
| Action la moins chère | Conversation WhatsApp service (1 crédit) |
|
| 255 |
+
| Action la plus chère | Broadcast marketing (3 crédits/destinataire) |
|
| 256 |
+
| Marge IA (Gemini) | 90% |
|
| 257 |
+
| Marge WhatsApp service | 22% |
|
| 258 |
+
| Seuil de rentabilité | 5 clients × 30 élèves chacun |
|
| 259 |
+
| Trésorerie | Positive dès la 1ère recharge (prépayé) |
|
| 260 |
+
| Risque financier | Zéro — aucun préfinancement nécessaire |
|
| 261 |
|
| 262 |
---
|
| 263 |
|
| 264 |
+
*Document prêt — En attente de validation pour lancer le développement.*
|