From e046c6f14e27ab124b601e7196e04dafe8fb9159 Mon Sep 17 00:00:00 2001 From: Projetapploccar <351336702+Projetapploccar@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:47:53 -0300 Subject: [PATCH 1/2] =?UTF-8?q?feat(US-701):=20caution=20fig=C3=A9e=20au?= =?UTF-8?q?=20checkout,=20vue=20du=20voyageur=20sans=20[C2],=20minuterie?= =?UTF-8?q?=20de=20r=C3=A9-autorisation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - deposit_hold (migration 0143) : une décision par hold, figée avant le paiement, revérifiée par la base ; aucun droit applicatif direct - porte de la caution avant T1, payment.deposit pour S05, refus 409 DEPOSIT_RAIL_UNAVAILABLE / DEPOSIT_PARAM_MISSING - S05 : aucune caution, montant et libération, ou refus avec les jours possibles (S-8) ; textes es, en, fr, pt-BR (catalogue v83) - minuterie deposit_timer : ré-autorisation ; refusée ⇒ décision avant l'expiration, alerte ops, aucun débit - clés de caution alignées sur 08 E4 (S-6) ; reauthorize : PENDING / SUBMITTED / UNKNOWN ⇒ REAUTH_PENDING - ADR-169, GL-46, passation Agent-Role: argent Agent-Model: claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 --- apps/api/openapi/openapi.json | 70 ++- .../internal/checkout/avl-checkout.module.ts | 28 +- .../avl/internal/checkout/payment-errors.ts | 4 + .../avl/internal/checkout/payment.service.ts | 112 +++- .../testing/checkout-deposit.contract.test.ts | 167 ++++++ .../testing/checkout-payment.contract.test.ts | 8 +- .../testing/fake-checkout-payment-store.ts | 35 +- .../src/modules/bus/internal/alert-channel.ts | 3 + apps/api/src/modules/pay/README.md | 50 +- apps/api/src/modules/pay/index.ts | 39 +- .../pay/internal/deposit-checkout.test.ts | 351 +++++++++++ .../modules/pay/internal/deposit-checkout.ts | 342 +++++++++++ .../modules/pay/internal/deposit-executor.ts | 59 +- .../src/modules/pay/internal/deposit-rails.ts | 83 ++- .../src/modules/pay/internal/deposit-timer.ts | 239 ++++++++ .../src/modules/pay/internal/idempotency.ts | 60 +- .../pay/internal/pg-deposit-checkout.ts | 131 ++++ .../pay/testing/deposit-rails.fake.test.ts | 3 + .../pay/testing/deposit-timer.fake.test.ts | 317 ++++++++++ apps/api/src/worker-tasks.test.ts | 3 + apps/api/src/worker-tasks.ts | 13 + apps/web/account/checkout-deposit.test.ts | 144 +++++ apps/web/account/checkout-payment.test.ts | 3 + apps/web/account/checkout-payment.ts | 86 +++ .../app/(app)/checkout/hold/[holdId]/page.tsx | 73 ++- apps/web/e2e/checkout-payment.spec.ts | 35 ++ apps/web/e2e/stub-api.mjs | 32 + changelog.d/US-701-caution-plateforme.md | 10 + docs/adr/ADR-169-caution-figee-au-checkout.md | 31 + docs/architecture/api.md | 2 +- docs/architecture/modules.md | 2 +- docs/architecture/schema.md | 36 +- docs/ops/GO_LIVE_CHECKLIST.md | 1 + docs/team/COMME_TURO.md | 2 + docs/team/handoffs/US-701.md | 44 ++ packages/db/README.md | 9 + packages/db/authorization-matrix.json | 13 + .../migrations/0143_payment_deposit_hold.sql | 562 ++++++++++++++++++ packages/db/personal-data-inventory.json | 39 ++ packages/db/security-definer-allowlist.json | 28 + packages/db/src/errors.ts | 7 + .../9945_test_us701_deposit_hold_fixtures.sql | 76 +++ packages/db/test/int/avl-schema.test.ts | 2 + .../db/test/l0/l0-us701-deposit-hold.test.ts | 431 ++++++++++++++ packages/i18n/src/catalogs/en.ts | 5 + packages/i18n/src/catalogs/es.ts | 5 + packages/i18n/src/catalogs/fr.ts | 5 + packages/i18n/src/catalogs/index.ts | 7 +- packages/i18n/src/catalogs/pt.ts | 5 + 49 files changed, 3732 insertions(+), 80 deletions(-) create mode 100644 apps/api/src/modules/avl/testing/checkout-deposit.contract.test.ts create mode 100644 apps/api/src/modules/pay/internal/deposit-checkout.test.ts create mode 100644 apps/api/src/modules/pay/internal/deposit-checkout.ts create mode 100644 apps/api/src/modules/pay/internal/deposit-timer.ts create mode 100644 apps/api/src/modules/pay/internal/pg-deposit-checkout.ts create mode 100644 apps/api/src/modules/pay/testing/deposit-timer.fake.test.ts create mode 100644 apps/web/account/checkout-deposit.test.ts create mode 100644 changelog.d/US-701-caution-plateforme.md create mode 100644 docs/adr/ADR-169-caution-figee-au-checkout.md create mode 100644 docs/team/handoffs/US-701.md create mode 100644 packages/db/migrations/0143_payment_deposit_hold.sql create mode 100644 packages/db/test-migrations/9945_test_us701_deposit_hold_fixtures.sql create mode 100644 packages/db/test/l0/l0-us701-deposit-hold.test.ts diff --git a/apps/api/openapi/openapi.json b/apps/api/openapi/openapi.json index 350d98748..cd2a7721f 100644 --- a/apps/api/openapi/openapi.json +++ b/apps/api/openapi/openapi.json @@ -7240,7 +7240,7 @@ "operationId": "checkoutHoldPayment", "tags": ["avl"], "summary": "État du paiement du hold du checkout (US-223b ; 16 PAY-034 ; écran S06, 10b UX-27)", - "description": "Route de réservation : SessionGuard puis TermsGuard. État dérivé de l'état du hold et du trip né de la conversion : CONFIRMED seulement si le hold est CONVERTED et qu'un trip existe (preuve par webhook signé, ADR-139). Le statut de l'opération chez le PSP n'est jamais rendu. Aucun montant ni référence du PSP.", + "description": "Route de réservation : SessionGuard puis TermsGuard. État dérivé de l'état du hold et du trip né de la conversion : CONFIRMED seulement si le hold est CONVERTED et qu'un trip existe (preuve par webhook signé, ADR-139). Le statut de l'opération chez le PSP n'est jamais rendu. Aucun montant ni référence du PSP. US-701 : payment.deposit porte la vue de la caution (décision figée, ou évaluée sans écriture tant qu'un paiement est possible ; montant de la caution seulement) ; absent sinon.", "parameters": [ { "name": "holdId", @@ -7316,7 +7316,7 @@ "operationId": "checkoutPayHold", "tags": ["avl"], "summary": "Paiement du hold du checkout (US-223b ; 17 §2.5 étapes 3a à 3c ; 16 PAY-006, PAY-019 ; 08 E7 règle 1) : intention de paiement (T1), ordre chez le PSP avec le montant explicite de chaque jambe, enregistrement de l'ordre (T2)", - "description": "Route de réservation : SessionGuard puis TermsGuard. Le corps ne porte que le moyen de paiement (défaut CARD) : aucun montant ni jambe n'est reçu, tout champ inconnu est refusé. Montant et jambes viennent du devis engagé au checkout, rejoués par la base. Idempotent par la base : un seul ordre vivant par hold ; pendant un ordre actif, aucun nouvel ordre (200 avec l'état). 201 : ordre créé, redirectUrl = page hébergée du PSP. Aucun connecteur servi (production jusqu'au lot C) : 503 PAYMENT_UNAVAILABLE sans toucher au hold.", + "description": "Route de réservation : SessionGuard puis TermsGuard. Le corps ne porte que le moyen de paiement (défaut CARD) : aucun montant ni jambe n'est reçu, tout champ inconnu est refusé. Montant et jambes viennent du devis engagé au checkout, rejoués par la base. Idempotent par la base : un seul ordre vivant par hold ; pendant un ordre actif, aucun nouvel ordre (200 avec l'état). 201 : ordre créé, redirectUrl = page hébergée du PSP. Aucun connecteur servi (production jusqu'au lot C) : 503 PAYMENT_UNAVAILABLE sans toucher au hold. US-701 : la caution est décidée avant T1 (08 BR-PAY-06) ; refus 409 DEPOSIT_RAIL_UNAVAILABLE ou DEPOSIT_PARAM_MISSING sans écriture ; sinon la décision est figée une fois (deposit_hold) et la vue du voyageur est rendue dans payment.deposit.", "parameters": [ { "name": "holdId", @@ -7438,7 +7438,7 @@ } }, "409": { - "description": "Hold échu ou déjà payé, réservation en revue avant tout débit (BOOKING_UNDER_REVIEW), début du trip dépassé, tentatives épuisées (PAY-017), capacité bloquante du PSP non validée (HOST_PAYOUT_RAIL_UNAVAILABLE, inconnue = non)", + "description": "Hold échu ou déjà payé, réservation en revue avant tout débit (BOOKING_UNDER_REVIEW), début du trip dépassé, tentatives épuisées (PAY-017), capacité bloquante du PSP non validée (HOST_PAYOUT_RAIL_UNAVAILABLE, inconnue = non) ; caution exigée sans rail possible pour ces dates (DEPOSIT_RAIL_UNAVAILABLE) ou sans montant fixé (DEPOSIT_PARAM_MISSING), avant tout ordre et sans écriture (US-701)", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" @@ -7456,7 +7456,9 @@ "BOOKING_UNDER_REVIEW", "START_PASSED", "PAYMENT_ATTEMPTS_EXCEEDED", - "HOST_PAYOUT_RAIL_UNAVAILABLE" + "HOST_PAYOUT_RAIL_UNAVAILABLE", + "DEPOSIT_RAIL_UNAVAILABLE", + "DEPOSIT_PARAM_MISSING" ] } } @@ -19268,9 +19270,66 @@ }, "request": { "$ref": "#/components/schemas/CheckoutRequestState" + }, + "deposit": { + "$ref": "#/components/schemas/CheckoutDeposit" } } }, + "CheckoutDeposit": { + "description": "Caution vue par le voyageur (US-701, ADR-169 ; 08 BR-PAY-06) : NONE (aucune caution), REQUIRED (montant en unités mineures, devise, HOLD = blocage sur la carte ou CHARGE = débit puis remboursement, libération au plus tard) ou UNAVAILABLE (réservation impossible avant le paiement ; maxBookableDays = jours entiers possibles, null ou 0 : aucun). Jamais les déclencheurs, l'âge, le signal de risque ni l'instantané des paramètres [C2].", + "oneOf": [ + { + "type": "object", + "required": ["status"], + "additionalProperties": false, + "properties": { + "status": { + "const": "NONE" + } + } + }, + { + "type": "object", + "required": ["status", "amountMinor", "currency", "kind", "releaseAt"], + "additionalProperties": false, + "properties": { + "status": { + "const": "REQUIRED" + }, + "amountMinor": { + "type": "string", + "pattern": "^[1-9][0-9]{0,17}$" + }, + "currency": { + "type": "string", + "pattern": "^[A-Z]{3}$" + }, + "kind": { + "type": "string", + "enum": ["HOLD", "CHARGE"] + }, + "releaseAt": { + "$ref": "#/components/schemas/DateTime" + } + } + }, + { + "type": "object", + "required": ["status", "maxBookableDays"], + "additionalProperties": false, + "properties": { + "status": { + "const": "UNAVAILABLE" + }, + "maxBookableDays": { + "type": ["integer", "null"], + "minimum": 0 + } + } + } + ] + }, "CheckoutPaymentStart": { "type": "object", "required": [ @@ -19328,6 +19387,9 @@ "request": { "$ref": "#/components/schemas/CheckoutRequestState" }, + "deposit": { + "$ref": "#/components/schemas/CheckoutDeposit" + }, "redirectUrl": { "type": ["string", "null"], "description": "Page hébergée du PSP (https), seulement si un ordre vient d'être créé" diff --git a/apps/api/src/modules/avl/internal/checkout/avl-checkout.module.ts b/apps/api/src/modules/avl/internal/checkout/avl-checkout.module.ts index 17737f098..e5dd0c075 100644 --- a/apps/api/src/modules/avl/internal/checkout/avl-checkout.module.ts +++ b/apps/api/src/modules/avl/internal/checkout/avl-checkout.module.ts @@ -27,6 +27,11 @@ */ import { Module } from '@nestjs/common'; import type { DynamicModule } from '@nestjs/common'; +import { + DepositCheckoutGate, + PgDepositCheckoutStore, + PgDepositRailConfigReader, +} from '../../../pay/index.js'; import { PgQuoteStore, UnavailableQuoteStore } from '../../../prc/index.js'; import type { QuoteParamsOf, QuoteStore } from '../../../prc/index.js'; import { CheckoutController } from './checkout.controller.js'; @@ -36,7 +41,7 @@ import { PgCheckoutStore, UnavailableCheckoutStore } from './store.js'; import type { CheckoutStore, SqlExecutor } from './store.js'; import { CheckoutPaymentController } from './payment.controller.js'; import { CheckoutPaymentService, LOG_PAYMENT_FAILURE } from './payment.service.js'; -import type { HostedPaymentProvider } from './payment.service.js'; +import type { DepositGatePort, HostedPaymentProvider } from './payment.service.js'; import { PgCheckoutPaymentStore, UnavailableCheckoutPaymentStore } from './payment-store.js'; import type { CheckoutPaymentStore } from './payment-store.js'; import { HostRequestsController } from './host-requests.controller.js'; @@ -74,8 +79,16 @@ export interface AvlCheckoutPaymentOptions { readonly store: CheckoutPaymentStore; /** Connecteurs par fournisseur (`payment_psp_account.provider`) ; vide : aucun paiement. */ readonly providers: ReadonlyMap; + /** Porte de la caution (US-701, ADR-169) : décidée et figée AVANT le paiement. */ + readonly deposits: DepositGatePort; } +/** Porte de la caution sans base : 503 (jamais un paiement sans décision de caution). */ +export const UNAVAILABLE_DEPOSIT_GATE: DepositGatePort = { + view: () => Promise.reject(new Error('porte de la caution indisponible')), + enforce: () => Promise.reject(new Error('porte de la caution indisponible')), +}; + /** Demandes de réservation de l'hôte (US-223c) : commandes de 0126 et connecteurs de capture. */ export interface AvlHostRequestOptions { readonly store: HostRequestStore; @@ -93,6 +106,7 @@ export const UNAVAILABLE_HOST_REQUESTS: AvlHostRequestOptions = { export const UNAVAILABLE_CHECKOUT_PAYMENTS: AvlCheckoutPaymentOptions = { store: new UnavailableCheckoutPaymentStore(), providers: new Map(), + deposits: UNAVAILABLE_DEPOSIT_GATE, }; export interface AvlCheckoutOptions { @@ -141,7 +155,16 @@ export function postgresCheckoutAdapters( store: new PgCheckoutStore(db), ...(cancellationParamsOf === undefined ? {} : { cancellationParamsOf }), // aucun connecteur de PSP en production avant le lot C (PRODUCTION_PROVIDERS vide) - payments: { store: new PgCheckoutPaymentStore(db), providers: new Map() }, + // US-701 : caution décidée et figée avant le paiement (0143), configuration du pays lue sous + // app_api + payments: { + store: new PgCheckoutPaymentStore(db), + providers: new Map(), + deposits: new DepositCheckoutGate( + new PgDepositCheckoutStore(db), + new PgDepositRailConfigReader(db), + ), + }, // US-223c : refus et lecture des demandes ; aucune capture avant le lot C hostRequests: { store: new PgHostRequestStore(db), providers: new Map() }, // US-224d : lecture du remboursement par la partie du trip (aucune écriture) @@ -184,6 +207,7 @@ export class AvlCheckoutModule { useValue: new CheckoutPaymentService( (options.payments ?? UNAVAILABLE_CHECKOUT_PAYMENTS).store, (options.payments ?? UNAVAILABLE_CHECKOUT_PAYMENTS).providers, + (options.payments ?? UNAVAILABLE_CHECKOUT_PAYMENTS).deposits, LOG_PAYMENT_FAILURE, ), }, diff --git a/apps/api/src/modules/avl/internal/checkout/payment-errors.ts b/apps/api/src/modules/avl/internal/checkout/payment-errors.ts index 4c16d821a..21fc69ce2 100644 --- a/apps/api/src/modules/avl/internal/checkout/payment-errors.ts +++ b/apps/api/src/modules/avl/internal/checkout/payment-errors.ts @@ -32,6 +32,10 @@ export const PAYMENT_MESSAGES = { KYC_BIOMETRIC_CONSENT_MISSING: CHECKOUT_MESSAGES.KYC_BIOMETRIC_CONSENT_MISSING, KYC_LICENSE_EXPIRED: CHECKOUT_MESSAGES.KYC_LICENSE_EXPIRED, AGE_CLASS_MISMATCH: CHECKOUT_MESSAGES.AGE_CLASS_MISMATCH, + // US-701 (ADR-169 ; 08 BR-PAY-06) : caution exigée sans rail possible pour ces dates, ou sans + // montant fixé (`deposit_amount` absent) ; refus AVANT le paiement, aucune écriture + DEPOSIT_RAIL_UNAVAILABLE: { status: 409, messageKey: 'common.payment.depositUnavailable' }, + DEPOSIT_PARAM_MISSING: { status: 409, messageKey: 'common.payment.depositUnavailable' }, PAYMENT_UNAVAILABLE: { status: 503, messageKey: 'common.payment.unavailable' }, BOOKING_UNAVAILABLE: CHECKOUT_MESSAGES.BOOKING_UNAVAILABLE, } as const; diff --git a/apps/api/src/modules/avl/internal/checkout/payment.service.ts b/apps/api/src/modules/avl/internal/checkout/payment.service.ts index 5438b4554..549e815b1 100644 --- a/apps/api/src/modules/avl/internal/checkout/payment.service.ts +++ b/apps/api/src/modules/avl/internal/checkout/payment.service.ts @@ -20,9 +20,21 @@ * signé, ADR-139) ; le statut brut de l'opération n'est jamais rendu ni lu pour confirmer : il ne * sert qu'à distinguer un refus (« payer de nouveau ») d'un paiement non prouvé (« ne paie pas de * nouveau, support »). + * + * US-701 (ADR-169 ; 08 BR-PAY-06 « Moment de l'évaluation ») : la caution est décidée AVANT le + * paiement. `payment` rend la vue du voyageur (`deposit` : aucune caution, montant et libération, + * ou réservation impossible et jours possibles ; jamais les déclencheurs ni l'instantané des + * paramètres, S-7) ; `pay` applique la porte avant T1 : refus ⇒ `DEPOSIT_RAIL_UNAVAILABLE` ou + * `DEPOSIT_PARAM_MISSING` sans écriture ni ordre ; sinon la décision est figée (`deposit_hold`), + * puis le paiement suit. */ import { assertMovingLegs, isPaymentError, PAYMENT_METHODS } from '../../../pay/index.js'; -import type { PaymentMethod, PaymentProvider } from '../../../pay/index.js'; +import type { + DepositEnforcement, + DepositGuestView, + PaymentMethod, + PaymentProvider, +} from '../../../pay/index.js'; import { failureFields } from './checkout.service.js'; import { isUuid } from './model.js'; import { PaymentHttpError } from './payment-errors.js'; @@ -38,6 +50,50 @@ import type { /** Ce que l'API demande au connecteur d'un PSP pour le paiement du checkout. */ export type HostedPaymentProvider = Pick; +/** Porte de la caution du checkout (PAY, `DepositCheckoutGate`). */ +export interface DepositGatePort { + view( + proof: Buffer, + holdId: string, + evaluate: boolean, + ): Promise; + enforce(proof: Buffer, holdId: string): Promise; +} + +/** + * Caution vue par le voyageur (S05) : statut, montant (texte d'unités mineures), devise, nature + * (`HOLD` blocage sur la carte, `CHARGE` débit puis remboursement) et libération au plus tard ; ou + * réservation impossible et jours entiers possibles (`null` : aucun). Aucun champ [C2]. + */ +export type CheckoutDepositView = + | { readonly status: 'NONE' } + | { + readonly status: 'REQUIRED'; + readonly amountMinor: string; + readonly currency: string; + readonly kind: 'HOLD' | 'CHARGE'; + readonly releaseAt: string; + } + | { readonly status: 'UNAVAILABLE'; readonly maxBookableDays: number | null }; + +/** Sérialisation de la vue (liste blanche des champs : rien d'autre ne sort). */ +export function depositViewOf(v: DepositGuestView): CheckoutDepositView { + switch (v.status) { + case 'NONE': + return { status: 'NONE' }; + case 'REQUIRED': + return { + status: 'REQUIRED', + amountMinor: v.amountMinor.toString(), + currency: v.currency, + kind: v.kind, + releaseAt: v.releaseAt.toISOString(), + }; + case 'UNAVAILABLE': + return { status: 'UNAVAILABLE', maxBookableDays: v.maxBookableDays }; + } +} + /** * États du paiement rendus au site (PROPOSÉS, ADR-142) : * - `PAYABLE` : hold vivant, aucun ordre ; `DECLINED` : hold vivant, dernier ordre refusé ; @@ -79,6 +135,11 @@ export interface CheckoutPayment { * 223c-écrans. */ readonly request?: { readonly status: RequestStatus; readonly respondBy: string | null }; + /** + * Caution (US-701) : champ absent tant qu'elle n'est ni figée ni évaluable (paiement terminé sans + * décision, devis indisponible). + */ + readonly deposit?: CheckoutDepositView; } /** @@ -127,6 +188,13 @@ export function paymentStateOf(row: CheckoutPaymentRow): PaymentState { } } +/** États où un paiement est possible : la caution y est évaluée (sans écriture) pour S05. */ +const PAYABLE_STATES: ReadonlySet = new Set([ + 'PAYABLE', + 'DECLINED', + 'INTERRUPTED', +]); + const viewOf = (holdId: string, row: CheckoutPaymentRow): CheckoutPayment => ({ holdId, state: paymentStateOf(row), @@ -150,7 +218,8 @@ export function parsePaymentDemand(body: unknown): PaymentMethod | null { : null; } -export type PaymentOperation = 'read' | 'start' | 'provider' | 'lookup' | 'psp' | 'record'; +export type PaymentOperation = + 'read' | 'start' | 'provider' | 'lookup' | 'psp' | 'record' | 'deposit'; /** Journal d'exploitation : opération, nom de l'erreur, SQLSTATE et code PSP ; aucune valeur. */ export type PaymentFailureLog = (operation: PaymentOperation, error: unknown) => void; @@ -175,6 +244,8 @@ export class CheckoutPaymentService { private readonly store: CheckoutPaymentStore, /** Connecteurs servis par cette image, par fournisseur ; vide en production (lot C). */ private readonly providers: ReadonlyMap, + /** Porte de la caution (US-701) ; sans base, elle échoue (503), jamais un paiement sans elle. */ + private readonly deposits: DepositGatePort, private readonly logFailure: PaymentFailureLog = LOG_PAYMENT_FAILURE, ) {} @@ -182,7 +253,22 @@ export class CheckoutPaymentService { async payment(proof: Buffer, holdId: string): Promise { if (!isUuid(holdId)) throw new PaymentHttpError('HOLD_NOT_FOUND'); const id = holdId.toLowerCase(); - return viewOf(id, await this.#read(proof, id)); + return this.#withDeposit(proof, viewOf(id, await this.#read(proof, id))); + } + + /** + * Vue de la caution ajoutée à l'état : décision figée, ou évaluée SANS écriture tant qu'un + * paiement est possible (S05 l'affiche avant le paiement, 08 BR-PAY-06). + */ + async #withDeposit(proof: Buffer, view: T): Promise { + const evaluate = PAYABLE_STATES.has(view.state); + const deposit = await this.#guard('deposit', () => + this.deposits.view(proof, view.holdId, evaluate), + ); + if (deposit === 'AUTH_REQUIRED' || deposit === 'HOLD_NOT_FOUND') { + throw new PaymentHttpError(deposit); + } + return deposit === null ? view : { ...view, deposit: depositViewOf(deposit) }; } /** @@ -205,7 +291,23 @@ export class CheckoutPaymentService { before.state !== 'DECLINED' && before.state !== 'INTERRUPTED' ) { - return { created: false, payment: { ...before, redirectUrl: null } }; + const view = await this.#withDeposit(proof, before); + return { created: false, payment: { ...view, redirectUrl: null } }; + } + // US-701 : caution décidée AVANT le paiement ; refus sans écriture ni ordre (08 BR-PAY-06) + const gate = await this.#guard('deposit', () => this.deposits.enforce(proof, id)); + switch (gate.kind) { + case 'ACCEPTED': + break; + case 'REFUSED': + throw new PaymentHttpError( + gate.view.code === 'PARAM_MISSING' ? 'DEPOSIT_PARAM_MISSING' : 'DEPOSIT_RAIL_UNAVAILABLE', + ); + case 'HOLD_NOT_PAYABLE': + // hold devenu terminal entre la lecture et la décision : l'état fait foi + return this.#current(proof, id, null); + default: + throw new PaymentHttpError(gate.kind); } // aucun connecteur dans cette image : refus AVANT T1 (le hold n'est pas mis en vol) if (this.providers.size === 0) throw new PaymentHttpError('PAYMENT_UNAVAILABLE'); @@ -297,7 +399,7 @@ export class CheckoutPaymentService { holdId: string, redirectUrl: string | null, ): Promise<{ readonly created: boolean; readonly payment: CheckoutPaymentStarted }> { - const view = viewOf(holdId, await this.#read(proof, holdId)); + const view = await this.#withDeposit(proof, viewOf(holdId, await this.#read(proof, holdId))); // une redirection n'a de sens que tant que le paiement est en cours const url = view.state === 'VERIFYING' || view.state === 'INTERRUPTED' ? redirectUrl : null; return { created: url !== null, payment: { ...view, redirectUrl: url } }; diff --git a/apps/api/src/modules/avl/testing/checkout-deposit.contract.test.ts b/apps/api/src/modules/avl/testing/checkout-deposit.contract.test.ts new file mode 100644 index 000000000..373f2a8a7 --- /dev/null +++ b/apps/api/src/modules/avl/testing/checkout-deposit.contract.test.ts @@ -0,0 +1,167 @@ +/** + * Contrat HTTP de la caution au paiement du hold (US-701, ADR-169 ; 08 BR-PAY-06 « Moment de + * l'évaluation » ; écran S05) sur l'application RÉELLE (ApiModule, harnais d'US-043) : chaque + * réponse est confrontée à `openapi.json`. + * + * Attendus tirés de 08 BR-PAY-06 et de 19 US-225 / US-701, jamais du code testé : + * - la caution est décidée AVANT le paiement : refus ⇒ 409 `DEPOSIT_RAIL_UNAVAILABLE` (T59) ou + * `DEPOSIT_PARAM_MISSING` (T72 c), AUCUN T1 ni ordre chez le PSP ; + * - le voyageur ne lit que le montant, la devise, la nature et la libération (S-7) : jamais les + * déclencheurs, l'âge, le signal de risque ni l'instantané des paramètres ; + * - porte indisponible ⇒ 503, jamais un paiement sans décision de caution (fail-closed). + * Montant : 300,00 de T57 (valeur de test du mécanisme) à l'exposant de la devise de chaque pays + * configuré (USD 30 000, PYG 300). + * Les règles de la porte sont prouvées par PAY (`deposit-checkout.test.ts`) et en base + * (`l0-us701-deposit-hold`). + */ +import { readFileSync } from 'node:fs'; +import { afterAll, describe, expect, it } from 'vitest'; +import { countryCases } from '../../../../test/support/countries.js'; +import { closeContractApps, startContractApp } from '../../../testing/contract/support.js'; +import type { ContractApp } from '../../../testing/contract/support.js'; +import type { CheckoutPaymentRow } from '../internal/checkout/payment-store.js'; +import { + FakeCheckoutPaymentStore, + FakeDepositGate, + RecordingHostedPayments, +} from './fake-checkout-payment-store.js'; + +const HOLD = '00000000-0000-4000-8000-0000000701b1'; +const EXPIRES = '2036-11-30T15:10:00.000Z'; +const RELEASE = '2036-12-06T15:00:00.000Z'; + +const ROW: CheckoutPaymentRow = { + holdStatus: 'ACTIVE', + tripId: null, + expiresAt: EXPIRES, + paymentInFlightUntil: null, + operationStatus: null, + request: null, +}; + +/** Pays configurés (lus dans la configuration) ; 300,00 de T57 à l'exposant de la devise. */ +const EXPONENTS = new Map( + ( + JSON.parse( + readFileSync(new URL('../../cfg/data/currencies.json', import.meta.url), 'utf8'), + ) as { currencies: { code: string; exponent: number }[] } + ).currencies.map((c) => [c.code, c.exponent]), +); +const CASES = countryCases().map((c) => ({ + ...c, + deposit: 300n * 10n ** BigInt(EXPONENTS.get(c.currency) ?? 0), +})); + +const apps: ContractApp[] = []; + +async function app() { + const store = new FakeCheckoutPaymentStore(); + const psp = new RecordingHostedPayments(); + const gate = new FakeDepositGate(); + const a = await startContractApp({ + checkout: { payments: { store, providers: new Map([['FAKE', psp]]), deposits: gate } }, + }); + apps.push(a); + const hold = (row: Partial = {}) => + store.holds.set(`${a.hash('voyageur')}:${HOLD}`, { row: { ...ROW, ...row } }); + const pay = () => + a.api.request('POST', `/checkout/holds/${HOLD}/payment`, { + headers: a.cookie('voyageur'), + body: { method: 'CARD' }, + }); + const read = () => + a.api.request('GET', `/checkout/holds/${HOLD}/payment`, { headers: a.cookie('voyageur') }); + return { store, psp, gate, hold, pay, read }; +} + +const C2 = ['triggers', 'paramsSnapshot', 'params_snapshot', 'youngestDriverAge', 'riskEvaluated']; + +describe('US-701 — caution au paiement du hold du checkout (contrat)', () => { + afterAll(async () => { + await closeContractApps(); + }); + + for (const c of CASES) { + it(`S05 (${c.country}, ${c.currency}) : caution exigée ⇒ montant, nature et libération seulement, jamais un champ [C2]`, async () => { + const { gate, hold, read } = await app(); + hold(); + gate.shown = { + status: 'REQUIRED', + amountMinor: c.deposit, + currency: c.currency, + kind: 'HOLD', + releaseAt: new Date(RELEASE), + }; + const r = await read(); + expect(r.status).toBe(200); + expect((r.json as { payment: { deposit: unknown } }).payment.deposit).toEqual({ + status: 'REQUIRED', + amountMinor: String(c.deposit), + currency: c.currency, + kind: 'HOLD', + releaseAt: RELEASE, + }); + for (const k of C2) expect(JSON.stringify(r.json)).not.toContain(k); + // un paiement est possible : la porte est évaluée (sans écriture) + expect(gate.views).toEqual([true]); + }); + } + + it('S05 : aucune caution (T70) ⇒ `NONE` ; réservation impossible (T59) ⇒ `UNAVAILABLE` et jours possibles', async () => { + const { gate, hold, read } = await app(); + hold(); + gate.shown = { status: 'NONE' }; + expect((await read()).json).toMatchObject({ payment: { deposit: { status: 'NONE' } } }); + gate.shown = { status: 'UNAVAILABLE', code: 'DEPOSIT_RAIL_UNAVAILABLE', maxBookableDays: 3 }; + const r = await read(); + expect((r.json as { payment: { deposit: unknown } }).payment.deposit).toEqual({ + status: 'UNAVAILABLE', + maxBookableDays: 3, + }); + // le code interne du refus n'est pas rendu dans la vue (le message suit maxBookableDays) + expect(JSON.stringify(r.json)).not.toContain('DEPOSIT_RAIL_UNAVAILABLE'); + }); + + it('paiement terminé ou en cours : la porte n’est PAS évaluée (décision figée seulement)', async () => { + const { gate, hold, read } = await app(); + hold({ holdStatus: 'PAYMENT_IN_FLIGHT', operationStatus: 'SUBMITTED' }); + const r = await read(); + expect(r.status).toBe(200); + expect((r.json as { payment: Record }).payment).not.toHaveProperty('deposit'); + expect(gate.views).toEqual([false]); + }); + + for (const [code, refusal] of [ + ['DEPOSIT_RAIL_UNAVAILABLE', 'DEPOSIT_RAIL_UNAVAILABLE'], + ['DEPOSIT_PARAM_MISSING', 'PARAM_MISSING'], + ] as const) { + it(`refus de la porte (${refusal}) ⇒ 409 ${code} AVANT T1 : aucun ordre, aucun appel au PSP`, async () => { + const { store, psp, gate, hold, pay } = await app(); + hold(); + gate.enforcement = { + kind: 'REFUSED', + view: { status: 'UNAVAILABLE', code: refusal, maxBookableDays: null }, + }; + const r = await pay(); + expect(r.status).toBe(409); + expect(r.json).toEqual({ code, messageKey: 'common.payment.depositUnavailable' }); + expect(gate.enforced).toEqual([HOLD]); + expect(store.starts).toEqual([]); + expect(psp.orders).toEqual([]); + }); + } + + it('porte de la caution en panne ⇒ 503 BOOKING_UNAVAILABLE (lecture et paiement), aucun T1', async () => { + const { store, gate, hold, pay, read } = await app(); + hold(); + gate.down = true; + for (const r of [await pay(), await read()]) { + expect(r.status).toBe(503); + expect(r.json).toEqual({ + code: 'BOOKING_UNAVAILABLE', + messageKey: 'common.checkout.unavailable', + }); + } + expect(store.starts).toEqual([]); + }); +}); diff --git a/apps/api/src/modules/avl/testing/checkout-payment.contract.test.ts b/apps/api/src/modules/avl/testing/checkout-payment.contract.test.ts index 2475ca3b3..334626545 100644 --- a/apps/api/src/modules/avl/testing/checkout-payment.contract.test.ts +++ b/apps/api/src/modules/avl/testing/checkout-payment.contract.test.ts @@ -29,6 +29,7 @@ import type { CheckoutPaymentRow, PaymentStart } from '../internal/checkout/paym import type { HostedPaymentProvider } from '../internal/checkout/payment.service.js'; import { FakeCheckoutPaymentStore, + FakeDepositGate, PaymentError, RecordingHostedPayments, } from './fake-checkout-payment-store.js'; @@ -79,7 +80,12 @@ async function app( const psp = options.psp ?? new RecordingHostedPayments(); const a = await startContractApp({ checkout: { - payments: { store, providers: options.providers ?? new Map([['FAKE', psp]]) }, + // US-701 : porte de la caution imposée « aucune caution » (contrat d'US-223 inchangé) + payments: { + store, + providers: options.providers ?? new Map([['FAKE', psp]]), + deposits: new FakeDepositGate(), + }, }, }); apps.push(a); diff --git a/apps/api/src/modules/avl/testing/fake-checkout-payment-store.ts b/apps/api/src/modules/avl/testing/fake-checkout-payment-store.ts index ed31f69f1..41cc571fa 100644 --- a/apps/api/src/modules/avl/testing/fake-checkout-payment-store.ts +++ b/apps/api/src/modules/avl/testing/fake-checkout-payment-store.ts @@ -8,11 +8,16 @@ import { assertMovingLegs, PaymentError } from '../../pay/index.js'; import type { CreateHostedPaymentRequest, + DepositEnforcement, + DepositGuestView, HostedPayment, OperationLookup, ProviderOperation, } from '../../pay/index.js'; -import type { HostedPaymentProvider } from '../internal/checkout/payment.service.js'; +import type { + DepositGatePort, + HostedPaymentProvider, +} from '../internal/checkout/payment.service.js'; import type { CheckoutPaymentRow, CheckoutPaymentStore, @@ -123,3 +128,31 @@ export class RecordingHostedPayments implements HostedPaymentProvider { } export { PaymentError }; + +/** + * Porte de la caution imposée (US-701) — TESTS SEULEMENT. Par défaut, AUCUNE vue (champ `deposit` + * absent, forme de 223b inchangée) et décision « aucune caution » : les contrats d'US-223 ne + * portent pas sur la caution. Les règles (déclencheurs, montant, rail, écriture unique) sont + * prouvées par PAY (`deposit-checkout.test.ts`) et en base (`l0-us701-deposit-hold`). + */ +export class FakeDepositGate implements DepositGatePort { + /** Vue rendue à la lecture ; `null` : champ `deposit` absent. */ + shown: DepositGuestView | null = null; + enforcement: DepositEnforcement = { kind: 'ACCEPTED', view: { status: 'NONE' } }; + down = false; + /** Appels de `view` (évaluation demandée ou non) et de `enforce`. */ + views: boolean[] = []; + enforced: string[] = []; + + view(_proof: Buffer, _holdId: string, evaluate: boolean): Promise { + this.views.push(evaluate); + if (this.down) return Promise.reject(new Error('base indisponible')); + return Promise.resolve(this.shown); + } + + enforce(_proof: Buffer, holdId: string): Promise { + this.enforced.push(holdId); + if (this.down) return Promise.reject(new Error('base indisponible')); + return Promise.resolve(this.enforcement); + } +} diff --git a/apps/api/src/modules/bus/internal/alert-channel.ts b/apps/api/src/modules/bus/internal/alert-channel.ts index a7e8fe7e8..a3c300acc 100644 --- a/apps/api/src/modules/bus/internal/alert-channel.ts +++ b/apps/api/src/modules/bus/internal/alert-channel.ts @@ -40,6 +40,9 @@ export const ALERT_CODES = [ // refusé ou report refusé (revue FIN). Une fois par instance et par état 'FIN_REFUND_BLOCKED', 'FIN_REFUND_FAILED', + // caution (US-701, ADR-169) : ré-autorisation refusée, trip signalé à l'ops, AUCUN débit + // (19 US-225 critère 3) ; une fois par caution (la transition retire la minuterie) + 'DEPOSIT_REAUTH_FAILED', // files de revue (US-106, ADR-106) : élément en retard (16 ADM-002, P2) ; dossier KYC en revue // qui ne peut pas être mis en file (P1 : personne ne le verrait) 'OPS_REVIEW_SLA_BREACH', diff --git a/apps/api/src/modules/pay/README.md b/apps/api/src/modules/pay/README.md index 5b5233b89..d6d90fe0a 100644 --- a/apps/api/src/modules/pay/README.md +++ b/apps/api/src/modules/pay/README.md @@ -19,27 +19,27 @@ Détail fichier par fichier, FAKE et mode hostile : [`internal/README.md`](inter Entités de 17 §3.2.7 : -| Entité | État en base | -| -------------------------- | ------------------------------------------------------------------------------------------------ | -| `payment_operation` | table `core.payment_payment_operation` (migration 0005 ; `psp_account_id` 0028, `NOT NULL` 0038) | -| `webhook_inbox` | table `core.payment_webhook_inbox` (migration 0005 ; clé étrangère du compte 0038) | -| `psp_account` | table `core.payment_psp_account` (migration 0028) | -| `psp_capability` | table `core.payment_psp_capability` (migration 0028) | -| `payment_operation_leg` | table `core.payment_payment_operation_leg` (migration 0028) | -| `payment_operation_event` | table `core.payment_payment_operation_event` (migration 0028) | -| `psp_submerchant` | table `core.payment_psp_submerchant` (migration 0039) | -| `payment_command` | table `core.payment_payment_command` (migration 0040, réduite à `CANCEL_ORDER`) | -| `payment_operation_link` | cible 17, pas encore créée | -| `payment_instrument` | cible 17, pas encore créée | -| `mit_consent` | cible 17, pas encore créée | -| `tender` | cible 17, pas encore créée | -| `refund_instance` | cible 17, pas encore créée | -| `deposit_hold` | cible 17, pas encore créée (US-701) ; rails et décision prêts en fonctions pures (US-225) | -| `chargeback` | cible 17, pas encore créée | -| `debt_balance` | cible 17, pas encore créée | -| `payment_plan` | cible 17, pas encore créée | -| `payment_plan_installment` | cible 17, pas encore créée | -| `credit_lot` | cible 17, pas encore créée | +| Entité | État en base | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `payment_operation` | table `core.payment_payment_operation` (migration 0005 ; `psp_account_id` 0028, `NOT NULL` 0038) | +| `webhook_inbox` | table `core.payment_webhook_inbox` (migration 0005 ; clé étrangère du compte 0038) | +| `psp_account` | table `core.payment_psp_account` (migration 0028) | +| `psp_capability` | table `core.payment_psp_capability` (migration 0028) | +| `payment_operation_leg` | table `core.payment_payment_operation_leg` (migration 0028) | +| `payment_operation_event` | table `core.payment_payment_operation_event` (migration 0028) | +| `psp_submerchant` | table `core.payment_psp_submerchant` (migration 0039) | +| `payment_command` | table `core.payment_payment_command` (migration 0040, réduite à `CANCEL_ORDER`) | +| `payment_operation_link` | cible 17, pas encore créée | +| `payment_instrument` | cible 17, pas encore créée | +| `mit_consent` | cible 17, pas encore créée | +| `tender` | cible 17, pas encore créée | +| `refund_instance` | cible 17, pas encore créée | +| `deposit_hold` | `core.payment_deposit_hold` (0143, US-701) : décision figée par hold avant le paiement, lue et écrite par les seules fonctions de cmd_hold_owner | +| `chargeback` | cible 17, pas encore créée | +| `debt_balance` | cible 17, pas encore créée | +| `payment_plan` | cible 17, pas encore créée | +| `payment_plan_installment` | cible 17, pas encore créée | +| `credit_lot` | cible 17, pas encore créée | Hors entités de 17 : `core.payment_psp_capability_catalog` (catalogue des capacités, migration 0039 ; `SUPPORTS_PAYOUT_WITHOUT_HOST_TAX_ID` ajoutée par 0087, non bloquante, lue par le KYC de l'hôte : inconnue ⇒ numéro fiscal exigé avant l'activation, ADR-115). Commandes `SECURITY DEFINER` (famille `cmd_money`) : `core.payment_cmd_record_operation`, `payment_cmd_apply_operation_status`, `payment_cmd_receive_webhook` (0028), `payment_cmd_register_submerchant`, `payment_cmd_record_submerchant_status` (0039). Détail : `packages/db/README.md`, sections « Port PaymentProvider » et « Port de place de marché ». @@ -47,6 +47,14 @@ Hors entités de 17 : `core.payment_psp_capability_catalog` (catalogue des capac **Aucune caution par défaut.** Une caution n'existe que si un déclencheur paramétré par pays est vrai (`deposit_always_required`, `deposit_trigger_classes` = {LUXE}, âge sur `deposit_young_driver_classes` = vide au PA et au PY, signal de risque si `risk_control_deployed`) : graine `0142`, valeurs PROPOSÉES. Au checkout, avant le paiement, `decideDepositGate` rend `NOT_REQUIRED` (aucun rail évalué), `REQUIRED` avec le rail choisi par configuration, ou un refus (`PARAM_MISSING` si `deposit_amount` manque, `DEPOSIT_RAIL_UNAVAILABLE` avec les jours possibles). Le rail « débit puis remboursement » reste fermé tant que `funds_holding_enabled[pays]` = `false` (aucun fonds de tiers détenu) ; une capacité PSP inconnue vaut « non ». `planDepositDecision` et `DepositRailExecutor` exécutent la décision sur le port (FAKE seulement) avec le montant explicite de chaque commande. **Non branché** au checkout ni à un travailleur dans cette story : `deposit_hold`, l'écriture au checkout, les minuteries et l'écran S05 sont à US-701 / US-702 (voir `docs/team/handoffs/US-225.md`). +### Caution figée au checkout, vue du voyageur, minuterie (US-701 ; ADR-169) + +- `DepositCheckoutGate` (`internal/deposit-checkout.ts`) : `view` (S05 : décision figée, ou évaluée **sans écriture** tant qu'un paiement est possible) et `enforce` (avant T1 : refus ⇒ aucune ligne ; sinon décision figée une fois par `core.payment_cmd_record_deposit_decision`, `EXISTING` ensuite). `evaluateDepositCheckout` (pur) rend la décision, la ligne à figer (mécanisme, déclencheurs [C2], instantané des paramètres [C2], montant, `H_requise`, `V`, échéancier de `planDepositSchedule`) et la vue du voyageur `DepositGuestView` (statut, montant, devise, `HOLD` / `CHARGE`, libération ; ou refus et jours possibles), jamais un champ [C2]. Âge des conducteurs et signal de risque non lus ici : inconnus, donc fail-closed (suite S-10). +- `PgDepositCheckoutStore` (`internal/pg-deposit-checkout.ts`) sous `app_api` : `core.payment_deposit_checkout`, `core.payment_cmd_record_deposit_decision` (0143). +- `DepositReauthTimer` / `registerDepositTimers` (`internal/deposit-timer.ts`) : tâche `deposit_timer` (60 s, nom `payment_command`) ; file `core.payment_deposit_reauth_due`, ré-autorisation par le port hors transaction, transition `core.payment_cmd_deposit_transition` (rang attendu) ; refusée ⇒ décision avancée à `expiration − deposit_safety_h`, alerte `DEPOSIT_REAUTH_FAILED`, aucun débit ; en cours ou inconnue ⇒ aucun changement, même clé au passage suivant. Aucun connecteur en production avant le lot C. +- `DepositRailExecutor.reauthorize` : `SUCCEEDED` seul ⇒ `REAUTHORIZED` ; `PENDING` / `SUBMITTED` / `UNKNOWN` / `UNKNOWN_OUTCOME` ⇒ `REAUTH_PENDING` (`needsLookup`). +- Clés d'idempotence (S-6, 08 E4) : `{trip}:{segment}:v0-DEPOSIT-{caution}:{opération}:{moyen}:i{n}:a{m}` (`depositOperationKey`) ; remboursement du rail (b) = `offSettlementRefundKey` d'origine `DEPOSIT`. + ## Événements Aucun événement de domaine n'est émis ni consommé par le code de PAY aujourd'hui. Chaque statut reçu est écrit dans `core.payment_payment_operation_event` (pas un événement d'outbox). La commande `CANCEL_ORDER` est écrite dans `core.payment_payment_command` par les commandes du hold (AVL, migration 0040), pas par un événement. diff --git a/apps/api/src/modules/pay/index.ts b/apps/api/src/modules/pay/index.ts index ed3508d6b..a3c00b3b4 100644 --- a/apps/api/src/modules/pay/index.ts +++ b/apps/api/src/modules/pay/index.ts @@ -106,7 +106,7 @@ export { COMMAND_KINDS, MoneyCommandSender } from './internal/money-command-send export type { CommandKind, MoneyCommand, SendOutcome } from './internal/money-command-sender.js'; export { depositOperationKey, DEPOSIT_OPERATION_TYPES } from './internal/idempotency.js'; -export type { DepositOperationType } from './internal/idempotency.js'; +export type { DepositKeyParts, DepositOperationType } from './internal/idempotency.js'; // Caution « comme Turo » : déclencheurs, rails, décision, exécution (US-225, ADR-164) export { @@ -136,9 +136,11 @@ export { depositHoldValidityHours, depositReauthDueAt, depositReleaseAt, + depositScheduleAfterReauth, isCapturableOnDeposit, nextDepositStatus, planDepositDecision, + planDepositSchedule, requiredHoldMinutes, selectDepositRail, } from './internal/deposit-rails.js'; @@ -157,7 +159,9 @@ export type { DepositRailParams, DepositRailRequest, DepositRailSelection, + DepositSchedule, DepositStep, + CompleteRailParams, } from './internal/deposit-rails.js'; export { DepositRailExecutor } from './internal/deposit-executor.js'; export type { @@ -170,6 +174,39 @@ export type { } from './internal/deposit-executor.js'; export { DEPOSIT_CONFIG_KEYS, PgDepositRailConfigReader } from './internal/pg-deposit-config.js'; export type { DepositRailConfig } from './internal/pg-deposit-config.js'; +// Caution au checkout, vue du voyageur, minuterie de ré-autorisation (US-701, ADR-169) +export { + DepositCheckoutGate, + evaluateDepositCheckout, + guestViewOfRecorded, +} from './internal/deposit-checkout.js'; +export type { + DepositCheckoutContext, + DepositCheckoutRead, + DepositCheckoutStore, + DepositConfigSource, + DepositDecisionRecord, + DepositEnforcement, + DepositGuestView, + DepositReadRefusal, + DepositRecordOutcome, + RecordedDeposit, +} from './internal/deposit-checkout.js'; +export { PgDepositCheckoutStore } from './internal/pg-deposit-checkout.js'; +export { + DEPOSIT_TIMER_BATCH, + DEPOSIT_TIMER_PERIOD_SECONDS, + DEPOSIT_TIMER_WORKER, + DepositReauthTimer, + PgDepositTimerStore, + postgresDepositTimerDeps, + registerDepositTimers, +} from './internal/deposit-timer.js'; +export type { + DepositTimerDeps, + DepositTimerStep, + DueDepositReauth, +} from './internal/deposit-timer.js'; // Webhooks (17 §4.4) export { diff --git a/apps/api/src/modules/pay/internal/deposit-checkout.test.ts b/apps/api/src/modules/pay/internal/deposit-checkout.test.ts new file mode 100644 index 000000000..efc78bbdd --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-checkout.test.ts @@ -0,0 +1,351 @@ +/** + * US-701 (ADR-169) — caution figée au checkout, échéancier et vue du voyageur (08 BR-PAY-06 + * « Moment de l'évaluation », « Montant unique », « Libération à heure fixe », « Mécanisme » ; + * 17 §3.2.7 ; 19 US-701 critères 1, 3 et 4). Attendus : oracle `docs/specs/tools/check_t49plus.py` + * (T57 : décision à fin + 70 h ; T59 : refus, 3 jours possibles ; T70 : aucune caution ; T72 c : + * PARAM_MISSING), exportés par `@rueda/money/golden-vectors`, et calcul de 08 refait à la main + * (heures) ; jamais le code testé. Chaque cas en USD (PA) et en PYG sans décimale (PY), paramètres + * lus dans la graine (`cfg/data/params.json`). + */ +import { readFileSync } from 'node:fs'; +import { createCurrencyRegistry } from '@rueda/money'; +import { checksFor, loadGoldenVectors } from '@rueda/money/golden-vectors'; +import type { GoldenValue } from '@rueda/money/golden-vectors'; +import { describe, expect, it } from 'vitest'; +import { CapabilitySet } from './capabilities.js'; +import type { CapabilityRecord } from './capabilities.js'; +import { + DepositCheckoutGate, + evaluateDepositCheckout, + guestViewOfRecorded, +} from './deposit-checkout.js'; +import type { + DepositCheckoutContext, + DepositCheckoutRead, + DepositCheckoutStore, + DepositDecisionRecord, + DepositReadRefusal, + DepositRecordOutcome, +} from './deposit-checkout.js'; +import { depositScheduleAfterReauth } from './deposit-rails.js'; +import type { DepositRailConfig } from './pg-deposit-config.js'; +import type { DepositValueClass } from './deposit-triggers.js'; +import { countryCases } from '../../../../test/support/countries.js'; + +const set = loadGoldenVectors(); +const check = (vectorId: string, label: RegExp): GoldenValue => { + const found = checksFor(set, vectorId).find((c) => label.test(c.label)); + if (found === undefined) throw new Error(`contrôle ${vectorId} ${label} absent`); + return found.expected; +}; + +const read = (file: string): unknown => + JSON.parse(readFileSync(new URL(`../../cfg/data/${file}`, import.meta.url), 'utf8')); +const CURRENCIES = createCurrencyRegistry( + (read('currencies.json') as { currencies: { code: string; exponent: number }[] }).currencies, +); +const PARAMS = ( + read('params.json') as { params: { key: string; values: Record }[] } +).params; +const p = (key: string, country: string): unknown => + PARAMS.find((x) => x.key === key)?.values[country]; + +const H = 3_600_000; +const T = Date.parse('2031-07-10T10:00:00.000Z'); +const at = (hours: number, minutes = 0): Date => new Date(T + hours * H + minutes * 60_000); + +/** 300,00 de T57 (valeur de test du mécanisme) à l'exposant de la devise du pays. */ +const CASES = countryCases().map((c) => ({ + ...c, + deposit: 300n * 10n ** BigInt(CURRENCIES.get(c.currency).exponent), +})); + +const rec = (capability: string, value: unknown): CapabilityRecord => ({ + capability, + method: '*', + value, + status: 'VALIDATED_SANDBOX', +}); + +/** PSP « à 7 j » de T57 (V = 168 h) ; `extra` : capacités ajoutées (ré-autorisation). */ +function config( + c: (typeof CASES)[number], + over: { amounts?: DepositRailConfig['amounts']; extra?: CapabilityRecord[] } = {}, +): DepositRailConfig { + return { + triggerParams: { + alwaysRequired: p('deposit_always_required', c.country) as boolean, + triggerClasses: p('deposit_trigger_classes', c.country) as DepositValueClass[], + youngDriverAge: p('deposit_young_driver_age', c.country) as number, + youngDriverClasses: p('deposit_young_driver_classes', c.country) as DepositValueClass[], + onRiskFlag: p('deposit_on_risk_flag', c.country) as boolean, + riskControlDeployed: p('risk_control_deployed', c.country) as boolean, + }, + amounts: 'amounts' in over ? over.amounts : { LUXE: c.deposit }, + railParams: { + authLeadH: p('auth_lead_h', c.country) as number, + releaseDelayH: p('release_delay_h', c.country) as number, + marginH: p('marge_h', c.country) as number, + safetyH: p('deposit_safety_h', c.country) as number, + reauthLeadH: p('deposit_reauth_lead_h', c.country) as number, + providerMaxHoldH: 168, + chargeCapMinor: 0n, + fundsHoldingEnabled: p('funds_holding_enabled', c.country) as boolean, + }, + feeNoticeH: p('deposit_fee_notice_h', c.country) as number, + capabilities: new CapabilitySet([ + rec('SUPPORTS_PREAUTH', true), + rec('MAX_HOLD_HOURS', 168), + rec('SUPPORTS_PARTIAL_CAPTURE', true), + rec('SUPPORTS_VOID', true), + rec('SUPPORTS_MIT', true), + ...(over.extra ?? []), + ]), + }; +} + +function ctx( + c: (typeof CASES)[number], + over: { valueClass?: DepositValueClass | null; tripMinutes?: number } = {}, +): DepositCheckoutContext { + return { + country: c.country, + currency: c.currency, + valueClass: over.valueClass === undefined ? 'LUXE' : over.valueClass, + // réservé bien avant : auth_at = début − 24 h (T57) + now: at(-24 * 10), + scheduledStart: at(0), + scheduledEnd: at(0, over.tripMinutes ?? 72 * 60), + provider: 'FAKE', + }; +} + +describe.each(CASES)('$country ($currency) — décision figée au checkout', (c) => { + it('critère 1 (T57) : 3 jours chez un PSP à 7 j ⇒ pré-autorisation unique à auth_at = début − 24 h ; libération à fin + 72 h ; décision à fin + 70 h', () => { + const t57 = check('T57', /^T57$/) as { single: boolean }; + const r = evaluateDepositCheckout(ctx(c), config(c)); + expect(t57.single).toBe(true); + // 08 : H_requise = 24 + 72 + 72 = 168 h ≤ V = 168 h ; décision = min(fin + 72 h ; fin + 72 h − 2 h) + expect(r.record).toMatchObject({ + mechanism: 'PREAUTH_SINGLE', + triggers: ['CLASS'], + amountMinor: c.deposit, + hRequiredHours: 168, + vHours: 168, + authAt: at(-24), + releaseAt: at(72 + 72), + decisionAt: at(72 + 70), + reauthDueAt: null, + }); + expect(r.view).toEqual({ + status: 'REQUIRED', + amountMinor: c.deposit, + currency: c.currency, + kind: 'HOLD', + releaseAt: at(72 + 72), + }); + }); + + it('critère 3 (T59) : 3 j + 25 min, SUPPORTS_REAUTH non validée ⇒ refus SANS ligne, 3 jours possibles', () => { + const [single] = check('T59', /forme heures/) as [boolean]; + const r = evaluateDepositCheckout(ctx(c, { tripMinutes: 72 * 60 + 25 }), config(c)); + expect(single).toBe(false); + expect(r.record).toBeNull(); + // V − avance − libération = 168 − 24 − 72 = 72 h ⇒ 3 jours entiers + expect(r.view).toEqual({ + status: 'UNAVAILABLE', + code: 'DEPOSIT_RAIL_UNAVAILABLE', + maxBookableDays: 3, + }); + }); + + it('critère 3 (T59, rail a) : SUPPORTS_REAUTH validée ⇒ REAUTH ; ré-autorisation à (auth_at + V) − 24 h ; décision planifiée à la libération', () => { + const r = evaluateDepositCheckout( + ctx(c, { tripMinutes: 72 * 60 + 25 }), + config(c, { extra: [rec('SUPPORTS_REAUTH', true)] }), + ); + // auth_at = −24 h ; expiration prévue = +144 h ; ré-autorisation à +120 h + expect(r.record).toMatchObject({ + mechanism: 'REAUTH', + authAt: at(-24), + releaseAt: at(72 + 72, 25), + decisionAt: at(72 + 72, 25), + reauthDueAt: at(120), + }); + }); + + it('T70 : véhicule STANDARD ⇒ NOT_REQUIRED figé (montant 0, aucun déclencheur, aucune échéance), vue « aucune caution »', () => { + const [none] = check('T70', /sans caution/) as [boolean]; + expect(none).toBe(false); + const r = evaluateDepositCheckout( + ctx(c, { valueClass: 'STANDARD', tripMinutes: 72 * 60 + 25 }), + config(c), + ); + expect(r.record).toMatchObject({ + mechanism: 'NOT_REQUIRED', + triggers: [], + amountMinor: 0n, + hRequiredHours: null, + authAt: null, + releaseAt: null, + decisionAt: null, + reauthDueAt: null, + }); + expect(r.view).toEqual({ status: 'NONE' }); + }); + + it('T72 c : caution exigée sans deposit_amount (LUXE À DÉCIDER) ⇒ PARAM_MISSING, aucune ligne, aucun jour', () => { + expect(check('T72', /a\/b\/c\/d/)).toEqual(expect.arrayContaining(['PARAM_MISSING'])); + const r = evaluateDepositCheckout(ctx(c), config(c, { amounts: undefined })); + expect(r.record).toBeNull(); + expect(r.view).toEqual({ status: 'UNAVAILABLE', code: 'PARAM_MISSING', maxBookableDays: null }); + }); + + it('classe inconnue (fail-closed) ⇒ CLASS vrai, jamais NOT_REQUIRED', () => { + const r = evaluateDepositCheckout(ctx(c, { valueClass: null }), config(c)); + expect(r.record).toBeNull(); + expect(r.decision.triggers.triggers).toContain('CLASS'); + }); + + it('[C2] : params_snapshot sans date ni donnée personnelle ; la vue du voyageur ne porte que statut, montant, devise, nature, libération', () => { + const r = evaluateDepositCheckout(ctx(c), config(c)); + const snapshot = JSON.stringify(r.record?.paramsSnapshot); + expect(snapshot).not.toMatch(/birth|naissance|\d{4}-\d{2}-\d{2}/); + expect(Object.keys(r.record?.paramsSnapshot ?? {}).sort()).toEqual([ + 'params', + 'provider', + 'riskEvaluated', + 'valueClass', + 'version', + 'youngestDriverAge', + ]); + expect(Object.keys(r.view).sort()).toEqual([ + 'amountMinor', + 'currency', + 'kind', + 'releaseAt', + 'status', + ]); + }); +}); + +describe.each(CASES)('$country ($currency) — échéances après une ré-autorisation', (c) => { + const params = { + safetyH: p('deposit_safety_h', c.country) as number, + reauthLeadH: p('deposit_reauth_lead_h', c.country) as number, + }; + const current = { authExpiryAt: at(144), releaseAt: at(144, 25) }; + + it('acceptée à +120 h ⇒ expiration +288 h, aucune autre ré-autorisation, décision à la libération', () => { + expect(depositScheduleAfterReauth('REAUTHORIZED', current, at(120), 168, params)).toEqual({ + authExpiryAt: at(288), + decisionAt: at(144, 25), + reauthDueAt: null, + }); + }); + + it('refusée ⇒ expiration inchangée, décision AVANT elle (expiration − 2 h), plus de minuterie', () => { + expect(depositScheduleAfterReauth('REAUTH_REFUSED', current, at(120), 168, params)).toEqual({ + authExpiryAt: at(144), + decisionAt: at(142), + reauthDueAt: null, + }); + }); +}); + +/** Magasin en mémoire : une décision par hold, comme la base (contrainte d'unicité). */ +class MemoryStore implements DepositCheckoutStore { + recorded: DepositDecisionRecord | null = null; + writes = 0; + constructor( + private readonly context: DepositCheckoutContext | DepositReadRefusal, + private readonly outcome: DepositRecordOutcome = 'RECORDED', + ) {} + read(): Promise { + if (typeof this.context === 'string') return Promise.resolve(this.context); + if (this.recorded !== null) { + return Promise.resolve({ + kind: 'RECORDED', + deposit: { + mechanism: this.recorded.mechanism, + amountMinor: this.recorded.amountMinor, + currency: this.context.currency, + releaseAt: this.recorded.releaseAt, + }, + }); + } + return Promise.resolve({ kind: 'OPEN', context: this.context }); + } + record(_p: Buffer, _h: string, r: DepositDecisionRecord): Promise { + this.writes++; + if (this.outcome === 'RECORDED') this.recorded = r; + return Promise.resolve(this.outcome); + } +} + +describe.each(CASES)('$country ($currency) — porte du checkout', (c) => { + const proof = Buffer.from('jeton'); + const gateOf = (store: MemoryStore, cfg = config(c)) => + new DepositCheckoutGate(store, { read: () => Promise.resolve(cfg) }); + + it('lecture de S05 : évaluée SANS écriture ; décision figée ensuite relue telle quelle', async () => { + const store = new MemoryStore(ctx(c)); + const g = gateOf(store); + expect(await g.view(proof, 'h', true)).toMatchObject({ status: 'REQUIRED' }); + expect(await g.view(proof, 'h', false)).toBeNull(); + expect(store.writes).toBe(0); + expect(await g.enforce(proof, 'h')).toMatchObject({ kind: 'ACCEPTED' }); + expect(store.writes).toBe(1); + // seconde tentative de paiement : la décision figée fait foi, rien n'est réécrit + expect(await g.enforce(proof, 'h')).toMatchObject({ kind: 'ACCEPTED' }); + expect(store.writes).toBe(1); + expect(await g.view(proof, 'h', false)).toEqual({ + status: 'REQUIRED', + amountMinor: c.deposit, + currency: c.currency, + kind: 'HOLD', + releaseAt: at(72 + 72), + }); + }); + + it('refus (T59) ⇒ REFUSED et AUCUNE écriture', async () => { + const store = new MemoryStore(ctx(c, { tripMinutes: 72 * 60 + 25 })); + expect(await gateOf(store).enforce(proof, 'h')).toEqual({ + kind: 'REFUSED', + view: { status: 'UNAVAILABLE', code: 'DEPOSIT_RAIL_UNAVAILABLE', maxBookableDays: 3 }, + }); + expect(store.writes).toBe(0); + }); + + it('refus de la base (hold devenu terminal, devis indisponible, session) ⇒ rendu tel quel', async () => { + expect(await gateOf(new MemoryStore(ctx(c), 'HOLD_NOT_PAYABLE')).enforce(proof, 'h')).toEqual({ + kind: 'HOLD_NOT_PAYABLE', + }); + expect(await gateOf(new MemoryStore('QUOTE_UNAVAILABLE')).enforce(proof, 'h')).toEqual({ + kind: 'QUOTE_UNAVAILABLE', + }); + expect(await gateOf(new MemoryStore('QUOTE_UNAVAILABLE')).view(proof, 'h', true)).toBeNull(); + expect(await gateOf(new MemoryStore('AUTH_REQUIRED')).view(proof, 'h', true)).toBe( + 'AUTH_REQUIRED', + ); + }); + + it('vue d’une décision figée : NOT_REQUIRED ⇒ NONE ; débit puis remboursement ⇒ CHARGE', () => { + expect( + guestViewOfRecorded({ + mechanism: 'NOT_REQUIRED', + amountMinor: 0n, + currency: c.currency, + releaseAt: null, + }), + ).toEqual({ status: 'NONE' }); + expect( + guestViewOfRecorded({ + mechanism: 'CHARGE_THEN_REFUND', + amountMinor: c.deposit, + currency: c.currency, + releaseAt: at(144), + }), + ).toMatchObject({ status: 'REQUIRED', kind: 'CHARGE' }); + }); +}); diff --git a/apps/api/src/modules/pay/internal/deposit-checkout.ts b/apps/api/src/modules/pay/internal/deposit-checkout.ts new file mode 100644 index 000000000..82125f1c2 --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-checkout.ts @@ -0,0 +1,342 @@ +/** + * Caution au checkout (US-701, ADR-169 ; 08 BR-PAY-06 « Moment de l'évaluation », « Fail-closed », + * « Montant unique » ; 17 §3.2.7 `deposit_hold` ; 19 US-701 critères 3 et 4 ; suites S-2, S-7, S-8 + * d'US-225). + * + * Avant le paiement du hold (`POST /checkout/holds/{id}/payment`), la porte de US-225 + * (`decideDepositGate`) est évaluée avec le contexte lu par la base (pays, devise, classe du + * véhicule du catalogue, période du devis ENGAGÉ, compte marchand du pays, heure `platform.now()`) + * et la configuration du pays (`PgDepositRailConfigReader`) : + * - refus (`PARAM_MISSING`, `DEPOSIT_RAIL_UNAVAILABLE`) ⇒ AUCUNE ligne `deposit_hold` (08 : « un + * checkout refusé n'écrit aucune ligne »), le paiement n'est pas démarré ; + * - sinon la décision est FIGÉE dans `deposit_hold` (mécanisme, déclencheurs [C2], instantané des + * paramètres [C2], montant, `H_requise`, `V`, échéancier) par la commande de la base, qui revérifie + * ce qu'elle peut (montant = `deposit_amount[pays][classe]`, aucun `NOT_REQUIRED` sur une classe ou + * un pays déclencheur, rail « débit puis remboursement » fermé tant que `funds_holding_enabled` = + * false) ; une décision déjà figée pour ce hold n'est jamais réécrite. + * + * Le voyageur ne reçoit que la **vue** `DepositGuestView` (S-7) : statut, montant, devise, nature + * (blocage ou débit) et date de libération ; jamais les déclencheurs, l'âge, le signal de risque ni + * l'instantané des paramètres (08 : « un fraudeur ne doit pas pouvoir sonder le contrôle de + * risque »). + * + * Non lus ici (fail-closed, suite S-10 de la passation) : l'âge des conducteurs approuvés (inconnu + * ⇒ `AGE` vrai sur une classe de `deposit_young_driver_classes`, vide au PA et au PY) et le signal du + * contrôle de risque (inconnu ⇒ `RISK` vrai si `risk_control_deployed`, faux au PA et au PY). + */ +import { PaymentError } from './errors.js'; +import { completeRailParams, decideDepositGate, planDepositSchedule } from './deposit-rails.js'; +import type { DepositGateDecision, DepositMechanism, DepositRail } from './deposit-rails.js'; +import { DEPOSIT_VALUE_CLASSES } from './deposit-triggers.js'; +import type { DepositTrigger, DepositValueClass } from './deposit-triggers.js'; +import type { DepositRailConfig } from './pg-deposit-config.js'; + +/** Contexte du hold lu par la base (`core.payment_deposit_checkout`), sans donnée [C2]. */ +export interface DepositCheckoutContext { + readonly country: string; + readonly currency: string; + /** `value_class` du véhicule (catalogue) ; `null` : inconnue (fail-closed : `CLASS` vrai). */ + readonly valueClass: DepositValueClass | null; + readonly scheduledStart: Date; + readonly scheduledEnd: Date; + /** Fournisseur du compte marchand du pays ; `null` : aucun (capacités inconnues = « non »). */ + readonly provider: string | null; + /** `platform.now()` : instant de la décision. */ + readonly now: Date; +} + +/** Décision déjà figée pour ce hold, telle que le voyageur peut la lire (aucun champ [C2]). */ +export interface RecordedDeposit { + readonly mechanism: Exclude; + readonly amountMinor: bigint; + readonly currency: string; + /** `null` pour `NOT_REQUIRED`. */ + readonly releaseAt: Date | null; +} + +export type DepositCheckoutRead = + | { readonly kind: 'RECORDED'; readonly deposit: RecordedDeposit } + | { readonly kind: 'OPEN'; readonly context: DepositCheckoutContext }; + +/** Ligne écrite par `core.payment_cmd_record_deposit_decision` (montants en unités mineures). */ +export interface DepositDecisionRecord { + readonly mechanism: Exclude; + /** [C2] */ + readonly triggers: readonly DepositTrigger[]; + /** [C2] : valeurs lues, âge entier du plus jeune conducteur, `risk_evaluated` ; aucune date. */ + readonly paramsSnapshot: Readonly>; + readonly amountMinor: bigint; + readonly provider: string | null; + readonly hRequiredHours: number | null; + readonly vHours: number | null; + readonly authAt: Date | null; + readonly releaseAt: Date | null; + readonly decisionAt: Date | null; + readonly reauthDueAt: Date | null; +} + +export type DepositRecordOutcome = + | 'RECORDED' + | 'EXISTING' + | 'AUTH_REQUIRED' + | 'HOLD_NOT_FOUND' + | 'HOLD_NOT_PAYABLE' + | 'QUOTE_UNAVAILABLE'; + +/** Lecture refusée : session absente, hold d'un autre voyageur, devis engagé indisponible. */ +export type DepositReadRefusal = 'AUTH_REQUIRED' | 'HOLD_NOT_FOUND' | 'QUOTE_UNAVAILABLE'; + +export interface DepositCheckoutStore { + read(proof: Buffer, holdId: string): Promise; + record( + proof: Buffer, + holdId: string, + record: DepositDecisionRecord, + ): Promise; +} + +export interface DepositConfigSource { + read(country: string, provider: string): Promise; +} + +/** + * Vue du voyageur (S05) : `NONE` (aucune caution), `REQUIRED` (montant, nature, libération au + * plus tard) ou `UNAVAILABLE` (réservation refusée avant le paiement ; `maxBookableDays` ≥ 1 : + * `web.deposit.unavailable`, 0 ou `null` : `web.deposit.unavailableNone`, suite S-8). + */ +export type DepositGuestView = + | { readonly status: 'NONE' } + | { + readonly status: 'REQUIRED'; + readonly amountMinor: bigint; + readonly currency: string; + /** `HOLD` : blocage sur la carte (pré-autorisation) ; `CHARGE` : débit puis remboursement. */ + readonly kind: 'HOLD' | 'CHARGE'; + readonly releaseAt: Date; + } + | { + readonly status: 'UNAVAILABLE'; + readonly code: 'PARAM_MISSING' | 'DEPOSIT_RAIL_UNAVAILABLE'; + readonly maxBookableDays: number | null; + }; + +const kindOf = (mechanism: DepositRail): 'HOLD' | 'CHARGE' => + mechanism === 'CHARGE_THEN_REFUND' ? 'CHARGE' : 'HOLD'; + +/** Vue d'une décision figée (aucun champ [C2]). */ +export function guestViewOfRecorded(d: RecordedDeposit): DepositGuestView { + if (d.mechanism === 'NOT_REQUIRED') return { status: 'NONE' }; + if (d.releaseAt === null || d.amountMinor <= 0n) { + throw new PaymentError('INVALID_REQUEST', 'caution figée sans montant ni libération'); + } + return { + status: 'REQUIRED', + amountMinor: d.amountMinor, + currency: d.currency, + kind: kindOf(d.mechanism), + releaseAt: d.releaseAt, + }; +} + +/** Clés de paramètres figées dans `params_snapshot` (valeurs lues, jamais une donnée personnelle). */ +function snapshotOf( + config: DepositRailConfig, + ctx: DepositCheckoutContext, + decision: DepositGateDecision, +): Readonly> { + const t = config.triggerParams; + const r = config.railParams; + const amount = + config.amounts === undefined || ctx.valueClass === null + ? null + : (config.amounts[ctx.valueClass] ?? null); + return { + version: 1, + valueClass: ctx.valueClass, + youngestDriverAge: decision.triggers.youngestDriverAge, + riskEvaluated: decision.triggers.riskEvaluated, + provider: ctx.provider, + params: { + deposit_always_required: t.alwaysRequired ?? null, + deposit_trigger_classes: t.triggerClasses ?? null, + deposit_young_driver_age: t.youngDriverAge ?? null, + deposit_young_driver_classes: t.youngDriverClasses ?? null, + deposit_on_risk_flag: t.onRiskFlag ?? null, + risk_control_deployed: t.riskControlDeployed ?? null, + deposit_amount: amount === null ? null : amount.toString(), + auth_lead_h: r.authLeadH, + release_delay_h: r.releaseDelayH, + marge_h: r.marginH, + deposit_safety_h: r.safetyH, + deposit_reauth_lead_h: r.reauthLeadH, + provider_max_hold_h: r.providerMaxHoldH, + deposit_charge_cap: r.chargeCapMinor.toString(), + funds_holding_enabled: r.fundsHoldingEnabled, + }, + }; +} + +/** Évaluation pure : décision de la porte, ligne à figer (si acceptée) et vue du voyageur. */ +export function evaluateDepositCheckout( + ctx: DepositCheckoutContext, + config: DepositRailConfig, +): { + readonly decision: DepositGateDecision; + readonly record: DepositDecisionRecord | null; + readonly view: DepositGuestView; +} { + const decision = decideDepositGate({ + triggerParams: config.triggerParams, + amounts: config.amounts, + railParams: config.railParams, + caps: { capabilities: config.capabilities }, + // âge et signal de risque non lus ici : inconnus (fail-closed de evaluateDepositTriggers) + context: { valueClass: ctx.valueClass, driverAges: null, riskFlagged: null }, + bookedAt: ctx.now, + scheduledStart: ctx.scheduledStart, + scheduledEnd: ctx.scheduledEnd, + }); + const paramsSnapshot = snapshotOf(config, ctx, decision); + if (decision.kind === 'REFUSED') { + return { + decision, + record: null, + view: { + status: 'UNAVAILABLE', + code: decision.code, + maxBookableDays: decision.maxBookableDays, + }, + }; + } + if (decision.kind === 'NOT_REQUIRED') { + return { + decision, + record: { + mechanism: 'NOT_REQUIRED', + triggers: [], + paramsSnapshot, + amountMinor: 0n, + provider: ctx.provider, + hRequiredHours: null, + vHours: null, + authAt: null, + releaseAt: null, + decisionAt: null, + reauthDueAt: null, + }, + view: { status: 'NONE' }, + }; + } + const params = completeRailParams(config.railParams); + // decideDepositGate rend PARAM_MISSING avant d'arriver ici si un paramètre manque + if (params === null) throw new PaymentError('INVALID_REQUEST', 'paramètres de rail incomplets'); + const schedule = planDepositSchedule(decision.rail, params, ctx.scheduledEnd); + return { + decision, + record: { + mechanism: decision.rail.mechanism, + triggers: decision.triggers.triggers, + paramsSnapshot, + amountMinor: decision.amountMinor, + provider: ctx.provider, + hRequiredHours: decision.rail.hRequiredHours, + vHours: decision.rail.vHours, + authAt: schedule.authAt, + releaseAt: schedule.releaseAt, + decisionAt: schedule.decisionAt, + reauthDueAt: schedule.reauthDueAt, + }, + view: { + status: 'REQUIRED', + amountMinor: decision.amountMinor, + currency: ctx.currency, + kind: kindOf(decision.rail.mechanism), + releaseAt: schedule.releaseAt, + }, + }; +} + +/** Configuration d'un pays sans compte marchand : aucune capacité (toute pose de caution refusée). */ +const NO_PROVIDER = ''; + +export type DepositEnforcement = + | { readonly kind: 'ACCEPTED'; readonly view: DepositGuestView } + | { + readonly kind: 'REFUSED'; + readonly view: DepositGuestView & { readonly status: 'UNAVAILABLE' }; + } + | { + readonly kind: 'AUTH_REQUIRED' | 'HOLD_NOT_FOUND' | 'HOLD_NOT_PAYABLE' | 'QUOTE_UNAVAILABLE'; + }; + +/** Porte de la caution du checkout (lecture pour S05, application avant le paiement). */ +export class DepositCheckoutGate { + constructor( + private readonly store: DepositCheckoutStore, + private readonly config: DepositConfigSource, + ) {} + + /** + * Vue pour S05 / S06 : la décision figée si elle existe ; sinon, si `evaluate`, la décision que + * prendrait la porte maintenant (aucune écriture) ; sinon `null`. + */ + async view( + proof: Buffer, + holdId: string, + evaluate: boolean, + ): Promise { + const read = await this.store.read(proof, holdId); + if (read === 'AUTH_REQUIRED' || read === 'HOLD_NOT_FOUND') return read; + if (read === 'QUOTE_UNAVAILABLE') return null; + if (read.kind === 'RECORDED') return guestViewOfRecorded(read.deposit); + if (!evaluate) return null; + return (await this.#evaluate(read.context)).view; + } + + /** Avant le paiement : refus sans écriture, ou décision figée (jamais réécrite). */ + async enforce(proof: Buffer, holdId: string): Promise { + const read = await this.store.read(proof, holdId); + if (typeof read === 'string') return { kind: read }; + if (read.kind === 'RECORDED') { + return { kind: 'ACCEPTED', view: guestViewOfRecorded(read.deposit) }; + } + const evaluated = await this.#evaluate(read.context); + if (evaluated.record === null || evaluated.view.status === 'UNAVAILABLE') { + if (evaluated.view.status !== 'UNAVAILABLE') { + throw new PaymentError('INVALID_REQUEST', 'caution : décision sans ligne'); + } + return { kind: 'REFUSED', view: evaluated.view }; + } + const outcome = await this.store.record(proof, holdId, evaluated.record); + switch (outcome) { + case 'RECORDED': + return { kind: 'ACCEPTED', view: evaluated.view }; + case 'EXISTING': { + // décision figée entre-temps (autre onglet) : elle fait foi + const again = await this.store.read(proof, holdId); + if (typeof again === 'string') return { kind: again }; + if (again.kind !== 'RECORDED') { + throw new PaymentError( + 'INVALID_REQUEST', + 'caution : décision introuvable après écriture', + ); + } + return { kind: 'ACCEPTED', view: guestViewOfRecorded(again.deposit) }; + } + default: + return { kind: outcome }; + } + } + + async #evaluate(ctx: DepositCheckoutContext) { + const config = await this.config.read(ctx.country, ctx.provider ?? NO_PROVIDER); + return evaluateDepositCheckout(ctx, config); + } +} + +/** Classe du catalogue lue en base ; tout autre texte ⇒ `null` (inconnue, fail-closed). */ +export function valueClassOf(v: unknown): DepositValueClass | null { + return (DEPOSIT_VALUE_CLASSES as readonly unknown[]).includes(v) + ? (v as DepositValueClass) + : null; +} diff --git a/apps/api/src/modules/pay/internal/deposit-executor.ts b/apps/api/src/modules/pay/internal/deposit-executor.ts index 3439270e5..64f48f094 100644 --- a/apps/api/src/modules/pay/internal/deposit-executor.ts +++ b/apps/api/src/modules/pay/internal/deposit-executor.ts @@ -6,12 +6,16 @@ * - Chaque commande porte son **montant explicite** et, si elle déplace des fonds, ses jambes * (`chargeLegs` pour la pose, jambes des frais pour une capture ou un débit MIT) ; l'adaptateur les * revérifie avant tout appel (`LEG_SUM_MISMATCH`). - * - Clé d'idempotence par tentative (`depositOperationKey`), transmise telle quelle ou condensée selon - * `IDEMPOTENCY_KEY_MAX_LEN` : un rejeu avec la même tentative ne crée jamais un second mouvement. + * - Clé d'idempotence par tentative (`depositOperationKey`, variante hors règlement de 08 E4 + * `{trip}:{segment}:v0-DEPOSIT-{deposit}:{opération}:{moyen}:i{n}:a{m}`, US-701, ADR-169), + * transmise telle quelle ou condensée selon `IDEMPOTENCY_KEY_MAX_LEN` : un rejeu avec la même + * tentative ne crée jamais un second mouvement. * - **Aucun fonds de tiers détenu** : le rail « débit puis remboursement » est refusé sans appel tant * que `funds_holding_enabled[pays]` = `false` (relu par l'appelant, jamais déduit ici). * - Ré-autorisation refusée (ou capacité non validée) : signal ops `DEPOSIT_REAUTH_FAILED`, **aucun - * débit** de remplacement. + * débit** de remplacement. Issue inconnue ou en cours (`PENDING`, `SUBMITTED`, `UNKNOWN`, + * `UNKNOWN_OUTCOME`) : `REAUTH_PENDING` (lire l'état puis rejouer la MÊME clé), jamais + * `REAUTHORIZED` à tort (US-701, suite des revues d'US-225). */ import { PaymentError, isPaymentError } from './errors.js'; import { depositOperationKey, idempotencyKeyToSend } from './idempotency.js'; @@ -37,8 +41,13 @@ export type DepositPaymentProvider = Pick< export interface DepositReference { /** `deposit_hold.id`. */ readonly depositId: string; - /** Trip dont le PSP tient les jambes. */ + /** Trip dont le PSP tient les jambes (référence transmise au PSP). */ readonly tripReference: string; + /** Trip et segment de la clé d'idempotence (08 E4). */ + readonly tripId: string; + readonly segmentId: string; + /** Moyen de paiement du trip (opération de loyer capturée) : `tender_id` de la clé (08 E4). */ + readonly tenderId: string; readonly currency: Currency; } @@ -51,7 +60,18 @@ export interface PlaceDepositRequest { } export type DepositReauthOutcome = + /** Statut `SUCCEEDED` seulement : la nouvelle autorisation est prouvée. */ | { readonly kind: 'REAUTHORIZED'; readonly result: OperationResult } + | { + /** + * Issue inconnue ou en cours : aucun changement d'état ; l'appelant lit l'état faisant foi + * (`getOperation`) avant tout rejeu, qui garde la MÊME clé (17 §4.3 point 3). + */ + readonly kind: 'REAUTH_PENDING'; + readonly needsLookup: true; + /** Statut rendu (`PENDING`, `SUBMITTED`, `UNKNOWN`) ; `null` : exception `UNKNOWN_OUTCOME`. */ + readonly status: OperationStatus | null; + } | { readonly kind: 'REAUTH_REFUSED'; /** Le trip est signalé à l'ops ; aucun débit. */ @@ -111,7 +131,15 @@ export class DepositRailExecutor { } #key(ref: DepositReference, op: DepositOperationType, instanceSeq: number, attemptNo: number) { - const plain = depositOperationKey(ref.depositId, op, instanceSeq, attemptNo); + const plain = depositOperationKey({ + tripId: ref.tripId, + segmentId: ref.segmentId, + depositId: ref.depositId, + operationType: op, + tenderId: ref.tenderId, + instanceSeq, + attemptNo, + }); return idempotencyKeyToSend( plain, this.#provider.capabilities().int('IDEMPOTENCY_KEY_MAX_LEN'), @@ -133,7 +161,7 @@ export class DepositRailExecutor { const amount = money(req.amountMinor, ref.currency); const charge = req.mechanism === 'CHARGE_THEN_REFUND'; return this.#provider.createHostedPayment({ - idempotencyKey: this.#key(ref, charge ? 'CHARGE' : 'AUTH', 1, req.attemptNo), + idempotencyKey: this.#key(ref, charge ? 'DEPOSIT_CHARGE' : 'DEPOSIT_AUTH', 1, req.attemptNo), tripReference: ref.tripReference, method: 'CARD', amountMinor: amount.amountMinor, @@ -144,9 +172,10 @@ export class DepositRailExecutor { } /** - * Ré-autorisation (rail a), demandée avant l'échéance. Refus reçu ou capacité non validée ⇒ - * `REAUTH_REFUSED` (trip signalé à l'ops, sans débit). Issue inconnue : l'erreur remonte, la - * même clé est rejouée après lecture de l'état (17 §4.3 point 3). + * Ré-autorisation (rail a), demandée avant l'échéance. `SUCCEEDED` ⇒ `REAUTHORIZED` ; refus reçu + * (`FAILED`, `DECLINED`) ou capacité non validée ⇒ `REAUTH_REFUSED` (trip signalé à l'ops, sans + * débit) ; `PENDING` / `SUBMITTED` / `UNKNOWN` ou `UNKNOWN_OUTCOME` ⇒ `REAUTH_PENDING` (lecture de + * l'état, puis la même clé est rejouée, 17 §4.3 point 3). Toute autre erreur remonte. */ async reauthorize( ref: DepositReference, @@ -156,14 +185,18 @@ export class DepositRailExecutor { ): Promise { try { const result = await this.#provider.reauthorize({ - idempotencyKey: this.#key(ref, 'REAUTH', instanceSeq, attemptNo), + idempotencyKey: this.#key(ref, 'DEPOSIT_REAUTH', instanceSeq, attemptNo), providerReference, }); + if (result.status === 'SUCCEEDED') return { kind: 'REAUTHORIZED', result }; if (result.status === 'FAILED') { return { kind: 'REAUTH_REFUSED', opsSignal: 'DEPOSIT_REAUTH_FAILED', reason: 'DECLINED' }; } - return { kind: 'REAUTHORIZED', result }; + return { kind: 'REAUTH_PENDING', needsLookup: true, status: result.status }; } catch (error) { + if (isPaymentError(error, 'UNKNOWN_OUTCOME')) { + return { kind: 'REAUTH_PENDING', needsLookup: true, status: null }; + } if (isPaymentError(error, 'DECLINED') || isPaymentError(error, 'UNSUPPORTED_CAPABILITY')) { return { kind: 'REAUTH_REFUSED', @@ -252,7 +285,7 @@ export class DepositRailExecutor { switch (step.op) { case 'CAPTURE': return this.#provider.capture({ - idempotencyKey: this.#key(ref, 'CAPTURE', i, a), + idempotencyKey: this.#key(ref, 'DEPOSIT_CAPTURE', i, a), providerReference: target.providerReference, amountMinor: step.amountMinor, currency, @@ -260,7 +293,7 @@ export class DepositRailExecutor { }); case 'VOID': return this.#provider.void({ - idempotencyKey: this.#key(ref, 'VOID', i, a), + idempotencyKey: this.#key(ref, 'DEPOSIT_VOID', i, a), providerReference: target.providerReference, }); case 'REFUND': diff --git a/apps/api/src/modules/pay/internal/deposit-rails.ts b/apps/api/src/modules/pay/internal/deposit-rails.ts index 97cc2b692..63eb0db76 100644 --- a/apps/api/src/modules/pay/internal/deposit-rails.ts +++ b/apps/api/src/modules/pay/internal/deposit-rails.ts @@ -142,7 +142,7 @@ export interface DepositRailRequest { readonly scheduledEnd: Date; } -type CompleteRailParams = DepositRailParams & { +export type CompleteRailParams = DepositRailParams & { readonly authLeadH: number; readonly releaseDelayH: number; readonly marginH: number; @@ -335,6 +335,87 @@ export function depositReauthDueAt( return new Date(authExpiry.getTime() - reauthLeadH * HOUR_MS); } +/** + * Échéancier planifié au checkout (US-701, ADR-169 ; 08 BR-PAY-06 « Libération à heure fixe », + * « Mécanisme ») et écrit dans `deposit_hold` avec la décision : + * - `releaseAt = scheduled_end + release_delay_h` (le retour réel, s'il est connu, le remplacera) ; + * - `PREAUTH_SINGLE` : `decisionAt = min(release_at, (auth_at + V) − deposit_safety_h)` (T57 : + * fin + 70 h) ; aucune ré-autorisation ; + * - `REAUTH` : première ré-autorisation à `(auth_at + V) − deposit_reauth_lead_h` ; la décision est + * planifiée à `release_at` et ramenée avant l'expiration à chaque transition (acceptée : nouvelle + * expiration ; refusée : `min(release_at, expiration − deposit_safety_h)`) ; + * - `CHARGE_THEN_REFUND` : aucune expiration ; décision (remboursement) à `release_at`. + * `auth_at + V` n'est qu'une PRÉVISION : `auth_expiry_at` réel vient de l'autorisation (PSP). + */ +export interface DepositSchedule { + readonly authAt: Date; + readonly releaseAt: Date; + readonly decisionAt: Date; + /** `null` : aucune ré-autorisation planifiée. */ + readonly reauthDueAt: Date | null; +} + +export function planDepositSchedule( + rail: Pick & { readonly mechanism: DepositRail }, + params: Pick, + scheduledEnd: Date, +): DepositSchedule { + const releaseAt = depositReleaseAt(null, scheduledEnd, params.releaseDelayH); + const authAt = rail.authAt; + if (rail.mechanism === 'CHARGE_THEN_REFUND') { + return { authAt, releaseAt, decisionAt: releaseAt, reauthDueAt: null }; + } + const expiry = depositAuthExpiry(authAt, rail.vHours, null); + if (rail.mechanism === 'PREAUTH_SINGLE') { + return { + authAt, + releaseAt, + decisionAt: depositDecisionAt(releaseAt, expiry, params.safetyH), + reauthDueAt: null, + }; + } + return { + authAt, + releaseAt, + decisionAt: releaseAt, + reauthDueAt: depositReauthDueAt(expiry, releaseAt, params.safetyH, params.reauthLeadH), + }; +} + +/** + * Échéances après une ré-autorisation (minuterie, US-701) : acceptée ⇒ nouvelle expiration + * `reauthorizedAt + V`, prochaine ré-autorisation si elle ne tient toujours pas jusqu'à + * `release_at`, décision `min(release_at, expiration − safety)` ; refusée ⇒ aucune nouvelle + * ré-autorisation, décision avancée avant l'expiration EN COURS (jamais de capture après + * `auth_expiry`, 08 BR-PAY-06). + */ +export function depositScheduleAfterReauth( + outcome: 'REAUTHORIZED' | 'REAUTH_REFUSED', + current: { readonly authExpiryAt: Date; readonly releaseAt: Date }, + reauthorizedAt: Date, + vHours: number, + params: Pick, +): { readonly authExpiryAt: Date; readonly decisionAt: Date; readonly reauthDueAt: Date | null } { + if (outcome === 'REAUTH_REFUSED') { + return { + authExpiryAt: current.authExpiryAt, + decisionAt: depositDecisionAt(current.releaseAt, current.authExpiryAt, params.safetyH), + reauthDueAt: null, + }; + } + const authExpiryAt = depositAuthExpiry(reauthorizedAt, vHours, null); + return { + authExpiryAt, + decisionAt: depositDecisionAt(current.releaseAt, authExpiryAt, params.safetyH), + reauthDueAt: depositReauthDueAt( + authExpiryAt, + current.releaseAt, + params.safetyH, + params.reauthLeadH, + ), + }; +} + // --- décision : commandes au PSP ------------------------------------------------------------------ /** Frais annexe de la liste fermée acceptée au checkout (08 BR-PAY-06 « Finalité »). */ diff --git a/apps/api/src/modules/pay/internal/deposit-timer.ts b/apps/api/src/modules/pay/internal/deposit-timer.ts new file mode 100644 index 000000000..14bd6fc82 --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-timer.ts @@ -0,0 +1,239 @@ +/** + * Minuterie de ré-autorisation de la caution (US-701, ADR-169 ; 08 BR-PAY-06 « Mécanisme » (a) ; + * 19 US-225 critère 3 « une ré-autorisation est demandée avant l'échéance et, refusée, le trip est + * signalé à l'ops sans débit » ; suite S-2 d'US-225). + * + * Tâche périodique `deposit_timer`, sous le nom de travailleur `payment_command` (exigé par la + * base) : la file `core.payment_deposit_reauth_due` rend les cautions `REAUTH` AUTORISÉES dont la + * ré-autorisation est échue (`reauth_due_at ≤ platform.now()`) ; pour chacune : + * 1. configuration du pays relue (`V`, `deposit_safety_h`, `deposit_reauth_lead_h`) ; un paramètre + * absent ⇒ rien n'est envoyé (fail-closed, revu au passage suivant) ; + * 2. ré-autorisation par le port (`DepositRailExecutor.reauthorize`), rang `reauth_seq + 1`, clé de + * 08 E4 ; HORS transaction de la base ; + * 3. issue reportée par `core.payment_cmd_deposit_transition` (machine d'état de la base) : + * acceptée ⇒ nouvelle expiration, prochaine ré-autorisation éventuelle, décision ramenée avant + * l'expiration ; refusée ⇒ aucune nouvelle ré-autorisation, décision AVANT l'expiration en cours, + * alerte ops `DEPOSIT_REAUTH_FAILED`, AUCUN débit ; en cours ou inconnue (`REAUTH_PENDING`) ⇒ + * aucun changement, la MÊME clé est rejouée au passage suivant (lecture de l'état d'abord, 17 + * §4.3). + * Aucun connecteur pour le fournisseur (production jusqu'au lot C) ⇒ rien n'est envoyé. + * Journal : comptes et codes seulement, jamais un identifiant (17 §6.3). + */ +import type { AlertChannel, BusRegistry, SqlClient, WorkerTransactions } from '../../bus/index.js'; +import { createCurrencyRegistry } from '@rueda/money'; +import { + completeRailParams, + depositHoldValidityHours, + depositScheduleAfterReauth, +} from './deposit-rails.js'; +import { DepositRailExecutor } from './deposit-executor.js'; +import { PgDepositRailConfigReader } from './pg-deposit-config.js'; +import type { DepositRailConfig } from './pg-deposit-config.js'; +import type { PaymentConnectorRegistry } from './production.js'; +import type { SqlExecutor } from './pg-stores.js'; + +export const DEPOSIT_TIMER_WORKER = 'deposit_timer'; +/** Nom de travailleur exigé par la base pour la file et la transition. */ +const PAYMENT_COMMAND_WORKER = 'payment_command'; +/** Période (PROPOSÉ) : la ré-autorisation est planifiée 24 h avant l'expiration. */ +export const DEPOSIT_TIMER_PERIOD_SECONDS = 60; +export const DEPOSIT_TIMER_BATCH = 50; + +/** Caution dont la ré-autorisation est échue (aucune donnée [C2]). */ +export interface DueDepositReauth { + readonly depositId: string; + readonly tripId: string; + readonly segmentId: string; + readonly tenderId: string; + readonly country: string; + readonly currency: string; + readonly currencyExponent: number; + readonly provider: string; + readonly providerReference: string; + readonly authExpiryAt: Date; + readonly releaseAt: Date; + readonly reauthSeq: number; + /** `platform.now()` à la lecture de la file. */ + readonly now: Date; +} + +export type DepositTimerStep = + 'NO_CONNECTOR' | 'PARAM_MISSING' | 'REAUTHORIZED' | 'REFUSED' | 'PENDING' | 'STALE' | 'ERROR'; + +const instant = (v: unknown): Date => { + const d = v instanceof Date ? v : new Date(String(v)); + if (Number.isNaN(d.getTime())) throw new TypeError('instant illisible'); + return d; +}; +const str = (v: unknown): string => { + if (typeof v !== 'string' || v === '') throw new TypeError('colonne inattendue'); + return v; +}; + +/** File et transition de la base (fonctions SECURITY DEFINER, `payment_command`). */ +export class PgDepositTimerStore { + constructor(private readonly db: SqlExecutor) {} + + async due(limit: number): Promise { + const { rows } = await this.db.query( + `SELECT d.*, c.exponent AS currency_exponent + FROM core.payment_deposit_reauth_due($1::integer) AS d + JOIN core.config_currency AS c ON c.code = d.currency`, + [limit], + ); + return rows.map((r) => ({ + depositId: str(r['deposit_id']), + tripId: str(r['trip_id']), + segmentId: str(r['segment_id']), + tenderId: str(r['tender_id']), + country: str(r['country_code']), + currency: str(r['currency']), + currencyExponent: Number(r['currency_exponent']), + provider: str(r['provider']), + providerReference: str(r['provider_reference']), + authExpiryAt: instant(r['auth_expiry_at']), + releaseAt: instant(r['release_at']), + reauthSeq: Number(r['reauth_seq']), + now: instant(r['now']), + })); + } + + /** `APPLIED` ; `STALE` : la caution a changé entre-temps (rang ou état), rien n'est écrit. */ + async transition( + depositId: string, + event: 'REAUTHORIZED' | 'REAUTH_REFUSED', + expectedSeq: number, + schedule: { authExpiryAt: Date; decisionAt: Date; reauthDueAt: Date | null }, + ): Promise<'APPLIED' | 'STALE'> { + const { rows } = await this.db.query<{ r: unknown }>( + `SELECT core.payment_cmd_deposit_transition($1::uuid, $2, $3::integer, $4::timestamptz, + $5::timestamptz, $6::timestamptz, NULL) AS r`, + [ + depositId, + event, + expectedSeq, + schedule.authExpiryAt.toISOString(), + schedule.decisionAt.toISOString(), + schedule.reauthDueAt === null ? null : schedule.reauthDueAt.toISOString(), + ], + ); + const r = String(rows[0]?.r ?? ''); + if (r !== 'APPLIED' && r !== 'STALE') throw new TypeError('issue inattendue de la transition'); + return r; + } +} + +export interface DepositTimerDeps { + /** Configuration du pays et du fournisseur (`PgDepositRailConfigReader`, transaction propre). */ + readonly config: (country: string, provider: string) => Promise; + /** Transition de la base (`PgDepositTimerStore.transition`, transaction propre). */ + readonly transition: PgDepositTimerStore['transition']; + readonly alerts: Pick; + readonly connectors: PaymentConnectorRegistry; +} + +/** Dépendances de production : chaque lecture et chaque écriture dans sa transaction. */ +export function postgresDepositTimerDeps( + transactions: WorkerTransactions, + alerts: Pick, + connectors: PaymentConnectorRegistry, +): DepositTimerDeps { + return { + config: (country, provider) => + transactions.run(PAYMENT_COMMAND_WORKER, (db) => + new PgDepositRailConfigReader(db).read(country, provider), + ), + transition: (depositId, event, expectedSeq, schedule) => + transactions.run(PAYMENT_COMMAND_WORKER, (db) => + new PgDepositTimerStore(db).transition(depositId, event, expectedSeq, schedule), + ), + alerts, + connectors, + }; +} + +export class DepositReauthTimer { + constructor(private readonly deps: DepositTimerDeps) {} + + /** Une caution ; ne lève jamais (une caution ne bloque pas les suivantes). */ + async process(due: DueDepositReauth): Promise { + try { + const provider = this.deps.connectors.get(due.provider); + if (provider === undefined) return 'NO_CONNECTOR'; + const config = await this.deps.config(due.country, due.provider); + const params = completeRailParams(config.railParams); + const vHours = depositHoldValidityHours(config.railParams, { + capabilities: config.capabilities, + }); + if (params === null || vHours === 0) return 'PARAM_MISSING'; + const executor = new DepositRailExecutor(provider); + const outcome = await executor.reauthorize( + { + depositId: due.depositId, + tripReference: due.tripId, + tripId: due.tripId, + segmentId: due.segmentId, + tenderId: due.tenderId, + currency: createCurrencyRegistry([ + { code: due.currency, exponent: due.currencyExponent }, + ]).get(due.currency), + }, + due.providerReference, + due.reauthSeq + 1, + 1, + ); + if (outcome.kind === 'REAUTH_PENDING') return 'PENDING'; + const event = outcome.kind === 'REAUTHORIZED' ? 'REAUTHORIZED' : 'REAUTH_REFUSED'; + const schedule = depositScheduleAfterReauth( + event, + { authExpiryAt: due.authExpiryAt, releaseAt: due.releaseAt }, + due.now, + vHours, + params, + ); + const applied = await this.deps.transition(due.depositId, event, due.reauthSeq, schedule); + if (applied === 'STALE') return 'STALE'; + if (event === 'REAUTH_REFUSED') { + await this.deps.alerts.send({ + code: 'DEPOSIT_REAUTH_FAILED', + severity: 'P1', + counts: { deposits: 1 }, + labels: { country: due.country, provider: due.provider }, + }); + return 'REFUSED'; + } + return 'REAUTHORIZED'; + } catch { + return 'ERROR'; + } + } +} + +/** Tâche périodique `deposit_timer` (comptes seulement dans le journal). */ +export function registerDepositTimers( + registry: BusRegistry, + transactions: WorkerTransactions, + alerts: AlertChannel, + log: (line: string) => void, + connectors: PaymentConnectorRegistry, +): void { + const timer = new DepositReauthTimer(postgresDepositTimerDeps(transactions, alerts, connectors)); + registry.registerPeriodic( + DEPOSIT_TIMER_WORKER, + DEPOSIT_TIMER_PERIOD_SECONDS, + async (_payload, tx: SqlClient) => { + await tx.query(`SELECT pg_catalog.set_config('app.worker_name', $1, true)`, [ + PAYMENT_COMMAND_WORKER, + ]); + const due = await new PgDepositTimerStore(tx).due(DEPOSIT_TIMER_BATCH); + const counts: Record = {}; + for (const d of due) { + const step = (await timer.process(d)).toLowerCase(); + counts[step] = (counts[step] ?? 0) + 1; + } + log( + JSON.stringify({ level: 'info', worker: DEPOSIT_TIMER_WORKER, due: due.length, ...counts }), + ); + }, + ); +} diff --git a/apps/api/src/modules/pay/internal/idempotency.ts b/apps/api/src/modules/pay/internal/idempotency.ts index e399d1ed2..cbae4bf6e 100644 --- a/apps/api/src/modules/pay/internal/idempotency.ts +++ b/apps/api/src/modules/pay/internal/idempotency.ts @@ -83,40 +83,54 @@ export function holdAttemptKey( } /** - * Opérations d'une caution (US-225, ADR-164 ; PROPOSÉ, à reporter dans 08 E4) : pose (`AUTH` - * pré-autorisation, `CHARGE` débit du rail « débit puis remboursement »), ré-autorisation, capture - * des frais, annulation, remboursement du débit, débit MIT des frais non capturés. + * Opérations d'une caution (US-225, ADR-164 ; alignées sur 08 E4 par US-701, ADR-169) : noms de + * 08 E4 quand ils existent (`DEPOSIT_CAPTURE`, `DEPOSIT_VOID`, `REFUND`, `MIT_CHARGE`) et de 17 + * §3.2.7 (`payment_operation.kind` `DEPOSIT_AUTH`) ; `DEPOSIT_CHARGE` (débit du rail « débit puis + * remboursement ») et `DEPOSIT_REAUTH` (ré-autorisation) sont PROPOSÉS, à reporter dans 08 E4 (S-5). */ export const DEPOSIT_OPERATION_TYPES = [ - 'AUTH', - 'CHARGE', - 'REAUTH', - 'CAPTURE', - 'VOID', + 'DEPOSIT_AUTH', + 'DEPOSIT_CHARGE', + 'DEPOSIT_REAUTH', + 'DEPOSIT_CAPTURE', + 'DEPOSIT_VOID', 'REFUND', 'MIT_CHARGE', ] as const; export type DepositOperationType = (typeof DEPOSIT_OPERATION_TYPES)[number]; +export interface DepositKeyParts { + readonly tripId: string; + readonly segmentId: string; + /** `deposit_hold.id` : origine hors règlement (`v0-DEPOSIT-{deposit_id}`). */ + readonly depositId: string; + readonly operationType: DepositOperationType; + /** Moyen de paiement du trip (opération de loyer capturée, comme les ordres de règlement). */ + readonly tenderId: string; + readonly instanceSeq: number; + readonly attemptNo: number; +} + /** - * `deposit:{deposit_id}:{opération}:i{instance_seq}:a{attempt_no}` : une clé par tentative, comme - * la variante pré-trip ; `i{n}` distingue deux ré-autorisations successives. + * Variante « hors règlement » de 08 E4 appliquée à TOUTES les opérations d'une caution (US-701, + * ADR-169, suite S-6 d'US-225) : `{trip_id}:{segment_id}:v0-DEPOSIT-{deposit_id}:{opération}: + * {tender_id}:i{instance_seq}:a{attempt_no}`. Le remboursement du rail « débit puis + * remboursement » est exactement la clé `offSettlementRefundKey` d'origine `DEPOSIT` ; le segment + * `v0-…` n'entre jamais en collision avec une version de règlement. Une clé par tentative ; + * `i{n}` distingue deux ré-autorisations successives et le repli de 08 E3 (rang 2). */ -export function depositOperationKey( - depositId: string, - operation: DepositOperationType, - instanceSeq: number, - attemptNo: number, -): string { - if (!(DEPOSIT_OPERATION_TYPES as readonly string[]).includes(operation)) { - throw new PaymentError('INVALID_REQUEST', `opération de caution inconnue : ${operation}`); +export function depositOperationKey(p: DepositKeyParts): string { + if (!(DEPOSIT_OPERATION_TYPES as readonly string[]).includes(p.operationType)) { + throw new PaymentError('INVALID_REQUEST', `opération de caution inconnue : ${p.operationType}`); } return [ - 'deposit', - part('deposit_id', depositId), - operation, - `i${rank('instance_seq', instanceSeq)}`, - `a${rank('attempt_no', attemptNo)}`, + part('trip_id', p.tripId), + part('segment_id', p.segmentId), + `v0-DEPOSIT-${part('deposit_id', p.depositId)}`, + p.operationType, + part('tender_id', p.tenderId), + `i${rank('instance_seq', p.instanceSeq)}`, + `a${rank('attempt_no', p.attemptNo)}`, ].join(':'); } diff --git a/apps/api/src/modules/pay/internal/pg-deposit-checkout.ts b/apps/api/src/modules/pay/internal/pg-deposit-checkout.ts new file mode 100644 index 000000000..fcc629f59 --- /dev/null +++ b/apps/api/src/modules/pay/internal/pg-deposit-checkout.ts @@ -0,0 +1,131 @@ +/** + * Magasin de la caution du checkout sous `app_api` (US-701, ADR-169 ; migration 0143) : + * - `core.payment_deposit_checkout(jeton, hold)` : contexte du hold du voyageur de la session + * (pays, devise et période du devis ENGAGÉ, classe du véhicule, compte marchand du pays, + * `platform.now()`) et, si elle existe, la décision figée telle que le voyageur peut la lire + * (mécanisme, montant, devise, libération : AUCUNE colonne [C2]) ; + * - `core.payment_cmd_record_deposit_decision(jeton, hold, décision)` : écriture unique de + * `deposit_hold` (commande SECURITY DEFINER de cmd_hold_owner, revérifications fail-closed). + * Paramètres liés, aucun SQL construit ; toute forme inattendue ⇒ erreur (503 chez l'appelant). + */ +import { PaymentError } from './errors.js'; +import { DEPOSIT_TRIGGERS } from './deposit-triggers.js'; +import { valueClassOf } from './deposit-checkout.js'; +import type { + DepositCheckoutRead, + DepositCheckoutStore, + DepositDecisionRecord, + DepositReadRefusal, + DepositRecordOutcome, + RecordedDeposit, +} from './deposit-checkout.js'; +import type { SqlExecutor } from './pg-stores.js'; + +const shape = (what: string): PaymentError => + new PaymentError('INVALID_REQUEST', `caution du checkout : ${what} illisible`); + +const instant = (v: unknown, what: string): Date => { + const d = v instanceof Date ? v : typeof v === 'string' ? new Date(v) : null; + if (d === null || Number.isNaN(d.getTime())) throw shape(what); + return d; +}; +const text = (v: unknown, what: string): string => { + if (typeof v !== 'string' || v === '') throw shape(what); + return v; +}; +const MINOR = /^(0|[1-9][0-9]{0,18})$/; +const minor = (v: unknown, what: string): bigint => { + const s = typeof v === 'number' || typeof v === 'bigint' ? String(v) : v; + if (typeof s !== 'string' || !MINOR.test(s)) throw shape(what); + return BigInt(s); +}; + +const RECORDED_MECHANISMS = ['NOT_REQUIRED', 'PREAUTH_SINGLE', 'REAUTH', 'CHARGE_THEN_REFUND']; +const RECORD_OUTCOMES: ReadonlySet = new Set([ + 'RECORDED', + 'EXISTING', + 'AUTH_REQUIRED', + 'HOLD_NOT_FOUND', + 'HOLD_NOT_PAYABLE', + 'QUOTE_UNAVAILABLE', +]); + +const iso = (d: Date | null): string | null => (d === null ? null : d.toISOString()); + +export class PgDepositCheckoutStore implements DepositCheckoutStore { + constructor(private readonly db: SqlExecutor) {} + + async read(proof: Buffer, holdId: string): Promise { + const { rows } = await this.db.query( + 'SELECT * FROM core.payment_deposit_checkout($1, $2::uuid)', + [proof, holdId], + ); + const r = rows[0]; + const outcome = r === undefined ? '' : String(r['outcome']); + if ( + outcome === 'AUTH_REQUIRED' || + outcome === 'HOLD_NOT_FOUND' || + outcome === 'QUOTE_UNAVAILABLE' + ) { + return outcome; + } + if (r === undefined || outcome !== 'DONE') throw shape('issue'); + const currency = text(r['currency'], 'devise'); + const mechanism = r['mechanism']; + if (mechanism !== null && mechanism !== undefined) { + if (typeof mechanism !== 'string' || !RECORDED_MECHANISMS.includes(mechanism)) { + throw shape('mécanisme'); + } + const deposit: RecordedDeposit = { + mechanism: mechanism as RecordedDeposit['mechanism'], + amountMinor: minor(r['amount_minor'], 'montant'), + currency, + releaseAt: r['release_at'] === null ? null : instant(r['release_at'], 'libération'), + }; + return { kind: 'RECORDED', deposit }; + } + const provider = r['provider']; + return { + kind: 'OPEN', + context: { + country: text(r['country_code'], 'pays'), + currency, + valueClass: valueClassOf(r['value_class']), + scheduledStart: instant(r['scheduled_start'], 'début'), + scheduledEnd: instant(r['scheduled_end'], 'fin'), + provider: typeof provider === 'string' && provider !== '' ? provider : null, + now: instant(r['now'], 'heure de la base'), + }, + }; + } + + async record( + proof: Buffer, + holdId: string, + record: DepositDecisionRecord, + ): Promise { + if (!record.triggers.every((t) => (DEPOSIT_TRIGGERS as readonly string[]).includes(t))) { + throw shape('déclencheur'); + } + const decision = { + mechanism: record.mechanism, + triggers: [...record.triggers], + paramsSnapshot: record.paramsSnapshot, + amountMinor: record.amountMinor.toString(), + provider: record.provider, + hRequiredHours: record.hRequiredHours, + vHours: record.vHours, + authAt: iso(record.authAt), + releaseAt: iso(record.releaseAt), + decisionAt: iso(record.decisionAt), + reauthDueAt: iso(record.reauthDueAt), + }; + const { rows } = await this.db.query<{ r: unknown }>( + 'SELECT core.payment_cmd_record_deposit_decision($1, $2::uuid, $3::jsonb) AS r', + [proof, holdId, JSON.stringify(decision)], + ); + const outcome = String(rows[0]?.r ?? ''); + if (!RECORD_OUTCOMES.has(outcome)) throw shape('issue de l’écriture'); + return outcome as DepositRecordOutcome; + } +} diff --git a/apps/api/src/modules/pay/testing/deposit-rails.fake.test.ts b/apps/api/src/modules/pay/testing/deposit-rails.fake.test.ts index 8de838449..7defcea36 100644 --- a/apps/api/src/modules/pay/testing/deposit-rails.fake.test.ts +++ b/apps/api/src/modules/pay/testing/deposit-rails.fake.test.ts @@ -45,6 +45,9 @@ function setup(c: (typeof CASES)[number], options: FakeStackOptions = {}) { const ref = { depositId: `dep-${c.country}`, tripReference: `trip-${c.country}`, + tripId: `trip-${c.country}`, + segmentId: `seg-${c.country}`, + tenderId: `tnd-${c.country}`, currency: CURRENCIES.get(c.currency), }; return { stack, executor, ref }; diff --git a/apps/api/src/modules/pay/testing/deposit-timer.fake.test.ts b/apps/api/src/modules/pay/testing/deposit-timer.fake.test.ts new file mode 100644 index 000000000..3d613ab24 --- /dev/null +++ b/apps/api/src/modules/pay/testing/deposit-timer.fake.test.ts @@ -0,0 +1,317 @@ +/** + * US-701 (ADR-169) — minuterie de ré-autorisation de la caution sur le PSP simulé (FAKE seulement, + * C19), en USD (PA) et en PYG sans décimale (PY). Attendus : 19 US-225 critère 3 (« une + * ré-autorisation est demandée avant l'échéance et, refusée, le trip est signalé à l'ops sans + * débit »), 08 BR-PAY-06 (jamais de capture après l'expiration : décision avancée à expiration − + * `deposit_safety_h`), 08 E4 (clé `{trip}:{segment}:v0-DEPOSIT-{caution}:…:i{n}:a{m}`, même clé au + * rejeu, condensé SHA-256 au-delà de `IDEMPOTENCY_KEY_MAX_LEN`) et 17 §4.3 (issue inconnue ⇒ + * lecture puis même clé, jamais `REAUTHORIZED` à tort). Valeurs de temps refaites à la main. + */ +import { createHash } from 'node:crypto'; +import { readFileSync } from 'node:fs'; +import { createCurrencyRegistry } from '@rueda/money'; +import { describe, expect, it } from 'vitest'; +import type { OpsAlert } from '../../bus/index.js'; +import { CapabilitySet } from '../internal/capabilities.js'; +import { DepositRailExecutor } from '../internal/deposit-executor.js'; +import type { DepositPaymentProvider } from '../internal/deposit-executor.js'; +import { DepositReauthTimer } from '../internal/deposit-timer.js'; +import type { DueDepositReauth } from '../internal/deposit-timer.js'; +import { PaymentError } from '../internal/errors.js'; +import { offSettlementRefundKey, depositOperationKey } from '../internal/idempotency.js'; +import type { OperationStatus } from '../internal/port.js'; +import type { PaymentProvider } from '../internal/port.js'; +import type { DepositRailConfig } from '../internal/pg-deposit-config.js'; +import { countryCases } from '../../../../test/support/countries.js'; +import { fakeStack } from './fake-stack.js'; +import type { FakeStackOptions } from './fake-stack.js'; + +const CURRENCIES = createCurrencyRegistry( + ( + JSON.parse( + readFileSync(new URL('../../cfg/data/currencies.json', import.meta.url), 'utf8'), + ) as { currencies: { code: string; exponent: number }[] } + ).currencies, +); +const PARAMS = ( + JSON.parse(readFileSync(new URL('../../cfg/data/params.json', import.meta.url), 'utf8')) as { + params: { key: string; values: Record }[]; + } +).params; +const p = (key: string, country: string): unknown => + PARAMS.find((x) => x.key === key)?.values[country]; + +const CASES = countryCases().map((c) => ({ + ...c, + exponent: CURRENCIES.get(c.currency).exponent, + deposit: 300n * 10n ** BigInt(CURRENCIES.get(c.currency).exponent), +})); + +const H = 3_600_000; +const T = Date.parse('2031-07-10T10:00:00.000Z'); +const at = (hours: number, minutes = 0): Date => new Date(T + hours * H + minutes * 60_000); + +const IDS = { + deposit: '0191d1a0-0000-7000-8000-000000000701', + trip: '0191d1a0-0000-7000-8000-0000000007a1', + segment: '0191d1a0-0000-7000-8000-0000000007b1', + tender: '0191d1a0-0000-7000-8000-0000000007c1', +}; + +function configOf( + c: (typeof CASES)[number], + caps: readonly { capability: string; method: string; value: unknown; status: string }[], +): DepositRailConfig { + return { + triggerParams: {}, + amounts: undefined, + railParams: { + authLeadH: p('auth_lead_h', c.country) as number, + releaseDelayH: p('release_delay_h', c.country) as number, + marginH: p('marge_h', c.country) as number, + safetyH: p('deposit_safety_h', c.country) as number, + reauthLeadH: p('deposit_reauth_lead_h', c.country) as number, + providerMaxHoldH: 168, + chargeCapMinor: 0n, + fundsHoldingEnabled: false, + }, + feeNoticeH: null, + // validité du PSP « à 7 j » de T57 (V = 168 h) : capacité absente de la matrice du FAKE + capabilities: new CapabilitySet([ + ...caps.map((x) => ({ ...x, status: x.status as 'VALIDATED_SANDBOX' })), + { capability: 'MAX_HOLD_HOURS', method: '*', value: 168, status: 'VALIDATED_SANDBOX' }, + ]), + }; +} + +/** Méthode du port liée à l'adaptateur (champs privés de la classe), autre propriété telle quelle. */ +function passThrough(target: PaymentProvider, prop: string | symbol): unknown { + const v = Reflect.get(target, prop) as unknown; + return typeof v === 'function' ? (v as (...a: unknown[]) => unknown).bind(target) : v; +} + +type Transition = [ + string, + string, + number, + { authExpiryAt: Date; decisionAt: Date; reauthDueAt: Date | null }, +]; + +function setup( + c: (typeof CASES)[number], + options: FakeStackOptions & { + wrap?: (p: PaymentProvider) => PaymentProvider; + applied?: 'APPLIED' | 'STALE'; + noConnector?: boolean; + } = {}, +) { + const stack = fakeStack(options); + const keys: string[] = []; + const base: PaymentProvider = options.wrap ? options.wrap(stack.provider) : stack.provider; + const provider = new Proxy(base, { + get(target, prop) { + if (prop === 'reauthorize') { + return (r: { idempotencyKey: string; providerReference: string }) => { + keys.push(r.idempotencyKey); + return target.reauthorize(r); + }; + } + return passThrough(target, prop); + }, + }); + const transitions: Transition[] = []; + const alerts: OpsAlert[] = []; + const timer = new DepositReauthTimer({ + config: () => Promise.resolve(configOf(c, stack.capabilities)), + transition: (id, event, seq, schedule) => { + transitions.push([id, event, seq, schedule]); + return Promise.resolve(options.applied ?? 'APPLIED'); + }, + alerts: { + send: (a) => { + alerts.push(a); + return Promise.resolve(); + }, + }, + connectors: { get: (name) => (options.noConnector || name !== 'FAKE' ? undefined : provider) }, + }); + return { stack, timer, keys, transitions, alerts }; +} + +/** Autorisation de la caution posée sur le FAKE (rail a) : rend sa référence. */ +async function authorize(c: (typeof CASES)[number], s: ReturnType): Promise { + const executor = new DepositRailExecutor(s.stack.provider); + const order = await executor.place( + { + depositId: IDS.deposit, + tripReference: IDS.trip, + tripId: IDS.trip, + segmentId: IDS.segment, + tenderId: IDS.tender, + currency: CURRENCIES.get(c.currency), + }, + { mechanism: 'REAUTH', amountMinor: c.deposit, fundsHoldingEnabled: false, attemptNo: 1 }, + ); + s.stack.psp.customerPays(order.providerReference); + return order.providerReference; +} + +/** T59 en rail (a) : autorisée à −24 h (expiration +144 h), libération à +144 h 25. */ +const due = (c: (typeof CASES)[number], reference: string, seq = 0): DueDepositReauth => ({ + depositId: IDS.deposit, + tripId: IDS.trip, + segmentId: IDS.segment, + tenderId: IDS.tender, + country: c.country, + currency: c.currency, + currencyExponent: c.exponent, + provider: 'FAKE', + providerReference: reference, + authExpiryAt: at(144), + releaseAt: at(144, 25), + reauthSeq: seq, + now: at(120), +}); + +/** Clé de 08 E4 attendue, recomposée ici (forme du texte de 08), puis condensée (64 caractères). */ +const expectedKey = (seq: number): string => { + const plain = `${IDS.trip}:${IDS.segment}:v0-DEPOSIT-${IDS.deposit}:DEPOSIT_REAUTH:${IDS.tender}:i${seq}:a1`; + return createHash('sha256').update(plain, 'utf8').digest('hex'); +}; + +const pendingPort = + (status: OperationStatus | 'THROW') => + (p: PaymentProvider): PaymentProvider => + new Proxy(p, { + get(target, prop) { + if (prop === 'reauthorize') { + return (r: { providerReference: string }) => + status === 'THROW' + ? Promise.reject(new PaymentError('UNKNOWN_OUTCOME', 'délai dépassé')) + : Promise.resolve({ providerReference: r.providerReference, status }); + } + return passThrough(target, prop); + }, + }); + +describe.each(CASES)('$country ($currency) — minuterie de ré-autorisation', (c) => { + it('acceptée ⇒ REAUTHORIZED : nouvelle expiration (+120 h + 168 h), décision à la libération, aucune alerte ; clé 08 E4 de rang 1', async () => { + const s = setup(c); + const ref = await authorize(c, s); + expect(await s.timer.process(due(c, ref))).toBe('REAUTHORIZED'); + expect(s.transitions).toEqual([ + [ + IDS.deposit, + 'REAUTHORIZED', + 0, + { authExpiryAt: at(288), decisionAt: at(144, 25), reauthDueAt: null }, + ], + ]); + expect(s.alerts).toEqual([]); + expect(s.keys).toEqual([expectedKey(1)]); + }); + + it('refusée ⇒ REAUTH_REFUSED : décision avancée à expiration − 2 h, plus de minuterie, alerte ops DEPOSIT_REAUTH_FAILED, AUCUN débit', async () => { + const s = setup(c, { + scenario: { responses: { REAUTHORIZE: [{ kind: 'DECLINE', code: 'do_not_honor' }] } }, + }); + const ref = await authorize(c, s); + expect(await s.timer.process(due(c, ref))).toBe('REFUSED'); + expect(s.transitions).toEqual([ + [ + IDS.deposit, + 'REAUTH_REFUSED', + 0, + { authExpiryAt: at(144), decisionAt: at(142), reauthDueAt: null }, + ], + ]); + expect(s.alerts).toEqual([ + { + code: 'DEPOSIT_REAUTH_FAILED', + severity: 'P1', + counts: { deposits: 1 }, + labels: { country: c.country, provider: 'FAKE' }, + }, + ]); + expect(s.stack.psp.calls('MIT_CHARGE')).toBe(0); + expect(s.stack.psp.movements()).toEqual([]); + }); + + for (const status of ['PENDING', 'SUBMITTED', 'UNKNOWN', 'THROW'] as const) { + it(`issue ${status === 'THROW' ? 'inconnue (UNKNOWN_OUTCOME)' : status} ⇒ PENDING : aucun changement d'état, aucune alerte, jamais REAUTHORIZED`, async () => { + const s = setup(c, { wrap: pendingPort(status) }); + const ref = await authorize(c, s); + expect(await s.timer.process(due(c, ref))).toBe('PENDING'); + expect(await s.timer.process(due(c, ref))).toBe('PENDING'); + expect(s.transitions).toEqual([]); + expect(s.alerts).toEqual([]); + // le rejeu garde la MÊME clé (rang inchangé, 17 §4.3) + expect(s.keys).toEqual([expectedKey(1), expectedKey(1)]); + }); + } + + it('deuxième ré-autorisation (reauth_seq = 1) ⇒ clé de rang 2, distincte de la première', async () => { + const s = setup(c); + const ref = await authorize(c, s); + expect(await s.timer.process(due(c, ref, 1))).toBe('REAUTHORIZED'); + expect(s.keys).toEqual([expectedKey(2)]); + }); + + it('aucun connecteur (production avant le lot C) ⇒ NO_CONNECTOR, aucun appel ; transition périmée ⇒ STALE sans alerte', async () => { + const none = setup(c, { noConnector: true }); + const ref = await authorize(c, none); + expect(await none.timer.process(due(c, ref))).toBe('NO_CONNECTOR'); + expect(none.stack.psp.calls('REAUTHORIZE')).toBe(0); + const stale = setup(c, { + applied: 'STALE', + scenario: { responses: { REAUTHORIZE: [{ kind: 'DECLINE', code: 'do_not_honor' }] } }, + }); + const ref2 = await authorize(c, stale); + expect(await stale.timer.process(due(c, ref2))).toBe('STALE'); + expect(stale.alerts).toEqual([]); + }); + + it('SUPPORTS_REAUTH non validée ⇒ refus sans appel au PSP, même signal ops', async () => { + const s = setup(c, { without: ['SUPPORTS_REAUTH'] }); + const ref = await authorize(c, s); + expect(await s.timer.process(due(c, ref))).toBe('REFUSED'); + expect(s.stack.psp.calls('REAUTHORIZE')).toBe(0); + expect(s.alerts.map((a) => a.code)).toEqual(['DEPOSIT_REAUTH_FAILED']); + }); +}); + +describe('clés d’idempotence de la caution (08 E4, suite S-6)', () => { + const parts = { + tripId: 'trp_8f3a', + segmentId: '1', + depositId: 'dep_01', + tenderId: 'tnd_card_01', + instanceSeq: 1, + attemptNo: 1, + }; + + it('variante hors règlement : `{trip}:{segment}:v0-DEPOSIT-{caution}:{opération}:{moyen}:i{n}:a{m}`', () => { + expect(depositOperationKey({ ...parts, operationType: 'DEPOSIT_CAPTURE' })).toBe( + 'trp_8f3a:1:v0-DEPOSIT-dep_01:DEPOSIT_CAPTURE:tnd_card_01:i1:a1', + ); + expect(depositOperationKey({ ...parts, operationType: 'DEPOSIT_VOID', instanceSeq: 2 })).toBe( + 'trp_8f3a:1:v0-DEPOSIT-dep_01:DEPOSIT_VOID:tnd_card_01:i2:a1', + ); + }); + + it('remboursement de la caution débitée = clé `offSettlementRefundKey` d’origine DEPOSIT (une seule forme)', () => { + expect(depositOperationKey({ ...parts, operationType: 'REFUND' })).toBe( + offSettlementRefundKey({ ...parts, originType: 'DEPOSIT', originId: parts.depositId }), + ); + }); + + it('jamais en collision avec une version de règlement (`v1`, `v2`…) ; opération inconnue refusée', () => { + expect(depositOperationKey({ ...parts, operationType: 'MIT_CHARGE' })).toMatch(/:v0-DEPOSIT-/); + expect(() => + depositOperationKey({ ...parts, operationType: 'AUTH' as 'DEPOSIT_AUTH' }), + ).toThrow(); + }); +}); + +// type utilisé par le port de test (garde de compilation) +export type _Port = DepositPaymentProvider; diff --git a/apps/api/src/worker-tasks.test.ts b/apps/api/src/worker-tasks.test.ts index e0d6dd6ad..f930e7f75 100644 --- a/apps/api/src/worker-tasks.test.ts +++ b/apps/api/src/worker-tasks.test.ts @@ -85,6 +85,8 @@ describe('tâches du travailleur (US-003)', () => { 'booking_contract', 'booking_conversion', 'booking_oracle', + // US-701 (ADR-169) : ré-autorisations de la caution (aucun connecteur en production) + 'deposit_timer', 'disposition_sweeper', 'hold_expiry', 'iam_otp_pruner', @@ -109,6 +111,7 @@ describe('tâches du travailleur (US-003)', () => { ).toEqual([ ['booking_conversion', 10, 5], ['booking_oracle', 86_400, 5], + ['deposit_timer', 60, 5], ['disposition_sweeper', 60, 5], ['hold_expiry', 60, 5], ['iam_otp_pruner', 3_600, 5], diff --git a/apps/api/src/worker-tasks.ts b/apps/api/src/worker-tasks.ts index e830e9f4b..347191c30 100644 --- a/apps/api/src/worker-tasks.ts +++ b/apps/api/src/worker-tasks.ts @@ -24,6 +24,8 @@ * | `trip_lifecycle` | 10 s (US-215, ADR-148) | `TripCancellationProcessor` de STL : chaque demande d'annulation de l'ops (`core.booking_trip_cancellations_pending`) réglée dans sa propre transaction (`core.booking_trip_cancellation_begin`, moteur unique, `core.settlement_cmd_record`, `core.booking_cmd_trip_settle_cancellation`, ordres REFUND bornés de 0121) ; refus garés par `core.booking_cmd_trip_park_cancellation`, alertes `FIN_SETTLEMENT_REVIEW` ou `TRIP_CANCELLATION_FAILED` (P1) | * | `refund_scheduler` | 10 s (US-224c, ADR-150) | `RefundScheduler` de STL sous le nom `payment_command` : file `core.payment_refunds_due` (0127), une instance par transaction ; `core.payment_cmd_submit_refund`, puis l'ordre stocké relu sous les verrous du trip et de l'ordre (`core.payment_cmd_refund_order_for_send`) et envoyé par `MoneyCommandSender` au connecteur du fournisseur ; report `core.settlement_cmd_apply_leg_movement` d'un remboursement prouvé ; alertes `FIN_REFUND_BLOCKED`, `FIN_REFUND_FAILED` (P1, une fois par état). Aucun connecteur en production avant le lot C : rien n'est autorisé ni envoyé | * + * | `deposit_timer` | 60 s (US-701, ADR-169) | `DepositReauthTimer` de PAY sous le nom `payment_command` : file `core.payment_deposit_reauth_due` (0143), ré-autorisation de la caution (rail a) par le connecteur du fournisseur, report `core.payment_cmd_deposit_transition` ; refusée ⇒ décision avancée avant l'expiration, alerte `DEPOSIT_REAUTH_FAILED` (P1), aucun débit. Aucun connecteur en production avant le lot C : rien n'est envoyé | + * * Non déclarés ici, faute de port réel (tracé dans docs/team/handoffs/US-003.md) : * `payment_intent_sweeper` et `payment_command` (lisent ou appellent le PSP : adaptateurs du lot C, * consommateur `payment_command` d'US-061). `booking_conversion` est déclaré depuis US-223 : il ne lit @@ -50,6 +52,7 @@ import { registerMoneyReconciliation } from './modules/fin/index.js'; import { PgWebhookWorkStore, PRODUCTION_PAYMENT_CONNECTORS, + registerDepositTimers, WebhookProcessor, } from './modules/pay/index.js'; import type { CountryConfig } from './modules/cfg/index.js'; @@ -319,6 +322,16 @@ export function registerWorkerTasks(registry: BusRegistry, deps: WorkerTaskDeps) PRODUCTION_PAYMENT_CONNECTORS, ); + // US-701 (ADR-169) : ré-autorisation de la caution avant l'échéance (rail a) ; refusée ⇒ ops, + // sans débit. Aucun connecteur en production avant le lot C : rien n'est envoyé + registerDepositTimers( + registry, + deps.transactions, + alerts, + deps.log, + PRODUCTION_PAYMENT_CONNECTORS, + ); + // Files de revue (US-106) : dossiers KYC en revue remis en file s'il le faut, puis chaque élément // en retard signalé UNE fois par la base ; une alerte par (file, pays). Un envoi en échec annule // la passe (marques comprises) : rejouée par le bus, livraison « au moins une fois ». diff --git a/apps/web/account/checkout-deposit.test.ts b/apps/web/account/checkout-deposit.test.ts new file mode 100644 index 000000000..daf513da1 --- /dev/null +++ b/apps/web/account/checkout-deposit.test.ts @@ -0,0 +1,144 @@ +/** + * US-701 (ADR-169) : caution lue par S05 dans la réponse du paiement. Attendus : contrat + * (`openapi.json`, `CheckoutDeposit`) et 08 BR-PAY-06 (« le voyageur ne voit que le montant… jamais + * les déclencheurs ») ; message du refus (suite S-8 d'US-225 ; 10b UX-24) : au moins un jour + * possible ⇒ `web.deposit.unavailable`, 0 ou aucun ⇒ `web.deposit.unavailableNone`. Montant de test + * 300,00 de T57 en devise à deux décimales (XTS, 30 000) et sans décimale (XXX, 300), codes de test ISO 4217, jamais le code testé. + */ +import { readFileSync } from 'node:fs'; +import { describe, expect, it } from 'vitest'; +import { createTranslator, getProfile } from '@rueda/i18n'; +import { LOCALE_CONFIG } from '../locale-config.ts'; +import { checkoutPaymentOf, depositRefusalMessage, paymentErrorKey } from './checkout-payment.ts'; + +const base = { + holdId: '00000000-0000-4000-8000-0000000701b1', + state: 'PAYABLE', + holdStatus: 'ACTIVE', + tripId: null, + expiresAt: '2036-11-30T15:10:00.000Z', + paymentInFlightUntil: null, +}; +const reply = (deposit: unknown) => ({ + status: 200, + json: { payment: { ...base, deposit } }, + session: null, +}); +const RELEASE = '2036-12-06T15:00:00.000Z'; + +describe('US-701 — caution sur S05 (site)', () => { + for (const [currency, amount] of [ + ['XTS', 30_000n], + ['XXX', 300n], + ] as const) { + it(`caution exigée (${currency}) : montant, nature et libération lus tels quels`, () => { + expect( + checkoutPaymentOf( + reply({ + status: 'REQUIRED', + amountMinor: String(amount), + currency, + kind: 'HOLD', + releaseAt: RELEASE, + }), + )?.deposit, + ).toEqual({ + status: 'REQUIRED', + amountMinor: amount, + currency, + kind: 'HOLD', + releaseAt: RELEASE, + }); + }); + } + + it('aucune caution ⇒ NONE ; champ absent ⇒ null ; refus ⇒ jours possibles (ou null)', () => { + expect(checkoutPaymentOf(reply({ status: 'NONE' }))?.deposit).toEqual({ status: 'NONE' }); + expect(checkoutPaymentOf(reply(undefined))?.deposit).toBeNull(); + expect( + checkoutPaymentOf(reply({ status: 'UNAVAILABLE', maxBookableDays: 3 }))?.deposit, + ).toEqual({ status: 'UNAVAILABLE', maxBookableDays: 3 }); + expect( + checkoutPaymentOf(reply({ status: 'UNAVAILABLE', maxBookableDays: null }))?.deposit, + ).toEqual({ status: 'UNAVAILABLE', maxBookableDays: null }); + }); + + it('fail-closed : champ [C2] (déclencheurs, âge), montant nul ou illisible, nature ou statut inconnus ⇒ réponse refusée', () => { + for (const deposit of [ + { status: 'NONE', triggers: ['RISK'] }, + { + status: 'REQUIRED', + amountMinor: '30000', + currency: 'XTS', + kind: 'HOLD', + releaseAt: RELEASE, + triggers: ['CLASS'], + }, + { status: 'REQUIRED', amountMinor: '0', currency: 'XTS', kind: 'HOLD', releaseAt: RELEASE }, + { status: 'REQUIRED', amountMinor: 300, currency: 'XXX', kind: 'HOLD', releaseAt: RELEASE }, + { status: 'REQUIRED', amountMinor: '300', currency: 'XXX', kind: 'AUTO', releaseAt: RELEASE }, + { status: 'REQUIRED', amountMinor: '300', currency: 'XXX', kind: 'HOLD', releaseAt: 'x' }, + { status: 'UNAVAILABLE', maxBookableDays: -1 }, + { status: 'UNAVAILABLE', maxBookableDays: 2.5 }, + { status: 'UNAVAILABLE', maxBookableDays: 3, youngestDriverAge: 25 }, + { status: 'REFUSED' }, + null, + [], + ]) { + expect(checkoutPaymentOf(reply(deposit)), JSON.stringify(deposit)).toBeNull(); + } + }); + + it('S-8 : au moins un jour ⇒ `web.deposit.unavailable` avec le nombre ; 0 ou aucun ⇒ `web.deposit.unavailableNone`', () => { + expect(depositRefusalMessage({ status: 'UNAVAILABLE', maxBookableDays: 3 })).toEqual({ + key: 'web.deposit.unavailable', + count: 3, + }); + expect(depositRefusalMessage({ status: 'UNAVAILABLE', maxBookableDays: 1 })).toEqual({ + key: 'web.deposit.unavailable', + count: 1, + }); + for (const days of [0, null]) { + expect(depositRefusalMessage({ status: 'UNAVAILABLE', maxBookableDays: days })).toEqual({ + key: 'web.deposit.unavailableNone', + }); + } + }); + + it('refus 409 de l’API ⇒ clé commune, et textes présents sans variable restante dans les quatre langues', () => { + for (const code of ['DEPOSIT_RAIL_UNAVAILABLE', 'DEPOSIT_PARAM_MISSING']) { + expect(paymentErrorKey({ status: 409, json: { code }, session: null })).toBe( + 'common.payment.depositUnavailable', + ); + } + for (const tag of LOCALE_CONFIG.locales.map((l) => l.tag)) { + const t = createTranslator(getProfile(LOCALE_CONFIG, tag)).t; + for (const text of [ + t('web.deposit.none'), + t('common.payment.depositUnavailable'), + t('web.deposit.unavailable', { count: 3 }), + t('web.deposit.unavailableNone'), + ]) { + expect(text.trim().length, tag).toBeGreaterThan(0); + expect(text, tag).not.toMatch(/[{}]/); + } + } + }); + + it('contrat : le schéma CheckoutDeposit ne porte aucun champ [C2]', () => { + const openapi = JSON.parse( + readFileSync(new URL('../../api/openapi/openapi.json', import.meta.url), 'utf8'), + ) as { components: { schemas: Record } }; + const fields = openapi.components.schemas['CheckoutDeposit']!.oneOf.flatMap((o) => + Object.keys(o.properties), + ); + expect([...new Set(fields)].sort()).toEqual([ + 'amountMinor', + 'currency', + 'kind', + 'maxBookableDays', + 'releaseAt', + 'status', + ]); + }); +}); diff --git a/apps/web/account/checkout-payment.test.ts b/apps/web/account/checkout-payment.test.ts index 147d33b39..6217232e2 100644 --- a/apps/web/account/checkout-payment.test.ts +++ b/apps/web/account/checkout-payment.test.ts @@ -44,6 +44,8 @@ describe('US-223b — paiement du hold (site)', () => { redirectUrl: 'https://psp.fake.invalid/pay/x', // US-223d : réservation immédiate (aucun champ `request`) ⇒ `null` request: null, + // US-701 : aucun champ `deposit` ⇒ `null` + deposit: null, }); for (const url of ['http://psp.test/x', 'javascript:alert(1)', 'https://a b', 42]) { expect(checkoutPaymentOf(reply({ ...base, redirectUrl: url }, 201))?.redirectUrl).toBeNull(); @@ -124,6 +126,7 @@ describe('US-223d — demande à l’hôte (site)', () => { paymentInFlightUntil: null, redirectUrl: null, request: status === null ? null : { status, respondBy: RESPOND_BY }, + deposit: null, }); it('champ `request` : lu tel quel ; absent ⇒ null ; état inconnu, heure illisible ou attente sans heure limite ⇒ refus', () => { diff --git a/apps/web/account/checkout-payment.ts b/apps/web/account/checkout-payment.ts index 16557298e..da4aca785 100644 --- a/apps/web/account/checkout-payment.ts +++ b/apps/web/account/checkout-payment.ts @@ -52,6 +52,22 @@ export interface PaymentRequestView { readonly respondBy: string | null; } +/** + * Caution vue par le voyageur (US-701, ADR-169 ; 08 BR-PAY-06) : aucune, montant et libération, ou + * réservation impossible avant le paiement. L'API ne rend jamais les déclencheurs (S-7). + */ +export type DepositView = + | { readonly status: 'NONE' } + | { + readonly status: 'REQUIRED'; + readonly amountMinor: bigint; + readonly currency: string; + /** `HOLD` : blocage sur la carte ; `CHARGE` : débit puis remboursement. */ + readonly kind: 'HOLD' | 'CHARGE'; + readonly releaseAt: string; + } + | { readonly status: 'UNAVAILABLE'; readonly maxBookableDays: number | null }; + export interface CheckoutPaymentView { readonly holdId: string; readonly state: PaymentStateView; @@ -62,6 +78,8 @@ export interface CheckoutPaymentView { readonly redirectUrl: string | null; /** Demande à l'hôte (hold `REQUEST`, US-223c) ; `null` : réservation immédiate. */ readonly request: PaymentRequestView | null; + /** Caution (US-701) ; `null` : ni figée ni évaluable (champ absent). */ + readonly deposit: DepositView | null; } const isObj = (v: unknown): v is Record => @@ -69,6 +87,68 @@ const isObj = (v: unknown): v is Record => const instantOrNull = (v: unknown): string | null | undefined => v === null ? null : typeof v === 'string' && INSTANT.test(v) ? v : undefined; +const DEPOSIT_MINOR = /^[1-9][0-9]{0,17}$/; +const CURRENCY_CODE = /^[A-Z]{3}$/; + +/** + * Champ `deposit` (US-701) : absent ⇒ `null` ; mal formé ou porteur d'un champ inattendu + * (déclencheurs, âge…) ⇒ `undefined` (réponse refusée, fail-closed). + */ +function depositOf(v: unknown): DepositView | null | undefined { + if (v === undefined) return null; + if (!isObj(v)) return undefined; + const keys = Object.keys(v).sort().join(','); + switch (v['status']) { + case 'NONE': + return keys === 'status' ? { status: 'NONE' } : undefined; + case 'REQUIRED': { + const amount = v['amountMinor']; + const currency = v['currency']; + const kind = v['kind']; + const releaseAt = v['releaseAt']; + if ( + keys !== 'amountMinor,currency,kind,releaseAt,status' || + typeof amount !== 'string' || + !DEPOSIT_MINOR.test(amount) || + typeof currency !== 'string' || + !CURRENCY_CODE.test(currency) || + (kind !== 'HOLD' && kind !== 'CHARGE') || + typeof releaseAt !== 'string' || + !INSTANT.test(releaseAt) + ) { + return undefined; + } + return { status: 'REQUIRED', amountMinor: BigInt(amount), currency, kind, releaseAt }; + } + case 'UNAVAILABLE': { + const days = v['maxBookableDays']; + if (keys !== 'maxBookableDays,status') return undefined; + if (days === null) return { status: 'UNAVAILABLE', maxBookableDays: null }; + return typeof days === 'number' && Number.isSafeInteger(days) && days >= 0 + ? { status: 'UNAVAILABLE', maxBookableDays: days } + : undefined; + } + default: + return undefined; + } +} + +/** + * Message du refus de la caution sur S05 (suite S-8 d'US-225 ; 10b UX-24) : au moins un jour + * possible ⇒ `web.deposit.unavailable` (« tu peux réserver jusqu'à {count} jours ») ; 0 ou aucun + * (montant non fixé) ⇒ `web.deposit.unavailableNone` (jamais « jusqu'à 0 jour »). + */ +export function depositRefusalMessage(deposit: DepositView & { readonly status: 'UNAVAILABLE' }): + | { readonly key: 'web.deposit.unavailable'; readonly count: number } + | { + readonly key: 'web.deposit.unavailableNone'; + } { + const days = deposit.maxBookableDays; + return days !== null && days >= 1 + ? { key: 'web.deposit.unavailable', count: days } + : { key: 'web.deposit.unavailableNone' }; +} + /** Champ `request` du paiement : absent ⇒ `null` (réservation immédiate), mal formé ⇒ `undefined`. */ function requestOf(v: unknown): PaymentRequestView | null | undefined { if (v === undefined) return null; @@ -169,6 +249,8 @@ export function checkoutPaymentOf(reply: ApiResult): CheckoutPaymentView | null if (state === 'CONFIRMED' && tripId === null) return null; const request = requestOf(p['request']); if (request === undefined) return null; + const deposit = depositOf(p['deposit']); + if (deposit === undefined) return null; const redirectUrl = typeof url === 'string' && HOSTED.test(url) && url.length <= HOSTED_MAX ? url : null; return { @@ -179,6 +261,7 @@ export function checkoutPaymentOf(reply: ApiResult): CheckoutPaymentView | null paymentInFlightUntil: inFlight, redirectUrl, request, + deposit, }; } @@ -192,6 +275,9 @@ const PAYMENT_KEYS: Readonly> = { HOLD_EXPIRED: 'common.payment.holdExpired', HOLD_NOT_PAYABLE: 'common.payment.holdNotPayable', BOOKING_UNDER_REVIEW: 'common.payment.underReview', + // US-701 (ADR-169) : caution impossible pour ces dates, ou montant non fixé + DEPOSIT_RAIL_UNAVAILABLE: 'common.payment.depositUnavailable', + DEPOSIT_PARAM_MISSING: 'common.payment.depositUnavailable', START_PASSED: 'common.payment.startPassed', PAYMENT_ATTEMPTS_EXCEEDED: 'common.payment.attemptsExceeded', HOST_PAYOUT_RAIL_UNAVAILABLE: 'common.payment.payoutRailUnavailable', diff --git a/apps/web/app/(app)/checkout/hold/[holdId]/page.tsx b/apps/web/app/(app)/checkout/hold/[holdId]/page.tsx index ddbaedc72..04ed77af5 100644 --- a/apps/web/app/(app)/checkout/hold/[holdId]/page.tsx +++ b/apps/web/app/(app)/checkout/hold/[holdId]/page.tsx @@ -5,7 +5,11 @@ import { Banner, ButtonLink, EmptyState, ErrorState } from '@rueda/ui'; import type { MessageKey } from '@rueda/i18n'; import { callApi, codeOf } from '../../../../../account/api-client.ts'; import { checkoutHoldOf, holdPayable, isUuid } from '../../../../../account/checkout.ts'; -import { checkoutPaymentOf, paymentHref } from '../../../../../account/checkout-payment.ts'; +import { + checkoutPaymentOf, + depositRefusalMessage, + paymentHref, +} from '../../../../../account/checkout-payment.ts'; import { publicListingOf } from '../../../../../account/host-listings.ts'; import { clientContext } from '../../../../../account/request.ts'; import { getRequestI18n, getRequestLocaleTag } from '../../../../../i18n.ts'; @@ -134,6 +138,11 @@ export default async function HoldPage({ currency: hold.currency, exponent: listing.currencyExponent, }); + // US-701 (ADR-169 ; 08 BR-PAY-06) : caution décidée AVANT le paiement, rendue par l'API (montant, + // nature, libération ; jamais les déclencheurs) ; réservation impossible ⇒ aucun bouton « Pagar » + const deposit = payment?.deposit ?? null; + const depositBlocked = deposit?.status === 'UNAVAILABLE'; + const depositRefusal = deposit?.status === 'UNAVAILABLE' ? depositRefusalMessage(deposit) : null; return ( + {/* US-701 : caution de la plateforme (10b §3.5, UX-24) : aucune, montant et libération au plus + tard, ou refus avant le paiement avec les jours possibles et une sortie */} + {deposit !== null && ( +
+

+ {t('web.s03.deposit.title')} +

+ {deposit.status === 'NONE' && ( +

{t('web.deposit.none')}

+ )} + {deposit.status === 'REQUIRED' && ( + <> +
+
+
{t('web.deposit.amount')}
+
+ {i18n.money({ + amountMinor: deposit.amountMinor, + currency: deposit.currency, + exponent: listing.currencyExponent, + })} +
+
+
+

+ {t( + deposit.kind === 'CHARGE' + ? 'web.deposit.how.chargeRefund' + : 'web.deposit.how.preauth', + )} +

+

+ {t('web.deposit.releaseBy', { date: i18n.dateTime(deposit.releaseAt, tz) })} +

+ + )} + {depositRefusal !== null && ( + <> + + {depositRefusal.key === 'web.deposit.unavailable' + ? t(depositRefusal.key, { count: depositRefusal.count }) + : t(depositRefusal.key)} + + + {t('web.listing.search')} + + + )} +
+ )} {/* US-223b : paiement sur la page hébergée du PSP (10b UX-26), montant rendu par l'API ; - jamais pendant une revue avant le débit (US-209c, N-203) */} - {payable && payment?.request === null && ( + jamais pendant une revue avant le débit (US-209c, N-203) ; jamais si la caution est + impossible (US-701) */} + {payable && !depositBlocked && payment?.request === null && (

{t('web.s05.pay.title')} @@ -240,7 +305,7 @@ export default async function HoldPage({ )} {/* US-223d : demande à l'hôte (10b S05 `web.s05.ctaRequest`) : le paiement est autorisé sur la page du PSP, débité seulement si l'hôte accepte (ADR-146) */} - {payable && payment !== null && payment.request !== null && ( + {payable && !depositBlocked && payment !== null && payment.request !== null && (
{ + await signInGuest(context, language); + await placeHold(page, 12); + const t = translator(language); + const section = page.locator('[data-testid="s05-deposit"]'); + await expect(section).toHaveAttribute('data-state', 'UNAVAILABLE'); + await expect(section.locator('[role="alert"]')).toHaveText( + t.t('web.deposit.unavailable', { count: 3 }), + ); + await expect(section.getByRole('link', { name: t.t('web.listing.search') })).toBeVisible(); + await expect(page.locator('[data-testid="s05-pay-submit"]')).toHaveCount(0); + await expectAccessible(page); + await expectMobileFriendly(page); + }); + + test('US-701 : caution exigée ⇒ montant, blocage temporaire et libération au plus tard sur S05 ; « Pagar » reste offert', async ({ + page, + context, + }) => { + await signInGuest(context, language); + await placeHold(page, 13); + const t = translator(language); + const section = page.locator('[data-testid="s05-deposit"]'); + await expect(section).toHaveAttribute('data-state', 'REQUIRED'); + await expect(section.locator('[data-testid="s05-deposit-amount"]')).toHaveText(/300[.,]00/); + await expect(section).toContainText(t.t('web.deposit.how.preauth')); + await expect(section).toContainText(fixedPart(t, 'web.deposit.releaseBy', 'date')); + await expect(page.locator('[data-testid="s05-pay-submit"]')).toBeVisible(); + await expectAccessible(page); + await expectMobileFriendly(page); + }); + for (const [day, key] of [ [18, 'common.payment.payoutRailUnavailable'], // le 19 (réservation en revue) : aucun bouton « Pagar » (US-209c, checkout-review.spec.ts) diff --git a/apps/web/e2e/stub-api.mjs b/apps/web/e2e/stub-api.mjs index aa7c6e7c0..18f0fe74e 100644 --- a/apps/web/e2e/stub-api.mjs +++ b/apps/web/e2e/stub-api.mjs @@ -721,6 +721,33 @@ const PAYMENT_REFUSALS = { // (`reviewed_at`, prolongation unique : échéance APPROVED_EXPIRES_AT, fenêtre de paiement), // REJECTED (RELEASED / REVIEW_REJECTED) ou LAPSE (revue non faite dans le délai : même état). const REVIEW_DAY = '-12-19T'; +// ---- Caution de la plateforme (US-701, ADR-169) ----------------------------------------------- +// Le 12 décembre : caution exigée mais impossible pour ces dates (T59) : vue `UNAVAILABLE` avec +// 3 jours possibles, paiement refusé (409 DEPOSIT_RAIL_UNAVAILABLE) avant tout ordre. Le 13 : +// caution exigée, blocage de 300,00 (T57, valeur de test) libéré au plus tard à fin + 72 h. Les +// autres jours : aucun champ `deposit` (forme d'US-223 inchangée). +const DEPOSIT_UNAVAILABLE_DAY = '-12-12T'; +const DEPOSIT_REQUIRED_DAY = '-12-13T'; +const DEPOSIT_RELEASE_DELAY_MS = 72 * 3_600_000; +const depositJson = (h) => { + if (h.kind === 'REQUEST') return {}; + if (h.quote.startAt.includes(DEPOSIT_UNAVAILABLE_DAY)) { + return { deposit: { status: 'UNAVAILABLE', maxBookableDays: 3 } }; + } + if (h.quote.startAt.includes(DEPOSIT_REQUIRED_DAY)) { + const releaseAt = new Date(Date.parse(h.quote.endAt) + DEPOSIT_RELEASE_DELAY_MS).toISOString(); + return { + deposit: { + status: 'REQUIRED', + amountMinor: '30000', + currency: MARKET.currency, + kind: 'HOLD', + releaseAt, + }, + }; + } + return {}; +}; const REVIEW_EXPIRES_AT = '2036-11-30T17:00:00.000Z'; const APPROVED_EXPIRES_AT = '2036-11-30T15:40:00.000Z'; const PAYMENT_IN_FLIGHT_UNTIL = '2036-11-30T15:16:00.000Z'; @@ -774,6 +801,7 @@ const paymentJson = (h, redirectUrl) => ({ ...(h.kind === 'REQUEST' ? { request: { status: requestStatusOf(h), respondBy: h.respondBy ?? null } } : {}), + ...depositJson(h), }); async function paymentRoute(req, res, url) { @@ -885,6 +913,10 @@ async function paymentRoute(req, res, url) { if (h.review === 'PENDING') { return err(res, 409, 'BOOKING_UNDER_REVIEW', 'common.payment.underReview'); } + // US-701 : caution décidée avant le paiement ; impossible ⇒ aucun ordre + if (h.quote.startAt.includes(DEPOSIT_UNAVAILABLE_DAY)) { + return err(res, 409, 'DEPOSIT_RAIL_UNAVAILABLE', 'common.payment.depositUnavailable'); + } const refusal = Object.entries(PAYMENT_REFUSALS).find(([day]) => h.quote.startAt.includes(day)); if (refusal !== undefined) return err(res, refusal[1][0], refusal[1][1], refusal[1][2]); h.status = 'PAYMENT_IN_FLIGHT'; diff --git a/changelog.d/US-701-caution-plateforme.md b/changelog.d/US-701-caution-plateforme.md new file mode 100644 index 000000000..cbba08640 --- /dev/null +++ b/changelog.d/US-701-caution-plateforme.md @@ -0,0 +1,10 @@ +lot: L2 +module: Paiements + +- Ajouté : décision de la caution figée une fois par réservation avant le paiement (migration 0143, US-701, ADR-169) ; la base revérifie le montant du pays et de la classe, refuse « aucune caution » sur une classe qui en exige une et ferme le « débit puis remboursement » tant que la détention de fonds est fermée +- Ajouté : la page de paiement affiche la caution avant de payer — aucune caution, montant, blocage temporaire et date de libération au plus tard, ou réservation impossible avec les jours possibles et un lien vers la recherche ; aucun bouton « Payer » quand la caution est impossible (US-701) +- Ajouté : refus du paiement quand la caution est impossible pour ces dates ou que son montant n'est pas fixé, avant tout ordre au PSP (409, US-701) +- Ajouté : ré-autorisation de la caution avant son expiration par une tâche du travailleur ; refusée, la décision est avancée avant l'expiration et le trip est signalé à l'ops sans débit (US-701) +- Ajouté : textes « aucune caution » et refus du paiement en espagnol, anglais, français et portugais du Brésil (catalogue v83, US-701) +- Modifié : clés d'idempotence des opérations de caution alignées sur la variante « hors règlement » de 08 E4 (US-701) +- Corrigé : une ré-autorisation en cours ou d'issue inconnue n'est plus prise pour une ré-autorisation acceptée (US-701, suite des revues d'US-225) diff --git a/docs/adr/ADR-169-caution-figee-au-checkout.md b/docs/adr/ADR-169-caution-figee-au-checkout.md new file mode 100644 index 000000000..3c3277b99 --- /dev/null +++ b/docs/adr/ADR-169-caution-figee-au-checkout.md @@ -0,0 +1,31 @@ +# ADR-169 — Caution figée au checkout : `deposit_hold` par hold, vue du voyageur sans [C2], minuterie de ré-autorisation, clés 08 E4 + +- **Statut** : PROPOSÉ (US-701, agent de story argent, claude-opus-5-5, 2026-11-18). Revues exigées : celles de `node scripts/ci/check-story-reviews.mjs` ; argent, RLS / rôles, `SECURITY DEFINER` et concurrence sur un autre modèle que l'auteur. À reporter par une PR revue de `docs/specs/` : 17 §3.2.7 (`deposit_hold` rattaché au hold, `REFUSED` jamais écrit, colonnes `provider`, `auth_provider_reference`, `reauth_due_at`, `reauth_seq`, `decided_at`), 08 E4 (opérations `DEPOSIT_AUTH`, `DEPOSIT_CHARGE`, `DEPOSIT_REAUTH` de la variante hors règlement), 16 PAY-011 (états de la ré-autorisation). +- **Complète** : ADR-108 (caution conditionnelle « comme Turo »), ADR-164 (rails, US-225 : suites S-2, S-6, S-7, S-8 et `reauthorize`), ADR-139 / ADR-142 (paiement du hold, S05). +- **Sources** : 08 BR-PAY-06 (« Moment de l'évaluation », « Fail-closed », « Montant unique », « Libération à heure fixe », « Mécanisme »), E4 (clé d'idempotence, variante hors règlement), vecteurs T57, T59, T70, T72 ; 17 §0.1, §3.2.7, §4.3 ; 19 US-701, US-225 (critère 3), US-702 (frontière) ; 10b §3.5, UX-24 ; oracle `docs/specs/tools/check_t49plus.py`. + +## Contexte + +US-225 a livré la décision pure (`decideDepositGate`), le choix du rail par configuration, la décision de libération et l'exécution sur le port, sans table, sans écran et sans minuterie. Restaient (passation US-225) : S-2 (table, branchement au checkout et à S05, minuteries), S-6 (clés `deposit:` différentes de 08 E4), S-7 (vue du voyageur sans `triggers` ni `params_snapshot`), S-8 (`web.deposit.unavailableNone` pour 0 jour) et `reauthorize`, qui rendait `REAUTHORIZED` pour un statut `PENDING` / `SUBMITTED` / `UNKNOWN`. + +## Décision + +1. **Une décision par hold, figée avant le paiement** (`core.payment_deposit_hold`, migration 0143). Le trip n'existe pas encore au checkout : la ligne porte `hold_id` (unique) ; le trip est retrouvé par `booking_checkout_hold.converted_trip_id` (écart PROPOSÉ à 17 §3.2.7 `trip_id`). Un checkout refusé n'écrit **aucune** ligne : `REFUSED` n'est jamais écrit (CHECK). `NOT_REQUIRED` ⇔ aucun déclencheur ⇔ montant 0, sans état ni échéance (CHECK). Identité et décision figées par une garde ; transitions de 16 PAY-011 seulement ; aucune suppression. RLS ENABLE + FORCE, **aucun droit** d'`app_api`, d'`app_worker` ni d'`app_anon` sur la table. +2. **Fonctions de cmd_hold_owner** (liste blanche RLS-15) : `payment_deposit_checkout` (voyageur de la session : contexte du hold, ou décision figée réduite à mécanisme, montant, devise, libération) ; `payment_cmd_record_deposit_decision` (écriture unique sous le verrou du hold, `EXISTING` ensuite) ; `payment_deposit_reauth_due` et `payment_cmd_deposit_transition` (travailleur `payment_command`). La commande d'écriture **revérifie ce que la base sait** : devise du devis engagé ; `NOT_REQUIRED` refusé si `deposit_always_required` n'est pas `false`, si `deposit_trigger_classes` est illisible ou contient la classe, ou si la classe est inconnue ; montant = `deposit_amount[pays][classe]` exactement ; rail « débit puis remboursement » refusé tant que `funds_holding_enabled[pays]` = `false` (17 §0.1). L'âge et le signal de risque ne sont pas revérifiables par la base : ils restent du ressort de la fonction pure (fail-closed, point 6). +3. **Branchement au paiement** (AVL, `CheckoutPaymentService`) : `GET …/payment` rend `payment.deposit` (décision figée, ou évaluée **sans écriture** tant qu'un paiement est possible) ; `POST …/payment` applique la porte **avant T1** : refus ⇒ 409 `DEPOSIT_RAIL_UNAVAILABLE` ou `DEPOSIT_PARAM_MISSING` (`common.payment.depositUnavailable`), aucune écriture, aucun ordre ; sinon la décision est figée puis le paiement suit. Porte indisponible ⇒ 503 (jamais un paiement sans décision). La vue du voyageur (S-7) ne porte que `status`, `amountMinor`, `currency`, `kind` (`HOLD` / `CHARGE`) et `releaseAt`, ou `maxBookableDays` : jamais les déclencheurs, l'âge, le signal de risque ni l'instantané (schéma OpenAPI `CheckoutDeposit` fermé, test d'absence). +4. **S05** : section « Depósito de garantía » : aucune caution (`web.deposit.none`), montant, nature (`web.deposit.how.*`) et libération au plus tard (`web.deposit.releaseBy`), ou refus dans une bannière `assertive` avec une sortie vers la recherche ; **aucun bouton « Pagar »** si la caution est impossible. S-8 : au moins un jour ⇒ `web.deposit.unavailable` ; 0 ou aucun (montant non fixé) ⇒ `web.deposit.unavailableNone` (`depositRefusalMessage`). +5. **Échéancier** (`planDepositSchedule`, pur) : `release_at = scheduled_end + release_delay_h` ; pré-autorisation unique : `decision_at = min(release_at, (auth_at + V) − deposit_safety_h)` (T57 : fin + 70 h) ; rail (a) : ré-autorisation à `(auth_at + V) − deposit_reauth_lead_h`, décision planifiée à la libération ; rail (b) : décision à la libération. Une décision au-delà de l'expiration en cours n'est admise par la base que tant qu'une ré-autorisation est planifiée avant elle (CHECK). +6. **Minuterie de ré-autorisation** (`deposit_timer`, 60 s, nom `payment_command`) : ré-autorisation par le port, **hors transaction** ; `SUCCEEDED` ⇒ nouvelle expiration (`maintenant + V`), décision ramenée avant elle ; refus reçu ou capacité non validée ⇒ aucune nouvelle ré-autorisation, décision avancée à `expiration − deposit_safety_h`, alerte ops `DEPOSIT_REAUTH_FAILED` (P1), **aucun débit** ; `PENDING` / `SUBMITTED` / `UNKNOWN` / `UNKNOWN_OUTCOME` ⇒ `REAUTH_PENDING` (`needsLookup`) : aucun changement, la **même clé** est rejouée (17 §4.3). Transition gardée par le rang attendu (`STALE` sinon). Aucun connecteur en production avant le lot C : rien n'est envoyé. +7. **Clés d'idempotence alignées sur 08 E4** (S-6) : variante hors règlement pour toute opération de caution, `{trip_id}:{segment_id}:v0-DEPOSIT-{deposit_id}:{opération}:{moyen}:i{n}:a{m}` ; opérations de 08 E4 (`DEPOSIT_CAPTURE`, `DEPOSIT_VOID`, `REFUND`, `MIT_CHARGE`) et `DEPOSIT_AUTH` (17 `payment_operation.kind`) ; `DEPOSIT_CHARGE` et `DEPOSIT_REAUTH` PROPOSÉS. Le remboursement du rail (b) est exactement la clé `offSettlementRefundKey` d'origine `DEPOSIT`. Moyen = opération de loyer convertie (comme les ordres de règlement). Aucune clé n'était encore persistée. + +## Options écartées + +- Écrire la décision dans T1 (`booking_cmd_checkout_pay`) : la décision est une fonction pure de TypeScript (US-225) ; la recopier en SQL doublerait la règle. La base revérifie seulement ce qu'elle sait (point 2). +- Rendre la table lisible par `app_api` sous RLS (voyageur, ops) : les colonnes [C2] imposeraient des droits de colonne fragiles ; lecture par fonctions sans ces colonnes, console ops en suite. +- Évaluer et écrire à la lecture de S05 : une simple lecture figerait une décision ; la lecture n'écrit jamais. + +## Conséquences + +- Au PA et au PY aujourd'hui : STANDARD et PREMIUM ⇒ « aucune caution » figée ; LUXE ⇒ refus avant le paiement (`DEPOSIT_PARAM_MISSING` tant que `deposit_amount` est À DÉCIDER), aucune ligne. Aucun fonds bloqué, aucun interrupteur touché. +- Non livré (suites) : pose de la caution à `auth_at` (S-1, lot C), décision de libération et transitions finales (US-702), âge des conducteurs et signal de risque au checkout (S-10), fiche et cartes de recherche sur `deposit_amount` (T70 c, N-89), console ops des déclencheurs. +- Preuves : `apps/api/src/modules/pay/internal/deposit-checkout.test.ts`, `pay/testing/deposit-timer.fake.test.ts`, `avl/testing/checkout-deposit.contract.test.ts`, `apps/web/account/checkout-deposit.test.ts`, e2e `checkout-payment.spec.ts` (US-701), `packages/db/test/l0/l0-us701-deposit-hold.test.ts`. diff --git a/docs/architecture/api.md b/docs/architecture/api.md index 48935f197..c66d8ca68 100644 --- a/docs/architecture/api.md +++ b/docs/architecture/api.md @@ -32,7 +32,7 @@ Chaque statut ci-dessous est exercé par un test de contrat sur l’application | ------- | ------ | ----------- | ------ | ---------------- | | `GET` | `/checkout/holds/{holdId}` | `checkoutHold` | Hold de checkout du voyageur de la session (US-208 critère 3) : état, échéance, devis engagé et version exacte de chaque document accepté | **200** application/json
**401** AUTH_REQUIRED
**404** HOLD_NOT_FOUND
**503** BOOKING_UNAVAILABLE | | `GET` | `/checkout/holds/{holdId}/payment` | `checkoutHoldPayment` | État du paiement du hold du checkout (US-223b ; 16 PAY-034 ; écran S06, 10b UX-27) | **200** application/json
**401** AUTH_REQUIRED
**404** HOLD_NOT_FOUND
**503** BOOKING_UNAVAILABLE | -| `POST` | `/checkout/holds/{holdId}/payment` | `checkoutPayHold` | Paiement du hold du checkout (US-223b ; 17 §2.5 étapes 3a à 3c ; 16 PAY-006, PAY-019 ; 08 E7 règle 1) : intention de paiement (T1), ordre chez le PSP avec le montant explicite de chaque jambe, enregistrement de l'ordre (T2) | **200** application/json
**201** application/json
**400** REQUEST_INVALID
**401** AUTH_REQUIRED
**403** ACCOUNT_RESTRICTED / KYC_NOT_APPROVED / KYC_BIOMETRIC_CONSENT_MISSING / KYC_LICENSE_EXPIRED / AGE_CLASS_MISMATCH
**404** HOLD_NOT_FOUND
**409** HOLD_EXPIRED / HOLD_NOT_PAYABLE / BOOKING_UNDER_REVIEW / START_PASSED / PAYMENT_ATTEMPTS_EXCEEDED / HOST_PAYOUT_RAIL_UNAVAILABLE
**422** PAYMENT_METHOD_UNAVAILABLE / QUOTE_UNAVAILABLE
**503** PAYMENT_UNAVAILABLE / BOOKING_UNAVAILABLE | +| `POST` | `/checkout/holds/{holdId}/payment` | `checkoutPayHold` | Paiement du hold du checkout (US-223b ; 17 §2.5 étapes 3a à 3c ; 16 PAY-006, PAY-019 ; 08 E7 règle 1) : intention de paiement (T1), ordre chez le PSP avec le montant explicite de chaque jambe, enregistrement de l'ordre (T2) | **200** application/json
**201** application/json
**400** REQUEST_INVALID
**401** AUTH_REQUIRED
**403** ACCOUNT_RESTRICTED / KYC_NOT_APPROVED / KYC_BIOMETRIC_CONSENT_MISSING / KYC_LICENSE_EXPIRED / AGE_CLASS_MISMATCH
**404** HOLD_NOT_FOUND
**409** HOLD_EXPIRED / HOLD_NOT_PAYABLE / BOOKING_UNDER_REVIEW / START_PASSED / PAYMENT_ATTEMPTS_EXCEEDED / HOST_PAYOUT_RAIL_UNAVAILABLE / DEPOSIT_RAIL_UNAVAILABLE / DEPOSIT_PARAM_MISSING
**422** PAYMENT_METHOD_UNAVAILABLE / QUOTE_UNAVAILABLE
**503** PAYMENT_UNAVAILABLE / BOOKING_UNAVAILABLE | | `POST` | `/checkout/quotes` | `checkoutCreateQuote` | Devis figé du voyageur pour une annonce et une période (US-208 ; 16 BKG-001, BKG-006, PRC-025) : lignes, taxes et total rejoués par la base, validité, documents à accepter | **201** application/json
**400** QUOTE_INPUT_INVALID
**401** AUTH_REQUIRED
**404** LISTING_NOT_FOUND
**409** QUOTE_MISMATCH / INSURER_CONTRACT_INACTIVE
**422** QUOTE_UNAVAILABLE / TAX_CONFIG_MISSING / LEG_AMOUNT_NEGATIVE / PROTECTION_LEVEL_REQUIRED / PROTECTION_LEVEL_NOT_ELIGIBLE
**429** QUOTE_RATE_LIMITED
**503** BOOKING_UNAVAILABLE | | `GET` | `/checkout/quotes/{quoteId}` | `checkoutQuote` | Devis figé du voyageur de la session (US-208) : lignes, total, validité (expired), boîte manuelle, mode de l'annonce, documents à accepter | **200** application/json
**401** AUTH_REQUIRED
**404** QUOTE_NOT_FOUND
**503** BOOKING_UNAVAILABLE | | `POST` | `/checkout/quotes/{quoteId}/hold` | `checkoutPlaceHold` | Checkout du devis (US-208 ; 16 BKG-001, BKG-002, BKG-025, BKG-008, BKG-023) : contrôles, consentements et pose du hold CHECKOUT en une transaction ; aucun paiement | **201** application/json
**400** REQUEST_INVALID
**401** AUTH_REQUIRED
**403** SELF_BOOKING_FORBIDDEN / ACCOUNT_RESTRICTED / KYC_NOT_APPROVED / KYC_BIOMETRIC_CONSENT_MISSING / KYC_LICENSE_EXPIRED / AGE_CLASS_MISMATCH
**404** QUOTE_NOT_FOUND
**409** QUOTE_EXPIRED / QUOTE_ALREADY_USED / INSURER_CONTRACT_INACTIVE / LISTING_UNAVAILABLE / REQUEST_MODE_UNAVAILABLE / TERMS_VERSION_CHANGED / DATES_UNAVAILABLE / GUEST_OVERLAP / HOLD_ALREADY_LIVE / HOLD_LIMIT_REACHED
**422** QUOTE_LINE_NOT_SUPPORTED / PROTECTION_LEVEL_REQUIRED / MANUAL_TRANSMISSION_NOT_CONFIRMED / DRIVER_MUST_BE_ACCOUNT_HOLDER / TERMS_NOT_ACCEPTED / DATES_NOTICE_TOO_SHORT
**429** HOLD_RATE_LIMITED
**503** TERMS_UNAVAILABLE / BOOKING_UNAVAILABLE | diff --git a/docs/architecture/modules.md b/docs/architecture/modules.md index 8a7618455..86ae213a5 100644 --- a/docs/architecture/modules.md +++ b/docs/architecture/modules.md @@ -110,7 +110,7 @@ flowchart LR | AVL | Availability & Booking | `booking` (17) | occupation unique, hold CHECKOUT, réservation, trip, segments, conducteurs, annulations et no-shows, import iCal en blocages | IAM, KYC, CAT, PRC, CTR, PAY, RISK, CFG, AUD, BUS | IAM, PRC, CTR, PAY, BUS | `GET /checkout/holds/{holdId}`
`GET /checkout/holds/{holdId}/payment`
`GET /checkout/quotes/{quoteId}`
`GET /host/accounts/{orgId}/earnings/{month}`
`GET /host/accounts/{orgId}/requests`
`GET /host/accounts/{orgId}/requests/{holdId}`
`GET /trips`
`GET /trips/{tripId}`
`GET /trips/{tripId}/receipt`
`GET /trips/{tripId}/refunds`
`POST /checkout/holds/{holdId}/payment`
`POST /checkout/quotes`
`POST /checkout/quotes/{quoteId}/hold`
`POST /host/accounts/{orgId}/requests/{holdId}/accept`
`POST /host/accounts/{orgId}/requests/{holdId}/decline` | construit | | PRC | Pricing & Quotes | `pricing` (PROPOSÉ) | devis versionné, jours facturables, lignes (trip fee, protection), taxes, instantané des paramètres, versions de prix du trip | CAT, CFG, AUD, BUS | CAT, CFG | — | construit | | CTR | Contracts & Documents | `contract` (PROPOSÉ) | gabarits juridiques versionnés, génération PDF (contrat entre l'hôte et le voyageur), signature électronique, consentements | IAM, CFG, AUD, BUS | IAM, CFG | `GET /host/accounts/{orgId}/terms`
`GET /legal/consents`
`GET /legal/documents`
`GET /legal/documents/{kind}`
`GET /trips/{tripId}/constancia`
`GET /trips/{tripId}/constancia/pdf`
`GET /trips/{tripId}/contract`
`GET /trips/{tripId}/contract/pdf`
`POST /host/accounts/{orgId}/terms/accept`
`POST /legal/consents/accept`
`POST /legal/consents/marketing`
`POST /trips/constancias/search`
`POST /trips/{tripId}/contract/sign` | construit | -| PAY | Payments abstraction | `payment` (17) | adaptateurs PSP de place de marché, sous-marchands hôtes, capacités, opérations avec montants par jambe, commandes monétaires, webhooks, remboursements, caution | CFG, AUD, BUS | CFG | `POST /webhooks/{provider}/{publicWebhookId}` | construit | +| PAY | Payments abstraction | `payment` (17) | adaptateurs PSP de place de marché, sous-marchands hôtes, capacités, opérations avec montants par jambe, commandes monétaires, webhooks, remboursements, caution | CFG, AUD, BUS | CFG, BUS | `POST /webhooks/{provider}/{publicWebhookId}` | construit | | STL | Settlement engine & Ledger | `settlement` (PROPOSÉ) | règlement économique pur, jambes, grand livre en partie double, host_ledger, insurer_ledger et bordereaux, avances de Kmino | PRC, PAY, CFG, AUD, BUS | PRC, PAY, BUS | — | construit | | PYO | Payouts | `payout` (PROPOSÉ) | compte de versement vérifié de l'hôte, lots depuis la jambe HOST, compensation des débits (NETTING), gel et reprise | KYC, PAY, STL, CFG, AUD, BUS | — | — | coquille | | TRP | Trip operations | `trip_ops` (PROPOSÉ) | check-in et check-out par l'hôte et le voyageur, hors ligne, retards et non-restitution, refus du véhicule, remises du jour | KYC, AVL, PAY, CFG, AUD, BUS | — | — | coquille | diff --git a/docs/architecture/schema.md b/docs/architecture/schema.md index ba7762c0b..42325980d 100644 --- a/docs/architecture/schema.md +++ b/docs/architecture/schema.md @@ -7,7 +7,7 @@ Lu dans le catalogue (`pg_catalog`) d'une base jetable du banc, après les seule ## Synthèse -- 143 migrations ; 127 tables ; 3 vues ; 714 politiques RLS ; 285 fonctions `SECURITY DEFINER` ; 249 autres fonctions. +- 144 migrations ; 128 tables ; 3 vues ; 720 politiques RLS ; 289 fonctions `SECURITY DEFINER` ; 251 autres fonctions. - Tables sans RLS `ENABLE` + `FORCE` : aucune. - Rôles applicatifs avec `SUPERUSER` ou `BYPASSRLS` : aucun. @@ -158,6 +158,7 @@ Lu dans le catalogue (`pg_catalog`) d'une base jetable du banc, après les seule | `0140_booking_defaulted_host_trips_cancel` | AVL / SUP : hôte défaillant, annulation de ses trips à venir par l'ops, voyageurs remboursés | | `0141_payment_refund_multi_tender` | PAY : remboursement réparti sur les moyens d'origine (TJ16c / TJ16d) et reprise après un | | `0142_config_deposit_rail_params` | graine complémentaire : paramètres « deposit_always_required* » (US-225 ; 17 §7.2). | +| `0143_payment_deposit_hold` | PAY : caution de la plateforme figée au checkout (`deposit_hold`), vue du voyageur sans champ [C2], | ## Rôles @@ -4209,6 +4210,39 @@ Déclencheurs : - `touch_row` : `CREATE TRIGGER touch_row BEFORE UPDATE ON core.outbox_scheduled_job FOR EACH ROW EXECUTE FUNCTION platform.touch_row()` +### `core.payment_deposit_hold` + +- RLS : ENABLE + FORCE ; propriétaire `migrator` +- Droits : cmd_hold_owner: SELECT ; migrator: DELETE, INSERT, REFERENCES, SELECT, TRIGGER, TRUNCATE, UPDATE + +| Colonne | Type | NOT NULL | Défaut | +| ------- | ---- | -------- | ------ | +| `id` | `uuid` | oui | `platform.uuid_v7()` | +| `hold_id` | `uuid` | oui | — | +| `country_code` | `text` | oui | — | +| `currency` | `text` | oui | — | +| `provider` | `text` | non | — | +| `mechanism` | `text` | oui | — | +| `triggers` | `text[]` | oui | — | +| `params_snapshot` | `jsonb` | oui | — | +| `amount_minor` | `bigint` | oui | — | +| `h_required_hours` | `integer` | non | — | +| `v_hours_snapshot` | `integer` | non | — | +| `auth_at` | `timestamp with time zone` | non | — | +| `auth_expiry_at` | `timestamp with time zone` | non | — | +| `auth_provider_reference` | `text` | non | — | +| `release_at` | `timestamp with time zone` | non | — | +| `decision_at` | `timestamp with time zone` | non | — | +| `reauth_due_at` | `timestamp with time zone` | non | — | +| `reauth_seq` | `integer` | oui | `0` | +| `status` | `text` | non | — | +| `decided_at` | `timestamp with time zone` | oui | `platform.now()` | +| `created_at` | `timestamp with time zone` | oui | `platform.now()` | +| `updated_at` | `timestamp with time zone` | oui | `platform.now()` | +| `row_version` | `integer` | oui | `0` | + +(section provisoire : recopiée de la sortie du job « base de données » au premier passage de la CI) + ### `core.payment_payment_command` - RLS : ENABLE + FORCE ; propriétaire `migrator` diff --git a/docs/ops/GO_LIVE_CHECKLIST.md b/docs/ops/GO_LIVE_CHECKLIST.md index 43bfa6e76..3e5f7d611 100644 --- a/docs/ops/GO_LIVE_CHECKLIST.md +++ b/docs/ops/GO_LIVE_CHECKLIST.md @@ -69,6 +69,7 @@ | GL-40 | **Créance de la règle 3 bis et hôte défaillant** (US-224 partie 224e, ADR-163). **Existe** (bêta, sur `FAKE`) : la créance de l'hôte née d'une avance de Kmino (`RELEASED_LEG_ADVANCE`) est écrite au `host_ledger` au report du remboursement ; l'ops annule en une action les trips à venir d'un hôte restreint (`CANCEL_HOST_TRIPS`, motif `HOST_ACCOUNT_CLOSED`, remboursement intégral). **Manque avant l'ouverture d'un pays** : recouvrement de la créance (GL-33) ; bouton de la fiche 360° de l'hôte et ses textes ; proposition de véhicules similaires au voyageur ; sanctions de l'hôte défaillant (BR-HP-05) décidées | annulation des trips d'un hôte restreint en préproduction, chaque voyageur remboursé du total payé ; créance d'une avance visible de FINANCE au solde de l'hôte ; preuves `l0-us224e-host-receivable`, `l0-us224e-defaulted-host` | US-709, console, fondateur (sanctions) | | GL-43 | **Remboursement réparti sur les moyens d'origine et choix d'un autre rail** (US-224 partie 224f, ADR-166). **Existe** (bêta, sur `FAKE`) : un trip encaissé en plusieurs fois est remboursé par moyen (08 E2, jambes en cascade, TJ16), jamais au-delà du payé d'un moyen ; un rejet confirmé met le remboursement en attente d'un autre rail (`PENDING_CUSTOMER_CHOICE`, `attempt_no` + 1). **Manque avant l'ouverture d'un pays** : choix du rail par le voyageur sur S10 et virement vers un compte vérifié à son nom (OQ-BR-12) ; relances et sort des sommes non réclamées (OQ-BR-44) ; refus d'un encaissement par crédit tant que les crédits n'existent pas ; crédit cash recréé (TJ16d) seulement après l'ouverture de `funds_holding_enabled` par décision écrite du fondateur | trip payé par deux cartes annulé en préproduction : deux remboursements aux jambes de l'oracle ; refus du PSP ⇒ attente d'un autre rail visible de FINANCE ; preuves `l0-us224f-multi-tender`, `trip-cancellation.test.ts` | US-224 (suite), lot C, fondateur (`funds_holding_enabled`) | | GL-41 | **Caution « comme Turo » prête avant l'ouverture d'un pays** (US-225, ADR-108, ADR-164 ; 08 BR-PAY-06). **Existe** (bêta, fonctions pures et FAKE) : aucune caution par défaut (graine 0142 : `deposit_always_required` faux, `deposit_trigger_classes` = {LUXE}, aucune classe pour l'âge, `risk_control_deployed` faux) ; décision du checkout avant le paiement (`PARAM_MISSING`, `DEPOSIT_RAIL_UNAVAILABLE` avec les jours possibles) ; rail choisi par configuration ; « débit puis remboursement » fermé par `funds_holding_enabled`. **À faire** : (1) `deposit_amount[pays][LUXE]` fixé et `deposit_trigger_classes` confirmé par le fondateur (sinon tout trip LUXE est refusé avant le paiement) ; (2) `provider_max_hold_h`, `MAX_HOLD_HOURS`, `SUPPORTS_PREAUTH`, `SUPPORTS_VOID`, `SUPPORTS_PARTIAL_CAPTURE`, `deposit_safety_h` validés en bac à sable (OQ-PAY-02 ; `SUPPORTS_REAUTH` OQ-PAY-17) ; (3) `deposit_hold`, écriture au checkout, minuteries de ré-autorisation et de décision, écran S05 (US-701, US-702) ; (4) pose à `auth_at` sans le voyageur validée avec le PSP | `l0-us225-deposit-rails.test.ts` et `deposit-rail-config.int.test.ts` verts au SHA déployé ; valeurs relues dans `core.config_param_value` et `core.payment_psp_capability` | fondateur (montants), US-701, US-702, lot C (PSP) | | +| GL-46 | **Caution figée au checkout et ré-autorisation branchées** (US-701, ADR-169 ; 08 BR-PAY-06). **Existe** (bêta, sur `FAKE`) : décision de la caution figée une fois par réservation avant le paiement (`deposit_hold`, migration 0143), revérifiée par la base (montant du pays et de la classe, aucune « sans caution » sur une classe déclencheur, « débit puis remboursement » fermé par `funds_holding_enabled`) ; S05 affiche la caution ou le refus avant tout paiement ; minuterie `deposit_timer` (ré-autorisation, refus signalé à l'ops sans débit). **À faire** : (1) pose à `auth_at` par le connecteur réel (S-1, lot C) et décision de libération (US-702) ; (2) âge des conducteurs et signal de risque lus au checkout (S-10) ; (3) fiche et cartes de recherche sur `deposit_amount` (T70 c, N-89) ; (4) console ops des déclencheurs ; (5) GL-41 levé (montant LUXE, capacités du PSP) | `l0-us701-deposit-hold.test.ts`, `deposit-checkout.test.ts`, `deposit-timer.fake.test.ts`, `checkout-deposit.contract.test.ts` et l'e2e S05 (US-701) verts au SHA fusionné | US-702, lot C (PSP), fondateur (montants) | | | # | Condition | Preuve exigée | Porteur | Coché (date, preuve) | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------- | | GL-01 | **EXC-003 fermée** (F-RLS-03, au registre RT-RLS-03, `core.iam_cmd_open_session` ne laisse plus `app_api` choisir l'acteur) | PR fusionnée de la story **US-410** (BOARD, « Suites de la porte du lot 0 ») ; run CI vert sur `main` où **RT-RLS-18 est inversé** (`packages/db/test/l0/redteam-rls/rt-rls-actors.test.ts`, « RT-RLS-18 » exige le refus) ; EXC-003 passée à FERMÉE dans `docs/team/DECISIONS.md` §3 et RT-RLS-03 dans `docs/team/RISKS.md` | US-410 (lot 4, US-003) | | diff --git a/docs/team/COMME_TURO.md b/docs/team/COMME_TURO.md index f7806140c..6742447cc 100644 --- a/docs/team/COMME_TURO.md +++ b/docs/team/COMME_TURO.md @@ -216,3 +216,5 @@ Règles : | 2026-11-18 | US-212 | Comment se règle un désaccord entre l'hôte et le voyageur ? | les parties échangent d'abord par la messagerie ; à défaut, le support examine le cas avec les deux parties et tranche (médiation) ; les recours légaux restent ouverts | aide publique de Turo (litiges entre hôte et voyageur) ; 16 LEG-015 | messagerie, support avec le numéro du trip et médiation, puis protection du consommateur ou tribunaux du lieu du trip ; aucune clause « definitiva e inapelable » ni arbitrage obligatoire (OQ-BR-24) | PROPOSÉ | | 2026-11-18 | US-225 | Si la durée du trip dépasse la validité d'une pré-autorisation, que fait-on de la caution ? | la caution n'existe que pour certains trips ; elle est affichée au checkout avant la réservation, puis rendue automatiquement après le trip ; les frais constatés ensuite sont débités sur la carte enregistrée | 08 BR-PAY-06 (pages d'aide de Turo sur les cautions, relues pour ADR-108) ; 10b UX-24 | aucune caution sans déclencheur : un trip sans caution n'est jamais refusé pour sa durée ; avec caution, ré-autorisation si le PSP la valide, sinon « débit puis remboursement » seulement si la détention de fonds est ouverte, sinon refus **avant le paiement** avec le nombre de jours possibles ; jamais de fonds bloqués faute de rail (ADR-164) | PROPOSÉ | | 2026-11-18 | US-225 | À la libération, comment prend-on les frais annexes sur la caution ? | la caution est rendue automatiquement ; les frais après le trip passent par la carte enregistrée | 08 BR-PAY-06 « Libération à heure fixe », E3 ; T57, T58 | frais prouvés, non contestés et notifiés au moins 48 h avant la décision capturés sur la caution (dans sa limite) puis le reste libéré ; sans capture partielle : caution entièrement libérée puis débit séparé ; « débit puis remboursement » : remboursement total puis débit séparé des frais (aucune retenue sur des fonds détenus) (ADR-164) | PROPOSÉ | +| 2026-11-18 | US-701 | Que voit le voyageur de la caution avant de payer, et que fait-on si elle est impossible pour ses dates ? | la caution est affichée au checkout avant la réservation (montant, rendue automatiquement après le trip) ; sinon aucune caution | 08 BR-PAY-06 (« Moment de l'évaluation », pages d'aide de Turo relues pour ADR-108) ; 10b UX-24 | la page de paiement dit « aucune caution », ou le montant, le blocage temporaire et la date de libération au plus tard ; caution impossible : message avec les jours possibles, aucun bouton « Payer », lien vers la recherche ; la décision est figée une fois par réservation, jamais les déclencheurs montrés (ADR-169) | PROPOSÉ | +| 2026-11-18 | US-701 | Que fait-on si la ré-autorisation de la caution est refusée pendant le trip ? | (mécanisme non publié par Turo) la caution est rendue à heure fixe et les frais passent par la carte enregistrée | 08 BR-PAY-06 « Mécanisme » ; 19 US-225 critère 3 | aucun débit de remplacement : la décision de libération est avancée avant l'expiration de l'autorisation en cours (2 h de marge) et le trip est signalé à l'ops ; les frais constatés plus tard passent par la carte enregistrée (ADR-169) | PROPOSÉ | diff --git a/docs/team/handoffs/US-701.md b/docs/team/handoffs/US-701.md new file mode 100644 index 000000000..c03e21230 --- /dev/null +++ b/docs/team/handoffs/US-701.md @@ -0,0 +1,44 @@ +# Passation US-701 — Caution de la plateforme et fenêtre de rétention + +- **Branche** : `story/US-701-caution-plateforme` ; agent de story argent, claude-opus-5-5 ; ADR-169 (PROPOSÉ). +- **Numéros pris** : migration `0143_payment_deposit_hold` (suivante de `main` au moment de pousser ; à renuméroter à chaque fusion de `main`), fixture `9945_test_us701_deposit_hold_fixtures.sql`, catalogue **v83**, ADR-169, GL-46. + +## Livré + +1. **`core.payment_deposit_hold`** (0143) : une décision par hold, figée avant le paiement ; `NOT_REQUIRED` ⇔ aucun déclencheur ⇔ montant 0 ; `REFUSED` jamais écrit (un checkout refusé n'écrit aucune ligne) ; `triggers` / `params_snapshot` [C2] ; garde et transitions ; aucun droit applicatif direct. Commandes de cmd_hold_owner : lecture du voyageur (sans [C2]), écriture unique revérifiée (montant = `deposit_amount[pays][classe]`, aucune `NOT_REQUIRED` sur une classe déclencheur ou inconnue, rail (b) fermé par `funds_holding_enabled`), file et transitions de la minuterie (`payment_command`). +2. **Checkout** (AVL) : `GET …/payment` rend `payment.deposit` ; `POST …/payment` applique la porte avant T1 (409 `DEPOSIT_RAIL_UNAVAILABLE` / `DEPOSIT_PARAM_MISSING`, aucune écriture ni ordre) ; OpenAPI (`CheckoutDeposit`, codes 409). +3. **S05** : aucune caution / montant, blocage temporaire, libération au plus tard / refus (`assertive`) avec les jours possibles et une sortie vers la recherche ; aucun « Pagar » si la caution est impossible. Textes `web.deposit.none`, `common.payment.depositUnavailable` (es, en, fr, pt-BR). +4. **Minuterie** `deposit_timer` (PAY, 60 s) : ré-autorisation par le port ; refusée ⇒ décision avancée à expiration − 2 h, alerte `DEPOSIT_REAUTH_FAILED`, aucun débit ; en cours ou inconnue ⇒ rien, même clé ensuite. +5. **Fonctions pures** : `evaluateDepositCheckout`, `planDepositSchedule` (T57 : décision à fin + 70 h), `depositScheduleAfterReauth`. + +## Critères de 19 (US-701) + +| Critère | Preuve | +| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| T57 : décision à fin + 70 h, capture 12,00 / VOID 288,00, réclamation sans effet | échéancier : `deposit-checkout.test.ts` (fin + 70 h, USD et PYG) ; capture / VOID : `deposit-rails.test.ts` et FAKE d'US-225. **Exécution à l'heure de décision : US-702** | +| Frais annexes capturés sur la caution : jambes BR-PAY-06, somme contrôlée | `planDepositDecision` d'US-225 (inchangé) ; branchement : US-702 | +| `H_requise ≤ V` ⇒ pré-autorisation unique à `auth_at`, sinon rails | `deposit-checkout.test.ts` (T57, T59 rail a), ligne figée ; **pose à `auth_at` : S-1 (lot C)** | +| T69–T73 au checkout ; montant unique ; `deposit_hold` fige mécanisme, déclencheurs, instantané ; ops seulement | `deposit-checkout.test.ts`, `l0-us701-deposit-hold.test.ts`, contrat (aucun [C2]) ; lecture ops : suite | +| T70 c : fiche, seuls `COUNTRY` et `CLASS` | **non fait** (suite N-89 / S-9) : la fiche lit encore `catalog_deposit_policy` (vide en production ⇒ mention générique) | + +## Suites d'US-225 + +S-2 **fait** (table, checkout, S05, minuterie de ré-autorisation ; minuterie de décision : US-702) ; S-6 **fait** (clés 08 E4, rien n'était persisté) ; S-7 **fait** ; S-8 **fait** ; `reauthorize` **aligné** (`REAUTH_PENDING`). + +## Tests existants modifiés (justification) + +- `pay/testing/deposit-rails.fake.test.ts` : référence de caution complétée (`tripId`, `segmentId`, `tenderId`) pour la clé 08 E4 ; aucun attendu changé. +- `avl/testing/checkout-payment.contract.test.ts` : porte de caution imposée « aucune caution » (`FakeDepositGate`) ; réponses d'US-223 inchangées. +- `web/account/checkout-payment.test.ts` : champ `deposit: null` ajouté aux deux vues attendues. +- `worker-tasks.test.ts` : tâche `deposit_timer` ajoutée aux listes. Aucun test de sécurité modifié. + +## Décisions PROPOSÉ + +COMME_TURO (deux lignes US-701) ; ADR-169 : décision par hold (trip par `converted_trip_id`), `REFUSED` jamais écrit, vue `HOLD` / `CHARGE`, décision au-delà de l'expiration admise seulement si une ré-autorisation est planifiée, `DEPOSIT_CHARGE` / `DEPOSIT_REAUTH` dans 08 E4. Aucun montant nouveau (LUXE toujours À DÉCIDER, POUR_LE_FONDATEUR §3). + +## Suites (pour l'orchestrateur) + +- **S-9** fiche et cartes de recherche : `deposit_amount` et déclencheurs `COUNTRY` / `CLASS` (T70 c, N-89) au lieu de `catalog_deposit_policy`. +- **S-10** âge des conducteurs (document vérifié) et signal de risque (US-209) passés à la porte ; aujourd'hui inconnus ⇒ fail-closed (sans effet au PA et au PY : classes d'âge vides, contrôle non déployé). +- **S-11** console ops : lecture des déclencheurs et de l'instantané (O01) ; S-12 report dans 17 §3.2.7 et 08 E4 (PR de `docs/specs/`). +- US-702 : minuterie de décision (`decision_at`), transitions finales, avis au voyageur. diff --git a/packages/db/README.md b/packages/db/README.md index 3cac6f8c8..113844956 100644 --- a/packages/db/README.md +++ b/packages/db/README.md @@ -1037,3 +1037,12 @@ Migration générée `0142_config_deposit_rail_params` (groupe `deposit_always_r - **Valeurs PROPOSÉES**, identiques au PA et au PY, `fail_mode` BLOCK, portée pays : `deposit_always_required` faux, `deposit_trigger_classes` `["LUXE"]` (à confirmer par le fondateur), `deposit_young_driver_age` 30, `deposit_young_driver_classes` `[]` (DEC-FONDATEUR-21), `deposit_on_risk_flag` vrai, `risk_control_deployed` faux, `deposit_reauth_lead_h` 24, `deposit_fee_notice_h` 48. `deposit_amount`, `deposit_charge_cap` et `provider_max_hold_h` restent sans valeur (absent : caution exigée refusée, rail « débit puis remboursement » interdit, aucune pré-autorisation). Aucun interrupteur touché ; aucun droit nouveau. - **Lecture** : `PgDepositRailConfigReader` (module PAY) sous `app_api` ou `app_worker` : `core.config_param_value`, `core.config_go_live('funds_holding_enabled', pays)`, `core.payment_psp_capability`. - **Preuves** : `test/l0/l0-us225-deposit-rails.test.ts` (PA USD, PY PYG ; `app_api`, `app_worker`, `app_anon`) ; `apps/api/src/modules/pay/testing/deposit-rail-config.int.test.ts` (décision du checkout sur la configuration réelle, sous `app_api`). + +## Caution figée au checkout (US-701 ; 08 BR-PAY-06 ; ADR-169) + +Migration `0143_payment_deposit_hold`, fixture `9945_test_us701_deposit_hold_fixtures.sql` (`test_fixture.us701_converted_deposit` : caution autorisée d'un hold converti, transaction annulée, EXECUTE `app_worker`). + +- **Table** `core.payment_deposit_hold` : une décision par hold (`hold_id` unique ; trip par `converted_trip_id`) ; `NOT_REQUIRED` ⇔ aucun déclencheur ⇔ montant 0, sans état ni échéance ; `REFUSED` jamais écrit ; `triggers` et `params_snapshot` [C2] ; garde de la décision et des transitions (`deposit_hold_guarded`), aucune suppression ; décision jamais après la libération ni après l'expiration (sauf ré-autorisation planifiée avant elle) ; RLS ENABLE + FORCE, **aucun droit** d'`app_api`, `app_worker`, `app_anon`. +- **Fonctions** (cmd_hold_owner, RLS-15) : `payment_deposit_checkout(jeton, hold)` et `payment_cmd_record_deposit_decision(jeton, hold, décision)` (EXECUTE `app_api`, voyageur de la session, hold d'un autre ⇒ `HOLD_NOT_FOUND`) ; `payment_deposit_reauth_due(lot)` et `payment_cmd_deposit_transition(…)` (EXECUTE `app_worker`, nom `payment_command`). Revérifications de l'écriture : `deposit_decision_mismatch` (montant ≠ `deposit_amount[pays][classe]`, `NOT_REQUIRED` sur un pays ou une classe déclencheurs, classe inconnue), `deposit_rail_closed` (`CHARGE_THEN_REFUND` tant que `funds_holding_enabled` = faux). +- **Droits ajoutés** à cmd_hold_owner : politiques de lecture `cmd_hold_deposit_read` de `config_param_value` (`deposit_always_required`, `deposit_trigger_classes`, `deposit_amount`, `funds_holding_enabled`) et de `config_param_definition` (`funds_holding_enabled`) ; `SELECT (conversion_operation_id)` de `booking_checkout_hold`. +- **Preuves** : `test/l0/l0-us701-deposit-hold.test.ts` (PA USD, PY PYG ; `app_api`, `app_worker`). diff --git a/packages/db/authorization-matrix.json b/packages/db/authorization-matrix.json index 8fb72ebbc..fc29aabf4 100644 --- a/packages/db/authorization-matrix.json +++ b/packages/db/authorization-matrix.json @@ -1710,6 +1710,19 @@ "bus_monitor": "tout" } }, + "core.payment_deposit_hold": { + "type": "table", + "droits": { + "app_api": {}, + "app_worker": {}, + "app_anon": {} + }, + "politiques": { + "app_api": [], + "app_worker": [], + "app_anon": [] + } + }, "core.payment_payment_command": { "type": "table", "droits": { diff --git a/packages/db/migrations/0143_payment_deposit_hold.sql b/packages/db/migrations/0143_payment_deposit_hold.sql new file mode 100644 index 000000000..58c4705e3 --- /dev/null +++ b/packages/db/migrations/0143_payment_deposit_hold.sql @@ -0,0 +1,562 @@ +-- 0143 — PAY : caution de la plateforme figée au checkout (`deposit_hold`), vue du voyageur sans +-- champ [C2], minuterie de ré-autorisation. +-- US-701 ; 19 US-701 (critères 3 et 4), US-225 (critère 3 : ré-autorisation avant l'échéance, +-- refusée ⇒ ops, sans débit) ; 16 PAY-011, PAY-036 ; 08 BR-PAY-06 (« Moment de l'évaluation », +-- « Fail-closed », « Montant unique », « Libération à heure fixe », « Mécanisme »), E4 ; +-- 17 v6 §3.2.7 (`deposit_hold`), §0.1 ; ADR-164 (rails, US-225), ADR-169 (cette migration). +-- Suites d'US-225 fermées : S-2 (table, branchement au checkout, minuterie de ré-autorisation), +-- S-7 (vue du voyageur sans `triggers` ni `params_snapshot`). Appliquée sous `migrator`. +-- +-- Cette migration : +-- 1. `core.payment_deposit_hold` : UNE décision par hold de checkout (le trip n'existe pas encore +-- au checkout : il est retrouvé par `booking_checkout_hold.converted_trip_id`, écart PROPOSÉ à +-- 17 §3.2.7 `trip_id`, ADR-169) ; mécanisme (`NOT_REQUIRED` ou un rail ; un checkout refusé +-- n'écrit AUCUNE ligne, 08), déclencheurs et instantané des paramètres [C2], montant en unités +-- mineures, `H_requise`, `V`, échéancier (`auth_at`, `release_at`, `decision_at`, +-- `reauth_due_at`), état de 16 PAY-011 ; identité figée, transitions gardées, aucune +-- suppression ; RLS ENABLE + FORCE, AUCUN droit direct d'app_api ni d'app_worker (lecture et +-- écriture par les seules fonctions ci-dessous) ; +-- 2. `core.payment_deposit_checkout(jeton, hold)` (app_api) : contexte du hold du voyageur de la +-- session (pays, devise et période du devis ENGAGÉ, classe du véhicule, compte marchand du +-- pays, `platform.now()`) ou décision figée réduite à ce que le voyageur peut lire (mécanisme, +-- montant, devise, libération) ; +-- 3. `core.payment_cmd_record_deposit_decision(jeton, hold, décision)` (app_api) : écriture +-- unique, revérifie ce que la base sait (fail-closed) : devise du devis, montant = +-- `deposit_amount[pays][classe]`, aucun `NOT_REQUIRED` sur un pays ou une classe déclencheurs +-- (paramètre absent ⇒ déclencheur vrai), rail « débit puis remboursement » refusé tant que +-- `funds_holding_enabled[pays]` = false (17 §0.1) ; une décision déjà figée n'est jamais +-- réécrite (`EXISTING`) ; +-- 4. `core.payment_deposit_reauth_due(lot)` et `core.payment_cmd_deposit_transition(…)` +-- (app_worker, nom `payment_command`) : file des ré-autorisations échues et transitions +-- `AUTHORIZED` (pose, lot C), `REAUTHORIZED`, `REAUTH_REFUSED` ; les transitions de décision +-- (capture, VOID, remboursement, expiration) appartiennent à US-702. +-- +-- Erreurs (SQLSTATE, contrainte) traduites par packages/db/src/errors.ts, sans DETAIL : +-- deposit_decision_mismatch (23514) → INVARIANT_VIOLATION ; deposit_rail_closed (55000) → +-- FORBIDDEN ; deposit_hold_guarded (55000) → INVARIANT_VIOLATION ; +-- deposit_hold_command_forbidden (42501) → FORBIDDEN ; deposit_hold_hold_unique (23505) → +-- INVARIANT_VIOLATION. +-- Issues rendues (texte, jamais une erreur) : AUTH_REQUIRED, HOLD_NOT_FOUND (hold d'un autre +-- voyageur : même réponse), QUOTE_UNAVAILABLE, HOLD_NOT_PAYABLE, RECORDED, EXISTING, APPLIED, STALE. +-- +-- Expand / contract : une table, six fonctions, deux déclencheurs et des politiques AJOUTÉS ; deux +-- droits de colonne et deux politiques de lecture de la configuration AJOUTÉS à cmd_hold_owner ; +-- rien de modifié ni de retiré. `catalog_deposit_policy.amount_minor` n'est pas touché (sa lecture +-- par la fiche est une suite, N-89). +-- +-- Retour arrière : +-- DROP FUNCTION core.payment_deposit_checkout(bytea, uuid), +-- core.payment_cmd_record_deposit_decision(bytea, uuid, jsonb), +-- core.payment_deposit_reauth_due(integer), +-- core.payment_cmd_deposit_transition(uuid, text, integer, timestamptz, timestamptz, +-- timestamptz, text), +-- core.payment_deposit_amount_param(text, text); +-- DROP TABLE core.payment_deposit_hold; DROP FUNCTION core.payment_deposit_hold_guard(); +-- DROP POLICY cmd_hold_deposit_read ON core.config_param_value; +-- DROP POLICY cmd_hold_deposit_read ON core.config_param_definition; +-- REVOKE SELECT (conversion_operation_id) ON core.booking_checkout_hold FROM cmd_hold_owner. + +-- 1. Table ---------------------------------------------------------------------------------------- +CREATE TABLE core.payment_deposit_hold ( + id uuid PRIMARY KEY DEFAULT platform.uuid_v7(), + hold_id uuid NOT NULL + CONSTRAINT deposit_hold_hold_fk REFERENCES core.booking_checkout_hold (id) + CONSTRAINT deposit_hold_hold_unique UNIQUE, + country_code text NOT NULL + CONSTRAINT deposit_hold_country_format CHECK (country_code ~ '^[A-Z]{2}$'), + currency text NOT NULL + CONSTRAINT deposit_hold_currency_format CHECK (currency ~ '^[A-Z]{3}$'), + -- fournisseur du compte marchand du pays à la décision (NULL : aucun ; aucune pose possible) + provider text + CONSTRAINT deposit_hold_provider_format CHECK (provider ~ '^[A-Z][A-Z0-9_]{1,31}$'), + -- REFUSED de 17 §3.2.7 jamais écrit : un checkout refusé n'écrit aucune ligne (08 BR-PAY-06) + mechanism text NOT NULL + CONSTRAINT deposit_hold_mechanism_valid CHECK (mechanism IN + ('NOT_REQUIRED', 'PREAUTH_SINGLE', 'REAUTH', 'CHARGE_THEN_REFUND')), + -- [C2] déclencheurs vrais (liste fermée), jamais lus par le voyageur ni l'hôte + triggers text[] NOT NULL + CONSTRAINT deposit_hold_triggers_valid CHECK ( + triggers <@ ARRAY['AGE', 'CLASS', 'COUNTRY', 'RISK']::text[] + AND pg_catalog.array_position(triggers, NULL) IS NULL), + -- [C2] valeurs des paramètres lues, âge ENTIER du plus jeune conducteur, risk_evaluated ; + -- aucune date de naissance ni autre donnée personnelle + params_snapshot jsonb NOT NULL + CONSTRAINT deposit_hold_snapshot_object CHECK (pg_catalog.jsonb_typeof(params_snapshot) = 'object'), + amount_minor bigint NOT NULL + CONSTRAINT deposit_hold_amount_nonnegative CHECK (amount_minor >= 0), + h_required_hours integer + CONSTRAINT deposit_hold_h_required_positive CHECK (h_required_hours > 0), + v_hours_snapshot integer + CONSTRAINT deposit_hold_v_nonnegative CHECK (v_hours_snapshot >= 0), + auth_at timestamptz, + auth_expiry_at timestamptz, + auth_provider_reference text + CONSTRAINT deposit_hold_provider_reference_format CHECK ( + auth_provider_reference ~ '^[A-Za-z0-9_.:-]{1,128}$'), + release_at timestamptz, + decision_at timestamptz, + reauth_due_at timestamptz, + -- rang de la dernière ré-autorisation tentée (clé 08 E4 `i{reauth_seq}`) + reauth_seq integer NOT NULL DEFAULT 0 + CONSTRAINT deposit_hold_reauth_seq_nonnegative CHECK (reauth_seq >= 0), + status text + CONSTRAINT deposit_hold_status_valid CHECK (status IN + ('PLANNED', 'AUTHORIZED', 'PARTIALLY_CAPTURED', 'VOIDED', 'REFUNDED', 'EXPIRED')), + decided_at timestamptz NOT NULL DEFAULT platform.now(), + created_at timestamptz NOT NULL DEFAULT platform.now(), + updated_at timestamptz NOT NULL DEFAULT platform.now(), + row_version integer NOT NULL DEFAULT 0, + -- 17 §3.2.7 : NOT_REQUIRED ⇔ triggers vide ⇔ montant 0, sans opération ni minuterie + CONSTRAINT deposit_hold_not_required_shape CHECK ( + (mechanism = 'NOT_REQUIRED') = (pg_catalog.cardinality(triggers) = 0) + AND (mechanism = 'NOT_REQUIRED') = (amount_minor = 0)), + CONSTRAINT deposit_hold_not_required_empty CHECK ( + mechanism <> 'NOT_REQUIRED' + OR (status IS NULL AND h_required_hours IS NULL AND v_hours_snapshot IS NULL + AND auth_at IS NULL AND auth_expiry_at IS NULL AND auth_provider_reference IS NULL + AND release_at IS NULL AND decision_at IS NULL AND reauth_due_at IS NULL + AND reauth_seq = 0)), + CONSTRAINT deposit_hold_required_shape CHECK ( + mechanism = 'NOT_REQUIRED' + OR (status IS NOT NULL AND h_required_hours IS NOT NULL AND v_hours_snapshot IS NOT NULL + AND auth_at IS NOT NULL AND release_at IS NOT NULL AND decision_at IS NOT NULL)), + -- jamais de décision après la libération ni après l'expiration de l'autorisation (08 BR-PAY-06) ; + -- rail (a) : une décision au-delà de l'expiration en cours n'est admise que tant qu'une + -- ré-autorisation est planifiée AVANT cette expiration (refusée : décision ramenée avant elle) + CONSTRAINT deposit_hold_decision_window CHECK ( + decision_at IS NULL + OR (decision_at <= release_at AND decision_at >= auth_at + AND (auth_expiry_at IS NULL OR decision_at <= auth_expiry_at + OR (mechanism = 'REAUTH' AND reauth_due_at IS NOT NULL)))), + -- minuterie de ré-autorisation : rail (a) seulement, avant l'expiration connue + CONSTRAINT deposit_hold_reauth_shape CHECK ( + reauth_due_at IS NULL + OR (mechanism = 'REAUTH' AND status IN ('PLANNED', 'AUTHORIZED') + AND (auth_expiry_at IS NULL OR reauth_due_at < auth_expiry_at))), + -- autorisation posée : référence du PSP ; expiration connue sauf débit (rail b) + CONSTRAINT deposit_hold_authorized_shape CHECK ( + status IS DISTINCT FROM 'AUTHORIZED' + OR (auth_provider_reference IS NOT NULL + AND (mechanism = 'CHARGE_THEN_REFUND' OR auth_expiry_at IS NOT NULL))) +); +CREATE INDEX deposit_hold_reauth_due_idx ON core.payment_deposit_hold (reauth_due_at) + WHERE reauth_due_at IS NOT NULL; +COMMENT ON TABLE core.payment_deposit_hold IS + 'PAY deposit_hold (17 §3.2.7) : décision de la caution figée au checkout, une par hold ; ' + 'triggers et params_snapshot [C2] (SYSTEM et ops seulement). US-701, ADR-169.'; + +-- Garde (tous rôles) : décision et identité figées ; NOT_REQUIRED jamais modifiée ; transitions de +-- 16 PAY-011 seulement (PLANNED → AUTHORIZED → AUTHORIZED | état final), un état final est figé. +CREATE FUNCTION core.payment_deposit_hold_guard() + RETURNS trigger + LANGUAGE plpgsql + SET search_path = pg_catalog, pg_temp +AS $fn$ +BEGIN + IF OLD.mechanism = 'NOT_REQUIRED' + OR NEW.id IS DISTINCT FROM OLD.id OR NEW.hold_id IS DISTINCT FROM OLD.hold_id + OR NEW.country_code IS DISTINCT FROM OLD.country_code + OR NEW.currency IS DISTINCT FROM OLD.currency OR NEW.provider IS DISTINCT FROM OLD.provider + OR NEW.mechanism IS DISTINCT FROM OLD.mechanism OR NEW.triggers IS DISTINCT FROM OLD.triggers + OR NEW.params_snapshot IS DISTINCT FROM OLD.params_snapshot + OR NEW.amount_minor IS DISTINCT FROM OLD.amount_minor + OR NEW.h_required_hours IS DISTINCT FROM OLD.h_required_hours + OR NEW.v_hours_snapshot IS DISTINCT FROM OLD.v_hours_snapshot + OR NEW.auth_at IS DISTINCT FROM OLD.auth_at OR NEW.release_at IS DISTINCT FROM OLD.release_at + OR NEW.decided_at IS DISTINCT FROM OLD.decided_at + OR NEW.created_at IS DISTINCT FROM OLD.created_at + OR NEW.reauth_seq < OLD.reauth_seq + OR (OLD.auth_provider_reference IS NOT NULL + AND NEW.auth_provider_reference IS DISTINCT FROM OLD.auth_provider_reference) + OR OLD.status IN ('PARTIALLY_CAPTURED', 'VOIDED', 'REFUNDED', 'EXPIRED') + OR (OLD.status = 'PLANNED' AND NEW.status NOT IN ('PLANNED', 'AUTHORIZED')) + OR (OLD.status = 'AUTHORIZED' AND NEW.status = 'PLANNED') THEN + RAISE EXCEPTION 'deposit_hold : décision figée ou transition refusée' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'deposit_hold_guarded'; + END IF; + RETURN NEW; +END +$fn$; +REVOKE ALL ON FUNCTION core.payment_deposit_hold_guard() FROM PUBLIC; + +CREATE TRIGGER deposit_hold_guard BEFORE UPDATE ON core.payment_deposit_hold + FOR EACH ROW EXECUTE FUNCTION core.payment_deposit_hold_guard(); +CREATE TRIGGER touch_row BEFORE UPDATE ON core.payment_deposit_hold + FOR EACH ROW EXECUTE FUNCTION platform.touch_row(); +CREATE TRIGGER money_no_delete BEFORE DELETE ON core.payment_deposit_hold + FOR EACH ROW EXECUTE FUNCTION core.settlement_no_delete(); +CREATE TRIGGER money_no_truncate BEFORE TRUNCATE ON core.payment_deposit_hold + FOR EACH STATEMENT EXECUTE FUNCTION core.settlement_no_delete(); + +ALTER TABLE core.payment_deposit_hold ENABLE ROW LEVEL SECURITY; +ALTER TABLE core.payment_deposit_hold FORCE ROW LEVEL SECURITY; +CREATE POLICY migrator_all ON core.payment_deposit_hold TO migrator USING (true) WITH CHECK (true); +REVOKE ALL ON core.payment_deposit_hold FROM PUBLIC; +-- aucun droit d'app_api, d'app_worker ni d'app_anon : lecture et écriture par les fonctions de +-- cmd_hold_owner ci-dessous ; lecture ops (triggers, params_snapshot) : suite (console O01) + +-- commandes (cmd_hold_owner) : écriture par le voyageur de la session (checkout), transitions par +-- le travailleur payment_command +GRANT SELECT ON core.payment_deposit_hold TO cmd_hold_owner; +GRANT INSERT (hold_id, country_code, currency, provider, mechanism, triggers, params_snapshot, + amount_minor, h_required_hours, v_hours_snapshot, auth_at, release_at, decision_at, + reauth_due_at, status) + ON core.payment_deposit_hold TO cmd_hold_owner; +GRANT UPDATE (status, auth_expiry_at, auth_provider_reference, decision_at, reauth_due_at, + reauth_seq) + ON core.payment_deposit_hold TO cmd_hold_owner; +CREATE POLICY cmd_hold_sel ON core.payment_deposit_hold FOR SELECT TO cmd_hold_owner USING (true); +CREATE POLICY cmd_hold_ins ON core.payment_deposit_hold FOR INSERT TO cmd_hold_owner + WITH CHECK (app.actor_kind() = 'GUEST' AND (status IS NULL OR status = 'PLANNED') + AND reauth_seq = 0 AND auth_expiry_at IS NULL AND auth_provider_reference IS NULL); +CREATE POLICY cmd_hold_upd ON core.payment_deposit_hold FOR UPDATE TO cmd_hold_owner + USING (app.actor_kind() = 'WORKER' AND app.worker_name() = 'payment_command') + WITH CHECK (app.actor_kind() = 'WORKER' AND app.worker_name() = 'payment_command'); + +-- 2. Droits complémentaires de cmd_hold_owner (au plus juste) -------------------------------------- +-- paramètres de la caution revérifiés par la commande ; interrupteur funds_holding_enabled lu par +-- core.config_go_live (politiques ajoutées à côté des autres : permissives, OU) +CREATE POLICY cmd_hold_deposit_read ON core.config_param_value FOR SELECT TO cmd_hold_owner + USING (key IN ('deposit_always_required', 'deposit_trigger_classes', 'deposit_amount', + 'funds_holding_enabled')); +CREATE POLICY cmd_hold_deposit_read ON core.config_param_definition FOR SELECT TO cmd_hold_owner + USING (key = 'funds_holding_enabled'); +-- moyen de paiement du trip (opération de loyer convertie) : `tender_id` de la clé 08 E4 +GRANT SELECT (conversion_operation_id) ON core.booking_checkout_hold TO cmd_hold_owner; + +-- 3. Fonctions (cmd_hold_owner, liste blanche RLS-15) ------------------------------------------- +GRANT CREATE ON SCHEMA core TO cmd_hold_owner; +SET LOCAL ROLE cmd_hold_owner; + +-- Valeur en vigueur d'un paramètre de pays (portée COUNTRY) ; NULL : absent. SECURITY INVOKER : +-- appelée par les commandes ci-dessous sous cmd_hold_owner (politique cmd_hold_deposit_read). +CREATE FUNCTION core.payment_deposit_amount_param(p_key text, p_country text) + RETURNS jsonb + LANGUAGE sql + STABLE + SET search_path = pg_catalog, pg_temp +AS $fn$ + WITH t AS (SELECT platform.now() AS ts) + SELECT v.value + FROM core.config_param_value AS v CROSS JOIN t + WHERE v.key = p_key AND v.country_code::text = p_country AND v.scope_type = 'COUNTRY' + AND v.valid_from <= t.ts AND (v.valid_to IS NULL OR v.valid_to > t.ts) + ORDER BY v.valid_from DESC + LIMIT 1 +$fn$; +REVOKE ALL ON FUNCTION core.payment_deposit_amount_param(text, text) FROM PUBLIC; + +-- Contexte de la caution du hold du checkout du voyageur de la session ; décision figée réduite à +-- ce que le voyageur peut lire (jamais triggers ni params_snapshot). Hold d'un autre voyageur ou +-- sans checkout : HOLD_NOT_FOUND (IDOR, 17 §2.3). +CREATE FUNCTION core.payment_deposit_checkout(p_token_hash bytea, p_hold_id uuid) + RETURNS TABLE (outcome text, + country_code text, + currency text, + value_class text, + scheduled_start timestamptz, + scheduled_end timestamptz, + provider text, + now timestamptz, + mechanism text, + amount_minor bigint, + release_at timestamptz) + LANGUAGE plpgsql + STABLE + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +#variable_conflict use_column +DECLARE + v_user uuid; + v_hold record; + v_dep record; + v_t record; +BEGIN + SELECT s.user_id INTO v_user FROM core.iam_session_resolve(p_token_hash) AS s; + IF v_user IS NULL THEN + outcome := 'AUTH_REQUIRED'; + RETURN NEXT; + RETURN; + END IF; + SELECT h.id, h.country_code, h.vehicle_id INTO v_hold + FROM core.booking_checkout_hold AS h + JOIN core.booking_checkout_acceptance AS a ON a.hold_id = h.id + WHERE h.id = p_hold_id AND h.guest_user_id = v_user AND a.guest_user_id = v_user; + IF v_hold.id IS NULL THEN + outcome := 'HOLD_NOT_FOUND'; + RETURN NEXT; + RETURN; + END IF; + now := platform.now(); + country_code := v_hold.country_code; + SELECT d.mechanism, d.amount_minor, d.currency, d.release_at INTO v_dep + FROM core.payment_deposit_hold AS d WHERE d.hold_id = v_hold.id; + IF v_dep.mechanism IS NOT NULL THEN + outcome := 'DONE'; + mechanism := v_dep.mechanism; + amount_minor := v_dep.amount_minor; + currency := v_dep.currency; + release_at := v_dep.release_at; + RETURN NEXT; + RETURN; + END IF; + SELECT * INTO v_t FROM core.booking_checkout_capture_terms(v_hold.id); + IF v_t.currency IS NULL THEN + outcome := 'QUOTE_UNAVAILABLE'; + RETURN NEXT; + RETURN; + END IF; + outcome := 'DONE'; + currency := v_t.currency; + scheduled_start := v_t.scheduled_start; + scheduled_end := v_t.scheduled_end; + SELECT v.value_class INTO value_class FROM core.catalog_vehicle AS v WHERE v.id = v_hold.vehicle_id; + -- compte marchand de Kmino du pays : même choix que T1 (0116) + SELECT a.provider INTO provider + FROM core.payment_psp_account AS a + WHERE a.country_code = v_hold.country_code AND a.status = 'ACTIVE' + AND (a.environment = 'LIVE' + OR COALESCE(platform.deployment_env(), 'production') IN ('test', 'development', 'staging')) + ORDER BY (a.environment = 'LIVE') DESC, a.provider, a.id + LIMIT 1; + RETURN NEXT; +END +$fn$; +COMMENT ON FUNCTION core.payment_deposit_checkout(bytea, uuid) IS + 'Caution du hold du checkout du voyageur de la session : contexte de la décision, ou décision ' + 'figée sans champ [C2] (S-7). SECURITY DEFINER, EXECUTE app_api. US-701 (ADR-169).'; + +-- Écriture unique de la décision (avant T1). Revérifie ce que la base sait ; une incohérence est une +-- panne du programme (exception), jamais un succès. +CREATE FUNCTION core.payment_cmd_record_deposit_decision(p_token_hash bytea, p_hold_id uuid, + p_decision jsonb) + RETURNS text + LANGUAGE plpgsql + VOLATILE + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_user uuid; + v_hold record; + v_t record; + v_class text; + v_mech text := p_decision ->> 'mechanism'; + v_triggers text[]; + v_amount bigint; + v_always jsonb; + v_classes jsonb; + v_amounts jsonb; + v_prev_kind text; + v_prev_actor text; + v_locked boolean; +BEGIN + SELECT s.user_id INTO v_user FROM core.iam_session_resolve(p_token_hash) AS s; + IF v_user IS NULL THEN + RETURN 'AUTH_REQUIRED'; + END IF; + SELECT h.id, h.country_code, h.vehicle_id, h.status INTO v_hold + FROM core.booking_checkout_hold AS h + JOIN core.booking_checkout_acceptance AS a ON a.hold_id = h.id + WHERE h.id = p_hold_id AND h.guest_user_id = v_user AND a.guest_user_id = v_user; + IF v_hold.id IS NULL THEN + RETURN 'HOLD_NOT_FOUND'; + END IF; + IF EXISTS (SELECT 1 FROM core.payment_deposit_hold AS d WHERE d.hold_id = v_hold.id) THEN + RETURN 'EXISTING'; + END IF; + IF v_hold.status NOT IN ('ACTIVE', 'PAYMENT_IN_FLIGHT') THEN + RETURN 'HOLD_NOT_PAYABLE'; + END IF; + SELECT * INTO v_t FROM core.booking_checkout_capture_terms(v_hold.id); + IF v_t.currency IS NULL THEN + RETURN 'QUOTE_UNAVAILABLE'; + END IF; + SELECT v.value_class INTO v_class FROM core.catalog_vehicle AS v WHERE v.id = v_hold.vehicle_id; + IF pg_catalog.jsonb_typeof(p_decision -> 'triggers') IS DISTINCT FROM 'array' + OR (p_decision ->> 'amountMinor') !~ '^(0|[1-9][0-9]{0,17})$' THEN + RAISE EXCEPTION 'caution : décision illisible' + USING ERRCODE = 'check_violation', CONSTRAINT = 'deposit_decision_mismatch'; + END IF; + v_triggers := ARRAY(SELECT pg_catalog.jsonb_array_elements_text(p_decision -> 'triggers')); + v_amount := (p_decision ->> 'amountMinor')::bigint; + v_always := core.payment_deposit_amount_param('deposit_always_required', v_hold.country_code); + v_classes := core.payment_deposit_amount_param('deposit_trigger_classes', v_hold.country_code); + v_amounts := core.payment_deposit_amount_param('deposit_amount', v_hold.country_code); + IF v_mech = 'NOT_REQUIRED' THEN + -- fail-closed (08 BR-PAY-06) : paramètre absent ou illisible, classe inconnue ⇒ déclencheur vrai + IF v_always IS DISTINCT FROM 'false'::jsonb + OR pg_catalog.jsonb_typeof(v_classes) IS DISTINCT FROM 'array' + OR v_class IS NULL + OR v_classes ? v_class THEN + RAISE EXCEPTION 'caution : aucune caution refusée pour ce pays ou cette classe' + USING ERRCODE = 'check_violation', CONSTRAINT = 'deposit_decision_mismatch'; + END IF; + ELSE + -- montant unique (08 « Montant unique ») : deposit_amount[pays][classe], jamais inventé + IF v_class IS NULL OR pg_catalog.jsonb_typeof(v_amounts) IS DISTINCT FROM 'object' + OR (v_amounts ->> v_class) IS NULL + OR (v_amounts ->> v_class) !~ '^[1-9][0-9]{0,17}$' + OR (v_amounts ->> v_class)::bigint <> v_amount THEN + RAISE EXCEPTION 'caution : montant différent de deposit_amount' + USING ERRCODE = 'check_violation', CONSTRAINT = 'deposit_decision_mismatch'; + END IF; + -- aucun fonds de tiers détenu (17 §0.1) : rail (b) fermé tant que l'interrupteur est faux + IF v_mech = 'CHARGE_THEN_REFUND' + AND NOT core.config_go_live('funds_holding_enabled', v_hold.country_code) THEN + RAISE EXCEPTION 'caution : débit puis remboursement fermé (funds_holding_enabled)' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'deposit_rail_closed'; + END IF; + END IF; + -- contexte du voyageur (comme T1, 0116) le temps du verrou et de l'écriture, puis remis ; une + -- erreur annule l'instruction (et le contexte avec elle) + v_prev_kind := pg_catalog.current_setting('app.actor_kind', true); + v_prev_actor := pg_catalog.current_setting('app.actor_id', true); + PERFORM pg_catalog.set_config('app.actor_kind', 'GUEST', true); + PERFORM pg_catalog.set_config('app.actor_id', v_user::text, true); + -- verrou du hold (politique cmd_hold_upd : hold vivant du voyageur) : deux onglets ne figent + -- jamais deux décisions ; la décision est relue sous le verrou + PERFORM 1 FROM core.booking_checkout_hold AS h WHERE h.id = v_hold.id FOR UPDATE; + v_locked := FOUND; + IF NOT v_locked OR EXISTS (SELECT 1 FROM core.payment_deposit_hold AS d + WHERE d.hold_id = v_hold.id) THEN + PERFORM pg_catalog.set_config('app.actor_kind', COALESCE(v_prev_kind, ''), true); + PERFORM pg_catalog.set_config('app.actor_id', COALESCE(v_prev_actor, ''), true); + RETURN CASE WHEN v_locked THEN 'EXISTING' ELSE 'HOLD_NOT_PAYABLE' END; + END IF; + INSERT INTO core.payment_deposit_hold (hold_id, country_code, currency, provider, mechanism, + triggers, params_snapshot, amount_minor, + h_required_hours, v_hours_snapshot, auth_at, release_at, + decision_at, reauth_due_at, status) + VALUES (v_hold.id, v_hold.country_code, v_t.currency, NULLIF(p_decision ->> 'provider', ''), + v_mech, v_triggers, p_decision -> 'paramsSnapshot', v_amount, + (p_decision ->> 'hRequiredHours')::integer, (p_decision ->> 'vHours')::integer, + (p_decision ->> 'authAt')::timestamptz, (p_decision ->> 'releaseAt')::timestamptz, + (p_decision ->> 'decisionAt')::timestamptz, (p_decision ->> 'reauthDueAt')::timestamptz, + CASE WHEN v_mech = 'NOT_REQUIRED' THEN NULL ELSE 'PLANNED' END); + PERFORM pg_catalog.set_config('app.actor_kind', COALESCE(v_prev_kind, ''), true); + PERFORM pg_catalog.set_config('app.actor_id', COALESCE(v_prev_actor, ''), true); + RETURN 'RECORDED'; +END +$fn$; +COMMENT ON FUNCTION core.payment_cmd_record_deposit_decision(bytea, uuid, jsonb) IS + 'Décision de la caution du hold du checkout du voyageur de la session, figée une fois avant le ' + 'paiement ; montant, pays, classe et rail (b) revérifiés. SECURITY DEFINER, EXECUTE app_api. ' + 'US-701 (ADR-169).'; + +-- File des ré-autorisations échues (travailleur payment_command) : caution REAUTH autorisée, hold +-- converti en trip ; clé 08 E4 (trip, segment n° 1, moyen = opération de loyer convertie). +CREATE FUNCTION core.payment_deposit_reauth_due(p_limit integer) + RETURNS TABLE (deposit_id uuid, + trip_id uuid, + segment_id uuid, + tender_id uuid, + country_code text, + currency text, + provider text, + provider_reference text, + auth_expiry_at timestamptz, + release_at timestamptz, + reauth_seq integer, + now timestamptz) + LANGUAGE sql + STABLE + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ + WITH t AS (SELECT platform.now() AS ts) + SELECT d.id, h.converted_trip_id, s.id, h.conversion_operation_id, d.country_code, d.currency, + d.provider, d.auth_provider_reference, d.auth_expiry_at, d.release_at, d.reauth_seq, t.ts + FROM core.payment_deposit_hold AS d + CROSS JOIN t + JOIN core.booking_checkout_hold AS h ON h.id = d.hold_id AND h.status = 'CONVERTED' + JOIN core.booking_trip_segment AS s ON s.trip_id = h.converted_trip_id AND s.seq = 1 + WHERE app.actor_kind() = 'WORKER' AND app.worker_name() = 'payment_command' + AND d.mechanism = 'REAUTH' AND d.status = 'AUTHORIZED' + AND d.reauth_due_at IS NOT NULL AND d.reauth_due_at <= t.ts + AND d.provider IS NOT NULL AND d.auth_provider_reference IS NOT NULL + ORDER BY d.reauth_due_at, d.id + LIMIT GREATEST(LEAST(p_limit, 500), 0) +$fn$; +COMMENT ON FUNCTION core.payment_deposit_reauth_due(integer) IS + 'Cautions REAUTH autorisées dont la ré-autorisation est échue (platform.now()), sans champ [C2]. ' + 'SECURITY DEFINER, EXECUTE app_worker (payment_command). US-701 (ADR-169).'; + +-- Transitions de la pose et de la ré-autorisation (16 PAY-011 « États ») ; rang attendu : un +-- passage concurrent ou un rejeu tardif rend STALE sans rien écrire. +CREATE FUNCTION core.payment_cmd_deposit_transition(p_deposit_id uuid, p_event text, + p_expected_seq integer, + p_auth_expiry_at timestamptz, + p_decision_at timestamptz, + p_reauth_due_at timestamptz, + p_provider_reference text) + RETURNS text + LANGUAGE plpgsql + VOLATILE + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_d record; +BEGIN + IF app.actor_kind() IS DISTINCT FROM 'WORKER' + OR app.worker_name() IS DISTINCT FROM 'payment_command' THEN + RAISE EXCEPTION 'caution : transition réservée au travailleur payment_command' + USING ERRCODE = 'insufficient_privilege', CONSTRAINT = 'deposit_hold_command_forbidden'; + END IF; + SELECT d.id, d.mechanism, d.status, d.reauth_seq INTO v_d + FROM core.payment_deposit_hold AS d WHERE d.id = p_deposit_id FOR UPDATE; + IF v_d.id IS NULL OR v_d.reauth_seq IS DISTINCT FROM p_expected_seq THEN + RETURN 'STALE'; + END IF; + CASE p_event + WHEN 'AUTHORIZED' THEN + IF v_d.status IS DISTINCT FROM 'PLANNED' THEN + RETURN 'STALE'; + END IF; + UPDATE core.payment_deposit_hold + SET status = 'AUTHORIZED', auth_expiry_at = p_auth_expiry_at, + auth_provider_reference = p_provider_reference, decision_at = p_decision_at, + reauth_due_at = p_reauth_due_at + WHERE id = p_deposit_id; + WHEN 'REAUTHORIZED', 'REAUTH_REFUSED' THEN + IF v_d.status IS DISTINCT FROM 'AUTHORIZED' OR v_d.mechanism <> 'REAUTH' THEN + RETURN 'STALE'; + END IF; + -- refusée : aucune nouvelle ré-autorisation, expiration inchangée (aucun débit, 19 US-225) + UPDATE core.payment_deposit_hold + SET auth_expiry_at = CASE WHEN p_event = 'REAUTHORIZED' THEN p_auth_expiry_at + ELSE auth_expiry_at END, + decision_at = p_decision_at, + reauth_due_at = CASE WHEN p_event = 'REAUTHORIZED' THEN p_reauth_due_at END, + reauth_seq = reauth_seq + 1 + WHERE id = p_deposit_id; + ELSE + RAISE EXCEPTION 'caution : événement inconnu' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'deposit_hold_guarded'; + END CASE; + RETURN 'APPLIED'; +END +$fn$; +COMMENT ON FUNCTION core.payment_cmd_deposit_transition(uuid, text, integer, timestamptz, + timestamptz, timestamptz, text) IS + 'Transitions AUTHORIZED, REAUTHORIZED, REAUTH_REFUSED de deposit_hold (machine d''état gardée). ' + 'SECURITY DEFINER, EXECUTE app_worker (payment_command). US-701 (ADR-169).'; + +RESET ROLE; +REVOKE CREATE ON SCHEMA core FROM cmd_hold_owner; + +REVOKE ALL ON FUNCTION core.payment_deposit_checkout(bytea, uuid), + core.payment_cmd_record_deposit_decision(bytea, uuid, jsonb), + core.payment_deposit_reauth_due(integer), + core.payment_cmd_deposit_transition(uuid, text, integer, timestamptz, timestamptz, timestamptz, + text) + FROM PUBLIC; +GRANT EXECUTE ON FUNCTION core.payment_deposit_checkout(bytea, uuid), + core.payment_cmd_record_deposit_decision(bytea, uuid, jsonb) + TO app_api; +GRANT EXECUTE ON FUNCTION core.payment_deposit_reauth_due(integer), + core.payment_cmd_deposit_transition(uuid, text, integer, timestamptz, timestamptz, timestamptz, + text) + TO app_worker; diff --git a/packages/db/personal-data-inventory.json b/packages/db/personal-data-inventory.json index 898c5d181..231cd9568 100644 --- a/packages/db/personal-data-inventory.json +++ b/packages/db/personal-data-inventory.json @@ -1604,6 +1604,45 @@ "row_version": "C1" } }, + "core.payment_deposit_hold": { + "lifecycle": "B", + "export": "none", + "columns": { + "id": "C1", + "hold_id": "C1", + "country_code": "C1", + "currency": "C1", + "provider": "C1", + "mechanism": "C1", + "triggers": { + "class": "C2", + "erasure": "derogation", + "justification": "déclencheurs et instantané des paramètres de la décision de caution (08 BR-PAY-06, 17 §3.2.7), figés par la garde de la table comme preuve devant ACODECO / SEDECO : âge entier seulement, aucune date de naissance ni identifiant ; aucun droit d'app_api ni d'app_worker, lus par les fonctions de cmd_hold_owner sans ces colonnes ; effacement avec le trip", + "report": "US-536" + }, + "params_snapshot": { + "class": "C2", + "erasure": "derogation", + "justification": "déclencheurs et instantané des paramètres de la décision de caution (08 BR-PAY-06, 17 §3.2.7), figés par la garde de la table comme preuve devant ACODECO / SEDECO : âge entier seulement, aucune date de naissance ni identifiant ; aucun droit d'app_api ni d'app_worker, lus par les fonctions de cmd_hold_owner sans ces colonnes ; effacement avec le trip", + "report": "US-536" + }, + "amount_minor": "C1", + "h_required_hours": "C1", + "v_hours_snapshot": "C1", + "auth_at": "C1", + "auth_expiry_at": "C1", + "auth_provider_reference": "C1", + "release_at": "C1", + "decision_at": "C1", + "reauth_due_at": "C1", + "reauth_seq": "C1", + "status": "C1", + "decided_at": "C1", + "created_at": "C1", + "updated_at": "C1", + "row_version": "C1" + } + }, "core.payment_payment_command": { "lifecycle": "T", "export": "none", diff --git a/packages/db/security-definer-allowlist.json b/packages/db/security-definer-allowlist.json index b831d9140..831b357a2 100644 --- a/packages/db/security-definer-allowlist.json +++ b/packages/db/security-definer-allowlist.json @@ -2008,6 +2008,34 @@ "owner": "cmd_money_owner", "execute": ["app_worker"], "story": "US-224" + }, + { + "signature": "core.payment_deposit_checkout(bytea,uuid)", + "family": "cmd_hold", + "owner": "cmd_hold_owner", + "execute": ["app_api"], + "story": "US-701" + }, + { + "signature": "core.payment_cmd_record_deposit_decision(bytea,uuid,jsonb)", + "family": "cmd_hold", + "owner": "cmd_hold_owner", + "execute": ["app_api"], + "story": "US-701" + }, + { + "signature": "core.payment_deposit_reauth_due(integer)", + "family": "cmd_hold", + "owner": "cmd_hold_owner", + "execute": ["app_worker"], + "story": "US-701" + }, + { + "signature": "core.payment_cmd_deposit_transition(uuid,text,integer,timestamp with time zone,timestamp with time zone,timestamp with time zone,text)", + "family": "cmd_hold", + "owner": "cmd_hold_owner", + "execute": ["app_worker"], + "story": "US-701" } ] } diff --git a/packages/db/src/errors.ts b/packages/db/src/errors.ts index f8def9ae5..257b64428 100644 --- a/packages/db/src/errors.ts +++ b/packages/db/src/errors.ts @@ -391,6 +391,13 @@ export const CONSTRAINT_CODES: Readonly; + +const NOW = '2026-12-01T12:00:00.000Z'; +const START = '2026-12-10T15:00:00.000Z'; +const H = 3_600_000; + +/** Vecteurs du checkout d'US-223 (en-tête de l0-us223-checkout-payment) : devis de 3 jours. */ +const VECTORS: Readonly> = { + PA: { + daily: 4_000, + schedule: { tiers: [{ maxDays: null, rateBps: 0 }], minMinor: '0' }, + fee: 0, + taxes: { TRIP_PRICE: 840 }, + host: 9_000, + total: 15_840, + basicaPrice: '1/4', + protection: 3_000, + insurer: 2_100, + }, + PY: { + daily: 333_334, + schedule: null, + fee: 150_000, + taxes: { TRIP_PRICE: 100_000, TRIP_FEE: 15_000 }, + host: 750_001, + total: 1_415_002, + basicaPrice: '3/20', + protection: 150_000, + insurer: 105_000, + }, +}; + +/** 300,00 de T57 (valeur de test du mécanisme) à l'exposant de la devise : USD 30 000, PYG 300. */ +const DEPOSIT: Readonly> = { USD: 30_000n, PYG: 300n }; +const depositOf = (cc: CountryCase): bigint => { + const d = DEPOSIT[cc.currency]; + if (d === undefined) throw new Error(`devise sans vecteur : ${cc.currency}`); + return d; +}; + +const at = (iso: string, hours: number): string => + new Date(Date.parse(iso) + hours * H).toISOString(); + +function scenario(cc: CountryCase) { + return (fn: (tx: Tx, groups: Map) => Promise) => + withRole('app_api', (client) => + withTestTransaction(client, { virtualNow: NOW }, async (tx) => { + await openSwitch(tx, 'p2p_private_hosts_enabled', cc.country); + await openSwitch(tx, 'insurer_contract_active', cc.country); + const v = VECTORS[cc.country]!; + if (v.schedule !== null) { + await tx.query('SELECT test_fixture.us704_set_trip_fee_schedule($1, $2::jsonb)', [ + cc.country, + JSON.stringify(v.schedule), + ]); + } + await protectionParams(tx, cc.country, v); + await tx.query('SELECT test_fixture.us024_psp_account($1)', [cc.country]); + await fn(tx, await taxGroups(tx, cc)); + }), + ); +} + +async function guest(tx: Tx, cc: CountryCase): Promise { + const p = await checkoutPerson(tx, cc.country); + await approveDriver(tx, p, cc.country, { birth: '1990-01-01', licenseExpiry: '2030-12-31' }); + return p; +} + +/** Devis de 3 jours puis checkout (vraies commandes) ; classe du véhicule imposée. */ +async function book( + tx: Tx, + cc: CountryCase, + groups: Map, + p: Person, + valueClass: 'STANDARD' | 'LUXE' | null, +) { + const v = VECTORS[cc.country]!; + const l = await listedListing(tx, cc, v.daily); + // null : classe inconnue du catalogue (fail-closed : déclencheur CLASS vrai) + await tx.query('SELECT test_fixture.us108_set_value_class($1, $2)', [l.vehicleId, valueClass]); + const d = quoteDocs(cc, v, groups, Date.parse(START), Date.parse(NOW)); + const quoteId = await frozenQuote(tx, p, l.listingId, d); + const r = await checkoutQuote(tx, p, quoteId); + expect(r.outcome).toBe('DONE'); + return r.hold_id!; +} + +const read = async (tx: Tx, hash: Buffer, holdId: string): Promise => + (await tx.query('SELECT * FROM core.payment_deposit_checkout($1, $2)', [hash, holdId])) + .rows[0]!; + +const record = async (tx: Tx, hash: Buffer, holdId: string, decision: object): Promise => + ( + await tx.query<{ r: string }>( + 'SELECT core.payment_cmd_record_deposit_decision($1, $2, $3::jsonb) AS r', + [hash, holdId, JSON.stringify(decision)], + ) + ).rows[0]!.r; + +const notRequired = { + mechanism: 'NOT_REQUIRED', + triggers: [], + paramsSnapshot: { version: 1, riskEvaluated: false, youngestDriverAge: null }, + amountMinor: '0', + provider: 'FAKE', + hRequiredHours: null, + vHours: null, + authAt: null, + releaseAt: null, + decisionAt: null, + reauthDueAt: null, +}; + +/** T57 : pré-autorisation unique, auth_at = début − 24 h, libération fin + 72 h, décision fin + 70 h. */ +const preauth = (amount: bigint, mechanism = 'PREAUTH_SINGLE') => ({ + mechanism, + triggers: ['CLASS'], + paramsSnapshot: { version: 1, riskEvaluated: false, youngestDriverAge: null }, + amountMinor: amount.toString(), + provider: 'FAKE', + hRequiredHours: 168, + vHours: 168, + authAt: at(START, -24), + releaseAt: at(START, 72 + 72), + decisionAt: at(START, 72 + 70), + reauthDueAt: null, +}); + +const amountParam = (tx: Tx, cc: CountryCase, amount: bigint) => + tx.query("SELECT test_fixture.us225_param_version('deposit_amount', $1, $2::jsonb)", [ + cc.country, + JSON.stringify({ LUXE: amount.toString() }), + ]); + +describe.each(COUNTRIES)('US-701 — caution figée au checkout ($country, $currency)', (cc) => { + const run = scenario(cc); + + it('T70 : STANDARD ⇒ contexte lu (devise et période du devis engagé), NOT_REQUIRED figé une fois, vue sans champ [C2]', async () => { + await run(async (tx, groups) => { + const p = await guest(tx, cc); + const hold = await book(tx, cc, groups, p, 'STANDARD'); + const ctx = await read(tx, p.hash, hold); + expect(ctx).toMatchObject({ + outcome: 'DONE', + country_code: cc.country, + currency: cc.currency, + value_class: 'STANDARD', + provider: 'FAKE', + mechanism: null, + }); + expect((ctx['scheduled_start'] as Date).toISOString()).toBe(START); + expect((ctx['scheduled_end'] as Date).toISOString()).toBe(at(START, 72)); + expect((ctx['now'] as Date).toISOString()).toBe(NOW); + expect(await record(tx, p.hash, hold, notRequired)).toBe('RECORDED'); + expect(await record(tx, p.hash, hold, notRequired)).toBe('EXISTING'); + const after = await read(tx, p.hash, hold); + expect(after).toMatchObject({ + outcome: 'DONE', + mechanism: 'NOT_REQUIRED', + amount_minor: '0', + currency: cc.currency, + release_at: null, + }); + // S-7 : jamais les déclencheurs ni l'instantané des paramètres dans la lecture du voyageur + expect(Object.keys(after).sort()).toEqual([ + 'amount_minor', + 'country_code', + 'currency', + 'mechanism', + 'now', + 'outcome', + 'provider', + 'release_at', + 'scheduled_end', + 'scheduled_start', + 'value_class', + ]); + }); + }); + + it('fail-closed : NOT_REQUIRED refusé sur une classe déclencheur (LUXE) et sur une classe inconnue ; rien n’est écrit', async () => { + await run(async (tx, groups) => { + for (const cls of ['LUXE', null] as const) { + const p = await guest(tx, cc); + const hold = await book(tx, cc, groups, p, cls); + const e = await failure( + tx, + 'SELECT core.payment_cmd_record_deposit_decision($1, $2, $3::jsonb)', + [p.hash, hold, JSON.stringify(notRequired)], + ); + expect(e).toMatchObject({ code: '23514', constraint: 'deposit_decision_mismatch' }); + expect(translateDbError(e ?? {}).code).toBe('INVARIANT_VIOLATION'); + expect((await read(tx, p.hash, hold))['mechanism']).toBeNull(); + } + }); + }); + + it('T72 c / montant unique : LUXE sans deposit_amount (À DÉCIDER) refusé ; avec 300,00 de test ⇒ T57 figé ; autre montant refusé', async () => { + await run(async (tx, groups) => { + const p = await guest(tx, cc); + const hold = await book(tx, cc, groups, p, 'LUXE'); + const sql = 'SELECT core.payment_cmd_record_deposit_decision($1, $2, $3::jsonb)'; + const deposit = depositOf(cc); + expect( + await failure(tx, sql, [p.hash, hold, JSON.stringify(preauth(deposit))]), + ).toMatchObject({ code: '23514', constraint: 'deposit_decision_mismatch' }); + await amountParam(tx, cc, deposit); + expect( + await failure(tx, sql, [p.hash, hold, JSON.stringify(preauth(deposit + 1n))]), + ).toMatchObject({ code: '23514', constraint: 'deposit_decision_mismatch' }); + expect(await record(tx, p.hash, hold, preauth(deposit))).toBe('RECORDED'); + const after = await read(tx, p.hash, hold); + expect(after).toMatchObject({ + mechanism: 'PREAUTH_SINGLE', + amount_minor: deposit.toString(), + currency: cc.currency, + }); + expect((after['release_at'] as Date).toISOString()).toBe(at(START, 144)); + }); + }); + + it('17 §0.1 : rail « débit puis remboursement » refusé tant que funds_holding_enabled = false', async () => { + await run(async (tx, groups) => { + const p = await guest(tx, cc); + const hold = await book(tx, cc, groups, p, 'LUXE'); + await amountParam(tx, cc, depositOf(cc)); + const e = await failure( + tx, + 'SELECT core.payment_cmd_record_deposit_decision($1, $2, $3::jsonb)', + [p.hash, hold, JSON.stringify(preauth(depositOf(cc), 'CHARGE_THEN_REFUND'))], + ); + expect(e).toMatchObject({ code: '55000', constraint: 'deposit_rail_closed' }); + expect(translateDbError(e ?? {}).code).toBe('FORBIDDEN'); + }); + }); + + it('IDOR et droits : hold d’un autre voyageur ⇒ HOLD_NOT_FOUND (lecture et écriture) ; session absente ⇒ AUTH_REQUIRED ; aucun droit direct ni sur les fonctions du travailleur', async () => { + await run(async (tx, groups) => { + const owner = await guest(tx, cc); + const other = await guest(tx, cc); + const hold = await book(tx, cc, groups, owner, 'STANDARD'); + expect((await read(tx, other.hash, hold))['outcome']).toBe('HOLD_NOT_FOUND'); + expect(await record(tx, other.hash, hold, notRequired)).toBe('HOLD_NOT_FOUND'); + expect((await read(tx, Buffer.alloc(32), hold))['outcome']).toBe('AUTH_REQUIRED'); + for (const sql of [ + 'SELECT 1 FROM core.payment_deposit_hold', + 'SELECT * FROM core.payment_deposit_reauth_due(10)', + `SELECT core.payment_cmd_deposit_transition('${uuid()}', 'REAUTHORIZED', 0, NULL, NULL, NULL, NULL)`, + ]) { + expect(await failure(tx, sql, []), sql).toMatchObject({ code: '42501' }); + } + }); + }); +}); + +describe.each(COUNTRIES)('US-701 — minuterie de ré-autorisation ($country, $currency)', (cc) => { + /** T59 en rail (a) : autorisée à début − 24 h (expiration début + 144 h), libération + 144 h 25. */ + const start = '2031-08-01T10:00:00.000Z'; + const expiry = at(start, 144); + const release = new Date(Date.parse(start) + (144 * 60 + 25) * 60_000).toISOString(); + const reauthDue = at(start, 120); + const seed = async (tx: Tx) => + ( + await tx.query( + `SELECT * FROM test_fixture.us701_converted_deposit($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`, + [ + cc.country, + cc.currency, + cc.timezone, + start, + at(start, 72), + depositOf(cc).toString(), + expiry, + release, + release, + reauthDue, + `fake-${uuid()}`, + ], + ) + ).rows[0]!; + const transition = ( + tx: Tx, + id: unknown, + event: string, + seq: number, + exp: string, + decision: string, + due: string | null, + ) => + tx.query<{ r: string }>( + 'SELECT core.payment_cmd_deposit_transition($1, $2, $3, $4, $5, $6, NULL) AS r', + [id, event, seq, exp, decision, due], + ); + + it('file : échue seulement à l’heure de la base, sans champ [C2] ; acceptée ⇒ nouvelle expiration, plus dans la file ; rang périmé ⇒ STALE', async () => { + await withRole('app_worker', (client) => + payTx(client, { worker: 'payment_command', virtualNow: at(start, 119) }, async (tx) => { + const s = await seed(tx); + const dueOf = async () => + (await tx.query('SELECT * FROM core.payment_deposit_reauth_due(500)')).rows.filter( + (r) => r['deposit_id'] === s['deposit_id'], + ); + expect(await dueOf()).toEqual([]); + await setClock(tx, reauthDue); + const due = await dueOf(); + expect(due).toHaveLength(1); + expect(due[0]).toMatchObject({ + trip_id: s['trip_id'], + segment_id: s['segment_id'], + tender_id: s['tender_id'], + country_code: cc.country, + currency: cc.currency, + provider: 'FAKE', + reauth_seq: 0, + }); + expect(Object.keys(due[0]!)).not.toContain('triggers'); + expect(Object.keys(due[0]!)).not.toContain('params_snapshot'); + // acceptée à +120 h (V = 168 h) : expiration +288 h, décision à la libération + const ok = await transition( + tx, + s['deposit_id'], + 'REAUTHORIZED', + 0, + at(start, 288), + release, + null, + ); + expect(ok.rows[0]!.r).toBe('APPLIED'); + expect(await dueOf()).toEqual([]); + // rejeu tardif avec l'ancien rang : rien n'est écrit + const stale = await transition( + tx, + s['deposit_id'], + 'REAUTHORIZED', + 0, + at(start, 288), + release, + null, + ); + expect(stale.rows[0]!.r).toBe('STALE'); + }), + ); + }); + + it('refusée ⇒ REAUTH_REFUSED : décision avant l’expiration en cours, plus de minuterie ; décision après l’expiration refusée par la base', async () => { + await withRole('app_worker', (client) => + payTx(client, { worker: 'payment_command', virtualNow: reauthDue }, async (tx) => { + const s = await seed(tx); + const late = await failure( + tx, + 'SELECT core.payment_cmd_deposit_transition($1, $2, $3, $4, $5, $6, NULL)', + [s['deposit_id'], 'REAUTH_REFUSED', 0, expiry, release, null], + ); + expect(late).toMatchObject({ code: '23514', constraint: 'deposit_hold_decision_window' }); + // 08 BR-PAY-06 : décision = expiration − deposit_safety_h (2 h) + const r = await transition( + tx, + s['deposit_id'], + 'REAUTH_REFUSED', + 0, + expiry, + at(start, 142), + null, + ); + expect(r.rows[0]!.r).toBe('APPLIED'); + const again = await tx.query('SELECT * FROM core.payment_deposit_reauth_due(500)'); + expect(again.rows.filter((x) => x['deposit_id'] === s['deposit_id'])).toEqual([]); + }), + ); + }); + + it('autre travailleur : file vide, transition refusée (42501)', async () => { + await withRole('app_worker', (client) => + payTx(client, { worker: 'payment_command', virtualNow: reauthDue }, async (tx) => { + const s = await seed(tx); + await tx.query(`SELECT pg_catalog.set_config('app.worker_name', 'settlement', true)`); + const due = await tx.query('SELECT * FROM core.payment_deposit_reauth_due(500)'); + expect(due.rows).toEqual([]); + const e = await failure( + tx, + 'SELECT core.payment_cmd_deposit_transition($1, $2, $3, $4, $5, $6, NULL)', + [s['deposit_id'], 'REAUTHORIZED', 0, at(start, 288), release, null], + ); + expect(e).toMatchObject({ code: '42501', constraint: 'deposit_hold_command_forbidden' }); + }), + ); + }); +}); diff --git a/packages/i18n/src/catalogs/en.ts b/packages/i18n/src/catalogs/en.ts index ad71ab843..eeb87afc6 100644 --- a/packages/i18n/src/catalogs/en.ts +++ b/packages/i18n/src/catalogs/en.ts @@ -110,6 +110,8 @@ export const EN_MESSAGES = { "We can't place the deposit on your card for these dates. You can book up to {count} days.", }, 'web.deposit.unavailableNone': "For now, we can't place the deposit on your card for this car.", + // US-701 (ADR-169) : S05, aucune caution pour ce trip (08 BR-PAY-06 : l'absence est affichée) + 'web.deposit.none': "This trip doesn't require a security deposit.", 'web.catalog.title': 'Component library', 'web.catalog.intro': 'Every component in each of its states. Pick the language, theme and width to review them.', @@ -2097,6 +2099,9 @@ export const EN_MESSAGES = { // du paiement rendus par l'API (common.payment.*) ; aucune durée écrite (heures lues dans l'API) 'common.payment.unavailable': 'Online payment isn’t available right now. You haven’t been charged.', + // US-701 (ADR-169) : refus du paiement, caution impossible pour ces dates ou montant non fixé + 'common.payment.depositUnavailable': + "We can't place the deposit on your card for these dates. You haven't been charged: change the dates or choose another car.", // US-223c (ADR-146) : demandes de réservation de l'hôte (mode REQUEST, 17 §2.5 ; 16 HDB-002) 'common.request.notFound': 'We couldn’t find this request.', 'common.request.expired': 'This request has expired. The guest wasn’t charged.', diff --git a/packages/i18n/src/catalogs/es.ts b/packages/i18n/src/catalogs/es.ts index 78fece706..5a09a81e8 100644 --- a/packages/i18n/src/catalogs/es.ts +++ b/packages/i18n/src/catalogs/es.ts @@ -119,6 +119,8 @@ export const ES_MESSAGES = { }, 'web.deposit.unavailableNone': 'Por ahora no podemos tomar el depósito en tu tarjeta para este auto.', + // US-701 (ADR-169) : S05, aucune caution pour ce trip (08 BR-PAY-06 : l'absence est affichée) + 'web.deposit.none': 'Este viaje no requiere depósito de garantía.', // Vitrine de la bibliothèque (US-032) : outil interne de revue du design, PROPOSÉ. 'web.catalog.title': 'Biblioteca de componentes', 'web.catalog.intro': @@ -2154,6 +2156,9 @@ export const ES_MESSAGES = { // du paiement rendus par l'API (common.payment.*) ; aucune durée écrite (heures lues dans l'API) 'common.payment.unavailable': 'El pago en línea no está disponible por ahora. No se te cobró nada.', + // US-701 (ADR-169) : refus du paiement, caution impossible pour ces dates ou montant non fixé + 'common.payment.depositUnavailable': + 'Para estas fechas no podemos tomar el depósito en tu tarjeta. No se te cobró nada: cambia las fechas o elige otro auto.', // US-223c (ADR-146) : demandes de réservation de l'hôte (mode REQUEST, 17 §2.5 ; 16 HDB-002) 'common.request.notFound': 'No encontramos esta solicitud.', 'common.request.expired': 'Esta solicitud ya venció. No se le cobró nada al viajero.', diff --git a/packages/i18n/src/catalogs/fr.ts b/packages/i18n/src/catalogs/fr.ts index d34613eed..d83e3914d 100644 --- a/packages/i18n/src/catalogs/fr.ts +++ b/packages/i18n/src/catalogs/fr.ts @@ -125,6 +125,8 @@ export const FR_MESSAGES = { }, 'web.deposit.unavailableNone': 'Pour l’instant, nous ne pouvons pas bloquer le dépôt sur ta carte pour cette voiture.', + // US-701 (ADR-169) : S05, aucune caution pour ce trip (08 BR-PAY-06 : l'absence est affichée) + 'web.deposit.none': 'Ce voyage ne demande pas de dépôt de garantie.', 'web.catalog.title': 'Bibliothèque de composants', 'web.catalog.intro': 'Chaque composant dans ses états. Choisis la langue, le thème et la largeur pour les passer en revue.', @@ -2205,6 +2207,9 @@ export const FR_MESSAGES = { // du paiement rendus par l'API (common.payment.*) ; aucune durée écrite (heures lues dans l'API) 'common.payment.unavailable': 'Le paiement en ligne n’est pas disponible pour le moment. Aucun débit n’a été effectué.', + // US-701 (ADR-169) : refus du paiement, caution impossible pour ces dates ou montant non fixé + 'common.payment.depositUnavailable': + 'Pour ces dates, nous ne pouvons pas bloquer le dépôt sur ta carte. Aucun débit n’a été effectué : change les dates ou choisis une autre voiture.', // US-223c (ADR-146) : demandes de réservation de l'hôte (mode REQUEST, 17 §2.5 ; 16 HDB-002) 'common.request.notFound': 'Nous n’avons pas trouvé cette demande.', 'common.request.expired': 'Cette demande a expiré. Le voyageur n’a pas été débité.', diff --git a/packages/i18n/src/catalogs/index.ts b/packages/i18n/src/catalogs/index.ts index 312b32699..87d5da481 100644 --- a/packages/i18n/src/catalogs/index.ts +++ b/packages/i18n/src/catalogs/index.ts @@ -255,8 +255,13 @@ export type { Catalog, Message, PluralCategory, PluralMessage, VersionedCatalog Version 82 (la 79 qui lui était réservée a été dépassée par la 81 d’US-224f) : rails de la caution (US-225, ADR-164) : `web.deposit.unavailable` (refus avant le paiement avec la durée possible, texte de 10b UX-24) et `web.deposit.unavailableNone` (aucune durée possible, PROPOSÉ), affichés par l'écran S05 quand il branchera la décision de la caution. + Version 83 (la 82 est celle d’US-225) : caution figée au checkout (US-701, ADR-169) : + `web.deposit.none` (S05 : aucune caution pour ce trip, 08 BR-PAY-06) et + `common.payment.depositUnavailable` (réponse 409 `DEPOSIT_RAIL_UNAVAILABLE` / + `DEPOSIT_PARAM_MISSING` de `POST /checkout/holds/{id}/payment`, avec une sortie : autres dates, + autre voiture). */ -export const CATALOG_VERSION = 82; +export const CATALOG_VERSION = 83; /** Catalogues de base par langue ; la langue d'un profil de locale choisit le sien. */ export const CATALOGS: Readonly>> = { diff --git a/packages/i18n/src/catalogs/pt.ts b/packages/i18n/src/catalogs/pt.ts index 7783b88bf..ce9fa7947 100644 --- a/packages/i18n/src/catalogs/pt.ts +++ b/packages/i18n/src/catalogs/pt.ts @@ -123,6 +123,8 @@ export const PT_MESSAGES = { }, 'web.deposit.unavailableNone': 'Por enquanto, não conseguimos bloquear a caução no seu cartão para este carro.', + // US-701 (ADR-169) : S05, aucune caution pour ce trip (08 BR-PAY-06 : l'absence est affichée) + 'web.deposit.none': 'Esta viagem não exige caução.', 'web.catalog.title': 'Biblioteca de componentes', 'web.catalog.intro': 'Cada componente em todos os seus estados. Escolha o idioma, o tema e a largura para revisar.', @@ -2159,6 +2161,9 @@ export const PT_MESSAGES = { // du paiement rendus par l'API (common.payment.*) ; aucune durée écrite (heures lues dans l'API) 'common.payment.unavailable': 'O pagamento on-line não está disponível no momento. Nada foi cobrado.', + // US-701 (ADR-169) : refus du paiement, caution impossible pour ces dates ou montant non fixé + 'common.payment.depositUnavailable': + 'Para essas datas não conseguimos bloquear a caução no seu cartão. Nada foi cobrado: mude as datas ou escolha outro carro.', // US-223c (ADR-146) : demandes de réservation de l'hôte (mode REQUEST, 17 §2.5 ; 16 HDB-002) 'common.request.notFound': 'Não encontramos esta solicitação.', 'common.request.expired': 'Esta solicitação expirou. Nada foi cobrado do viajante.', From bf0e85125eccfc43ecc2376af5bdb673e1170afc Mon Sep 17 00:00:00 2001 From: Projetapploccar <351336702+Projetapploccar@users.noreply.github.com> Date: Wed, 18 Nov 2026 16:12:43 -0300 Subject: [PATCH 2/2] =?UTF-8?q?fix(US-701):=20politiques=20de=20lecture=20?= =?UTF-8?q?de=20la=20caution=20dans=20la=20liste=20attendue,=20file=20depo?= =?UTF-8?q?sit=5Ftimer=20de=20la=20r=C3=A9p=C3=A9tition,=20schema.md=20du?= =?UTF-8?q?=20job=20=C2=AB=20base=20de=20donn=C3=A9es=20=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - config-country.test.ts : cmd_hold_deposit_read (config_param_value, config_param_definition) ajoutée à la liste fermée des politiques, avec sa justification (paramètres de la caution, US-701) ; aucune politique existante retirée - scripts/deploy/rehearsal.sh : file deposit_timer attendue au démarrage du travailleur - schema.md recopié de la sortie du job « base de données » du run 44374098328 - pg-deposit-checkout.test.ts : lecture défensive du magasin de la caution Agent-Role: argent Agent-Model: claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 --- .../pay/internal/pg-deposit-checkout.test.ts | 138 ++++++++++++++++++ docs/architecture/schema.md | 52 ++++++- packages/db/test/int/config-country.test.ts | 7 +- scripts/deploy/rehearsal.sh | 2 +- 4 files changed, 196 insertions(+), 3 deletions(-) create mode 100644 apps/api/src/modules/pay/internal/pg-deposit-checkout.test.ts diff --git a/apps/api/src/modules/pay/internal/pg-deposit-checkout.test.ts b/apps/api/src/modules/pay/internal/pg-deposit-checkout.test.ts new file mode 100644 index 000000000..ff793ced5 --- /dev/null +++ b/apps/api/src/modules/pay/internal/pg-deposit-checkout.test.ts @@ -0,0 +1,138 @@ +/** + * US-701 (ADR-169) — lecture défensive des fonctions de 0144 par `PgDepositCheckoutStore` (sans + * base : exécutant simulé). Attendus : forme des fonctions de la migration (colonnes, issues) ; une + * forme inattendue ⇒ erreur (503 chez l'appelant), jamais une décision devinée. Les fonctions + * elles-mêmes sont prouvées en base (`l0-us701-deposit-hold`). + */ +import { describe, expect, it } from 'vitest'; +import { isPaymentError } from './errors.js'; +import { PgDepositCheckoutStore } from './pg-deposit-checkout.js'; +import type { SqlExecutor } from './pg-stores.js'; + +const PROOF = Buffer.from('jeton'); +const START = new Date('2031-07-10T10:00:00.000Z'); +const END = new Date('2031-07-13T10:00:00.000Z'); +const NOW = new Date('2031-07-01T10:00:00.000Z'); + +function db(row: Record | undefined, calls: unknown[][] = []): SqlExecutor { + return { + query: >(text: string, values?: readonly unknown[]) => { + calls.push([text, ...(values ?? [])]); + return Promise.resolve({ rows: (row === undefined ? [] : [row]) as R[] }); + }, + }; +} + +const open = { + outcome: 'DONE', + country_code: 'ZZ', + currency: 'XTS', + value_class: 'LUXE', + scheduled_start: START, + scheduled_end: END, + provider: 'FAKE', + now: NOW, + mechanism: null, + amount_minor: null, + release_at: null, +}; + +describe('PgDepositCheckoutStore — lecture', () => { + it('contexte ouvert : classe du catalogue, période, fournisseur et heure de la base', async () => { + expect(await new PgDepositCheckoutStore(db(open)).read(PROOF, 'h')).toEqual({ + kind: 'OPEN', + context: { + country: 'ZZ', + currency: 'XTS', + valueClass: 'LUXE', + scheduledStart: START, + scheduledEnd: END, + provider: 'FAKE', + now: NOW, + }, + }); + }); + + it('classe hors vocabulaire ⇒ inconnue (fail-closed) ; aucun compte marchand ⇒ fournisseur null', async () => { + const r = await new PgDepositCheckoutStore( + db({ ...open, value_class: 'SUPER', provider: null }), + ).read(PROOF, 'h'); + expect(r).toMatchObject({ kind: 'OPEN', context: { valueClass: null, provider: null } }); + }); + + it('décision figée : mécanisme, montant (bigint), devise, libération ; aucun autre champ', async () => { + const r = await new PgDepositCheckoutStore( + db({ ...open, mechanism: 'PREAUTH_SINGLE', amount_minor: '30000', release_at: END }), + ).read(PROOF, 'h'); + expect(r).toEqual({ + kind: 'RECORDED', + deposit: { + mechanism: 'PREAUTH_SINGLE', + amountMinor: 30000n, + currency: 'XTS', + releaseAt: END, + }, + }); + }); + + it('issues de la base rendues telles quelles ; mécanisme, montant ou issue inattendus ⇒ erreur', async () => { + for (const outcome of ['AUTH_REQUIRED', 'HOLD_NOT_FOUND', 'QUOTE_UNAVAILABLE']) { + expect(await new PgDepositCheckoutStore(db({ outcome })).read(PROOF, 'h')).toBe(outcome); + } + for (const row of [ + { ...open, mechanism: 'REFUSED', amount_minor: '0' }, + { ...open, mechanism: 'PREAUTH_SINGLE', amount_minor: '-1', release_at: END }, + { ...open, outcome: 'SURPRISE' }, + undefined, + ]) { + const e = await new PgDepositCheckoutStore(db(row)).read(PROOF, 'h').catch((x: unknown) => x); + expect(isPaymentError(e, 'INVALID_REQUEST'), JSON.stringify(row)).toBe(true); + } + }); +}); + +describe('PgDepositCheckoutStore — écriture', () => { + const record = { + mechanism: 'PREAUTH_SINGLE' as const, + triggers: ['CLASS' as const], + paramsSnapshot: { version: 1 }, + amountMinor: 30000n, + provider: 'FAKE', + hRequiredHours: 168, + vHours: 168, + authAt: START, + releaseAt: END, + decisionAt: END, + reauthDueAt: null, + }; + + it('décision transmise en JSON (montant en texte, instants ISO) ; issue de la commande rendue', async () => { + const calls: unknown[][] = []; + const out = await new PgDepositCheckoutStore(db({ r: 'RECORDED' }, calls)).record( + PROOF, + 'h', + record, + ); + expect(out).toBe('RECORDED'); + expect(JSON.parse(String(calls[0]?.[3]))).toMatchObject({ + mechanism: 'PREAUTH_SINGLE', + triggers: ['CLASS'], + amountMinor: '30000', + authAt: START.toISOString(), + reauthDueAt: null, + }); + }); + + it('issue inconnue ou déclencheur hors liste ⇒ erreur, rien n’est supposé écrit', async () => { + const e1 = await new PgDepositCheckoutStore(db({ r: 'DONE' })) + .record(PROOF, 'h', record) + .catch((x: unknown) => x); + expect(isPaymentError(e1, 'INVALID_REQUEST')).toBe(true); + const calls: unknown[][] = []; + const e2 = await new PgDepositCheckoutStore(db({ r: 'RECORDED' }, calls)) + .record(PROOF, 'h', { ...record, triggers: ['ZODIAC' as 'CLASS'] }) + .catch((x: unknown) => x); + expect(isPaymentError(e2, 'INVALID_REQUEST')).toBe(true); + expect(calls).toEqual([]); + }); +}); diff --git a/docs/architecture/schema.md b/docs/architecture/schema.md index 038a1af85..49e76a99c 100644 --- a/docs/architecture/schema.md +++ b/docs/architecture/schema.md @@ -159,7 +159,7 @@ Lu dans le catalogue (`pg_catalog`) d'une base jetable du banc, après les seule | `0141_payment_refund_multi_tender` | PAY : remboursement réparti sur les moyens d'origine (TJ16c / TJ16d) et reprise après un | | `0142_config_deposit_rail_params` | graine complémentaire : paramètres « deposit_always_required* » (US-225 ; 17 §7.2). | | `0143_settlement_insurer_ledger` | STL / FIN : jambe de l'assureur — registre `insurer_ledger`, bordereau mensuel à double | -| `0144_payment_deposit_hold` | PAY : caution de la plateforme figée au checkout (`deposit_hold`), vue du voyageur sans champ [C2], | +| `0144_payment_deposit_hold` | PAY : caution de la plateforme figée au checkout (`deposit_hold`), vue du voyageur sans | ## Rôles @@ -2557,6 +2557,7 @@ Politiques RLS : - `catalog_cmd_read` (SELECT, PERMISSIVE, catalog_cmd_owner) USING `(key = ANY (ARRAY['price_display_step_minor'::text, 'listing_min_photos'::text, 'price_ceiling_daily_minor'::text, 'price_ceiling_extra_km_minor'::text, 'p2p_private_hosts_enabled'::text, 'vehicle_financed_requires_lender_consent'::text, 'elig_age_years_ceiling'::text, 'elig_odometer_km_ceiling'::text, 'elig_doc_title'::text, 'elig_doc_plate_vin_photo'::text, 'elig_doc_inspection'::text, 'elig_doc_compulsory_insurance'::text, 'elig_doc_owner_authorization'::text, 'elig_doc_lender_consent'::text]))` - `catalog_cmd_upload_read` (SELECT, PERMISSIVE, catalog_cmd_owner) USING `(key = ANY (ARRAY['upload_photo_max_kb'::text, 'upload_gallery_photos_max'::text, 'upload_documents_per_minute'::text]))` - `cmd_golive_sel` (SELECT, PERMISSIVE, cmd_golive_owner) USING `go_live_switch` +- `cmd_hold_deposit_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = 'funds_holding_enabled'::text)` - `cmd_hold_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = ANY (ARRAY['p2p_private_hosts_enabled'::text, 'insurer_contract_active'::text]))` - `cmd_money_sel` (SELECT, PERMISSIVE, cmd_money_owner) USING `go_live_switch` - `kyc_cmd_host_read` (SELECT, PERMISSIVE, kyc_cmd_owner) USING `(key = ANY (ARRAY['p2p_private_hosts_enabled'::text, 'insurer_contract_active'::text]))` @@ -2621,6 +2622,7 @@ Politiques RLS : - `cmd_golive_sel` (SELECT, PERMISSIVE, cmd_golive_owner) USING `((go_live_request_id IS NOT NULL) OR (key IN ( SELECT d.key FROM core.config_param_definition d WHERE d.go_live_switch)))` - `cmd_hold_cancel_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = ANY (ARRAY['free_cancel_lead'::text, 'last_minute_threshold'::text, 'host_penalty'::text, 'platform_funded_host_compensation'::text]))` - `cmd_hold_contract_param_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = 'grace_minutes'::text)` +- `cmd_hold_deposit_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = ANY (ARRAY['deposit_always_required'::text, 'deposit_trigger_classes'::text, 'deposit_amount'::text, 'funds_holding_enabled'::text]))` - `cmd_hold_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = ANY (ARRAY['buffer_minutes'::text, 'hold_ttl_minutes'::text, 'hold_max_total_minutes'::text, 'max_active_holds_per_guest'::text, 'hold_creations_per_guest_vehicle_hour'::text, 'sweep_grace_s'::text, 'flagged_booking_payment_order'::text, 'review_hold_minutes'::text, 'payment_in_flight_margin_s'::text, 'psp_call_timeout_s'::text, 'conversion_start_tolerance_minutes'::text, 'payment_attempts_per_hold'::text, 'max_trip_days'::text, 'advance_notice_minutes'::text, 'no_show_grace_minutes'::text, 'overdue_detection_minutes'::text, 'p2p_private_hosts_enabled'::text, 'insurer_contract_active'::text]))` - `cmd_hold_request_param_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = ANY (ARRAY['booking_request_mode_enabled'::text, 'booking_request_expiry_hours'::text]))` - `cmd_hold_risk_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `(key = ANY (ARRAY['min_driver_age'::text, 'foreign_license_review_enabled'::text]))` @@ -4242,6 +4244,48 @@ Déclencheurs : | `updated_at` | `timestamp with time zone` | oui | `platform.now()` | | `row_version` | `integer` | oui | `0` | +Contraintes : + +- `deposit_hold_amount_nonnegative` : `CHECK (amount_minor >= 0)` +- `deposit_hold_authorized_shape` : `CHECK (status IS DISTINCT FROM 'AUTHORIZED'::text OR auth_provider_reference IS NOT NULL AND (mechanism = 'CHARGE_THEN_REFUND'::text OR auth_expiry_at IS NOT NULL))` +- `deposit_hold_country_format` : `CHECK (country_code ~ '^[A-Z]{2}$'::text)` +- `deposit_hold_currency_format` : `CHECK (currency ~ '^[A-Z]{3}$'::text)` +- `deposit_hold_decision_window` : `CHECK (decision_at IS NULL OR decision_at <= release_at AND decision_at >= auth_at AND (auth_expiry_at IS NULL OR decision_at <= auth_expiry_at OR mechanism = 'REAUTH'::text AND reauth_due_at IS NOT NULL))` +- `deposit_hold_h_required_positive` : `CHECK (h_required_hours > 0)` +- `deposit_hold_hold_fk` : `FOREIGN KEY (hold_id) REFERENCES core.booking_checkout_hold(id)` +- `deposit_hold_hold_unique` : `UNIQUE (hold_id)` +- `deposit_hold_mechanism_valid` : `CHECK (mechanism = ANY (ARRAY['NOT_REQUIRED'::text, 'PREAUTH_SINGLE'::text, 'REAUTH'::text, 'CHARGE_THEN_REFUND'::text]))` +- `deposit_hold_not_required_empty` : `CHECK (mechanism <> 'NOT_REQUIRED'::text OR status IS NULL AND h_required_hours IS NULL AND v_hours_snapshot IS NULL AND auth_at IS NULL AND auth_expiry_at IS NULL AND auth_provider_reference IS NULL AND release_at IS NULL AND decision_at IS NULL AND reauth_due_at IS NULL AND reauth_seq = 0)` +- `deposit_hold_not_required_shape` : `CHECK ((mechanism = 'NOT_REQUIRED'::text) = (cardinality(triggers) = 0) AND (mechanism = 'NOT_REQUIRED'::text) = (amount_minor = 0))` +- `deposit_hold_provider_format` : `CHECK (provider ~ '^[A-Z][A-Z0-9_]{1,31}$'::text)` +- `deposit_hold_provider_reference_format` : `CHECK (auth_provider_reference ~ '^[A-Za-z0-9_.:-]{1,128}$'::text)` +- `deposit_hold_reauth_seq_nonnegative` : `CHECK (reauth_seq >= 0)` +- `deposit_hold_reauth_shape` : `CHECK (reauth_due_at IS NULL OR mechanism = 'REAUTH'::text AND (status = ANY (ARRAY['PLANNED'::text, 'AUTHORIZED'::text])) AND (auth_expiry_at IS NULL OR reauth_due_at < auth_expiry_at))` +- `deposit_hold_required_shape` : `CHECK (mechanism = 'NOT_REQUIRED'::text OR status IS NOT NULL AND h_required_hours IS NOT NULL AND v_hours_snapshot IS NOT NULL AND auth_at IS NOT NULL AND release_at IS NOT NULL AND decision_at IS NOT NULL)` +- `deposit_hold_snapshot_object` : `CHECK (jsonb_typeof(params_snapshot) = 'object'::text)` +- `deposit_hold_status_valid` : `CHECK (status = ANY (ARRAY['PLANNED'::text, 'AUTHORIZED'::text, 'PARTIALLY_CAPTURED'::text, 'VOIDED'::text, 'REFUNDED'::text, 'EXPIRED'::text]))` +- `deposit_hold_triggers_valid` : `CHECK (triggers <@ ARRAY['AGE'::text, 'CLASS'::text, 'COUNTRY'::text, 'RISK'::text] AND array_position(triggers, NULL::text) IS NULL)` +- `deposit_hold_v_nonnegative` : `CHECK (v_hours_snapshot >= 0)` +- `payment_deposit_hold_pkey` : `PRIMARY KEY (id)` + +Index : + +- `deposit_hold_reauth_due_idx` : `CREATE INDEX deposit_hold_reauth_due_idx ON core.payment_deposit_hold USING btree (reauth_due_at) WHERE (reauth_due_at IS NOT NULL)` + +Politiques RLS : + +- `cmd_hold_ins` (INSERT, PERMISSIVE, cmd_hold_owner) WITH CHECK `((app.actor_kind() = 'GUEST'::text) AND ((status IS NULL) OR (status = 'PLANNED'::text)) AND (reauth_seq = 0) AND (auth_expiry_at IS NULL) AND (auth_provider_reference IS NULL))` +- `cmd_hold_sel` (SELECT, PERMISSIVE, cmd_hold_owner) USING `true` +- `cmd_hold_upd` (UPDATE, PERMISSIVE, cmd_hold_owner) USING `((app.actor_kind() = 'WORKER'::text) AND (app.worker_name() = 'payment_command'::text))` WITH CHECK `((app.actor_kind() = 'WORKER'::text) AND (app.worker_name() = 'payment_command'::text))` +- `migrator_all` (ALL, PERMISSIVE, migrator) USING `true` WITH CHECK `true` + +Déclencheurs : + +- `deposit_hold_guard` : `CREATE TRIGGER deposit_hold_guard BEFORE UPDATE ON core.payment_deposit_hold FOR EACH ROW EXECUTE FUNCTION core.payment_deposit_hold_guard()` +- `money_no_delete` : `CREATE TRIGGER money_no_delete BEFORE DELETE ON core.payment_deposit_hold FOR EACH ROW EXECUTE FUNCTION core.settlement_no_delete()` +- `money_no_truncate` : `CREATE TRIGGER money_no_truncate BEFORE TRUNCATE ON core.payment_deposit_hold FOR EACH STATEMENT EXECUTE FUNCTION core.settlement_no_delete()` +- `touch_row` : `CREATE TRIGGER touch_row BEFORE UPDATE ON core.payment_deposit_hold FOR EACH ROW EXECUTE FUNCTION platform.touch_row()` + ### `core.payment_payment_command` - RLS : ENABLE + FORCE ; propriétaire `migrator` @@ -6651,8 +6695,10 @@ Chacune a un propriétaire `NOLOGIN` dédié (ADR-053) et un `search_path` figé | `core.kyc_worker_prune(p_batch integer)` | `integer` | `kyc_cmd_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; kyc_cmd_owner: EXECUTE | | `core.payment_assert_operation_legs()` | `trigger` | `integrity_owner` | search_path=pg_catalog, pg_temp | integrity_owner: EXECUTE | | `core.payment_cmd_apply_operation_status(p_operation_id uuid, p_status text, p_source text, p_raw_ref uuid, p_provider_reference text)` | `text` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | +| `core.payment_cmd_deposit_transition(p_deposit_id uuid, p_event text, p_expected_seq integer, p_auth_expiry_at timestamp with time zone, p_decision_at timestamp with time zone, p_reauth_due_at timestamp with time zone, p_provider_reference text)` | `text` | `cmd_hold_owner` | search_path=pg_catalog, pg_temp | PUBLIC: EXECUTE ; cmd_hold_owner: EXECUTE | | `core.payment_cmd_plan_refund(p_instance_id uuid, p_operation_id uuid, p_settlement_id uuid, p_refunded_operation_id uuid, p_instance_seq integer, p_rail text, p_legs jsonb, p_idem_plain text, p_idem_sent text)` | `TABLE(instance_id uuid, operation_id uuid, advance_id uuid, status text, blocked_reason text, replayed boolean)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.payment_cmd_receive_webhook(p_account_id uuid, p_provider_event_id text, p_dedup_key bytea, p_signature_valid boolean, p_signed_at timestamp with time zone, p_headers jsonb, p_normalized jsonb)` | `TABLE(outcome text, inbox_id uuid)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_api: EXECUTE ; cmd_money_owner: EXECUTE | +| `core.payment_cmd_record_deposit_decision(p_token_hash bytea, p_hold_id uuid, p_decision jsonb)` | `text` | `cmd_hold_owner` | search_path=pg_catalog, pg_temp | PUBLIC: EXECUTE ; cmd_hold_owner: EXECUTE | | `core.payment_cmd_record_operation(p_id uuid, p_hold_id uuid, p_trip_id uuid, p_psp_account_id uuid, p_method text, p_kind text, p_purpose text, p_amount_minor bigint, p_currency text, p_attempt_no integer, p_idem_plain text, p_idem_sent text, p_legs jsonb, p_settlement_id uuid, p_settlement_version integer)` | `TABLE(operation_id uuid, replayed boolean)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.payment_cmd_record_submerchant_status(p_submerchant_id uuid, p_status text, p_provider_ref text, p_reason text)` | `text` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.payment_cmd_refund_await_choice(p_instance_id uuid)` | `text` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | @@ -6660,6 +6706,8 @@ Chacune a un propriétaire `NOLOGIN` dédié (ADR-053) et un `search_path` figé | `core.payment_cmd_refund_order_for_send(p_instance_id uuid)` | `TABLE(operation_id uuid, operation_status text, idem_sent text, amount_minor bigint, currency text, legs jsonb, target_reference text, provider_reference text, provider text, sendable boolean, reason text)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.payment_cmd_register_submerchant(p_id uuid, p_org_id uuid, p_psp_account_id uuid, p_attempt_no integer)` | `TABLE(submerchant_id uuid, idem_plain text, replayed boolean)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.payment_cmd_submit_refund(p_instance_id uuid)` | `TABLE(outcome text, blocked_reason text)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | +| `core.payment_deposit_checkout(p_token_hash bytea, p_hold_id uuid)` | `TABLE(outcome text, country_code text, currency text, value_class text, scheduled_start timestamp with time zone, scheduled_end timestamp with time zone, provider text, now timestamp with time zone, mechanism text, amount_minor bigint, release_at timestamp with time zone)` | `cmd_hold_owner` | search_path=pg_catalog, pg_temp | PUBLIC: EXECUTE ; cmd_hold_owner: EXECUTE | +| `core.payment_deposit_reauth_due(p_limit integer)` | `TABLE(deposit_id uuid, trip_id uuid, segment_id uuid, tender_id uuid, country_code text, currency text, provider text, provider_reference text, auth_expiry_at timestamp with time zone, release_at timestamp with time zone, reauth_seq integer, now timestamp with time zone)` | `cmd_hold_owner` | search_path=pg_catalog, pg_temp | PUBLIC: EXECUTE ; cmd_hold_owner: EXECUTE | | `core.payment_refund_instance_gate()` | `trigger` | `integrity_owner` | search_path=pg_catalog, pg_temp | integrity_owner: EXECUTE | | `core.payment_refund_instance_sync()` | `trigger` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | | `core.payment_refunds_due(p_limit integer)` | `TABLE(instance_id uuid, country_code text, status text, operation_status text, provider text, blocked_reason text, fin_alert text, target_known boolean)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | @@ -6912,6 +6960,8 @@ Chacune a un propriétaire `NOLOGIN` dédié (ADR-053) et un `search_path` figé | `core.payment_capability_bool(p_provider text, p_country text, p_method text, p_capability text)` | `boolean` | `migrator` | app_worker: EXECUTE ; cmd_hold_owner: EXECUTE ; migrator: EXECUTE | | `core.payment_capability_int(p_provider text, p_country text, p_method text, p_capability text)` | `integer` | `migrator` | app_worker: EXECUTE ; cmd_hold_owner: EXECUTE ; migrator: EXECUTE | | `core.payment_capability_value(p_provider text, p_country text, p_method text, p_capability text)` | `jsonb` | `migrator` | app_worker: EXECUTE ; cmd_hold_owner: EXECUTE ; migrator: EXECUTE | +| `core.payment_deposit_amount_param(p_key text, p_country text)` | `jsonb` | `cmd_hold_owner` | cmd_hold_owner: EXECUTE | +| `core.payment_deposit_hold_guard()` | `trigger` | `migrator` | migrator: EXECUTE | | `core.payment_missing_blocking_capabilities(p_provider text, p_country text, p_mode text)` | `text[]` | `migrator` | app_api: EXECUTE ; app_worker: EXECUTE ; cmd_hold_owner: EXECUTE ; cmd_money_owner: EXECUTE ; kyc_cmd_owner: EXECUTE ; migrator: EXECUTE | | `core.payment_operation_leg_release_guard()` | `trigger` | `migrator` | migrator: EXECUTE | | `core.payment_psp_account_fake_guard()` | `trigger` | `migrator` | migrator: EXECUTE | diff --git a/packages/db/test/int/config-country.test.ts b/packages/db/test/int/config-country.test.ts index 1457758c8..bb46e8809 100644 --- a/packages/db/test/int/config-country.test.ts +++ b/packages/db/test/int/config-country.test.ts @@ -160,7 +160,7 @@ describe('configuration pays : structure et droits', () => { ); }); - it('base de production : seules les politiques migrator_all et app_read (SELECT) existent, plus la lecture du tampon par cmd_hold_owner, celle des codes pays par iam_staff_owner (US-012) et celle des fuseaux par risk_limit_owner (US-052) et celle des interrupteurs par cmd_money_owner (US-049), et celle des codes pays par iam_auth_owner (US-102), et celle de l’âge minimal de l’hôte par iam_auth_owner (US-107), et celle des délais des files par iam_staff_owner (US-109), et celle des paramètres de l’OTP par iam_auth_owner (US-104), et celle du pas de prix, du minimum de photos et de l’ouverture aux hôtes par catalog_cmd_owner (US-115), et celle des pays et de la rétention biométrique par kyc_cmd_owner (US-105), et la lecture et l’écriture des interrupteurs par cmd_golive_owner (US-125), et celle de l’âge minimal, du numéro fiscal et des interrupteurs de l’hôte par kyc_cmd_owner (US-123), et celles de la revue par exception par kyc_cmd_owner et du contrat d’assureur par catalog_cmd_owner (US-108), et celle du registre et des durées de la vie privée par privacy_cmd_owner (US-111), et celle des délais de notification d’une violation par iam_staff_owner (US-112), et celle du plafond des contestations par catalog_cmd_owner (US-122), et celle des plafonds de téléversement par catalog_cmd_owner (US-122, passe n° 2), et celles des paramètres et des taxes du rejeu du devis par cmd_money_owner (US-202), et celle de la durée maximale et du tampon par catalog_cmd_owner (US-201), et celle de la fenêtre de notation par review_cmd_owner (US-218), et celle des interrupteurs de l’hôte activable par cmd_hold_owner (US-208), et celle de l’annulation et du minimum de RC par catalog_cmd_owner (US-205), et celle des paramètres d’annulation réglée par cmd_hold_owner (US-215)', async () => { + it('base de production : seules les politiques migrator_all et app_read (SELECT) existent, plus la lecture du tampon par cmd_hold_owner, celle des codes pays par iam_staff_owner (US-012) et celle des fuseaux par risk_limit_owner (US-052) et celle des interrupteurs par cmd_money_owner (US-049), et celle des codes pays par iam_auth_owner (US-102), et celle de l’âge minimal de l’hôte par iam_auth_owner (US-107), et celle des délais des files par iam_staff_owner (US-109), et celle des paramètres de l’OTP par iam_auth_owner (US-104), et celle du pas de prix, du minimum de photos et de l’ouverture aux hôtes par catalog_cmd_owner (US-115), et celle des pays et de la rétention biométrique par kyc_cmd_owner (US-105), et la lecture et l’écriture des interrupteurs par cmd_golive_owner (US-125), et celle de l’âge minimal, du numéro fiscal et des interrupteurs de l’hôte par kyc_cmd_owner (US-123), et celles de la revue par exception par kyc_cmd_owner et du contrat d’assureur par catalog_cmd_owner (US-108), et celle du registre et des durées de la vie privée par privacy_cmd_owner (US-111), et celle des délais de notification d’une violation par iam_staff_owner (US-112), et celle du plafond des contestations par catalog_cmd_owner (US-122), et celle des plafonds de téléversement par catalog_cmd_owner (US-122, passe n° 2), et celles des paramètres et des taxes du rejeu du devis par cmd_money_owner (US-202), et celle de la durée maximale et du tampon par catalog_cmd_owner (US-201), et celle de la fenêtre de notation par review_cmd_owner (US-218), et celle des interrupteurs de l’hôte activable par cmd_hold_owner (US-208), et celle de l’annulation et du minimum de RC par catalog_cmd_owner (US-205), et celle des paramètres d’annulation réglée par cmd_hold_owner (US-215), et celle des paramètres de la caution par cmd_hold_owner (US-701)', async () => { await withRole( 'app_api', async (client) => { @@ -246,6 +246,11 @@ describe('configuration pays : structure et droits', () => { ...(t === 'config_param_value' ? [{ t, pol: 'cmd_hold_contract_param_read', cmd: 'r', roles: 'cmd_hold_owner' }] : []), + // caution figée au checkout (US-701, 0144) : déclencheurs pays / classe, montant et + // interrupteur funds_holding_enabled (valeur et définition) seulement + ...(t === 'config_param_definition' || t === 'config_param_value' + ? [{ t, pol: 'cmd_hold_deposit_read', cmd: 'r', roles: 'cmd_hold_owner' }] + : []), // commandes d'occupation (0032, US-022) : clé buffer_minutes seulement, en lecture ; // checkout (US-208, 0108) : interrupteurs de l'hôte activable (définition et valeur) ...(t === 'config_param_definition' || t === 'config_param_value' diff --git a/scripts/deploy/rehearsal.sh b/scripts/deploy/rehearsal.sh index 7b75d5544..a91784e48 100644 --- a/scripts/deploy/rehearsal.sh +++ b/scripts/deploy/rehearsal.sh @@ -76,7 +76,7 @@ say 'API saine ; route de webhook FAKE absente (404)' worker_logs="$(local_compose logs --no-color worker)" grep -q '"event":"worker.started"' <<<"$worker_logs" || fail 'travailleur : démarrage non journalisé' -grep -q '"queues":\["booking_contract","booking_conversion","booking_oracle","bordereau","disposition_sweeper","hold_expiry","iam_otp_pruner","iam_otp_sender","kyc_score_pruner","ntf_dispatcher","ntf_sender","ops_monitor","privacy_request","reconciliation","refund_scheduler","review_sla_watch","risk_pruner","security_incident_watch","trip_lifecycle","webhook_ingest"\]' <<<"$worker_logs" || { +grep -q '"queues":\["booking_contract","booking_conversion","booking_oracle","bordereau","deposit_timer","disposition_sweeper","hold_expiry","iam_otp_pruner","iam_otp_sender","kyc_score_pruner","ntf_dispatcher","ntf_sender","ops_monitor","privacy_request","reconciliation","refund_scheduler","review_sla_watch","risk_pruner","security_incident_watch","trip_lifecycle","webhook_ingest"\]' <<<"$worker_logs" || { # diagnostic : la ligne de démarrage (version et noms des files seulement, aucun secret) grep -F '"event":"worker.started"' <<<"$worker_logs" | tail -n 3 >&2 || true fail 'travailleur : files attendues absentes'