Les choix d’ingénierieÉtudes de cas techniques14 min de lecture
Un ordre dont on ne sait pas s’il est parti
Un remboursement envoyé à Stripe qui reste sans réponse, un e-mail dont Resend n’a rien dit, une vente envoyée deux fois au magasin. Je raconte comment l’ERP traite l’issue inconnue comme un état à part, avec des clés tirées du fait annoncé et des états qui ne reculent pas.
Le problème
Un appel à un service extérieur a trois issues. Il a réussi, il a échoué, ou on ne sait pas. Quand le délai expire, que la connexion tombe ou que le serveur répond par une erreur générique, la demande est peut-être partie. Le code le plus simple range cette troisième issue avec l’une des deux autres. Dans un magasin, les deux choix coûtent cher.
Les audits des remboursements de septembre 2026 en ont trouvé deux exemples.
Le 1er septembre, un remboursement dont la réponse de Stripe s’était perdue restait en attente. C’était juste, parce que la demande avait peut-être abouti. Si on avait fermé la ligne, on aurait rendu remboursable un montant peut-être déjà parti. Sauf que rien ne la fermait ensuite. Le plafond remboursable de la commande restait amputé. Le webhook n’avait aucun identifiant Stripe pour retrouver la ligne. Et la veille ne la signalait qu’au quatorzième jour, celui où le client doit avoir été remboursé après une rétractation (article L221-24 du Code de la consommation, 68416dd042).
Le 4 septembre, la reprise qui interroge Stripe écrivait son résultat sous une condition trop large (status: { notIn: [SUCCEEDED] }). Sauf que trois lignes plus haut, elle venait de faire un aller-retour chez Stripe, et ça dure des secondes. Si un webhook fermait la ligne en échec pendant cet appel, une lecture plus ancienne le réécrivait. L’écriture ne regardait pas non plus son nombre de lignes modifiées, et l’écran annonçait « statut appliqué » alors que rien n’avait été écrit (d1a24c301e).
On retrouve le même problème ailleurs, sous d’autres formes. Au magasin, un double clic ou un réseau qui reprend envoie deux fois la même vente. Stripe livre ses événements au moins une fois et sans ordre garanti, et un paiement peut arriver pendant que l’atelier annule la commande. Resend peut ne rien répondre dans le délai que le code lui laisse (RESEND_TIMEOUT_MS) alors que l’e-mail est parti. Et certains e-mails sont obligatoires, comme l’accusé de réception d’une rétractation.
Les contraintes
- Un doublon ne s’efface pas. La base refuse de modifier ou de supprimer un encaissement, un avoir ou une facture émise (ADR 0008). Une vente enregistrée deux fois se corrige par une nouvelle écriture, qui reste visible dans la chaîne des encaissements.
- Une transaction ne traverse ni Stripe ni Resend. L’écriture en base et l’appel extérieur sont deux étapes. Si une panne arrive entre les deux, l’une est faite et pas l’autre (Données).
- Le projet n’a ni file d’attente durable, ni processus qui tourne en continu, ni astreinte (Dette, risques et évolutions). Il n’y a que la veille, qui passe une fois par matin.
- Stripe et Resend acceptent une clé d’idempotence. Quand une demande reprend la même clé, Stripe lui rend la réponse de la première. Resend refuse une clé déjà servie, et le code reconnaît ce refus (
keyAlreadyUsed). - Stripe relivre un événement non acquitté pendant trois jours (
STRIPE_EVENT_RETRY_SECONDS), et il ne garantit pas l’ordre.
Les alternatives
- Traiter toute erreur comme un échec et laisser la personne recommencer. C’est le réflexe le plus courant, et c’est comme ça qu’on rembourse deux fois quand la première demande avait abouti. Le commit du 1er septembre l’écarte pour cette raison : fermer la ligne « libérerait un plafond peut-être déjà consommé » (
68416dd042). - Traiter toute erreur comme un succès. L’écran reste calme, et le client attend une facture ou un remboursement qui ne viendra pas.
- Confier les envois à une file d’attente durable et à un processus qui les reprend. La file garantit qu’une demande sera retentée. Mais à chaque reprise, le processus retombe sur la même question : est-ce que la tentative précédente est partie ? Donc il lui faut les mêmes clés d’idempotence, avec en plus une file à héberger et à surveiller. Le projet n’en a pas, et la page sur la dette dit à partir de quand ce choix deviendrait mauvais.
- Au magasin, garder la clé de la vente dans une colonne unique de la base. Elle serait durable, et la garde ne dépendrait d’aucun autre service. Le code la garde dans Redis (voir les limites).
Seule la première piste est écartée par écrit. Les autres, ce sont celles qu’un lecteur se poserait, et je n’ai trouvé aucune trace qui montre qu’elles ont été comparées.
La décision
L’issue inconnue est un état à part. Le code ne la confond ni avec le succès ni avec l’échec. Il laisse la ligne dans un état intermédiaire, il le dit à la personne et il lui propose une sortie qui interroge l’autre côté. Trois règles vont avec ce choix.
- Une demande porte une clé tirée du fait qu’elle annonce. Un remboursement porte son identifiant local. L’accusé de rétractation porte la commande et la date de la demande. Une vente au magasin porte un identifiant tiré une fois par ticket. Du coup, une reprise retombe sur la même clé, d’où qu’elle vienne.
- Une écriture qui applique un état venu de l’extérieur nomme les états qu’elle a le droit de quitter, et elle lit son nombre de lignes modifiées. Une lecture périmée perd alors la course, alors qu’avant elle la gagnait.
- Un état terminal ne se réécrit pas. Quand l’extérieur le contredit, une alerte part et c’est une personne qui tranche.
L’implémentation
Une clé par fait
Au magasin, le navigateur tire une clé au premier envoi d’un ticket et la garde jusqu’à ce que le ticket soit enregistré (crypto.randomUUID(), dans apps/erp/modules/payments/components/off-site/off-site-basket.tsx pour une vente et apps/erp/modules/orders/components/store-payments-section.tsx pour un encaissement). Donc un second clic ou un envoi repris porte la même clé. Le serveur la réserve dans Redis pour une durée limitée (SUBMISSION_TTL_SECONDS), avec un SET … NX qui ne réussit que pour le premier arrivé (apps/erp/shared/server/idempotency.ts#claimSubmission). Il y a trois réponses possibles.
- La clé est libre, et la vente s’enregistre.
- La clé est réservée mais n’a pas de résultat, et l’envoi est refusé comme déjà en cours.
- La clé porte l’identifiant d’une vente enregistrée. Le serveur relit cette vente et rend la même réponse que la première fois (
record-off-site-basket.ts).
Si l’enregistrement échoue, la clé est libérée et la personne peut recommencer. Une vente écrit aussi sa clé sur la commande, sous une contrainte d’unicité (Order.submissionKey) : quand la réservation Redis a expiré ou manque, la base retrouve la vente au lieu d’en écrire une seconde (off-site-sale.service.ts#BasketAlreadyRecorded).
Les remboursements partent vers Stripe avec leur identifiant local comme clé (stripe-refund.service.ts#sendReservedRefund). Pour les e-mails, c’est la même logique. L’accusé de réception d’une rétractation a pour clé la commande et la date de la demande (packages/orders/src/withdrawal.ts#createWithdrawalNotices), et un avis au client a pour clé la commande et sa dernière modification. Comme la clé vient du fait annoncé, deux chemins qui annoncent le même fait se rencontrent chez le fournisseur, par exemple la reprise d’un traitement et un nouveau clic.
Trois issues, et une suite pour chacune
sendReservedRefund trie les erreurs de Stripe. Un refus certain (isPermanentStripeFailure) ferme la ligne en échec, et le montant redevient remboursable. Tout le reste (délai dépassé, coupure réseau ou erreur du serveur) laisse la ligne en attente, envoie l’alerte « réponse Stripe PERDUE — le remboursement est peut-être parti » et dit à la personne que l’issue est incertaine. Un dernier cas a sa propre branche : Stripe a accepté, mais l’identifiant n’a pas pu être noté en base. Dans ce cas, la ligne reste en attente, et le webhook la retrouvera avec l’identifiant local passé en métadonnées.
Pour les e-mails, la liste est écrite dans l’autre sens. isCertainlyUnsent (packages/infra/src/email.ts) nomme les codes d’erreur de Resend qui prouvent que rien n’est parti : une clé invalide, une validation refusée, un quota atteint, un envoi que le code n’a pas tenté. Tout ce qui n’est pas dans la liste, délai dépassé compris, compte comme peut-être parti. Du coup, si Resend ajoutait un code d’erreur demain, il tomberait du côté prudent.
L’accusé de réception d’une rétractation montre le geste en entier. Il part d’abord, et la commande n’est notée accusée (withdrawalAcknowledgedAt) qu’après, par une écriture conditionnelle. Ensuite, il y a quatre cas. Si Resend a déjà vu la clé, l’e-mail est parti et la commande est notée. Si une autre requête envoie sous la même clé, elle la notera. Si l’échec est certain, rien n’est noté et l’erreur remonte. Dans tous les autres cas, rien n’est noté non plus, et une alerte part. La commande reste « jamais accusée » : la veille et le bouton « Renvoyer l’accusé » de la fiche le relancent sous la même clé, que Resend ne sert pas deux fois dans les 24 heures. L’ordre inverse, la marque avant l’envoi, évitait tout doublon. Mais un processus tué entre les deux laissait une commande notée accusée sans e-mail parti, et plus rien ne la relisait. Un doublon reste possible si la reprise arrive plus de 24 heures après un premier envoi, alors qu’un accusé que la loi impose ne peut plus manquer sans que personne le sache.
Sortir de l’attente en interrogeant Stripe
Une ligne en attente sans identifiant Stripe ne peut pas sortir par le webhook. Le commit du 1er septembre le dit : le webhook « ne se déclenche que si Stripe parle, et tout le problème est que Stripe n’a peut-être jamais reçu la demande » (68416dd042). Du coup, la reprise va interroger Stripe (stripe-refund.service.ts#reconcileStripeRefund). Elle cherche le remboursement par son identifiant Stripe. S’il n’y en a pas, elle le cherche par l’identifiant local parmi les remboursements du paiement. Pour une ligne sans identifiant Stripe, elle refuse de chercher avant un délai (LOST_REFUND_RESPONSE_MAX_AGE_MS). Sinon, elle pourrait conclure qu’une demande n’existe pas alors qu’elle est encore en route.
Stripe peut répondre de trois façons.
- Il connaît le remboursement. La ligne prend son identifiant et son statut, par la même fonction que le webhook (
refund-settlement.ts#applyStripeRefund). - Il ne le connaît pas. La ligne se ferme en échec avec la mention « jamais reçu par Stripe », le montant redevient remboursable, et on peut réessayer sans risque.
- Il ne répond pas. La reprise ne conclut rien, et la ligne reste où elle était.
Les issues forment une union typée (StripeRefundReconciliation), et l’action la traduit en une phrase pour la personne. Ce que personne n’a repris, c’est la veille qui le ramasse : un remboursement en attente depuis trop longtemps (PENDING_REFUND_MAX_AGE_MS) apparaît dans l’e-mail du matin (Une veille qui dit ce qu’elle n’a pas pu lire).
Un état ne recule pas
Le webhook ne se fie pas au contenu de l’événement. Il relit le remboursement chez Stripe (webhook-refund.service.ts), comme la reprise. Deux relectures lancées l’une après l’autre peuvent revenir dans l’ordre inverse. C’est ce qui causait la réécriture du 4 septembre.
Du coup, l’écriture nomme les états d’où elle a le droit de partir. Un état « en cours » (en attente, action requise) s’applique seulement à une ligne encore en cours. Un état d’arrivée (abouti, échoué, annulé) s’applique à une ligne en cours ou aboutie, parce qu’un remboursement abouti peut encore échouer chez Stripe. Une ligne échouée ou annulée ne change plus. Cette règle est écrite une seule fois, dans une fonction que l’écriture met dans son where (settleRefund).
apps/erp/shared/lib/refund-status.ts · lignes 32–37export function refundSourceStatuses(target: RefundStatus): RefundStatus[] {
if (target === RefundStatus.PENDING || target === RefundStatus.REQUIRES_ACTION) {
return IN_FLIGHT_REFUND_STATUSES;
}
return NON_TERMINAL_REFUND_STATUSES;
}Une relecture périmée trouve alors une ligne qui a déjà avancé. Son écriture ne modifie rien, et le code lit ce zéro. Le webhook répond normalement, et la reprise annonce qu’elle a perdu la course (RECONCILE_RACED). Avant le 4 septembre, elle annonçait « statut appliqué ». Le test rejoue les deux cas sur une vraie base : il retient la première relecture de Stripe jusqu’à ce que la seconde ait abouti.
Un état terminal que Stripe contredit ne bouge pas, mais il est signalé. Si Stripe fait revivre un remboursement que la base considère comme échoué, une alerte prévient que l’argent est peut-être parti (applyStripeRefund). Les litiges suivent la même règle : un litige gagné ou perdu ne revient pas en arrière sur un événement tardif (dispute-webhook.db.test.ts).
Pour tout l’ERP, le test des transitions vérifie qu’une colonne d’état écrite est dans le where d’une écriture conditionnelle (Des tests qui lisent le code à la place du relecteur). La liste des états de départ, ce sont les tests de chaque domaine qui la vérifient.
Inscrire un événement ne suffit pas à le traiter une fois
L’ERP inscrit chaque événement Stripe par son identifiant avant de le traiter (WebhookEvent), et il le marque traité à la fin. Un doublon déjà marqué reçoit une réponse immédiate. Un doublon inscrit mais pas marqué est traité à nouveau, parce que le premier passage a pu s’arrêter au milieu. Une alerte qui n’a pas pu partir fait aussi répondre une erreur, pour que Stripe relivre (stripe-webhook.service.ts).
Donc la table ne garantit pas qu’un événement sera traité une seule fois. Elle évite de refaire un événement déjà traité. Ce qui empêche le double effet, c’est l’écriture de chaque traitement : une commande passe payée seulement si elle était en attente, et le stock baisse seulement s’il suffit. Une relivraison retrouve l’état déjà avancé et ne fait rien (Données). Et pour un événement que Stripe n’a pas réussi à livrer, même en trois jours d’essais, la veille demande chaque matin la liste des livraisons manquées et rejoue ces événements par le même chemin (Stripe).
Le même raisonnement règle un croisement plus rare : l’atelier annule une commande au moment où son paiement arrive. L’annulation prend le verrou de la commande en premier, alors que le client vient de payer. L’argent est chez Stripe, et l’ERP ne peut pas le refuser. Le webhook, qui attendait le verrou, trouve la commande annulée. Il encaisse le paiement sans décompter le stock, émet la facture et alerte pour qu’on rembourse. La base décrit ce qui s’est passé, et la suite revient à une personne.
Provoquer la course dans le test
Si on espère reproduire une course avec des pauses, on obtient un test qui passe par chance. Du coup, les tests de concurrence forcent l’ordre d’arrivée. Une transaction du test prend d’abord le verrou de la ligne visée. Le test lance le premier geste et attend que Postgres compte une session bloquée sur un verrou (pg_stat_activity). Il lance le second, attend une deuxième session bloquée, puis relâche le verrou. Si le croisement n’a pas lieu, le test échoue et le dit. Il ne passe pas sans avoir rien vérifié.
packages/testing/src/db-fixtures.ts · lignes 161–171export async function untilLockWaiters(expected: number): Promise<void> {
const deadline = Date.now() + 10_000;
while ((await lockWaiters()) < expected) {
if (Date.now() > deadline) {
throw new Error(
`jamais ${expected} sessions en attente de verrou : le croisement n'a pas eu lieu`,
);
}
await new Promise((resolve) => setTimeout(resolve, 25));
}
}Le 16 novembre 2026, quatorze fichiers de test de l’ERP et du site s’en servent (compté avec rg -l untilLockWaiters, sans les fichiers d’aide). Un aller-retour chez Stripe ne prend aucun verrou en base. Pour le reproduire, le double de Stripe retient la première relecture derrière une promesse, et le test la libère seulement quand la seconde a abouti (refund-stale-read.db.test.ts).
Les résultats
- Une vente envoyée deux fois au magasin est enregistrée une seule fois, et le second envoi reçoit la réponse du premier.
- Un remboursement resté sans réponse attend, puis la reprise le range selon ce que Stripe en sait. Les deux relectures croisées du 4 septembre finissent sur l’état le plus récent, sur une vraie base (
refund-stale-read.db.test.ts). - Une reprise n’envoie pas deux fois un e-mail obligatoire, et un envoi incertain arrive en alerte avec ce qu’il faut vérifier.
- Une relivraison de Stripe ne compte rien deux fois, et un paiement qui croise une annulation est encaissé, facturé et signalé (
cancellation-versus-payment.db.test.ts).
Les limites
- Quand Redis manque ou ne répond pas, la garde du magasin laisse passer, et le journal le dit. La raison est écrite : bloquer la caisse parce qu’un cache est tombé serait pire (Dette, risques et évolutions). Mais un encaissement doublé ne se corrige que par une nouvelle écriture. Une clé enregistrée en base avec la vente, sous une contrainte d’unicité, fermerait ce trou sans dépendre d’un second service. Je n’ai trouvé aucune trace écrite qui explique le choix de Redis.
- La réservation de la clé expire. Un encaissement repris après sa durée (
SUBMISSION_TTL_SECONDS) n’est plus reconnu, alors qu’une vente l’est encore par sa clé en base. Et si le résultat n’a pas pu être noté dans Redis, les nouveaux essais restent refusés comme « en cours » jusqu’à l’expiration (settleSubmissionl’écrit dans le journal). - L’issue incertaine d’un e-mail revient à une personne. Resend ne renvoie aucun événement aux applications (Stripe et Resend), donc l’ERP ne peut pas vérifier tout seul qu’un e-mail est parti. Tout repose sur l’alerte et sur quelqu’un qui la lit.
- La partition des états est écrite une fois pour les remboursements, mais chaque modèle à état a la sienne. Le test des transitions vérifie que l’état est dans le
where. Il ne peut pas dire si la liste des états de départ est juste. Ça, c’est aux tests de chaque domaine de le faire.