Skip to content

Plan de mise en place — 2 projets Firebase (Stripe + Firebase)

Date de création : 12 décembre 2025
Statut : 🟠 Plan d'exécution (décision actée via ADR)
Propriétaire : Équipe

Objectif

Mettre en place une stratégie permettant d'avoir :

  • un environnement TEST : paiements Stripe en mode test (clés sk_test_*, webhooks test, prix test)
  • un environnement PROD : paiements Stripe en mode live (clés sk_live_*, webhooks live, prix live)

Contrainte : projet multi-plateforme (Android, iOS, Web, macOS, Windows à terme).

Note : côté DEV/TEST (PWA-first), l'intégration Stripe est réalisée via l'extension Firebase invertase/firestore-stripe-payments (voir ARCHITECTURE_STRIPE.md). Note : l'alignement/migration de la PROD vers cette extension (et/ou son paramétrage équivalent) fait partie des évolutions PROD.

Décision : docs/06_decisions/ADR-001-environnements-firebase-stripe-pwa-first.md.

## État actuel du projet (important pour la mise en place)

  • Le repo est configuré pour supporter un build Web DEV/TEST qui pointe vers yin-shi-dev (PWA test), et un build PROD qui pointe vers yin-shi-1967c.
  • Côté Firebase, Stripe est géré via l'extension invertase/firestore-stripe-payments.

Conséquence : l'environnement DEV/TEST séparé existe ; le reste du travail consiste surtout à :

  • s'assurer que chaque build (DEV/TEST vs PROD) embarque la bonne configuration Firebase
  • éviter toute confusion de déploiement (déployer rules/index/extension au bon projet)

## Stratégie retenue — 2 projets Firebase (DEV/TEST + PROD)

Principe : créer un projet Firebase DEV/TEST séparé du projet PROD, et y déployer la même “stack” (Firestore, règles, extension Stripe, etc.) avec des secrets Stripe de test.

  • Projet PROD : yin-shi-1967c (existant)
  • Projet DEV/TEST : yin-shi-dev (créé)

L'app Flutter doit pouvoir être compilée/configurée pour pointer vers DEV/TEST ou PROD.

Ce qu'on fait maintenant (PWA-first)

Objectif : valider rapidement l'environnement DEV/TEST et le flow Stripe en mode test via le Web/PWA.

  • URL PWA DEV/TEST : https://yinshi-test.yinshi.app/
  • Le build web “test” doit pointer vers le projet Firebase DEV/TEST (sinon on teste encore la prod).

Stratégie "2 rails" (rappel)

Rail 1 — Débloquer l'E2E Stripe sur DEV/TEST (prioritaire)

  • Objectif : réussir un paiement Stripe test depuis la PWA yinshi-test.yinshi.app.
  • Moyens : rules DEV/TEST minimales pour le flux Stripe + URLs success_url/cancel_url cohérentes DEV/TEST.

Rail 2 — Durcissement / industrialisation (après E2E)

  • Décider le modèle admin (custom claims vs rôle Firestore).
  • Versionner les rules (fichier firestore.rules) et définir un déploiement par environnement.
  • Revoir les rules PROD uniquement après décision.

Ce qu'on ne fait pas maintenant (plus tard)

  • Android : configuration DEV/TEST vs PROD par builds (tracks Play Console) et durcissement complet
  • iOS : configurations/schemes et distribution TestFlight
  • Industrialisation CI/CD multi-plateforme complète

## Implications (ce que ça va changer concrètement)

### Facturation / crédits / quotas

  • Les coûts/quota sont par projet.
  • Pour utiliser Cloud Functions et la plupart des extensions Firebase (dont invertase/firestore-stripe-payments), il faut généralement un projet en Blaze (facturation activée).
  • Conséquence : le projet DEV/TEST devra très probablement avoir la facturation activée lui aussi.

Implications concrètes :

  • DEV/TEST et PROD ont des factures séparées (ou au minimum des métriques séparées).
  • Les coûts DEV/TEST sont en général faibles si l'usage est limité, mais existent (Firestore/Functions/egress/logging).

