# 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.