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

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 :

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