Bonnes pratiques pour cadrer les coûts DEV/TEST :

  • définir un budget/alerte côté Google Cloud Billing (sur le projet DEV/TEST)
  • limiter la distribution (Internal testing / TestFlight, groupe de testeurs)
  • éviter de logger des volumes importants (surtout si logs très verbeux)
  • éviter toute réplication massive de données prod

Note : côté Stripe, le mode test ne facture pas de “vrais paiements”, mais le backend Firebase (Functions/Firestore) consomme quand même des ressources.

### Gouvernance / droits d'accès

Pour mettre en place correctement DEV/TEST, il faudra au minimum un profil ayant les droits pour :

  • créer le projet DEV/TEST
  • activer la facturation si nécessaire
  • installer/configurer l'extension Stripe
  • gérer les domaines Hosting / redirect URLs si utilisés

### Données / utilisateurs (Auth + Firestore)

  • Les utilisateurs DEV/TEST et PROD seront différents (Auth isolé).
  • Les données Firestore seront différentes.
  • Il faut dupliquer/synchroniser la “configuration infra” :
  • règles Firestore
  • index Firestore
  • éventuellement quelques collections de configuration non sensibles

Point d'attention important : toute configuration “par UID” (ex : customers/{uid}) sera séparée par projet. Cela simplifie les tests, mais implique que les comptes et abonnements de test n'existent pas en prod.

### Stripe (clé test vs clé live)

  • Le projet DEV/TEST utilisera sk_test_* et un whsec_* de test.
  • Le projet PROD utilisera sk_live_* et un whsec_* de live.
  • Dans Stripe, les objets sont séparés entre mode test et mode live (produits/prix/webhooks).

Points d'attention :

  • Les webhooks test et live sont distincts : il faudra donc 2 configurations de webhook (au minimum) côté Stripe.
  • Les prix/produits doivent exister en test ET en live (souvent recréés deux fois).

## Pistes de mise en place (organisation de la configuration côté Flutter)

Le point le plus structurant est : sur mobile (Android/iOS), la config Firebase ne se change pas “juste” par --dart-define. Il faut embarquer des fichiers de config distincts par environnement.

Ce que ça implique dans ce repo (fichiers impactés)

Aujourd'hui, le repo est configuré pour un seul projet. Pour supporter 2 projets, il faudra gérer 2 configurations, typiquement via :

  • lib/firebase_options.dart : devra devenir multi-environnement (2 fichiers générés, ou 1 wrapper qui choisit les options)
  • Android : un google-services.json par environnement (souvent par flavor)
  • iOS : un GoogleService-Info.plist par environnement (souvent par scheme/configuration)
  • .firebaserc : pour gérer des alias dev / prod côté déploiements

Pour générer des FirebaseOptions propres par environnement, FlutterFire CLI peut sortir un fichier distinct par projet (par ex. lib/firebase_options_dev.dart et lib/firebase_options_prod.dart).

### Piste 1 (recommandée) — Builds distincts (Android flavors/build types + iOS schemes) + config Web dédiée

Objectif : avoir 2 builds distincts (DEV/TEST vs PROD), avec une configuration Firebase différente selon le build.

  • Android : productFlavors (ex : prod et dev) + un google-services.json par flavor
  • iOS : configurations/schemes distincts + un GoogleService-Info.plist par environnement
  • Web : 2 builds qui pointent vers 2 projets Firebase (souvent via 2 configurations FirebaseOptions)
  • Windows : même logique que Web (sélection de la configuration au runtime/build)

C'est la piste la plus “propre” pour :

  • avoir des builds DEV/TEST et PROD bien séparés
  • éviter les erreurs (un build dev ne peut pas pointer par accident sur la prod)

### Piste 2 — DEV/TEST comme “backend only” (sans publier une app dédiée)

Objectif : limiter la charge si on ne veut pas deux apps installables.

  • on garde une seule app distribuée
  • DEV/TEST est principalement utilisé :
  • par des builds internes (CI)
  • par les devs

Cela reste compatible avec la séparation en 2 projets, mais c'est moins pratique pour des testeurs.

## Outils complémentaires (autour de la stratégie 2 projets)

### Hosting preview channels (Web)

  • utile pour publier des previews de l'UI Web
  • recommandé : faire pointer les previews vers le projet DEV/TEST
  • ne remplace pas la séparation DEV/TEST vs PROD côté backend

