Aller au contenu
Meubles Morinière

Le codeArchitecture29 min de lecture

Données

Le modèle Prisma et PostgreSQL d’un magasin de meubles (catalogue, ventes, stock, achats, comptabilité) : ses relations, ce que la base refuse elle-même, les transactions et les verrous, avec leurs raisons et leurs limites.

L’ERP et le site tournent sur une seule base Postgres, hébergée chez Neon. Un seul schéma Prisma la décrit (packages/db/prisma/schema.prisma). Le modèle suit une règle : tout ce qui touche à l’argent, à la loi et au stock, c’est la base qui le protège, peu importe le code qui écrit. Le reste est dans le code, où on peut le changer sans migration. Les règles de calcul (prix, TVA, délais, stock, comptabilité) sont dans Logique métier. Ici, je décris la forme des données sur lesquelles elles s’appuient.

ChoixProblème régléCe qui le fait respecter
Des migrations écrites à la mainPrisma ne sait écrire ni une contrainte métier, ni un triggermigrations SQL commentées, jouées par l’ERP avant la fusion
Un modèle à la mesure du magasinstock et fabrication à la commande, vente en ligne, au magasin et sur devis, livraison de meublesdeux politiques de stock, deux canaux de vente, deux états par commande
Une vente garde ce qui a été venduune retouche du catalogue réécrivait les ventes, les factures et les déclarations passéescolonnes recopiées à la création de la ligne, identifiants gelés par la base
L’argent en centimes entiersà cause d’un arrondi, la facture, le remboursement et la déclaration ne tombaient plus d’accorddes entiers partout, des égalités vérifiées par CHECK
Des relations qui retiennentune cascade effaçait de l’argent, et un remboursement pouvait viser la ligne d’une autre commandeonDelete écrit pour chaque relation, clés composites, index uniques partiels
Ce que la base refuse elle-mêmeune règle que seul le code impose saute au premier script, ou dès qu’une deuxième application écritCHECK, gardes, valeurs calculées par la base
Le stock, un solde et son journalun solde seul ne dit pas pourquoi il a bougé, et un journal seul ne se verrouille passolde et mouvement écrits dans la même transaction, réservations déduites
Des transactions courtes et verrouilléesdeux gestes en même temps vendaient la même pièce ou émettaient deux facturesFOR UPDATE ordonné, verrous consultatifs, mises à jour conditionnelles
Deux rôlesle site, ouvert à tout Internet, écrit dans la même base que l’ERPmoriniere_site, droits par colonne, gardes propres au site
Vérifier la base réelleune garde absente ou désactivée ne se voit paspnpm db:invariants à chaque migration jouée en prod, tests sur une vraie base Postgres

Le schéma Prisma et des migrations écrites à la main

Prisma décrit les tables, les relations et les index, et il en tire un client typé. Par contre, il ne sait pas dire qu’un stock ne descend pas sous zéro, qu’une facture ne se modifie plus ou qu’un encaissement s’enchaîne au précédent. Dans son schéma, il n’y a pas de place pour une contrainte CHECK, un trigger ou une fonction, et ses migrations ne les comparent pas.

Le schéma et les migrations sont dans packages/db/prisma, et @meublesmoriniere/db exporte le client généré (client) et les énumérations (enums). Dans le schéma, il y a tout ce que Prisma sait exprimer, y compris les index uniques partiels (partialIndexes) et les lectures jointes en une requête (relationJoins). Le reste, on l’écrit en SQL directement dans la migration : contraintes, triggers, fonctions, extension pg_trgm, collation française. Quand une migration pose ou change une règle, elle commence par un commentaire qui dit pourquoi. Et si la règle vient de la loi, elle cite sa source (20261110100000_ventes_scellees_a_l_encaissement cite le Code général des impôts). Seul l’ERP joue les migrations, et il les joue avant la fusion sur main. La raison, c’est que le build prérend des pages qui lisent la base de prod. Si le code était déployé avant sa migration, ça casserait le build ou les pages. Une migration déjà jouée ne se retouche plus. Pour corriger, on écrit une nouvelle migration.

Du coup, le schéma se lit comme le dictionnaire des données, et les migrations comme le registre des règles, avec leurs raisons. Quand une migration retire une possibilité, elle peut d’abord vérifier que la prod ne s’en sert pas, et refuser de s’appliquer si c’est le cas. Par exemple, 20261109160000_grille_de_port_proportionnee s’arrête si un tarif a encore un supplément par pièce. Les connexions s’ouvrent en UTC (POOL_OPTIONS, packages/infra/src/prisma-adapter.ts). Un instant, c’est un timestamptz au millième. Une date civile (une fermeture, la validité d’un devis), c’est un date.

