Audit — le systeme de paiement comme un seul parcours

Portee volontairement plus large que le pilier billing : la demande etait de traiter decouverte -> pricing -> inscription -> checkout -> activation -> usage -> upgrade -> facture -> echec -> annulation comme une seule infrastructure, pas comme une page de tarifs plus des composants Stripe.

Perimetre : src/modules/billing/**, src/services/billing|stripe/**, src/services/webhooks.ts, src/lib/security/billing-gate.ts, src/app/api/{stripe,credits,usage,me,stores,organizations}/**, src/app/(marketing)/pricing/**, src/app/(dashboard)/[orgSlug]/~/billing/**, src/app/(minimal)/onboarding/**, src/components/shared/credits/**, src/components/patterns/{paid-gate,upgrade-wall,billing}/**, src/features/ai/orchestrator/runtime/** (gardes de cout), src/types/billing-*.ts, src/config/plans.ts, prisma/schema.prisma.

Ce document n'est pas en lecture seule. Contrairement a l'audit du 25 aout, il a ete suivi d'implementation dans la meme PR : chaque constat porte son etat (corrige / ouvert / decision produit).

Ce qui va bien, et qu'il ne faut pas casser

Le premier resultat de l'audit est qu'il n'y a pas de dette mecanique. Verifie ligne a ligne :

La qualite de cette couche est reelle et ses commentaires nomment les incidents qu'elle previent. Le probleme n'est pas la mecanique.

Le probleme : tout ce qui entoure la mecanique

Trois familles, et elles se ressemblent :

1. Le catalogue promet des choses que rien n'applique.
2. Le tunnel n'a ni debut ni fin : l'intention se perd avant le paiement, et le paiement ne mene nulle part apres.
3. Des surfaces affichent des nombres que le produit n'a pas.

1. Cartographie — ou vit la verite

Les trois couches d'entitlement, apres cette PR

entitlement.ts        (pur)     "cette org a-t-elle le droit de payer-pour-utiliser"
quota.ts              (pur)     "peut-elle en ajouter un de plus, et quel plan le debloque"
billing-gate.ts       (securite) requirePaidPlan / requireQuota + les deux 402

quota.ts est neuf et comble le trou central : la question comptable n'avait aucune reponse dans le depot.

Points d'entree du checkout

2. Constats

P0 — argent, acces, securite

P1 — tunnel casse, etat incoherent

P2 — UX, conversion, verite affichee

Troisieme passe — ce que le rejeu a trouve

Numerotation separee : ces trois constats sont posterieurs aux tables ci-dessus, et viennent d'un angle different. Les deux premieres passes lisaient le code ; celle-ci rejoue des sequences et regarde l'etat final (src/test/payment-funnels.test.ts).

Le point D merite une note de methode. Sa premiere version de test etait sequentielle et passait sur le code casse : un evenement perime sort avant d'estampiller, donc rien n'etait exerce. Il a fallu le reecrire en course reelle. C'est la raison pour laquelle chaque affirmation du fichier de rejeu a ete verifiee en remettant le defaut et en regardant le cas nomme echouer : quatorze mutations, quatorze prises. Le detail est en tete du fichier.

3. Ce qui reste ouvert

Decisions produit, pas des bugs

Ces claims de /pricing n'ont aucune implementation dans le depot. Les corriger, c'est soit construire la fonctionnalite, soit retirer la ligne : dans les deux cas c'est un arbitrage commercial, et un test ne doit pas le trancher en silence.

Un cas est symetrique et merite un arbitrage a lui seul : PLAN_LIMITS.free.stores et PLAN_LIMITS.pro.stores valent tous deux 1. L'offre a $49 n'ajoute donc aucun store, et le plan le moins cher qui en autorise un deuxieme est Max 5x a $149. C'est peut-etre voulu (Pro achete les credits et les surfaces payantes, pas des stores) — mais c'est le genre de marche qu'il vaut mieux decider que subir, d'autant que l'echappatoire vendue sur les cartes (« +$9 par store ») n'a pas de chemin de facturation. src/services/billing/quota.test.ts epingle le comportement actuel, avec la raison ecrite.

Dette identifiee, non traitee dans cette PR

• L'editeur de plans admin ecrit trois colonnes que rien ne lit (Plan.markup, Plan.dailyBonusUsd, Plan.additionalStorePrice), avec un toast de succes et une entree d'audit ; et Plan.monthlyCredits n'est honore qu'a la creation d'org, pas par les grants recurrents.
• /pricing rend le price id fusionne depuis la DB alors que /api/stripe/checkout resout contre le catalogue env : remplir le champ dans l'admin produit un CTA qui 400.
• Quatre statuts Stripe n'ont aucune representation locale (incomplete, incomplete_expired, unpaid, paused), tous replies sur past_due. Sur direction, pas de bug ; mais aucune UI ne peut distinguer « 3DS a authentifier » de « carte refusee ».
• Aucune facture n'est jamais lue depuis Stripe : la section « Billing History » est un etat vide inconditionnel dont la copie promet le contraire.
• charge.dispute.* n'est pas dispatche, alors que docs/business-model/operations.md decrit un clawback de 14 jours sur chargeback comme actif.
• Les holds de credits fuient sur les canaux non-web (bot, WhatsApp, API REST) : seul le chat web libere le hold en cas d'echec.
• Le canal API REST n'a pas de hard cap mid-stream, contrairement a ses quatre freres.

4. Ce que cet audit n'a pas couvert

• Aucun Postgres, aucun Stripe, aucun navigateur. src/test/payment-funnels.test.ts rejoue desormais les huit parcours contre les vrais handlers — machine d'idempotence, filigrane d'ordonnancement, grant mensuel, CAS du top-up, entitlement, quota — mais sur un magasin en memoire. Il prouve que notre code, recevant les evenements que Stripe envoie, atteint l'etat voulu. Il ne prouve pas que Postgres applique les index uniques que ce magasin imite, ni que Stripe accepte une session, ni qu'une page s'affiche. Le seul test d'integration reel reste describe.skipIf(!TEST_DATABASE_URL), et ne tourne pas en CI.
• Aucun rendu verifie. vitest tourne en environnement node ici : les gardes statiques lisent la source, ce qui est le bon niveau pour des defauts de cablage, et ne prouve rien sur les pixels.
• Le modele financier (docs/business-model/financial-model.md) n'a pas ete confronte au code.
• Le markup 1.5x sur le chemin de charge reel n'a pas ete exerce bout en bout ; seule l'incoherence de l'affichage a ete corrigee.