CognxSafeTrack commited on
Commit
7e22952
·
1 Parent(s): bc01171

docs(business): update economic model — wallet/ledger decision v2.0

Browse files
Files changed (1) hide show
  1. docs/business/MODELE-ECONOMIQUE.md +195 -220
docs/business/MODELE-ECONOMIQUE.md CHANGED
@@ -1,289 +1,264 @@
1
- # Modèle économique XAMLÉ — Guide de décision
2
 
3
- **Document de travail — 2026-05-11**
4
- **Objectif :** Comprendre les coûts réels, les options de monétisation, et choisir la stratégie à implémenter.
5
 
6
  ---
7
 
8
- ## PARTIE 1 — Ce que Meta facture
9
 
10
- ### Comment Meta facture WhatsApp Business API
11
-
12
- Meta ne facture **pas au message**. Il facture à la **conversation**.
13
-
14
- > Une conversation = une fenêtre de 24h.
15
- > Peu importe combien de messages s'échangent dans ces 24h **1 seule conversation facturée**.
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 2Ce que tu paies, toi
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
- ### Le coût variable : l'Intelligence Artificielle
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
- GPT-4o : ~$0.020-0.030 par évaluation
67
- Gemini Flash : ~$0.002-0.005 par évaluation (10x moins cher)
68
  ```
69
 
70
- **Simulation coût IA mensuel selon les clients :**
71
 
72
- | Scénario | Élèves total | Évals/mois | GPT-4o | Gemini Flash |
73
- |----------|-------------|-----------|--------|--------------|
74
- | 1 client, 50 élèves | 50 | 1 500 | ~$37 | ~$4 |
75
- | 3 clients, 150 élèves | 150 | 4 500 | ~$112 | ~$12 |
76
- | 5 clients, 300 élèves | 300 | 9 000 | ~$225 | ~$22 |
77
- | 10 clients, 600 élèves | 600 | 18 000 | ~$450 | ~$45 |
 
 
78
 
79
- > **Protection déjà en place dans le code :** chaque organisation peut avoir ses propres clés OpenAI/Gemini. Si le client apporte ses clés �� coût IA = 0 $ pour toi.
 
80
 
81
  ---
82
 
83
- ## PARTIE 3Les deux modèles possibles
84
-
85
- ### Modèle A — SaaS Pur ✅ (ce que tu as aujourd'hui)
86
 
87
- Chaque client connecte **son propre compte Meta** via Embedded Signup.
88
- → Meta facture **le client directement**.
89
- → Toi tu factures uniquement la **plateforme XAMLÉ**.
90
 
91
  ```
92
- Client ─────── paie Meta (ses conversations)
93
- Client ─────── paie XAMLÉ (la plateforme)
94
- XAMLÉ ─────── paie son infrastructure
 
 
 
 
 
 
 
 
 
 
 
95
  ```
96
 
97
- **Avantages :**
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
- Client ─────── paie XAMLÉ (plateforme + conversations)
117
- XAMLÉ ─────── paie Meta (toutes les conversations)
118
- XAMLÉ ─────── garde la marge sur Meta
 
 
 
 
 
 
 
 
119
  ```
120
 
121
- **Avantages :**
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 4 — Les options de tarification
 
 
 
136
 
137
- ### Option 1 Abonnement fixe (le plus simple)
 
 
 
 
138
 
139
- Tu fixes un prix mensuel par tier. Tu absorbes les coûts IA en dessous d'un seuil.
140
 
141
- | Tier | Prix/mois | Élèves max | IA incluse | Meta |
142
- |------|-----------|-----------|-----------|------|
143
- | **Starter** | 35 000 FCFA | 100 | (clés XAMLÉ) | Client paie |
144
- | **Growth** | 75 000 FCFA | 400 | (clés XAMLÉ) | Client paie |
145
- | **Scale** | 150 000 FCFA | Illimité | (clés client) | Client paie |
 
146
 
147
- Simple à vendre
148
- ✅ Prévisible pour le client
149
- ⚠️ Risque : gros clients avec beaucoup d'IA consomment tes crédits
150
 
151
  ---
152
 
153
- ### Option 2Crédit XAMLÉ (le plus flexible)
154
-
155
- Le client achète des crédits à l'avance. Chaque action consomme des crédits.
156
 
157
- **Table de conversion :**
158
  ```
159
- 1 crédit XAMLÉ = 10 FCFA
160
-
161
- Conversation (élève envoie) = 1 crédit
162
- Évaluation IA d'un exercice = 3 crédits
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
- Trésorerie positive (encaissé avant consommé)
172
- ✅ Granulaire — le client comprend ce qu'il paie
173
- Facile à faire des promotions (bonus crédits)
174
- ⚠️ Plus complexe à développer et à expliquer
175
-
176
- ---
177
-
178
- ### Option 3 — Hybride (abonnement + surconsommation)
179
 
180
- Base fixe légère + facturation à l'usage au-delà.
181
 
 
182
  ```