### Firebase Emulator Suite (local)

  • utile pour dev local et tests automatisés (Auth/Firestore/Functions)
  • ne remplace pas un environnement DEV/TEST cloud pour tester Stripe end-to-end

## Checklist de mise en place (Firebase + Stripe)

## Checklist PWA-first (Web uniquement) — chemin court (prioritaire)

Objectif : avoir un environnement DEV/TEST Firebase + Stripe fonctionnel et validé via la PWA de test https://yinshi-test.yinshi.app/.

### 0) Pré-requis (accès)

  • avoir accès : Firebase Console / Google Cloud Billing / Stripe Dashboard

### 1) Créer le projet Firebase DEV/TEST

  • créer le projet (ex : yin-shi-dev)
  • activer la facturation (Blaze) si nécessaire (extensions + Cloud Functions)

DoD : le projet DEV/TEST existe et la facturation est activée (si requise).

### 2) Activer les services requis (DEV/TEST)

  • Firestore
  • Cloud Functions
  • Extensions
  • Authentication (si l'app Web utilise l'auth)

DoD : services activés, pas de blocage “billing required”.

### 3) Répliquer la configuration Firestore “infra”

  • déployer les mêmes rules et index que PROD

DoD : rules + index DEV/TEST identiques à PROD (à l'exception éventuelle de règles de debug explicitement voulues).

### 4) Enregistrer l'app Web dans Firebase DEV/TEST

  • créer l'app Web dans le projet DEV/TEST
  • récupérer la config (apiKey/authDomain/projectId/appId, etc.)

DoD : l'app Web DEV/TEST est enregistrée et la configuration est disponible.

### 5) Installer/configurer l'extension Stripe en DEV/TEST

  • installer invertase/firestore-stripe-payments
  • fournir les secrets de test :
  • STRIPE_API_KEY = sk_test_*
  • STRIPE_WEBHOOK_SECRET = whsec_* (test)

DoD : les fonctions ext-firestore-stripe-payments-* existent dans DEV/TEST et les secrets sont présents dans Secret Manager.

### 6) Configurer Stripe Dashboard (test mode)

  • créer/recréer les produits/prix en mode test
  • créer un endpoint webhook (test) vers la fonction DEV/TEST ext-firestore-stripe-payments-handleWebhookEvents

DoD : Stripe envoie des événements “test” au webhook DEV/TEST et la fonction les traite (visible dans logs).

### 7) Autoriser le domaine Web de test côté Firebase Auth (si Auth)

  • ajouter yinshi-test.yinshi.app aux domaines autorisés

DoD : login/logout fonctionne sur la PWA test.

### 8) Faire pointer le build Web “test” vers Firebase DEV/TEST

  • générer une configuration FlutterFire DEV/TEST (fichier dédié ou wrapper)
  • s'assurer que le build utilisé par le workflow deploy-web-test.yml embarque bien la config DEV/TEST

DoD : sur https://yinshi-test.yinshi.app/, l'app utilise projectId = yin-shi-dev (ou l'id DEV/TEST choisi).

### 9) Aligner les URLs de retour Stripe (success/cancel) pour DEV/TEST

  • s'assurer que les success_url / cancel_url utilisés par la création de checkout_sessions pointent vers l'environnement Web de test

DoD : après un checkout test, la redirection revient sur https://yinshi-test.yinshi.app/ (et pas https://yinshi.app/).

### 10) Validation end-to-end (PWA)

  • depuis la PWA test : création d'une checkout_session
  • paiement avec une carte de test Stripe
  • vérification : webhook reçu/traité et abonnement reflété dans Firestore DEV/TEST

DoD : un utilisateur DEV/TEST passe un paiement test et obtient un état “abonné/premium” cohérent dans DEV/TEST.

### 1) Créer le projet DEV/TEST

  • créer un nouveau projet Firebase (ex : yin-shi-dev)
  • choisir la même région/zone “logique” que la prod (notamment pour les fonctions de l'extension)
  • activer la facturation si nécessaire (Blaze)

2) Enregistrer les apps client dans le projet DEV/TEST + récupérer les fichiers

  • Android : créer l'app Android (package name dev ou prod selon la piste choisie) et télécharger google-services.json
  • iOS : créer l'app iOS (bundle id dev ou prod selon la piste choisie) et télécharger GoogleService-Info.plist
  • Web : créer l'app Web (pour obtenir l'appId Web et config) si nécessaire