Cette approche a deux limites :

  • Ce que Prisma ne voit pas, il ne le vérifie pas. Si on oublie une contrainte dans une migration, ni la génération du client ni la compilation n’échouent. C’est pour ça qu’il y a une liste de ce que la base doit avoir, écrite dans le code et comparée à la base (plus bas).
  • Le client typé ne connaît pas les contraintes. Un refus de la base arrive à l’exécution, pas à la compilation, et l’ERP doit le traduire (plus bas).

Un modèle à la mesure du magasin

Un magasin de meubles vend des pièces en stock et des meubles fabriqués à la commande. Il vend en ligne, au magasin et sur devis. Il encaisse des acomptes, livre en colis ou en messagerie, reprend l’ancien mobilier, déclare l’éco-contribution de chaque pièce vendue et achète du bois dont il doit pouvoir montrer l’origine. Le schéma se lit par domaines, et la figure en montre le cœur.

Le cœur du schéma, de la pièce au clientQuote référence Order (Restrict), Customer (Restrict). QuoteLine référence Quote (Cascade), ProductVariant (SetNull). Order référence Customer (Restrict). OrderItem référence Order (Restrict), ProductVariant (SetNull). Payment référence Order (Restrict). Refund référence Order (Restrict), Payment (Restrict, clé composite). RefundItem référence Refund (Restrict, clé composite), OrderItem (Restrict, clé composite). Invoice référence Order (Restrict), Refund (Restrict, clé composite), Payment (Restrict, clé composite). InvoiceLine référence Invoice (Restrict). PurchaseOrder référence Supplier (Restrict). PurchaseOrderLine référence PurchaseOrder (Cascade), ProductVariant (SetNull), OrderItem (Restrict). Product référence Supplier (Restrict). ProductVariant référence Product (Cascade). StockMovement référence ProductVariant (Cascade), Order (Restrict), PurchaseOrderLine (Restrict).CustomerQuoteQuoteLineOrderOrderItemPaymentRefundRefundItemInvoiceInvoiceLineSupplierPurchaseOrderPurchaseOrderLineProductProductVariantStockMovement
Lu dans packages/db/prisma/schema.prisma à chaque build de cette documentation. Chaque flèche part de la table qui porte la clé. Trait plein : Restrict, la cible ne se supprime pas tant qu’une ligne la référence ; tirets : Cascade ou SetNull, la ligne part avec sa cible ou s’en détache. Survoler une table isole ses flèches.
  • Le catalogue : un meuble (Product : fiche, adresse, statut brouillon, publié ou archivé, délai de fabrication) se vend en déclinaisons (ProductVariant : finition, taille, prix, coût, éco-contribution et son code de catégorie, cotes en millimètres, poids en grammes, politique de stock). Les couleurs et les matières sont des référentiels rangés par famille, et le site les propose en filtres. Elles sont reliées à la déclinaison par des tables de liaison explicites qui gardent un rang. La première matière, c’est la matière principale. Une photo appartient au meuble et se rattache à certaines de ses déclinaisons (VariantMedia). Les catégories forment un arbre. La marque contient le fabricant et la personne responsable dans l’Union, que la fiche d’un produit doit nommer. Le lexique d’un fournisseur (SupplierLexiconEntry) traduit les mots de ses documents en couleurs et matières du catalogue.
  • Deux sortes de pièces : une déclinaison est soit suivie en stock (TRACKED), soit fabriquée à la commande (MADE_TO_ORDER). Dans le deuxième cas, elle n’a pas de solde (ProductVariant_made_to_order_stock_check). Le délai de fabrication s’écrit en semaines, avec une fourchette. La commande garde la date promise au client (promisedWorkshopDueAt) à côté de l’échéance actuelle de l’atelier (workshopDueAt). Si un fournisseur est en retard, l’échéance de l’atelier recule, mais la date promise ne bouge pas (Délais et dates promises).
  • La vente : un devis (Quote, QuoteLine : lignes du catalogue ou libres, avec les précisions de l’atelier, cotes, essence, finition) devient une commande quand il est accepté, et une seule (Quote.orderId est unique). Une commande (Order) est créée sur le site (WEB) ou au magasin (STORE), et chaque canal a ses obligations. En ligne, il faut les conditions générales acceptées et une adresse complète (Order_channel_check). Au magasin, l’acompte ne peut pas dépasser le total (Order_store_check). La commande a deux états côte à côte, l’argent (PaymentStatus) et la préparation (FulfillmentStatus), et la base les relie : on ne prépare rien avant le paiement, sauf pour une vente du magasin, qui part en fabrication sur acompte (Order_fulfillment_payment_check). Elle regroupe ses lignes (OrderItem), ses encaissements (Payment), ses remboursements pièce par pièce (Refund, RefundItem), ses factures, factures d’acompte et avoirs (Invoice, InvoiceLine), ses colis (OrderParcel), les étapes de sa préparation (OrderStep) et les litiges ouverts par la banque du client (Dispute). Une commande en ligne ne demande pas de compte. Elle a ses propres coordonnées, et la fiche client (Customer) est facultative.
  • La livraison : il y a un mode (ShippingMethod : retrait, colis ou messagerie, délai de transport, reprise de l’ancien meuble), des zones faites de débuts de code postal (ShippingZone, ShippingZoneArea), et un tarif par mode, zone et tranche de poids (ShippingRate). C’est la tranche de poids qui dit qu’un buffet ne part pas en colis. La commande garde le rendez-vous de livraison, les réserves notées à la réception et la réclamation au transporteur.
  • Le stock et les achats : chaque pièce suivie a son solde et son journal (StockMovement, plus bas). Dans les commandes fournisseurs (PurchaseOrder, PurchaseOrderLine), une ligne peut être liée à la ligne du client pour qui la pièce est commandée. Une ligne de bois a la référence de diligence raisonnée que demande le règlement européen contre la déforestation, ou la raison pour laquelle elle n’en a pas (DueDiligenceBasis). Une facture électronique reçue d’un fournisseur (SupplierInvoice) garde ce que le document dit, figé au dépôt, avec l’achat qu’elle facture et son état.
  • La comptabilité, les comptes, les réglages : les compteurs de numéros par série (DocumentCounter), les clôtures de caisse (CashClosure), les déclarations de TVA (AccountingDeclaration), le personnel et les comptes clients du site (User et les tables de Better Auth), les réglages du magasin, en une ligne unique (StoreSettings_singleton_check), et ses fermetures (ClosurePeriod).

