Skip to content

Checklist — Firebase DEV/TEST pour Yinshi (PWA-first)

Objectif : configurer un projet Firebase DEV/TEST séparé de PROD, pour valider Stripe en mode test via la PWA https://yinshi-test.yinshi.app/.

Projet DEV/TEST : yin-shi-dev

Principes (à garder en tête)

  • Séparation stricte : le DEV/TEST ne doit pas pouvoir "toucher" les données, Auth, Stripe et secrets de PROD.
  • Reproductible : on privilégie des étapes vérifiables + des secrets GitHub plutôt que des configs commitées.
  • Choix irréversible : la localisation Firestore ne se change pas une fois la DB créée.

État actuel (18/12/2025)

  • PWA test : https://yinshi-test.yinshi.app/ s’affiche correctement.
  • Incident précédent : crash NoSuchMethodError: c.b is not a function.
  • Cause : client bloqué sur un ancien bundle via cache/service worker.
  • Statut : résolu après rafraîchissement « hard » (désinscription du service worker + purge du cache navigateur).
  • Sujet restant : les règles Firestore doivent être revues et clarifiées (DEV/TEST et PROD), notamment :
  • accès foods (lecture publique attendue)
  • écriture logs au démarrage (avant authentification)
  • modèle Stripe Invertase (customers/{uid}/... + products/...)
  • Firestore DEV/TEST : base vide (normal) mais nécessite soit un seed, soit un import contrôlé.
  • Seed DEV/TEST : effectué via scripts/seed-devtest.js.
  • Index Firestore : déployé (fichier firestore.indexes.json).
  • Paiement Stripe (test) : réalisé avec succès via la PWA test.
  • Cloud Functions (repo) : syncStripeToAppUser* déployées sur yin-shi-dev.
  • Problème restant : re-tester l’E2E pour valider que le rôle premium est bien appliqué après achat.

0) Prérequis

  • [x] Accès Console Firebase au projet yin-shi-dev
  • Pourquoi : toutes les étapes suivantes sont dans la console.

  • Validation : le projet yin-shi-dev apparaît dans la liste des projets.

  • [x] Comprendre le besoin Blaze (facturation)

  • Pourquoi : l’extension Stripe (et Cloud Functions) nécessitent généralement le plan Blaze.
  • Validation : tu sais qu’on ne passera en Blaze que juste avant d’installer l’extension.

1) Création du projet Firebase (si ce n’est pas déjà fait)

  • [x] Créer un projet Firebase avec Project ID : yin-shi-dev
  • Pourquoi : isolation complète DEV/TEST.

  • Validation : URL du projet du type https://console.firebase.google.com/project/yin-shi-dev/overview.

  • [ ] (Optionnel) Définir le type d’environnement (DEV/TEST)

  • Pourquoi : réduire les erreurs humaines (confusion prod/test).
  • Validation : Paramètres du projet → "Environnement" non vide.

2) Créer l’application Web Firebase (pour le build PWA test)

  • [x] Paramètres du projet → "Vos applications" → Ajouter une application → Web
  • Nom conseillé : yinshi-web-dev
  • Ne pas activer Firebase Hosting (déploiement web actuel via DreamHost/CI)

Pourquoi

  • Le build web test utilise --dart-define pour injecter les FirebaseOptions web DEV/TEST.

Validation

  • [x] L’app yinshi-web-dev apparaît dans "Vos applications".
  • [x] Tu peux afficher l’objet firebaseConfig (onglet "Configuration") contenant :
  • apiKey
  • authDomain
  • projectId
  • storageBucket (parfois sous la forme *.firebasestorage.app, c’est normal)
  • messagingSenderId
  • appId

3) Renseigner les secrets GitHub (pour deploy-web-test.yml)

Créer les secrets GitHub Actions suivants (valeurs copiées depuis la config Web de yinshi-web-dev) :

  • [x] FIREBASE_WEB_API_KEY_DEV
  • [x] FIREBASE_WEB_APP_ID_DEV
  • [x] FIREBASE_WEB_MESSAGING_SENDER_ID_DEV
  • [x] FIREBASE_WEB_PROJECT_ID_DEV (doit être yin-shi-dev)
  • [x] FIREBASE_WEB_AUTH_DOMAIN_DEV
  • [x] FIREBASE_WEB_STORAGE_BUCKET_DEV

