geo/app/docs/STRIPE-MIGRATION-RESUME.md

# ✅ Migration Stripe "Option A" - Résumé

## 📅 Date : 3 novembre 2025

---

## 🎯 Objectif

Optimiser la création de compte Stripe Connect en **1 seule requête** côté Flutter qui crée :
1. Le compte Stripe Connect
2. La Location Terminal (pour Tap to Pay)
3. Le lien d'onboarding

---

## ✅ Modifications Flutter APPLIQUÉES

### **1. Modèle `AmicaleModel`**
- ✅ Ajout du champ `stripeLocationId` (HiveField 27)
- ✅ Ajout dans le constructeur
- ✅ Ajout dans `fromJson()`
- ✅ Ajout dans `toJson()`
- ✅ Ajout dans `copyWith()`
- ✅ Adaptateurs Hive régénérés

### **2. Service `StripeTapToPayService`**
- ✅ Récupération du `location_id` depuis `amicale.stripeLocationId`
- ✅ Validation que le `location_id` existe avant initialisation
- ✅ Suppression de la méthode `_fetchConfiguration()` (inutile)
- ✅ Plus besoin de l'endpoint `GET /api/stripe/configuration`

### **3. Service `StripeConnectService`**
- ✅ Simplification de `createStripeAccount()` : 1 seule requête
- ✅ Ajout des URLs `return_url` et `refresh_url` dans la requête
- ✅ Récupération de `location_id` et `onboarding_url` dans la réponse
- ✅ Suppression de l'appel à `/stripe/locations`
- ✅ Ajout de `locationId` dans `StripeAccountStatus`
- ✅ Conservation de `getOnboardingLink()` (marqué déprécié)

---

## ⚠️ Modifications Backend REQUISES

### **1. Base de données**
```sql
ALTER TABLE amicales
ADD COLUMN stripe_location_id VARCHAR(255) NULL
AFTER stripe_id;
```

### **2. Endpoint `POST /stripe/accounts`**
**Modifications nécessaires** :
- Accepter `return_url` et `refresh_url` dans la requête
- Créer le compte Stripe Connect
- Créer la Location Terminal
- Créer le lien d'onboarding
- Sauvegarder `stripe_id`, `stripe_location_id`, `chk_stripe` en BDD
- Retourner : `account_id`, `location_id`, `onboarding_url`, `charges_enabled`, `payouts_enabled`, `existing`

**Voir le code complet** : `docs/STRIPE-BACKEND-MIGRATION.md`

### **3. Endpoint `GET /stripe/accounts/{id}/status`**
**Modification** :
- Ajouter `location_id` dans la réponse JSON

### **4. Endpoint `POST /stripe/locations`**
**Action** : À supprimer (devenu inutile) ou garder pour compatibilité temporaire

---

## 📊 Comparaison Avant/Après

| Aspect | Avant | Après |
|--------|-------|-------|
| **Appels API Flutter → Backend** | 3 | 1 |
| **Latence totale** | ~3-5s | ~1-2s |
| **Gestion erreurs** | Complexe (try/catch multiples) | Simplifié (transaction atomique) |
| **Atomicité BDD** | ❌ Non garantie | ✅ Oui (transaction) |
| **Location ID sauvegardé** | ❌ Non | ✅ Oui |
| **Code à maintenir** | Plus complexe | Plus simple |

---

## 🔄 Flow optimisé

```
Flutter (1 appel)          Backend (3 appels Stripe)       Stripe API
      │                              │                           │
      │  POST /stripe/accounts       │                           │
      │  {                           │                           │
      │    fk_entite: 123,          │                           │
      │    return_url: "...",       │                           │
      │    refresh_url: "..."       │                           │
      │  }                           │                           │
      ├─────────────────────────────>│                           │
      │                              │  1. Create Account        │
      │                              ├──────────────────────────>│
      │                              │<──────────────────────────┤
      │                              │  account_id: acct_xxx     │
      │                              │                           │
      │                              │  2. Create Location       │
      │                              ├──────────────────────────>│
      │                              │<──────────────────────────┤
      │                              │  location_id: tml_xxx     │
      │                              │                           │
      │                              │  3. Create AccountLink    │
      │                              ├──────────────────────────>│
      │                              │<──────────────────────────┤
      │                              │  onboarding_url           │
      │                              │                           │
      │                              │  (Sauvegarde en BDD)      │
      │                              │                           │
      │<─────────────────────────────┤                           │
      │  {                           │                           │
      │    account_id: acct_xxx,    │                           │
      │    location_id: tml_xxx,    │                           │
      │    onboarding_url: "..."    │                           │
      │  }                           │                           │
```