Ce modèle a ses limites :

  • Une déclinaison, c’est une combinaison complète, avec sa référence, son prix et son stock. Le meuble ne nomme qu’un seul axe de choix (choiceTerm : « Assise », « Finition »). Il n’y a pas de grille d’options combinées. Un meuble très configurable se vend donc sur devis, en lignes libres avec leurs précisions. Sinon, il faudrait des centaines de déclinaisons.
  • Order est une table large. Chaque étape de la livraison, chaque étape de la rétractation et chaque avis envoyé a sa colonne datée. Une table d’événements serait plus étroite. Mais chaque contrôle sur l’ordre des étapes (une livraison après l’expédition, Order_delivery_sequence_check) deviendrait un trigger entre lignes. Et pour savoir si un avis est parti, il faudrait une recherche, alors qu’aujourd’hui on lit une colonne. OrderStep garde la chronologie des étapes de préparation pour l’affichage, mais aucune décision ne s’appuie dessus.

Une vente garde ce qui a été vendu

Le catalogue change tous les jours : un prix baisse, on corrige un nom, une déclinaison disparaît, un code de catégorie d’éco-contribution change. Mais une vente, sa facture et la déclaration du trimestre doivent garder ce qui a été vendu, au prix et avec la description du moment.

Du coup, quand une ligne est créée, elle recopie ce qu’elle vend : nom, déclinaison, référence, GTIN et précisions de l’atelier (colonnes …Snapshot), prix unitaire, taux de TVA, éco-contribution et son code de catégorie, fabrication à la commande ou non, coût d’achat. La commande recopie le nom de sa zone et de son mode de livraison, et la base refuse une zone sans son nom (Order_shippingZone_snapshot_check). La facture a tout ce qu’il lui faut : l’identité du vendeur, les adresses de l’acheteur et de livraison, ses totaux et ses propres lignes (InvoiceLine). On peut donc la relire sans la commande ni le catalogue, et son PDF est archivé avec son empreinte (Commandes et comptabilité). La base gèle aussi les identifiants que d’autres citent : l’adresse d’un meuble une fois qu’il est publié (Product_slug_guard), et la référence d’une pièce une fois qu’elle a été commandée, chiffrée, achetée ou facturée (ProductVariant_reference_guard).

Retoucher le catalogue ne réécrit donc pas le passé. La clé d’une ligne vers sa déclinaison peut se détacher (SetNull), donc quand on retire une déclinaison, ses lignes restent intactes. Le code d’éco-contribution est un bon exemple. La déclaration à Ecomaison compte les pièces vendues par code. Quand on le lisait sur la déclinaison actuelle, ça réécrivait les trimestres déjà déclarés. Du coup, un trigger le recopie sur la ligne quand elle est créée ou qu’elle change de déclinaison, puis il le garde (OrderItem_eco_category). Et une adresse publiée reste valide pour les liens, les moteurs de recherche et le flux produits.

Ces copies ont leurs limites :

  • Les coordonnées existent en plusieurs copies (commande, devis, facture). Une anonymisation doit toutes les retrouver. Order_anonymized_check liste les colonnes de la commande qu’elle vide (Données personnelles).
  • Si on copie une valeur fausse, la copie reste fausse. Une erreur sur une vente encaissée se corrige avec un remboursement, un avoir ou une facture rectificative. On ne réécrit pas la ligne.