Pourquoi

  • On évite de commiter une config DEV/TEST dans le repo.
  • Le workflow test doit échouer si la config DEV/TEST est absente (sécurité).

Validation

  • [x] Les secrets existent dans GitHub.
  • [x] Le workflow "Deploy Flutter Web (test)" passe l’étape Build web (test env).

3bis) Déployer réellement la PWA de test (pas un dry-run)

  • [x] Lancer le workflow "Deploy Flutter Web (test)" sans dry_run

Pourquoi

  • Le dry-run valide seulement le build, pas le déploiement du site.

Validation

  • [x] https://yinshi-test.yinshi.app/ sert la nouvelle version.
  • [x] La PWA utilise bien le Firebase DEV/TEST (projectId = yin-shi-dev).

3ter) Important — Cache PWA / Service Worker (éviter les faux négatifs)

Symptôme

  • Une correction est déployée mais un navigateur continue à exécuter un ancien main.dart.js.

Diagnostic / Fix

  • Désinscrire les service workers et purger le cache (Chrome : DevTools → Application → Service Workers / Clear storage).
  • Tester avec une URL “cache-busting” (ex : /?cb=<timestamp>).
  • Vérifier côté console que les logs “d’initialisation Firebase” correspondent au dernier build.

4) Activer Firestore (DEV/TEST)

  • [x] Firestore Database → Créer une base de données
  • [x] Choisir le mode (recommandé : Production)
  • [x] Choisir la localisation : nam5

Pourquoi

  • Yinshi utilise Firestore (données applicatives + modèle customers/{uid}/... pour Stripe).
  • Aligner DEV/TEST avec PROD évite des surprises (latence, coûts inter-régions, contraintes de déploiement Functions).

Validation

  • [x] Firestore affiche une base (-default-).
  • [x] L’UI indique une localisation nam5.

4bis) Firestore Rules — point d’attention (PROD et DEV/TEST)

Point clé

  • request.auth == null signifie client non authentifié, pas “Cloud Function”.
  • Les Cloud Functions utilisant l’Admin SDK ne sont pas soumises aux rules Firestore.

Source de vérité (à clarifier)

  • Actuellement, les rules peuvent être modifiées directement dans la console Firebase.
  • Pour éviter la dérive PROD/DEV/TEST, il est recommandé de versionner les rules dans le repo (ex: firestore.rules) et de les déployer via CI.

Erreurs typiques observées

  • Dupliquer des blocs match /app_users/{userId} dans le même fichier rend l’intention ambiguë et complique la relecture.
  • Autoriser des écritures “serveur” via request.auth == null ouvre en réalité l’accès aux utilisateurs non authentifiés.

Décisions à prendre (architecture sécurité)

  • Définition de l’admin :
  • Option A : custom claims (request.auth.token.admin == true) (recommandé)
  • Option B : rôle stocké dans un document (app_users/{uid}.app_user_role) (possible, mais bootstrap/admin initial à sécuriser)

Objectif minimal DEV/TEST (pour débloquer l’E2E Stripe)

  • foods : lecture publique
  • logs : autoriser au minimum create sans auth (si l’app logge avant login)
  • Stripe (Invertase) : règles customers/{uid}/... + products/...

5) Activer Authentication (DEV/TEST)

  • [x] Authentication → Get started
  • [x] Activer les providers utilisés (au minimum : Email/Password)

Pourquoi

  • Yinshi utilise Firebase Auth (web inclus).

Validation

  • [x] Le provider Email/Password est "Enabled".

6) Autoriser le domaine PWA test (Auth)

  • [x] Authentication → Settings → Authorized domains
  • [x] Ajouter : yinshi-test.yinshi.app

Pourquoi

  • Firebase Auth web bloque les domaines non autorisés.

Validation

  • [x] yinshi-test.yinshi.app apparaît dans la liste des domaines autorisés.

7) Passer en Blaze (quand on est prêt à installer Stripe)

  • [x] Plan → "Mettre à niveau" → Blaze

Pourquoi

  • Extensions + Cloud Functions requièrent généralement Blaze.

Validation

  • [x] La console affiche le plan "Blaze" pour yin-shi-dev.