3) Activer les services nécessaires

  • Authentication (si utilisé)
  • Firestore Database
  • Cloud Functions
  • Extensions
  • Storage / Hosting selon besoin

4) Reproduire la configuration Firestore “infra”

  • déployer les mêmes règles Firestore
  • déployer les mêmes index Firestore
  • initialiser les collections de configuration non sensibles si besoin

5) Installer et configurer Stripe dans DEV/TEST

  • installer l'extension invertase/firestore-stripe-payments dans le projet DEV/TEST
  • renseigner les secrets Stripe de test :
  • STRIPE_API_KEY = sk_test_*
  • STRIPE_WEBHOOK_SECRET = whsec_* de test

6) Configurer Stripe côté Dashboard (test mode)

  • créer/recréer les produits/prix en mode test
  • créer/configurer un endpoint webhook de test qui pointe vers les fonctions du projet DEV/TEST

7) Smoke tests (minimum)

  • depuis une app DEV/TEST : création d'une checkout_session en écriture Firestore
  • vérification que les fonctions ext-firestore-stripe-payments-* réagissent dans le projet DEV/TEST
  • vérification qu'un paiement test (carte de test Stripe) suit le flow attendu

## CI/CD et déploiements (recommandations)

  • définir des aliases dans .firebaserc (ex : prod et dev) pour éviter les erreurs de déploiement
  • séparer clairement les jobs :
  • déploiements DEV/TEST (rules/index/hosting/functions) déclenchés sur branches/PR
  • déploiements PROD uniquement sur tag/release
  • côté Web : utiliser Hosting + éventuellement preview channels pour publier des versions temporaires pointant vers DEV/TEST

## Impacts “build & multi-plateforme” (2 projets Firebase)

### Android

Objectif : une seule app Play Store, avec des builds distincts selon le track (internal/closed testing vs production).

  • applicationId : identique entre DEV/TEST et PROD (la différence est dans la configuration Firebase embarquée et le pipeline de release).

Mécanisme : un mécanisme de build (ex : productFlavors et/ou build types) + un google-services.json DEV/TEST vs PROD.

Implications côté Firebase :

  • enregistrer l'app Android dans le projet PROD et dans le projet DEV/TEST
  • ajouter les SHA (debug/release) dans chaque projet, sinon certains flows (Google Sign-In, etc.) peuvent échouer

### iOS

Objectif : builds DEV/TEST vs PROD avec configuration Firebase distincte (même principe que Web). La stratégie exacte (bundle id distinct ou non) est à confirmer plus tard.

  • Prod : bundle id actuel
  • Dev/Test : bundle id distinct (ex : .dev) + plist Firebase distinct

Mécanisme : configurations/schemes Xcode séparés.

Implications côté Firebase :

  • enregistrer l'app iOS dans le projet PROD et dans le projet DEV/TEST
  • gérer les identifiants/bundle id et les fichiers GoogleService-Info.plist par environnement

### Web

Objectif : 2 builds qui pointent vers 2 Firebase différents.

  • Prod : build/hosting prod
  • Dev/Test : build/hosting dev (idéalement sous-domaine distinct)

Mécanisme : 2 jeux de FirebaseOptions.web ou une sélection par --dart-define.

Point d'attention : le Web est le plus simple car la config est purement “côté code”. Il faut surtout s'assurer que les URLs (Hosting, domaines, redirect URLs OAuth) sont cohérentes entre DEV/TEST et PROD.

### Windows

Même approche que Web/multi-config : le runtime doit choisir le bon FirebaseOptions.

## Réplication des données prod vers test

Firebase ne fournit pas une réplication continue “1 clic” gratuite.

Approches possibles (à cadrer RGPD) :

  • copie ponctuelle (export/import) pour des tests réalistes
  • copie partielle (ex : seulement payment_plans, pas les utilisateurs)
  • anonymisation si des données personnelles sont copiées

## Décision (rappel)

Décision actée : voir docs/06_decisions/ADR-001-environnements-firebase-stripe-pwa-first.md.