L’argent en centimes entiers

Une somme en virgule flottante ne s’arrondit pas pareil selon l’ordre des opérations. Au bout d’un moment, la facture, le remboursement partiel et la déclaration de TVA ont un centime d’écart. Et en comptabilité, un centime d’écart, il faut le justifier.

Il y a trois règles pour éviter ces écarts :

  • Un montant, c’est toujours un entier en centimes (priceCents, amountTotalCents…). Un taux, c’est un entier en points de base (vatRateBps : 20 % s’écrit 2000, et percentBps pour un code promo). Une cote est un entier en millimètres, et un poids un entier en grammes. Pour l’argent, on n’utilise ni Float ni Decimal.

  • Les égalités qui comptent sont écrites dans la base :

    -- Order_total_check
    CHECK ("amountTotalCents" = "amountItemsCents" - "amountDiscountCents" + "amountShippingCents")
    -- OrderItem_lineTotal_check
    CHECK ("lineTotalCents" = ("unitPriceCents" + "ecoContributionUnitCents") * "quantity")
  • Les calculs (répartition d’une remise au plus fort reste, TVA par taux, part du port) sont écrits une seule fois, dans packages/domain (Prix, remises, TVA et port).

Du coup, il n’y a aucun arrondi en base. Une somme de lignes est exacte. Et la vérification de la base contrôle que les montants de chaque commande sont égaux à la somme de ses lignes, remises comprises (plus bas).

Par contre, le type ne fait pas la différence entre des centimes et des euros. Seul le nom de la colonne donne l’unité (…Cents, …Bps, …Mm, …G). Et un entier Postgres limite un montant à 2 147 483 647 centimes, soit plus de 21 millions d’euros. Pour une commande de meubles, ça laisse de la marge.

Des relations qui retiennent

Dans une base de ventes, une suppression en cascade efface de l’argent. Si on retirait un client, ses commandes, leurs encaissements et leurs factures partiraient avec. Et dans l’autre sens, une relation trop lâche laisse écrire des choses incohérentes : un remboursement qui rend la ligne d’une autre commande, ou une photo rattachée à la déclinaison d’un autre meuble.

  • Chaque relation écrit sa règle de suppression. On ne laisse pas le défaut de Prisma décider, et chaque règle a un sens :
    • Restrict pour ce qui touche à l’argent, à la loi ou au stock : toute relation vers une commande, un encaissement, un remboursement, une facture ou un client.
    • Cascade pour ce qui n’existe pas sans son parent : la déclinaison d’un meuble, ses photos, les lignes d’un devis ou d’une commande fournisseur, les sessions d’un compte, les codes postaux d’une zone.
    • SetNull pour une référence au catalogue ou à un auteur : la déclinaison d’une ligne vendue, ou la personne qui a fait un geste (createdById). Si elle part, ses écritures restent.
  • Quand il le faut, une garde bloque une cascade. Un devis supprimé emporte ses lignes, mais un devis accepté ne peut plus être supprimé (Quote_guard). Pour une commande fournisseur, seul un brouillon part avec ses lignes (PurchaseOrder_guard). Les mouvements de stock suivent leur déclinaison, mais StockMovement_guard refuse d’effacer une vente, un achat ou une perte. Concrètement, une pièce vendue ne se supprime pas, elle s’archive. Une pièce jamais vendue, elle, part avec son stock de départ et ses comptages.
  • D’autres règles empêchent d’écrire une relation incohérente :
    • Une clé composite garantit que le parent est le même. Une pièce remboursée référence Refund(id, orderId) et OrderItem(id, orderId), donc elle appartient forcément à la commande remboursée. On retrouve le même principe ailleurs. Il lie un remboursement au paiement de sa commande. Il lie une facture à son remboursement, à son paiement et à la facture qu’elle corrige. Et il lie une photo et la déclinaison qu’elle montre au même meuble (VariantMedia). L’index unique (id, orderId) du parent n’existe que pour servir de cible à ces clés.

      model RefundItem {
        refund    Refund    @relation(fields: [refundId, orderId], references: [id, orderId], onDelete: Restrict)
        orderItem OrderItem @relation(fields: [orderItemId, orderId], references: [id, orderId], onDelete: Restrict)
      }
    • Les index uniques partiels servent pour l’unicité métier. Quand on archive un mode de livraison, un transporteur, un fournisseur ou un code promo, son nom redevient libre (il est unique tant que archivedAt est nul), et les commandes passées continuent de pointer dessus. Une commande n’a qu’une facture de vente d’origine (Invoice_orderId_sale_key), une facture n’est rectifiée qu’une fois (Invoice_rectification_key), et une déclinaison n’a qu’un stock de départ. Un GTIN ou l’e-mail d’un client sont uniques quand ils sont renseignés. Dans un index unique, Postgres considère que deux NULL sont différents. Du coup, la grille de port a un index en plus pour la tranche sans plafond de poids (ShippingRate_unbounded_key), et un autre pour le tarif valable dans toute la métropole (ShippingRate_zoneless_key).

    • Le colis principal est désigné du côté du colis (OrderParcel.mainOrderId, unique, égal à orderId par OrderParcel_main_check). Ce n’est pas une colonne de la commande. La commande ne pointe vers aucun colis, et aucune des deux tables n’attend l’autre pour s’insérer.

