Les choix d’ingénierieDécisions d’architecture4 min de lecture
0004 · Ce qui ne se défait pas appartient à l’ERP
Seul l’ERP confirme un paiement, émet une pièce, écrit dans le stockage et a les clés d’écriture. Le site lui parle par des canaux signés.
Statut : acceptée · Décidée : 18 octobre 2026, avec la séparation des applications · Sources : 90ccdfd846, apps/site/shared/schemas/env.schema.ts, packages/contracts/src/site-events.ts
Contexte
Une fois le site séparé de l’ERP (ADR 0002), il fallait décider qui fait les gestes qui engagent : confirmer un paiement, émettre une facture, rembourser, déposer un document, prévenir le personnel, inscrire un effacement de données, vider un cache.
Contraintes
- Stripe confirme un paiement par un webhook. Il arrive parfois en retard, en double, ou pas du premier coup.
- Une pièce émise ne se retouche pas, et sa numérotation ne doit pas avoir de trou (ADR 0008).
- Le site doit pouvoir ouvrir un paiement, obtenir un PDF ou annoncer une rétractation, sans avoir lui-même les moyens de les produire.
Alternatives
- Si chaque application traitait ses paiements, il faudrait deux webhooks, deux émetteurs de factures et deux numérotations sans trou.
- Une API générale de l’ERP pour le site ouvrirait une surface large, qu’il faudrait authentifier, documenter et versionner.
- Si le site écrivait lui-même ce dont il a besoin (statut payé, document), une faille du site pourrait le détourner.
Décision
Seul l’ERP reçoit le webhook Stripe, marque une commande payée, émet les pièces, rembourse et écrit dans Vercel Blob. Il est le seul à avoir la clé Stripe qui rembourse (complète sk_, ou de préférence restreinte rk_), le jeton Blob, les clés de notification et l’accès à la passerelle IA.
Le site n’a qu’une clé Stripe restreinte : sur un déploiement, STRIPE_SECRET_KEY doit commencer par rk_ (STRIPE_RESTRICTED_KEY, apps/site/shared/schemas/env.schema.ts). La prod en construction démarre sans elle. Un test vérifie que son environnement ne connaît ni le jeton Blob ni les clés de notification (env.schema.erp-rights.test.ts).
Quatre canaux HTTP relient les deux applications, avec un secret par usage : le cache, les événements et les documents. Pour les documents, les deux canaux de PDF partagent le même secret. Le corps des requêtes, la signature des événements et les tags de cache sont dans packages/contracts (Échanges entre les applications).
Raisons
Confirmées
- Le site a une clé restreinte parce que « le site ne crée que des sessions Checkout et des coupons, une clé sk_ ouvrirait tout le compte Stripe à un site compromis » (
env.schema.ts). - Le contrat des événements est dans un paquet « pour qu’aucun [des deux côtés] ne puisse le réécrire seul » (
packages/contracts/src/site-events.ts).
Hypothèses
- Le raisonnement fait pour Stripe vaut aussi pour le reste : on met tout ce qui est irréversible dans l’application la moins exposée. Tout le code va dans ce sens (Sécurité). Mais cette raison n’est écrite que pour la clé Stripe.
- Des canaux étroits suffisent, sans API générale, parce que le site n’a besoin que de quatre gestes.
Compromis
- Un paiement n’est confirmé que si l’ERP répond. S’il ne répond pas, Stripe renvoie l’événement plus tard (Stripe).
- Chaque canal a son schéma et sa vérification. Chaque usage a son secret, à poser à l’identique dans les deux projets Vercel.
- Le cache du site dépend d’un avis envoyé par l’ERP (
POST /api/revalidate). Si l’avis se perd, la page reste périmée jusqu’à la fin de son profil (ADR 0007).
Conséquences
- Au pire, une faille du site peut créer des commandes en attente de paiement et écrire les données d’un compte client.
- Un événement du site ne contient que sa sorte et un identifiant. L’ERP relit le reste dans la base. Et avant de lire quoi que ce soit, il refuse une signature fausse ou trop ancienne.
- Quand un nouveau geste doit passer d’une application à l’autre, on ouvre un canal décrit dans
packages/contracts. On ne donne pas d’accès direct.
Risques résiduels
- L’ERP concentre tout ce qui engage. Une faille de l’ERP, ou un compte du personnel volé, donne accès à l’argent et à toutes les données. Deux choses limitent ce risque : la connexion récente exigée pour les gestes lourds, et la base qui refuse de réécrire le passé (ADR 0008, ADR 0011).
- Si l’ERP est en panne longtemps, les confirmations de paiement attendent. Stripe relivre un événement refusé pendant quelques jours, puis il arrête. Chaque matin, la veille va chercher chez Stripe les événements jamais livrés (Stripe les garde trente jours) et les fait repasser par le webhook, sans doublon (
recoverUndeliveredStripeEvents,stripe-event-recovery.service.ts). Elle liste aussi les commandes dont le paiement n’a jamais été confirmé (stale-pending-sessions). Au-delà de trente jours, il ne reste que l’espace Stripe.
Quand la revoir
- Avec un deuxième canal de vente (une place de marché, un second site), chaque appelant ajouterait ses canaux et ses secrets. Au-delà de quelques-uns, une API de l’ERP authentifiée par appelant coûterait moins cher.
- Si les pertes d’événements entre les applications se répétaient, une file durable remplacerait l’envoi unique (Webhooks et échanges).