Skip to content

Stripe — Guide de Navigation

Date de création : 11 novembre 2025
Statut : En cours (PWA-first / DEV/TEST)
Propriétaire : Équipe
Dernière mise à jour : 18 décembre 2025

Bienvenue !

Vous êtes ici pour comprendre comment implémenter la gestion des abonnements Stripe de façon sécurisée et conforme légalement.

Ce guide vous explique comment naviguer dans les documents et par où commencer.

État actuel (18/12/2025) — exécution (résumé pour dev)

Ce qui est stabilisé

  • La PWA de test https://yinshi-test.yinshi.app/ s'affiche correctement.
  • Le crash web précédent (NoSuchMethodError: c.b is not a function) était lié au cache/service worker, pas à une régression fonctionnelle.
  • Un projet Firebase DEV/TEST séparé existe : yin-shi-dev.
  • L'extension Stripe Invertase est installée sur yin-shi-dev et le webhook test est configuré.
  • Les données minimales DEV/TEST ont été seedées (script scripts/seed-devtest.js + foods / payment_plans).
  • Les index Firestore nécessaires au flux consentements ont été déployés en DEV/TEST (via firestore.indexes.json).
  • Un paiement Stripe (mode test) via la PWA test a été réalisé avec succès.
  • Les Cloud Functions "métier" de synchro rôle Stripe → app_users sont déployées sur yin-shi-dev (ex: syncStripeToAppUser*).
  • Le repo gère désormais explicitement les environnements Firebase via alias .firebaserc (dev / prod).

Notes de déploiement (DEV/TEST)

  • Le déploiement Cloud Functions requiert les dépendances NPM dans functions/ (ex: npm --prefix functions ci) car firebase.json exécute lint + build en predeploy.
  • Premier déploiement 2nd gen (Node 22) : la mise en place Eventarc/Cloud Run peut nécessiter un retry après quelques minutes (propagation des permissions).
  • Un warning peut apparaître sur la cleanup policy d'Artifact Registry (impact coût faible, à traiter ensuite).

Ce qui bloque encore les tests end-to-end Stripe

  • Refaire un test E2E (idéalement avec un nouvel utilisateur) et vérifier que app_users/{uid}.app_user_role passe bien à Paid après checkout.