Du coup, on ne peut pas écrire une relation incohérente, même avec un script. Et rien de ce qui a été vendu ne disparaît par effet de bord. Si on essaie de supprimer un client qui a commandé, une commande encaissée ou une couleur utilisée par une déclinaison, ça échoue.

Ces relations ont un coût :

  • Un client ne se supprime pas, il s’anonymise, à la fin de sa durée de conservation ou à sa demande (Données personnelles). Les modes et zones de livraison, les transporteurs, les fournisseurs et les codes promo s’archivent, ils ne se suppriment pas, et chaque liste écarte les archivés. Les couleurs, matières, catégories, collections et marques se suppriment, mais seulement si rien ne les utilise.
  • Une clé composite recopie orderId dans la table enfant et demande un index de plus sur le parent.
  • Un Restrict refuse sans dire pourquoi. Donc les services de l’ERP comptent d’abord ce qui retient une ligne, pour pouvoir l’expliquer (« 3 variantes portent cette couleur », color-admin.service.ts). La contrainte sert seulement de filet, pour une écriture arrivée entre-temps.

Ce que la base refuse elle-même

Une règle que seul le code impose ne résiste pas longtemps. Il suffit d’un script de reprise, d’un chemin oublié ou d’une deuxième application qui écrit dans les mêmes tables. Et c’est le cas ici : le site écrit des commandes, l’ERP les encaisse, et des scripts de maintenance touchent la prod.

Les migrations posent trois sortes de garanties :

  • Les contraintes CHECK imposent ce qu’une ligne doit respecter à elle seule. Le stock ne descend pas sous zéro (ProductVariant_stock_check). Le signe d’un mouvement dépend de sa raison : une vente retire, une réception ajoute, un comptage fait l’un ou l’autre (StockMovement_delta_sign_check). Un mouvement n’est rattaché à une commande que s’il en vient (StockMovement_reason_order_check). Une livraison vient après l’expédition (Order_delivery_sequence_check). Un code promo est un pourcentage ou un montant, pas les deux (Promotion_kind_check). Une commande anonymisée ne garde aucune coordonnée (Order_anonymized_check).
  • Les gardes sont des triggers. Elles imposent ce qui dépend d’autres lignes ou du temps. Les encaissements, les lignes de facture et les clôtures de caisse ne peuvent être ni modifiés ni effacés : UPDATE, DELETE et TRUNCATE sont refusés, et une erreur se corrige avec une nouvelle écriture. Le reste est figé sur ce qui compte. Un remboursement garde son montant, sa commande et son mode, mais son état avance jusqu’à abouti, échoué ou annulé (Refund_guard). Une facture reçoit une seule fois son PDF, son empreinte et sa date d’envoi (Invoice_guard). Un mouvement de stock ne s’efface pas, sauf un stock de départ ou un comptage, qui part avec sa déclinaison (StockMovement_guard). Une vente est scellée dès son premier encaissement : ses montants, ses lignes, leurs prix et leurs quantités ne changent plus (Order_guard, OrderItem_guard). C’est parce que le code traite l’ERP comme un système de caisse au sens du Code général des impôts. Une commande fournisseur passe de brouillon à passée, puis à reçue ou annulée. Si elle est entamée, on la solde, on ne l’annule pas (PurchaseOrder_transition). Un devis envoyé garde son numéro, sa validité, son port et son délai (Quote_guard). Une ligne d’achat ne fait pas entrer en stock plus de pièces qu’elle n’en a reçu (StockMovement_purchase_line). Un avoir cite une facture, jamais un autre avoir (Invoice_chain_guard).
  • La base calcule elle-même certaines valeurs, et le code n’a pas à les fournir. Il y a le numéro d’ordre et l’empreinte chaînée de chaque encaissement et remboursement (Des encaissements qui ne se retouchent pas). Il y a la référence d’une déclinaison (MM-0001, tirée d’une séquence par ProductVariant_next_reference, qui saute une référence déjà saisie à la main). Et il y a le coût unitaire d’un mouvement de stock, pris sur la ligne d’achat ou sur la déclinaison (StockMovement_cost). La base calcule aussi le document de recherche de chaque meuble, sans casse ni accents, indexé en trigrammes (ProductSearch). Il est dans une table à part, pour que ses triggers ne verrouillent jamais la ligne du meuble.

