# Guide d'utilisation — Admin Facturation & Quotas

## Objectif

La page **Admin > Facturation & Quotas** permet de gérer, sans redéploiement :

- les limites mensuelles par fonctionnalité IA (par tier)
- les Price IDs Stripe utilisés par le checkout
- l'activation/désactivation de l'interface de facturation
- un aperçu d'usage (requêtes/tokens)

---

## Accès

1. Connectez-vous avec un compte **ADMIN**.
2. Ouvrez la console admin (`/admin`).
3. Cliquez sur **Facturation & quotas** dans la sidebar.

> Si vous n'êtes pas admin, les actions sont refusées côté serveur.

---

## Section 1 — Config Stripe (métier)

Cette section sert à configurer les éléments business de Stripe :

- `STRIPE_PRICE_PRO_MONTHLY`
- `STRIPE_PRICE_PRO_ANNUAL`
- `STRIPE_PRICE_BUSINESS_MONTHLY`
- `STRIPE_PRICE_BUSINESS_ANNUAL`
- toggle **Activer la facturation**

### Procédure

1. Renseignez/mettez à jour les `price_...` IDs.
2. Activez ou désactivez la facturation via la case.
3. Cliquez sur **Enregistrer la config**.

### Important sécurité

- `STRIPE_SECRET_KEY` et `STRIPE_WEBHOOK_SECRET` **ne sont pas gérés ici**.
- Ils doivent rester dans les secrets d'environnement serveur (Docker/env/vault).

---

## Section 2 — Quotas par palier

Vous pouvez définir, pour chaque tier (**BASIC**, **PRO**, **BUSINESS**, **ENTERPRISE**) :

- **Indisponible** : fonctionnalité non accessible
- **Limité** : plafond mensuel (nombre entier >= 0)
- **Illimité** : pas de plafond

### Procédure

1. Cliquez sur le tier ciblé.
2. Pour chaque fonctionnalité :
   - choisissez le mode d'accès
   - si mode **Limité**, entrez la valeur mensuelle
3. Cliquez sur **Enregistrer** sur la ligne concernée.

### Délai d'effet

Les changements sont appliqués rapidement (cache), en général sous **~60 secondes**.

---

## Section 3 — Aperçu consommation

La section affiche :

- usage par fonctionnalité (requêtes + tokens)
- top utilisateurs
- date de dernière synchronisation

### Source des données

- Compteurs temps réel : Redis
- Consolidation historique : table `UsageLog`
- Sync via cron (`/api/cron/sync-usage`)

Si la synchronisation n'a pas encore tourné, l'interface peut indiquer un état non synchronisé.

---

## Cas d'usage fréquents

## 1) Augmenter temporairement le quota chat de PRO

1. Tier: **PRO**
2. Ligne `chat` -> mode **Limité**
3. Mettre par exemple `50 -> 100`
4. **Enregistrer**

## 2) Désactiver la vente (maintenance Stripe)

1. Décochez **Activer la facturation**
2. **Enregistrer la config**
3. Vérifiez côté utilisateur: `/settings/billing` montre l'état désactivé

## 3) Rendre une feature inaccessible en BASIC

1. Tier: **BASIC**
2. Ligne feature -> mode **Indisponible**
3. **Enregistrer**

---

## Validation rapide après changement

Après une modification importante, vérifier :

1. Le toast de succès en admin
2. Le comportement côté utilisateur (`/settings/billing` / appels IA)
3. Les logs serveur en cas d'erreur
4. L'`AuditLog` pour tracer qui a modifié quoi

---

## Dépannage

## "Le bouton Enregistrer ne semble rien faire"

- Vérifiez que vous êtes bien connecté en ADMIN.
- Regardez le toast d'erreur.
- Vérifiez les logs serveur (action rejetée, validation invalide, etc.).

## "Les quotas ne changent pas immédiatement"

- Attendez ~60 secondes (cache).
- Relancez une action IA qui consomme réellement le quota.
- Vérifiez que la feature est bien en mode attendu (indisponible/limité/illimité).

## "Le checkout ne démarre pas"

- Vérifiez les 4 `STRIPE_PRICE_*` IDs.
- Vérifiez que la facturation est activée.
- Vérifiez que les secrets Stripe serveur sont présents (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`).

---

## Bonnes pratiques d'exploitation

- Éviter les changements massifs sans validation progressive.
- Journaliser les changements critiques (tiers très utilisés).
- Préférer des paliers de quota cohérents entre fonctionnalités similaires.
- Garder un rituel de revue hebdo des usages (section Aperçu consommation).

---

## Référence technique (fichiers clés)

- `app/(admin)/admin/billing/page.tsx`
- `app/(admin)/admin/billing/billing-admin-client.tsx`
- `app/actions/admin-billing.ts`
- `lib/plan-entitlements.ts`
- `lib/entitlements.ts`
- `lib/billing/stripe-prices.ts`
- `app/api/billing/status/route.ts`