183
- Base mensuelle : 25 000 FCFA
184
- Inclus : 500 élèves-jours/mois
185
- Au-delà : 50 FCFA / élève-jour supplémentaire
 
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 — Simulation de rentabilité
195
-
196
- ### Avec l'Option 1 (Abonnement fixe)
197
-
198
- **Hypothèse : clés IA XAMLÉ pour Starter/Growth, clés client pour Scale**
199
-
200
- | Clients | Mix | Revenu | Infra | IA | **Marge nette** |
201
- |---------|-----|--------|-------|-----|-----------------|
202
- | 2 Starter + 1 Growth | | 145 000 FCFA | 41 000 | 25 000 | **79 000 (54%)** |
203
- | 3 Growth | | 225 000 FCFA | 41 000 | 45 000 | **139 000 (62%)** |
204
- | 2 Growth + 2 Scale | | 450 000 FCFA | 45 000 | 30 000 | **375 000 (83%)** |
205
- | 5 Growth + 3 Scale | | 825 000 FCFA | 55 000 | 60 000 | **710 000 (86%)** |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
206
 
207
- > À partir de 5 clients, la marge dépasse 80%. C'est l'effet levier du SaaS.
 
 
 
 
208
 
209
  ---
210
 
211
- ## PARTIE 6 — Ce qu'il faut afficher dans le dashboard
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
- Consommation WhatsApp — Mai 2026 │
220
- │ │
221
- │ Service 847 conv. incluses (quota gratuit) │
222
- Marketing 12 conv. ~$0.48 │
223
- Utility 3 conv. ~$0.06 │
224
-
225
- │ Coût estimé Meta ce mois ~$0.54 │
226
- │ Quota gratuit restant 153 / 1 000 ✅ │
227
- │ │
228
- │ [Voir détail par jour ↓] │
229
- └──────────────────────────────────────────────────────┘
230
  ```
231
 
232
- **Ce que ça nécessite techniquement :**
233
- 1. Endpoint API : `GET /v1/organizations/:id/meta-billing?month=2026-05`
234
- 2. Appel Meta : `GET /{waba_id}/analytics?granularity=MONTH&...`
235
- 3. Permission requise sur le token : `whatsapp_business_management`
236
- 4. Cache Redis 1h (Meta met à jour en différé)
 
 
237
 
238
  ---
239
 
240
- ## PARTIE 7 — Questions à décider
241
-
242
- Réponds à chacune pour qu'on sache exactement quoi construire :
243
 
244
- ### Q1Modèle Meta
245
- > Veux-tu que chaque client gère son propre compte Meta (Modèle A), ou veux-tu centraliser et facturer Meta en plus (Modèle B) ?
246
- - [ ] **A SaaS pur** (client gère son Meta, moins de complexité)
247
- - [ ] **B BSP** (tu gères Meta pour tout le monde, marge supplémentaire)
248
 
249
- ### Q2Modèle de tarification
250
- > Comment veux-tu facturer tes clients ?
251
- - [ ] **Option 1Abonnement fixe** (Starter/Growth/Scale — simple)
252
- - [ ] **Option 2 Crédits** (achats à l'avance trésorerie positive)
253
- - [ ] **Option 3 Hybride** (base + surconso)
 
 
254
 
255
- ### Q3Coûts IA
256
- > Qui paie l'IA (OpenAI/Gemini) ?
257
- - [ ] **XAMLÉ paie pour tous** (inclus dans l'abonnement, risque si gros volumes)
258
- - [ ] **Clés client obligatoires dès le départ** (zéro risque IA pour toi)
259
- - [ ] **XAMLÉ paie jusqu'à X élèves, clés client au-delà** (hybride)
260
 
261
- ### Q4Affichage consommation
262
- > Veux-tu afficher la vraie consommation Meta dans le dashboard ?
263
- - [ ] **Oui intégrer l'API Meta Analytics** (nécessite permission `whatsapp_business_management` sur les tokens)
264
- - [ ] **Non juste les stats internes** (conversations comptées dans notre DB)
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
- ## Résumé recommandé (point de départ)
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
- Cela représente **2-3 jours de développement** pour les tiers + alerts + page de tarification, vs **3-4 semaines** pour le système de crédits complet.
 
 
 
 
 
 
 
 
 
286
 
287
  ---
288
 
289
- *Réponds aux 5 questions ci-dessus et on implémente exactement ce qu'il faut.*
 
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 1La 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 2Ce 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 4Simulation 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à |
148
+ | `UsageEvent` | Ledger IA (coût USD) | Garder, enrichir |
149
+ | `AuditLog` | Logs d'actions admin | Déjà |
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.*