Une garde lève une erreur nommée (code 23000, « Order_guard : une commande encaissée garde ses montants… »), et l’ERP la traduit (handleActionError, apps/erp/shared/server/actions/errors.ts). Une référence gelée devient une erreur sur son champ. Une commande fournisseur qui a changé invite à recharger. Un document figé le dit. Le code valide d’abord, avec ses schémas Zod et ses services, pour donner un message précis à la personne. La base, c’est le dernier filet. Donc quand un CHECK se déclenche, ça veut dire qu’il manque une validation dans le code, et il part au collecteur d’erreurs en plus du message.

Ces garanties ont leurs limites :

  • Une garde fait une lecture avant chaque écriture (est-ce qu’il y a une facture, un encaissement ?). Au volume d’un magasin, ça ne coûte presque rien.
  • Un trigger peut se désactiver, et ça ne laisse aucune trace dans les données. C’est pour ça que les encaissements sont chaînés, et que la vérification relève un trigger désactivé (plus bas).
  • Doubler une règle dans la base a un prix, parce que chaque changement demande une migration. Donc la base ne garde que les contrôles qui protègent l’argent, la loi, le stock ou la sécurité, plus ceux des tables que le site écrit. La longueur d’un texte que seul l’ERP saisit reste dans son schéma de saisie (20261113150200_controles_de_texte_laisses_a_la_console).

Le stock : un solde et le journal qui l’explique

Une pièce unique ne doit se vendre qu’une fois. Et pour une date passée, il faut pouvoir dire combien il y en avait, pourquoi, et ce que valait le stock.

Chaque déclinaison suivie a son solde (ProductVariant.stock), et chaque variation s’écrit dans le journal (StockMovement : quantité, raison, commande ou ligne d’achat d’où elle vient, auteur, coût unitaire). Les deux s’écrivent dans la même transaction. Pour le journal, ça passe par les fonctions de apps/erp/shared/server/stock-ledger.ts. Le solde est là pour être lu sur chaque page du catalogue, verrouillé au paiement et limité par un CHECK. Le journal, lui, sert à expliquer et à rejouer. Une réception a une clé unique par pièce (receiptKey), donc si on la rejoue, elle n’entre pas deux fois. Les réservations, elles, ne sont pas stockées. Une pièce est retenue par les commandes en ligne impayées dont la session de paiement est encore ouverte, et le stock libre se déduit à la lecture (pendingReservationWhere, packages/domain/src/stock-reservation.ts).

Du coup, il n’y a aucune réservation à faire expirer ou à nettoyer. Une commande abandonnée arrête de retenir ses pièces quand sa fenêtre se ferme. La valeur du stock à une date passée se recalcule en rejouant le journal. Et une correction de coût s’écrit en paire, une sortie puis une entrée (Stock et achats).

Il y a trois limites :

  • Aucun trigger ne recalcule le solde à partir du journal. Ce sont deux écritures, et c’est le code qui doit les faire ensemble. La vérification de la base compare chaque solde à la somme de son journal et signale l’écart.
  • Déduire les réservations coûte une agrégation à chaque paiement et à chaque affichage du panier.
  • Le stock n’est décompté qu’une fois le paiement confirmé. Donc un paiement qui arrive après la fermeture de sa fenêtre peut tomber sur une pièce déjà partie. Dans ce cas, la ligne passe en rupture, et la pièce n’est pas survendue (plus bas).

Des transactions courtes et verrouillées

L’équipe au magasin, le site et le webhook de Stripe écrivent les mêmes lignes au même moment. Si on ne fait rien, deux paiements prennent la même pièce unique, une commande reçoit deux factures, une réception est comptée deux fois, ou le dernier usage d’un code promo part deux fois.