8) Installer l’extension Stripe en DEV/TEST

  • [x] Extensions → installer invertase/firestore-stripe-payments
  • [x] Configurer Stripe en mode test (clés test + webhooks), selon l’assistant d’installation

Pourquoi

  • Reproduire le flux Stripe en environnement isolé, sans risque pour prod.

Validation

  • [x] L’extension apparaît comme installée.
  • [x] Les fonctions ext-firestore-stripe-payments-* sont déployées.
  • [ ] Stripe affiche des livraisons de webhook (deliveries) en succès (2xx) vers l’endpoint Firebase.
  • [ ] Firestore reçoit les documents sous customers/{uid}/checkout_sessions lors d’un test.

8bis) Déployer les Cloud Functions "métier" du repo sur DEV/TEST

Contexte

  • L’extension Stripe gère les écritures customers/{uid}/... et les webhooks.
  • Le passage "premium" côté app dépend des Cloud Functions du repo (mise à jour de app_users/{uid}.app_user_role).

Prérequis repo (une fois)

  • [x] Ajouter des alias de projets dans .firebaserc :
  • dev → yin-shi-dev
  • prod → yin-shi-1967c

Préparer l’environnement local

  • [x] Installer les dépendances NPM des functions (nécessaire car firebase.json exécute lint + build en predeploy) :
  • npm --prefix functions ci

Déploiement DEV/TEST

  • [x] Déployer sur yin-shi-dev (alias dev) :
  • firebase deploy --only functions --project dev --non-interactive

Notes

  • Premier déploiement 2nd gen : Eventarc/Cloud Run peut nécessiter un retry après quelques minutes (propagation des permissions).
  • Un warning peut apparaître sur la cleanup policy Artifact Registry (à traiter ensuite).

Validation

  • [x] Dans la console yin-shi-dev → Functions, voir :
  • syncStripeToAppUser
  • syncStripeToAppUserOnCreate

9) Test E2E minimal (PWA test → Stripe test → Webhook → Firestore)

  • [ ] Se connecter sur https://yinshi-test.yinshi.app/
  • [ ] Déclencher un checkout depuis la PWA
  • [ ] Payer avec une carte test (ex: 4242 4242 4242 4242)
  • [ ] Vérifier que customers/{uid}/checkout_sessions/{id} est créé puis mis à jour
  • [ ] Vérifier que Stripe → Webhooks affiche des deliveries récentes en succès
  • [ ] Vérifier que app_users/{uid}.app_user_role passe à Paid

10) Seed de la collection foods en DEV/TEST

Contexte

  • La base yin-shi-dev est vide par défaut.
  • Le code contient déjà une méthode d’import depuis un asset : importFoodsFromAssets('assets/bdd/aliments.json').

À décider

  • Option A : réactiver un bouton “Importer” visible uniquement pour admin (rapide).
  • Option B : script serveur (Admin SDK) / fonction one-shot pour importer (ne dépend pas des rules, plus sûr).

Validation

  • [ ] foods contient des documents et l’écran aliments affiche des résultats.

11) Stripe — URLs success/cancel en DEV/TEST

Contexte

  • Pour l’E2E test, success_url et cancel_url doivent pointer vers https://yinshi-test.yinshi.app/.

Validation

  • [ ] Après checkout test, Stripe redirige bien vers yinshi-test.yinshi.app.

12) Prochaines étapes (priorités)

  • [ ] Choisir une stratégie “admin” unique :
  • custom claims (request.auth.token.admin == true) ou
  • rôle stocké dans app_users/{uid}.app_user_role.
  • [ ] Définir et appliquer des rules DEV/TEST minimales (pour débloquer l’E2E) :
  • foods read public
  • logs create public (si logs avant login)
  • Stripe Invertase (customers/{uid}/..., products/...)
  • [ ] Valider sur yin-shi-dev :
  • plus de permission-denied au démarrage
  • lecture foods OK même si la base est vide
  • [ ] Choisir et exécuter une stratégie de seed foods en DEV/TEST.
  • [ ] Fixer les success_url / cancel_url DEV/TEST vers yinshi-test.yinshi.app.
  • [ ] Exécuter le test E2E Stripe complet et vérifier webhook + Firestore.