---

## ✅ Tests à effectuer

### **Backend (après implémentation)**
1. [ ] Migration SQL appliquée
2. [ ] Test avec Postman : nouvelle amicale
3. [ ] Test avec Postman : amicale existante
4. [ ] Vérification BDD : `stripe_location_id` bien sauvegardé
5. [ ] Logs vérifiés (pas d'erreurs)

### **Flutter (maintenant)**
1. [ ] Compilation OK (déjà fait ✅)
2. [ ] Test création compte depuis l'app Web admin
3. [ ] Vérification que le `location_id` est bien dans l'amicale
4. [ ] Test paiement Tap to Pay avec le `location_id`
5. [ ] Vérification que l'erreur "Erreur inattendue" n'apparaît plus

---

## 🚨 Points d'attention

### **Backend**
- Utiliser une **transaction BDD** pour garantir l'atomicité
- Bien logger chaque étape pour le debug
- Gérer le cas des comptes existants (avec/sans `location_id`)
- Tester avec des clés Stripe de test d'abord

### **Flutter**
- Le backend doit être déployé **AVANT** de tester l'app
- Si le backend n'est pas prêt, l'app retournera une erreur 400/500
- Les anciens comptes sans `location_id` devront être migrés

---

## 📚 Documentation

- **Code Backend complet** : `docs/STRIPE-BACKEND-MIGRATION.md`
- **Code Flutter modifié** : `lib/core/services/stripe_connect_service.dart`
- **Modèle modifié** : `lib/core/data/models/amicale_model.dart`
- **Service Tap to Pay** : `lib/core/services/stripe_tap_to_pay_service.dart`

---

## 🎯 Prochaines étapes

### **Étape 1 : Backend**
1. Implémenter les modifications backend
2. Tester avec Postman
3. Valider que tout fonctionne

### **Étape 2 : Migration des données existantes**
Pour les amicales qui ont déjà un `stripe_id` mais pas de `stripe_location_id` :

```sql
-- Identifier les amicales concernées
SELECT id, name, stripe_id, stripe_location_id
FROM amicales
WHERE stripe_id IS NOT NULL
  AND stripe_location_id IS NULL;
```

**Option A** : Les créer manuellement via l'API Stripe
**Option B** : Ajouter un endpoint de migration `POST /stripe/migrate-locations`

### **Étape 3 : Tests complets**
1. Test création nouvelle amicale
2. Test amicale existante avec compte
3. Test Tap to Pay avec paiement CB
4. Validation que l'erreur est corrigée

---

## ✅ État actuel

| Composant | État | Commentaire |
|-----------|------|-------------|
| **AmicaleModel** | ✅ Modifié | Champ `stripeLocationId` ajouté |
| **StripeTapToPayService** | ✅ Modifié | Utilise `amicale.stripeLocationId` |
| **StripeConnectService** | ✅ Modifié | 1 seule requête optimisée |
| **Build Runner** | ✅ Exécuté | Adaptateurs Hive régénérés |
| **Compilation Flutter** | ✅ OK | Aucune erreur |
| **Backend** | ⏳ En attente | À implémenter |
| **Tests** | ⏳ En attente | Après implémentation Backend |

---

## 📞 Support

- Documentation Stripe Connect : https://stripe.com/docs/connect
- Documentation Terminal Locations : https://stripe.com/docs/terminal/fleet/locations
- Documentation AccountLinks : https://stripe.com/docs/connect/account-links