Les transactions sont interactives et courtes, au niveau d’isolation par défaut de Postgres (READ COMMITTED). Elles ont une durée limitée : dix secondes pour obtenir une connexion, quinze pour finir (TRANSACTION_OPTIONS, packages/infra/src/transaction.ts). Il n’y a pas de SERIALIZABLE, ni de reprise en bloc. Quand une décision dépend d’une lecture, la transaction verrouille ce qu’elle lit. Et tout ce qui sort de la base (e-mail, Stripe, purge du cache du site) part après la validation.

  • Les verrous font passer les gestes concurrents l’un après l’autre :
    • Les verrous de ligne sont pris dans un ordre stable. Avant de lire un stock ou un prix pour décider, la transaction verrouille les déclinaisons concernées, triées par identifiant (SELECT … FOR UPDATE, ORDER BY "id"). Comme ça, deux transactions qui veulent les mêmes pièces s’attendent, et il n’y a pas d’interblocage (lockVariants dans apps/erp/shared/server/store-order.ts, et côté paiement du site findTrackedStockShortage, packages/domain/src/stock-reservation.ts, qui trie les identifiants avant de les verrouiller un par un).
    • Les verrous consultatifs couvrent ce qui n’a pas encore de ligne (pg_advisory_xact_lock, relâchés à la validation). Il y a le client qu’on va créer pour un e-mail ou un téléphone, que rien d’unique ne protège (customer-link.ts). Il y a aussi le passage en caisse d’un même e-mail ou d’une même adresse IP, les usages d’un code promo (sous un verrou que le site et l’ERP partagent), le paiement d’un devis, l’ordre d’une liste et la déclaration de TVA en cours.
    • La numérotation n’a pas de trou. Une facture prend son numéro avec UPDATE "DocumentCounter" SET "value" = "value" + 1 … RETURNING, dans la transaction qui l’insère. Avec le verrou de la ligne, les émissions passent l’une après l’autre, et une annulation rend le numéro (withReservedNumber, apps/erp/shared/invoicing/invoice.ts). Une séquence Postgres laisserait un trou à chaque annulation. Ça suffit pour les numéros de commande, mais pas pour des pièces comptables.
  • D’autres écritures ne passent qu’à une condition :
    • Une mise à jour conditionnelle sert de porte d’entrée. Le webhook ne passe une commande à « payée » que si elle était en attente. C’est le nombre de lignes modifiées qui décide si le reste s’écrit (encaissement, devis accepté, stock décompté). Si le même événement est livré une deuxième fois, il ne se passe rien (extrait simplifié de webhook-session.service.ts) :

      const transition = await tx.order.updateMany({
      	where: {
      		id: order.id,
      		paymentStatus: PaymentStatus.PENDING,
      		fulfillmentStatus: { not: FulfillmentStatus.CANCELED },
      	},
      	data: { paymentStatus: PaymentStatus.PAID, paidAt, confirmedAt: paidAt },
      });
      if (transition.count === 0) return; // déjà payée, ou annulée entre-temps

      Le stock est décompté de la même façon, seulement s’il y en a assez (stock: { gte: quantity }). Sinon, la ligne passe en rupture et le magasin est prévenu. Ça évite de vendre une pièce qui n’existe plus (decrementPaidStock, apps/erp/modules/payments/services/paid-stock.ts). Une réception n’avance que si la quantité déjà reçue est bien celle que l’écran a lue. Et un avis au client ne part qu’une fois (il faut que sa date d’envoi soit encore nulle, et il y a en plus une clé d’idempotence chez le fournisseur d’e-mail).

    • Des contraintes d’unicité servent de clés d’idempotence. L’identifiant d’un événement Stripe est la clé de WebhookEvent, donc on reconnaît une relivraison au refus du doublon. Les identifiants Stripe d’une session, d’un paiement et d’un remboursement sont uniques, et la clé d’une réception aussi.

    • Une permission peut être limitée à une transaction. Le prix d’une vente du magasin déjà facturée ne peut changer qu’avec une facture rectificative. La correction pose moriniere.price_correction uniquement pour la transaction en cours (set_config(…, true), openPriceCorrection). La garde n’accepte le changement que pour cette commande. Et à la validation, un trigger de contrainte différé (Order_price_correction_check, DEFERRABLE INITIALLY DEFERRED) vérifie que la facture rectificative a bien été émise dans la même transaction.

Du coup, une course finit par une réponse claire (« déjà annulée », « pièce en cours de paiement », « recharge la page ») et pas par une donnée fausse. Ces courses sont rejouées sur une vraie base. Dix émissions simultanées donnent dix numéros distincts et consécutifs (apps/erp/test/db/concurrence.db.test.ts). Deux paiements sur la dernière pièce n’en laissent passer qu’un, sans que le stock descende sous zéro (overselling.db.test.ts). Et une annulation de l’atelier croise un encaissement (cancellation-versus-payment.db.test.ts).

Tout ça a un coût :

  • Les verrous mettent tout en file, donc deux factures sont émises l’une après l’autre. Au volume d’un magasin, ça ne se voit pas. À grande échelle, ce compteur deviendrait un goulot.
  • L’ordre des verrous, c’est une discipline à respecter dans chaque service. Aucun outil ne vérifie qu’une nouvelle écriture trie ses identifiants.
  • En READ COMMITTED, une lecture faite hors verrou peut ne plus être vraie au moment d’écrire. Donc le code qui décide doit verrouiller, ou mettre une condition sur sa mise à jour. Quand Postgres refuse un conflit d’écriture, la personne voit « à refaire dans un instant » (CONFLICT_RETRY_MESSAGE).
  • Une transaction interactive occupe une connexion du pool tant qu’elle dure. Et si on glissait un appel réseau dedans, elle garderait ses verrous pendant ce temps. C’est pour ça que les effets partent après la validation et que la durée est limitée.
  • Une transaction ne passe pas par Stripe. Envoyer un remboursement et l’enregistrer, ce sont deux étapes, et c’est le webhook qui les réconcilie (Stripe).

