556a0b2f3f
Un pot de crédits global (BASIC 100 / PRO 1 000 / BUSINESS 4 000) remplace les seaux par fonction côté débit. Packs one-shot S/M/L, admin sans seaux legacy, usage multi-features, hints de coût, anti-flash thème et hydratation admin. Inclut aussi le pipeline slides renforcé et la page publique polishée.
143 lines
4.9 KiB
Markdown
143 lines
4.9 KiB
Markdown
# Guide admin — Facturation et crédits IA
|
||
|
||
## Objectif
|
||
|
||
La page **Admin → Facturation & crédits IA** sert à :
|
||
|
||
1. Configurer Stripe (prix d’abonnement + **packs de crédits** one-shot, activation)
|
||
2. **Comprendre le solde de crédits** par palier (source de vérité du débit)
|
||
3. Consulter un aperçu d’usage agrégé
|
||
|
||
Le **débit réel** des utilisateurs n’est **pas** un plafond par fonction (chat 50, slides 20…).
|
||
C’est un **pot unique de crédits** (modèle A, option M).
|
||
|
||
---
|
||
|
||
## Accès
|
||
|
||
1. Compte **ADMIN**
|
||
2. Console admin → **Facturation & crédits IA**
|
||
|
||
Les actions non-admin sont refusées côté serveur.
|
||
|
||
---
|
||
|
||
## 1. Config Stripe (métier)
|
||
|
||
### Abonnements
|
||
|
||
- `STRIPE_PRICE_PRO_MONTHLY` / `ANNUAL`
|
||
- `STRIPE_PRICE_BUSINESS_MONTHLY` / `ANNUAL`
|
||
- Case **Activer la facturation**
|
||
|
||
### Packs de crédits (paiement unique)
|
||
|
||
Produits Stripe en **mode payment** (one-shot), **pas** abonnement :
|
||
|
||
| Clé admin | Pack | Crédits | Prix catalogue (défaut UI) |
|
||
|-----------|------|---------|----------------------------|
|
||
| `STRIPE_PRICE_CREDITS_S` | S | **100** | 4,90 € |
|
||
| `STRIPE_PRICE_CREDITS_M` | M | **500** | 19,90 € |
|
||
| `STRIPE_PRICE_CREDITS_L` | L | **2 000** | 49,90 € |
|
||
|
||
Dans Stripe Dashboard :
|
||
|
||
1. Créer 3 **Products** one-time (ex. « Memento crédits S / M / L »)
|
||
2. Prix uniques (EUR)
|
||
3. Copier les `price_...` dans Admin → Facturation
|
||
4. Webhook : événement `checkout.session.completed` déjà géré (mode `payment` + metadata `type=credit_pack`)
|
||
|
||
Les secrets (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`) restent dans l’environnement serveur (Docker), **jamais** dans cette page.
|
||
|
||
---
|
||
|
||
## 2. Crédits IA par palier (source de vérité)
|
||
|
||
### Allocations mensuelles (option M)
|
||
|
||
| Palier | Crédits / mois | Notes |
|
||
|--------|----------------|--------|
|
||
| **BASIC** | **100** | Découverte |
|
||
| **PRO** | **1 000** | Aligné marché type « ~1 000 crédits » Pro |
|
||
| **BUSINESS** | **4 000** | Usage intensif / équipe |
|
||
| **ENTERPRISE** | **Illimité** | Contrat |
|
||
|
||
Ces valeurs sont définies dans le code : `lib/credits.ts` → `CREDIT_ALLOCATIONS`.
|
||
Elles s’appliquent au premier usage / grant de période, et après **reset** utilisateur.
|
||
|
||
### Packs achetés
|
||
|
||
- Crédités via `addPurchasedCredits` (ledger `PURCHASE_PACK`)
|
||
- Stockés dans `purchasedBalance` — **reportables** d’un mois à l’autre
|
||
- Consommés **après** l’allocation abonnement du mois
|
||
|
||
### Coûts typiques (extrait)
|
||
|
||
| Action | Coût |
|
||
|--------|------|
|
||
| Recherche, chat, étiquettes, titres, reformulation… | **1** crédit |
|
||
| Flashcards, publication IA | **3** |
|
||
| Diagramme Excalidraw | **4** |
|
||
| Création brainstorm | **5** |
|
||
| **Présentation** (note) | **1 + N** (N = nombre de diapositives, 3–8) |
|
||
|
||
Exemple : 7 diapositives ≈ **8 crédits**.
|
||
|
||
### Réinitialiser un utilisateur
|
||
|
||
**Admin → Utilisateurs** → bouton **réinitialiser les crédits** sur la ligne du compte.
|
||
Cela recharge l’allocation du palier pour le mois en cours (journal `ADMIN_RESET`). Les packs achetés sont **conservés** par défaut.
|
||
|
||
### Clé personnelle (BYOK)
|
||
|
||
Si l’utilisateur a une clé active pour la voie concernée (chat / tags / embeddings), l’usage **ne débite en général pas** le solde Memento.
|
||
|
||
---
|
||
|
||
## 3. Aperçu consommation
|
||
|
||
- Agrégats par fonction (historique PostgreSQL / sync)
|
||
- Top utilisateurs
|
||
- Sync : cron `/api/cron/sync-usage` (compteurs legacy éventuels)
|
||
|
||
Le compteur **utilisateur** (sidebar / facturation) affiche le **solde de crédits** et la **répartition par fonction** (journal des consommations).
|
||
|
||
---
|
||
|
||
## 4. Côté produit (rappel)
|
||
|
||
| Surface | Message attendu |
|
||
|---------|-----------------|
|
||
| Landing / tarifs | Basic 100 · Pro 1 000 · Business 4 000 crédits / mois |
|
||
| Paramètres facturation | Même grille + **acheter des packs** (S/M/L) |
|
||
| Sidebar | Solde restant + tableau multi-fonctions |
|
||
| Publication IA / diagramme | Hint coût (3 / 4 crédits) |
|
||
| Fin de solde | Plan supérieur, pack de crédits, ou clé personnelle |
|
||
|
||
---
|
||
|
||
## 5. Délai d’effet
|
||
|
||
- Allocations code : au prochain grant / reset / appel `ensureCreditAccount`
|
||
- Config Stripe (abos + packs) : immédiat après enregistrement
|
||
- Crédit pack après paiement : webhook `checkout.session.completed` (+ filet de sécurité sur `/api/billing/status?session_id=`)
|
||
|
||
---
|
||
|
||
## 6. Fichiers techniques de référence
|
||
|
||
| Rôle | Fichier |
|
||
|------|---------|
|
||
| Allocations + coûts + réserve + packs ledger | `lib/credits.ts` |
|
||
| Catalogue packs + price IDs | `lib/billing/credit-packs.ts` |
|
||
| Checkout pack | `app/api/billing/create-pack-checkout/route.ts` |
|
||
| Webhook abo + pack | `app/api/billing/webhook/route.ts` |
|
||
| UI admin | `app/(admin)/admin/billing/billing-admin-client.tsx` |
|
||
| UI facturation utilisateur | `components/settings/billing-plans.tsx` |
|
||
|
||
---
|
||
|
||
## Note legacy
|
||
|
||
Le modèle `PlanEntitlement` (anciens seaux par fonction) peut encore exister en base pour d’éventuels garde-fous « fonction indisponible », mais **n’apparaît plus** dans l’UI admin et **ne pilote plus** le débit principal.
|