Faits vérifiés dans le repo (important pour reprendre le sujet)

  • Les rules Firestore sont versionnées : firestore.rules est référencé par firebase.json.
  • Les indexes Firestore sont versionnées : firestore.indexes.json est référencé par firebase.json.
  • Le rôle admin côté app est basé sur Firestore : champ app_users/{uid}.app_user_role (pas de custom claims consommés par l'app).

Stratégie "2 rails" (pour avancer sans bloquer)

Rail 1 — Court terme : débloquer Stripe E2E sur DEV/TEST (sans refondre l'auth)

Objectif : réussir un paiement Stripe en mode test depuis https://yinshi-test.yinshi.app/ et observer : - création de customers/{uid}/checkout_sessions/{sessionId} - apparition du champ url (ajouté par l'extension) - paiement test OK - webhook OK (deliveries 2xx) et documents subscriptions alimentés

Actions attendues

  • Définir des rules DEV/TEST minimales nécessaires au flux Stripe (sans toucher PROD).
  • Corriger les URLs success_url / cancel_url pour DEV/TEST.
  • Exécuter le test E2E et valider les preuves (Stripe deliveries + documents Firestore).

Documents à suivre

  • Checklist d'exécution (DEV/TEST) : CHECKLIST_FIREBASE_DEVTEST_YINSHI.md
  • Plan environnements : OPTIONS_ENVIRONNEMENTS_TEST_PROD.md

Rail 2 — Moyen terme : sécurité & industrialisation (PROD)

Objectif : sécuriser durablement les rules et éviter la dérive entre console et repo.

Décisions à prendre (avec le dev qui a implémenté l'auth)

  • Modèle admin :
  • Option A : custom claims (plus sûr, nécessite un mécanisme serveur)
  • Option B : rôle Firestore (app_users/{uid}.app_user_role) (actuel, nécessite des rules strictes anti auto-promotion)

Actions attendues

  • Versionner les rules dans Git (ajout de firestore.rules) et définir un mode de déploiement par environnement.
  • Revoir les rules PROD (et uniquement après décision A/B) et ajouter des garde-fous (notamment éviter d'utiliser request.auth == null comme pseudo "server" côté client).
  • Stabiliser l'update PWA (cache/service worker) pour éviter les clients bloqués sur d'anciens bundles.

Structure des Documents

docs/05_chantiers_actifs/stripe/
├── README.md ← Vous êtes ici
├── AUDIT_CONFORMITE_STRIPE.md ← Analyse des risques
├── CHECKLIST_SECURITE.md ← Bonnes pratiques de sécurité
├── CHECKLIST_FIREBASE_DEVTEST_YINSHI.md ← Setup Firebase DEV/TEST (PWA-first)
├── RESSOURCES_OFFICIELLES.md ← Liens officiels
├── BACKLOG_STRIPE.md ← User stories et épiques
├── SPRINT_PLANNING.md ← Planification détaillée
├── ARCHITECTURE_STRIPE.md ← Design technique (inclut l'état actuel)
└── OPTIONS_ENVIRONNEMENTS_TEST_PROD.md ← Plan de mise en place (2 projets Firebase + PWA-first)

Décisions (ADR) :

docs/06_decisions/
└── ADR-001-environnements-firebase-stripe-pwa-first.md ← Décision : 2 projets Firebase + PWA-first

✅ Maintenant / Plus tard (environnements Stripe)

Maintenant (PWA-first)

  • créer/configurer le projet Firebase DEV/TEST (Stripe en mode test)
  • faire pointer le build Web/PWA de test vers DEV/TEST
  • valider les parcours Stripe sur https://yinshi-test.yinshi.app/

Plus tard

  • Android : builds DEV/TEST vs PROD (tracks Play Console)
  • iOS : builds DEV/TEST vs PROD + TestFlight

🎯 Par Où Commencer ?

Chemin rapide (dev) — objectif : tester Stripe sur DEV/TEST

  • Lire la section "Stratégie \"2 rails\"" dans ce README.
  • Exécuter le Rail 1 en suivant : CHECKLIST_FIREBASE_DEVTEST_YINSHI.md.
  • Garder le Rail 2 (décision A/B + durcissement PROD + versioning rules) pour une discussion dédiée avec le dev qui a implémenté l'auth.

Étape 1 : Comprendre les Risques (30 min)

Lire : AUDIT_CONFORMITE_STRIPE.md

Sections importantes : - Section 1 : Contexte & Scope - Section 2 : Matrice de Conformité - Section 3 : Risques Identifiés - Section 4 : Recommandations Prioritaires

Objectif : Comprendre ce qu'il faut faire et pourquoi

Questions à vous poser : - ✅ Comprends-je les risques légaux ? - ✅ Comprends-je les risques de sécurité ? - ✅ Suis-je d'accord avec les priorités ?

Étape 2 : Valider avec l'Équipe (1h)

Réunion d'équipe : - Vous (PO) : Présenter l'audit - Dev 1 & 2 : Poser des questions - Ensemble : Valider l'approche

Points à discuter : - [ ] Sommes-nous d'accord avec les risques identifiés ? - [ ] Sommes-nous d'accord avec les priorités ? - [ ] Avons-nous les ressources nécessaires ? - [ ] Avons-nous des questions ?

Étape 3 : Lire les Bonnes Pratiques (2h)

Lire : CHECKLIST_SECURITE.md

Sections importantes : - Section 1 : OWASP Top 10 (survoler) - Section 2 : Stripe Security (lire en détail) - Section 3 : Firebase Security (lire en détail)

Objectif : Comprendre les bonnes pratiques de sécurité

Pour les développeurs : - [ ] Comprendre OWASP Top 10 - [ ] Comprendre Stripe Security - [ ] Comprendre Firebase Security - [ ] Savoir où trouver les ressources

Étape 4 : Accéder aux Ressources Officielles (Au besoin)

Lire : RESSOURCES_OFFICIELLES.md

Sections importantes : - Section 1 : OWASP - Section 2 : Stripe Security - Section 3 : Firebase Security - Section 4 : Conformité Légale (RGPD, CCPA, LGPD) - Section 7 : Plan de Lecture Recommandé

Objectif : Avoir accès à toutes les ressources officielles

Utilisation : - Chercher le sujet qui vous intéresse - Cliquer sur le lien officiel - Lire la documentation - Implémenter les recommandations

Étape 5 : Comprendre le Backlog (1h)

Lire : BACKLOG_STRIPE.md

Sections importantes : - Épique 1 : Documents Légaux & Consentement - Épique 2 : Validation des Webhooks Stripe - Épique 3 : Audit Trails Complets - Section 8 : Résumé des Phases

Objectif : Comprendre ce qu'il faut implémenter

Pour chaque épique, lire : - 🎯 Perspective PO : Pourquoi ? Quand ? Coûts/Bénéfices ? - 👨‍💻 Perspective Développeur : Comment ? Avec quoi ? Estimations ? - 👥 Perspective Client : Ça me sert à quoi ? C'est sûr ?

Étape 6 : Planifier les Sprints (1h)

Lire : SPRINT_PLANNING.md

Sections importantes : - Sprint 1 : Phase 1 - Critique - Sprint 2-3 : Phase 2 - Haute Priorité - Sprint 4-5 : Phase 3 - Moyenne Priorité

Objectif : Avoir un plan détaillé semaine par semaine

Pour chaque sprint : - [ ] Quelles sont les tâches ? - [ ] Combien de temps ça prend ? - [ ] Qui fait quoi ? - [ ] Quand on commence ?

Étape 7 : Comprendre l'Architecture (1h)

Lire : ARCHITECTURE_STRIPE.md

Sections importantes : - Architecture globale - Flux de paiement - Flux d'authentification - Sécurité

Objectif : Comprendre comment tout s'imbrique

Pour les développeurs : - [ ] Comprendre l'architecture globale - [ ] Comprendre les flux de données - [ ] Savoir où implémenter quoi

Étape 8 : Comprendre les Remboursements & Annulations (1h)

Lire : REMBOURSEMENTS_ET_ANNULATIONS.md

Sections importantes : - Section 1 : Politique de Remboursement - Section 2 : Gestion des Annulations - Section 3 : Conformité Légale - Délais d'Annulation - Section 4 : User Stories

Objectif : Comprendre les délais légaux et la politique de remboursement

Pour le PO : - [ ] Définir la politique de remboursement - [ ] Définir la politique d'annulation - [ ] Valider avec l'équipe

Pour les développeurs : - [ ] Comprendre les délais légaux - [ ] Comprendre l'implémentation Stripe - [ ] Savoir comment tester

Étape 9 : Comprendre la Gestion Avancée Stripe (1h)

Lire : GESTION_AVANCEE_STRIPE.md

Sections importantes : - Section 1 : Gestion des Litiges (Disputes) - Section 2 : Gestion des Moyens de Paiement - Section 3 : Upgrade/Downgrade d'Abonnement - Section 4 : Prévention de la Fraude (Stripe Radar)

Objectif : Comprendre les aspects avancés de Stripe

Pour le PO : - [ ] Comprendre les risques de fraude - [ ] Comprendre l'impact du churn involontaire - [ ] Planifier les priorités

Pour les développeurs : - [ ] Comprendre les webhooks avancés - [ ] Comprendre l'implémentation des SetupIntents - [ ] Comprendre la configuration de Radar

📋 Checklist de Démarrage

Pour le PO

  • [ ] Lire AUDIT_CONFORMITE_STRIPE.md (30 min)
  • [ ] Réunion d'équipe pour valider (1h)
  • [ ] Lire BACKLOG_STRIPE.md (1h)
  • [ ] Lire SPRINT_PLANNING.md (1h)
  • [ ] Lire REMBOURSEMENTS_ET_ANNULATIONS.md (1h)
  • [ ] Lire GESTION_AVANCEE_STRIPE.md (1h)
  • [ ] Planifier les sprints avec l'équipe (1h)

Total : 6h30

Pour les Développeurs

  • [ ] Lire AUDIT_CONFORMITE_STRIPE.md (30 min)
  • [ ] Lire CHECKLIST_SECURITE.md (2h)
  • [ ] Lire BACKLOG_STRIPE.md (1h)
  • [ ] Lire ARCHITECTURE_STRIPE.md (1h)
  • [ ] Lire REMBOURSEMENTS_ET_ANNULATIONS.md (1h)
  • [ ] Lire GESTION_AVANCEE_STRIPE.md (1h)
  • [ ] Réunion d'équipe pour questions (1h)

Total : 7h30

Pour l'Équipe

  • [ ] Réunion de démarrage (1h)
  • Présentation de l'audit
  • Questions/réponses
  • Validation de l'approche
  • Planification des sprints

🎬 Scénarios de Lecture

Scénario 1 : Vous êtes PO et pressé (2h)

  1. Lire AUDIT_CONFORMITE_STRIPE.md - Section 4 (Recommandations)
  2. Lire BACKLOG_STRIPE.md - Section 8 (Résumé des Phases)
  3. Lire SPRINT_PLANNING.md - Sprint 1

Résultat : Vous comprenez les priorités et pouvez planifier

Scénario 2 : Vous êtes Développeur et pressé (2h)

  1. Lire CHECKLIST_SECURITE.md - Section 2 & 3 (Stripe & Firebase)
  2. Lire BACKLOG_STRIPE.md - Épique 2 (Webhooks)
  3. Lire ARCHITECTURE_STRIPE.md - Flux de paiement

Résultat : Vous comprenez ce qu'il faut implémenter

Scénario 3 : Vous voulez tout comprendre (6h)

  1. Lire tous les documents dans l'ordre
  2. Prendre des notes
  3. Poser des questions à l'équipe

Résultat : Vous êtes expert sur le sujet

🔗 Liens Rapides

Documents Principaux

  • Audit : AUDIT_CONFORMITE_STRIPE.md
  • Sécurité : CHECKLIST_SECURITE.md
  • Ressources : RESSOURCES_OFFICIELLES.md
  • Backlog : BACKLOG_STRIPE.md
  • Sprints : SPRINT_PLANNING.md
  • Architecture : ARCHITECTURE_STRIPE.md

Ressources Officielles

  • OWASP Top 10 : https://owasp.org/www-project-top-ten/
  • Stripe Security : https://stripe.com/docs/security
  • Firebase Security : https://firebase.google.com/docs/firestore/security/start
  • RGPD : https://www.cnil.fr/fr/rgpd-par-ou-commencer
  • App Store : https://developer.apple.com/app-store/review/guidelines/
  • Play Store : https://play.google.com/about/developer-content-policy/

❓ Questions Fréquentes

Q : Par où je commence ?

R : Commencez par AUDIT_CONFORMITE_STRIPE.md pour comprendre les risques.

Q : Combien de temps ça va prendre ?

R : - Lecture : 5-6 heures - Implémentation : 4-6 semaines (5 sprints) - Total : 6-7 semaines

Q : C'est obligatoire de faire tout ça ?

R : - Phase 1 (Critique) : OUI, avant production - Phase 2 (Haute Priorité) : OUI, avant production - Phase 3 (Moyenne Priorité) : NON, avant expansion

Q : Qu'est-ce qui est le plus important ?

R : 1. Documents légaux (politique de confidentialité) 2. Validation des webhooks Stripe 3. Audit trails complets

Q : Où trouver de l'aide ?

R : - OWASP : https://owasp.org/ - Stripe Support : support@stripe.com - Firebase Support : support@firebase.google.com - CNIL (France) : https://www.cnil.fr/

📞 Contacts & Support

Interne

  • PO : Julien
  • Dev 1 : [Nom]
  • Dev 2 : [Nom]

Externe

  • Stripe : support@stripe.com
  • Firebase : support@firebase.google.com
  • Juriste : À chercher si besoin

✅ Checklist Finale

Avant de commencer l'implémentation :

  • [ ] Tous les documents lus
  • [ ] Équipe alignée
  • [ ] Ressources confirmées
  • [ ] Budget approuvé
  • [ ] Calendrier défini
  • [ ] Questions répondues
  • [ ] Prêt à commencer !

🎯 Prochaines Étapes

  1. Aujourd'hui : Lire README.md (ce document)
  2. Demain : Lire AUDIT_CONFORMITE_STRIPE.md
  3. Jour 3 : Réunion d'équipe
  4. Jour 4-5 : Lire les autres documents
  5. Semaine 2 : Commencer Sprint 1

Document créé par Cascade - Guide de démarrage pour Yinshi