Deux rôles Postgres, avec des droits différents

Le site est ouvert à tout Internet, et il écrit dans la même base que l’ERP : des commandes, leurs lignes, des comptes clients. S’il y a une faille dans son code, elle ne doit pas lui donner plus que ce dont il a besoin.

L’ERP se connecte avec le rôle propriétaire de la base. Le site se connecte avec moriniere_site. Ses droits sont écrits dans le code, table par table et colonne par colonne (apps/site/scripts/lib/database-grants.ts) :

  • Il ne voit ni les colonnes réservées à l’ERP (ERP_ONLY_COLUMNS : notes internes, auteur d’une écriture), ni le coût d’une pièce.
  • Il n’écrit que dans les colonnes dont il a besoin. Sur les déclinaisons, il ne peut écrire que updatedAt, parce que le verrou FOR UPDATE du paiement l’exige (lockColumns).
  • Ses requêtes ont une durée limitée, et une transaction abandonnée ne garde pas ses verrous plus de trente secondes (SITE_SESSION_SETTINGS).
  • Des triggers vérifient ce qu’il insère ou modifie. Il ne peut créer qu’une commande en ligne en attente de paiement (Order_site_guard_insert). Et quand il insère une ligne, c’est la base qui remplit son coût, avec les droits du propriétaire (OrderItem_site_cost, SECURITY DEFINER). Lui ne peut pas le lire.

Du coup, c’est la base qui limite ce que le site peut faire, peu importe son code. Sur un déploiement, le site refuse de démarrer s’il n’est pas connecté avec ce rôle (apps/site/shared/server/database-role-check.ts). Et un test relève chaque requête du site et refuse celle qui n’a pas son droit. Je raconte ce choix dans l’étude de cas Le site n’a que les droits qu’il lui faut.

Par contre, il faut mettre les droits à jour à la main quand le schéma change. Si le site doit lire une colonne, on l’ajoute à sa liste. Et pour rester dans ses droits par colonne, le site charge ses relations avec une requête par relation, sans jointure (withColumnGrantSafeRelations, apps/site/shared/server/prisma.ts).

Vérifier la base réelle

Une contrainte oubliée dans une migration, un trigger désactivé pendant une reprise, un compteur en retard sur les numéros déjà émis : rien de tout ça ne se voit dans le code, et rien de tout ça ne fait échouer un build.

La liste de ce que la base doit avoir est dans le code (apps/erp/scripts/constants/db-invariants.ts : contraintes par table, dont certaines comparées à leur définition exacte, triggers, fonctions, séquences, séries de numérotation). pnpm db:invariants lit la base réelle et relève tout ce qui ne va pas : une contrainte manquante, non validée ou absente de la liste, un trigger absent ou désactivé, un compteur en retard sur le dernier numéro émis, une migration inachevée, une session qui ne serait pas en UTC, un solde différent de la somme de son journal, une commande dont les montants ne sont pas égaux à la somme de ses lignes, et un maillon cassé dans la chaîne des encaissements. Le script qui joue les migrations avant un déploiement (db:pre-deploy) les applique, puis il relance cette vérification et celle des droits du site. Par défaut, il fait d’abord une sauvegarde, parce que Prisma n’a pas de migration de retour. En prod, je le lance avec --sans-sauvegarde, et le retour arrière passe par la restauration à un instant de Neon (ADR 0009).

Du coup, on relit les garanties comme Postgres les applique vraiment, et pas comme les migrations les décrivent. Un test vérifie que la liste et les migrations restent d’accord (apps/erp/test/check-constraints.regression.test.ts). Les tests de apps/erp/test/db tournent sur une vraie base, pour ce que seule la base peut prouver : contraintes, gardes, droits du site, verrous, courses. Les plus importants savent échouer. Par exemple, la course entre une anonymisation et un remboursement est aussi rejouée sans le verrou, et là l’invariant casse (anonymization-race.db.test.ts). Le nombre de requêtes est contrôlé aussi. La fiche d’une commande se lit en une seule requête, avec ses relations jointes, sans requête en plus par ligne (admin-order-query-count.db.test.ts). Et l’ERP journalise toute requête de plus de 50 ms (SLOW_QUERY_MS).

Cette liste reste une copie de plus à maintenir à côté des migrations. La vérification la rend sûre, mais ce n’est pas gratuit : si on ajoute une contrainte sans la mettre dans la liste, elle est signalée comme inconnue. Les tests sur une vraie base demandent un Postgres local. Le hook pre-push lance toute la suite dès que le push touche du code qui parle à la base, sauf si on atteste l’avoir jouée (TEST_DB_JOUE=1).

Sur cette page