From 4b43a2c0397b1938c7233a19c4232933cdcc0c57 Mon Sep 17 00:00:00 2001 From: Projetapploccar <351336702+Projetapploccar@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:34:25 -0300 Subject: [PATCH 1/2] =?UTF-8?q?feat(US-224):=20remboursement=20r=C3=A9part?= =?UTF-8?q?i=20sur=20les=20moyens=20d'origine=20(TJ16c=20/=20TJ16d),=20rep?= =?UTF-8?q?rise=20apr=C3=A8s=20un=20=C3=A9chec=20confirm=C3=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 224f, critère 6 d'US-224 (N-238), ADR-166, migration 0141, catalogue v81, GL-43 : 08 E2 (imputation incrémentale) dans @rueda/money ; processeur des annulations multi-moyens (un ordre par encaissement, jambes en cascade) ; en base, jamais plus que le payé d'un moyen et rail natif sur la carte seulement ; crédit cash recréé refusé en bêta (rien n'est écrit, demande garée) ; FAILED confirmé ⇒ PENDING_CUSTOMER_CHOICE, attempt_no + 1, appelé par l'ordonnanceur. Agent-Role: argent Agent-Model: claude-opus-5-5 Co-Authored-By: Claude Opus 5.5 --- apps/api/src/modules/pay/README.md | 2 +- .../api/src/modules/pay/internal/pg-stores.ts | 16 + apps/api/src/modules/stl/README.md | 2 + apps/api/src/modules/stl/index.ts | 5 + .../stl/internal/refund-scheduler.test.ts | 33 ++ .../modules/stl/internal/refund-scheduler.ts | 23 +- .../stl/internal/trip-cancellation.test.ts | 133 +++++- .../modules/stl/internal/trip-cancellation.ts | 205 +++++++-- .../app/console/cancel-view.test.tsx | 4 +- apps/backoffice/app/console/cancel-view.tsx | 4 + apps/web/account/trip-refunds.test.ts | 3 +- apps/web/account/trip-refunds.ts | 11 +- changelog.d/US-224-multi-moyens.md | 6 + .../adr/ADR-166-remboursement-multi-moyens.md | 34 ++ docs/architecture/schema.md | 4 +- docs/ops/GO_LIVE_CHECKLIST.md | 1 + docs/team/COMME_TURO.md | 1 + docs/team/POUR_LE_FONDATEUR.md | 2 +- docs/team/handoffs/US-224.md | 63 +++ packages/db/README.md | 9 + .../0141_payment_refund_multi_tender.sql | 398 ++++++++++++++++ packages/db/security-definer-allowlist.json | 7 + packages/db/src/errors.ts | 5 + .../db/test/l0/l0-us224f-multi-tender.test.ts | 432 ++++++++++++++++++ packages/db/test/support/pay.ts | 5 +- packages/i18n/src/catalogs/en.ts | 7 + packages/i18n/src/catalogs/es.ts | 7 + packages/i18n/src/catalogs/fr.ts | 7 + packages/i18n/src/catalogs/index.ts | 6 +- packages/i18n/src/catalogs/pt.ts | 7 + packages/money/src/settlement/index.ts | 8 + .../money/src/settlement/tender-refunds.ts | 189 ++++++++ .../settlement/tender-refunds.golden.test.ts | 202 ++++++++ 33 files changed, 1790 insertions(+), 51 deletions(-) create mode 100644 changelog.d/US-224-multi-moyens.md create mode 100644 docs/adr/ADR-166-remboursement-multi-moyens.md create mode 100644 packages/db/migrations/0141_payment_refund_multi_tender.sql create mode 100644 packages/db/test/l0/l0-us224f-multi-tender.test.ts create mode 100644 packages/money/src/settlement/tender-refunds.ts create mode 100644 packages/money/test/settlement/tender-refunds.golden.test.ts diff --git a/apps/api/src/modules/pay/README.md b/apps/api/src/modules/pay/README.md index aa8d2f9b..c80f7341 100644 --- a/apps/api/src/modules/pay/README.md +++ b/apps/api/src/modules/pay/README.md @@ -56,7 +56,7 @@ Cible (17 §2.2, §4.5) : - `PaymentProvider` (`internal/port.ts`, 17 §2.8) : toute méthode qui déplace des fonds reçoit des `LegAmounts` (`MONEY_MOVING_METHODS`) ; méthodes de place de marché idempotentes (`MARKETPLACE_WRITE_METHODS`). - `WebhookVerifier` : vérification de signature par fournisseur, utilisée par `WebhookIngestService`. -- Magasins (`internal/stores.ts`) : `OperationStatusStore`, `WebhookInboxStore`, `WebhookWorkStore`, adaptateurs PostgreSQL `PgOperationRecorder`, `PgWebhookInboxStore`, `PgWebhookWorkStore`. US-224 (ADR-145) : `PgOperationRecorder.record` appelle la commande à 15 arguments ; un ordre REFUND / LEG_REALLOCATION / LEG_RELEASE d'un trip porte `settlement` (identifiant et version en tête du règlement), sinon la base le refuse ; un webhook de ces ordres sans montant ne les prouve pas (`UNPROVEN`). US-224b (ADR-147) : `PgRefundPlanner` planifie un remboursement de règlement (`plan` : instance SM-8, avance de Kmino attendue si la part HOST est déjà versée, ordre PENDING) et autorise son envoi (`submit` : `SUBMITTED`, `DUPLICATE`, `SUPERSEDED` ou `BLOCKED` avec son motif, tant qu'une avance n'a pas de décision FINANCE à deux personnes) ; l'appel au PSP ne suit que `SUBMITTED`. US-224c (ADR-150) : `PgRefundOrders` (`due` : file de l'ordonnanceur ; `orderForSend` : ordre stocké relu sous les verrous du trip et de l'ordre, gardés pendant l'appel au PSP, refus `NOT_SUBMITTED`, `FINAL`, `SUPERSEDED_UNSENT`, `NO_TARGET` ; `markAlerted` ; `applyLegMovement`) ; `PaymentConnectorRegistry` et `PRODUCTION_PAYMENT_CONNECTORS` (aucun connecteur avant le lot C) ; `REFUND_INSTANCE_STATUSES` (types resserrés de `PgRefundPlanner`, N-227). +- Magasins (`internal/stores.ts`) : `OperationStatusStore`, `WebhookInboxStore`, `WebhookWorkStore`, adaptateurs PostgreSQL `PgOperationRecorder`, `PgWebhookInboxStore`, `PgWebhookWorkStore`. US-224 (ADR-145) : `PgOperationRecorder.record` appelle la commande à 15 arguments ; un ordre REFUND / LEG_REALLOCATION / LEG_RELEASE d'un trip porte `settlement` (identifiant et version en tête du règlement), sinon la base le refuse ; un webhook de ces ordres sans montant ne les prouve pas (`UNPROVEN`). US-224b (ADR-147) : `PgRefundPlanner` planifie un remboursement de règlement (`plan` : instance SM-8, avance de Kmino attendue si la part HOST est déjà versée, ordre PENDING) et autorise son envoi (`submit` : `SUBMITTED`, `DUPLICATE`, `SUPERSEDED` ou `BLOCKED` avec son motif, tant qu'une avance n'a pas de décision FINANCE à deux personnes) ; l'appel au PSP ne suit que `SUBMITTED`. US-224c (ADR-150) : `PgRefundOrders` (`due` : file de l'ordonnanceur ; `orderForSend` : ordre stocké relu sous les verrous du trip et de l'ordre, gardés pendant l'appel au PSP, refus `NOT_SUBMITTED`, `FINAL`, `SUPERSEDED_UNSENT`, `NO_TARGET` ; `markAlerted` ; `applyLegMovement`) ; `PaymentConnectorRegistry` et `PRODUCTION_PAYMENT_CONNECTORS` (aucun connecteur avant le lot C) ; `REFUND_INSTANCE_STATUSES` (types resserrés de `PgRefundPlanner`, N-227). US-224f (ADR-166) : `PgRefundOrders.awaitChoice` (instance `FAILED` après un rejet confirmé ⇒ `PENDING_CUSTOMER_CHOICE`, `attempt_no` + 1 ; `DUPLICATE`, `SUPERSEDED`) ; la base refuse un rail natif sur un moyen autre qu'une carte et tout remboursement d'un moyen au-delà de ce qu'il a payé. - FAKE : `FakePsp` de `@rueda/fake-adapters/psp`, traduit vers le port par `testing/fake-payment-provider.ts` ; `testing/` n'est exporté par aucun index et reste hors de la compilation de production. API publique (`index.ts`, liste complète dans le fichier) : `PayModule`, `PayWebhookModule`, `postgresPayAdapters`, `PRODUCTION_PROVIDERS` ; types et constantes du port ; jambes (`LEGS`, `assertMovingLegs`, `legSum`…) ; erreurs (`PaymentError`, `PAYMENT_ERROR_CODES`) ; capacités (`CapabilitySet`, `CAPABILITIES`) ; idempotence (`settlementOperationKey`, `holdAttemptKey`…) ; `MoneyCommandSender` ; webhooks (`WebhookIngestService`, `WebhookProcessor`) ; PAN (`containsPan`, `maskPan`) ; démarrage (`assertPaymentStartup`, `checkPaymentStartup`). diff --git a/apps/api/src/modules/pay/internal/pg-stores.ts b/apps/api/src/modules/pay/internal/pg-stores.ts index 3d19f1cb..bb2fd264 100644 --- a/apps/api/src/modules/pay/internal/pg-stores.ts +++ b/apps/api/src/modules/pay/internal/pg-stores.ts @@ -472,6 +472,22 @@ export class PgRefundOrders { return rows[0]?.changed === true; } + /** + * US-224f (ADR-166, 08 SM-8) : instance `FAILED` après un rejet confirmé ⇒ `PENDING_CUSTOMER_CHOICE` + * (`attempt_no` + 1) ; déjà en attente ⇒ `DUPLICATE` ; remplacée ⇒ `SUPERSEDED`. + */ + async awaitChoice(instanceId: string): Promise<'AWAITING_CHOICE' | 'DUPLICATE' | 'SUPERSEDED'> { + const { rows } = await this.#tx.query<{ outcome: string }>( + 'SELECT core.payment_cmd_refund_await_choice($1) AS outcome', + [instanceId], + ); + const outcome = rows[0]?.outcome; + if (outcome !== 'AWAITING_CHOICE' && outcome !== 'DUPLICATE' && outcome !== 'SUPERSEDED') { + throw new Error('PAY : attente du choix du rail sans issue connue'); + } + return outcome; + } + /** Opération d'une instance (report après confirmation). */ async operationOf(instanceId: string): Promise { const { rows } = await this.#tx.query<{ operation_id: string }>( diff --git a/apps/api/src/modules/stl/README.md b/apps/api/src/modules/stl/README.md index 5bc9baff..c04c148a 100644 --- a/apps/api/src/modules/stl/README.md +++ b/apps/api/src/modules/stl/README.md @@ -120,3 +120,5 @@ Les tests L0 et d'intégration demandent PostgreSQL : guide `docs/ops/INSTALL.md La pénalité de l'hôte qui annule (`host_penalty_minor` du règlement, 08 E7 règle 7) est écrite au `host_ledger` (`core.settlement_host_ledger_entry`, migration 0129) par la base elle-même, dans la transaction de `TripCancellationProcessor` : la liaison du règlement à la demande (`core.booking_cmd_trip_settle_cancellation`) déclenche `core.settlement_cmd_post_host_penalty`. Aucun code de l'API n'écrit ni ne lit le `host_ledger` ; FINANCE et ADMIN du pays lisent le solde par hôte et par devise (`core.settlement_host_ledger_balance_v`). Aucune retenue sur un versement (GL-33, suite US-709 / US-314). **Créance de la règle 3 bis (US-224e, ADR-163).** Quand une avance de Kmino sur une jambe `HOST` déjà versée devient effective (`OPEN`, au report du remboursement par `core.settlement_cmd_apply_leg_movement`, `RefundScheduler`), la base écrit dans la même instruction la créance de l'hôte (`RELEASED_LEG_ADVANCE`, montant de l'avance stockée, 08 TJ18b / TJ18d) par le déclencheur `platform_advance_receivable_posted`. Aucun code de l'API n'y participe ; aucun recouvrement (`NETTING`, SM-6b) avant US-709. + +**Remboursement réparti sur les moyens d'origine (US-224f, ADR-166).** Le processeur des annulations lit tous les encaissements réussis du loyer du trip (`tendersOf` : capture, débit MIT, recouvrement, devise du trip, ordre des captures, montant déjà engagé sur chacun) et `ordersByTender` (pur) en tire un ordre par moyen : 08 E2 décide le montant de chaque moyen (`refundsByTender` de `@rueda/money`), la règle 10 ses jambes ; la réaffectation est rattachée au premier moyen de la cascade ; clé `…:REFUND:{moyen}:i1:a1`. Bêta (fail-closed) : seule la carte est remboursée (`NATIVE_PARTIAL`) ; un moyen non natif ou un crédit qui doit rembourser quelque chose ⇒ `REFUND_RAIL_UNAVAILABLE`, rien n'est écrit, la demande est garée avec une alerte. L'ordonnanceur (`RefundScheduler`) fait passer une instance en échec confirmé à `PENDING_CUSTOMER_CHOICE` (`attempt_no` + 1, `PgRefundOrders.awaitChoice`) dans la transaction qui pose l'alerte `FIN_REFUND_FAILED` ; aucun autre rail n'est ouvert en bêta. diff --git a/apps/api/src/modules/stl/index.ts b/apps/api/src/modules/stl/index.ts index afd96246..0b296376 100644 --- a/apps/api/src/modules/stl/index.ts +++ b/apps/api/src/modules/stl/index.ts @@ -11,14 +11,19 @@ export { TripCancellationProcessor, cancellationEvent, cancellationParams, + ordersByTender, planCancellation, registerTripCancellations, + tenderKindOf, } from './internal/trip-cancellation.js'; export type { + BetaRefundRail, CancellationFacts, CancellationOrder, CancellationOutcome, CancellationPlan, + CaptureTender, + TenderOrder, } from './internal/trip-cancellation.js'; // Ordonnanceur des remboursements planifiés (US-224c, ADR-150) export { diff --git a/apps/api/src/modules/stl/internal/refund-scheduler.test.ts b/apps/api/src/modules/stl/internal/refund-scheduler.test.ts index 284ba794..2b57652c 100644 --- a/apps/api/src/modules/stl/internal/refund-scheduler.test.ts +++ b/apps/api/src/modules/stl/internal/refund-scheduler.test.ts @@ -182,6 +182,7 @@ function answers(over: Partial> = {}): Answer if (sql.includes('payment_cmd_refund_order_for_send')) return [orderRow('TJ02b')]; if (sql.includes('payment_cmd_apply_operation_status')) return [{ outcome: 'APPLIED' }]; if (sql.includes('payment_cmd_refund_mark_alerted')) return [{ changed: true }]; + if (sql.includes('payment_cmd_refund_await_choice')) return [{ outcome: 'AWAITING_CHOICE' }]; if (sql.includes('FROM core.payment_refund_instance')) return [{ operation_id: OPERATION }]; if (sql.includes('settlement_cmd_apply_leg_movement')) return [{ outcome: 'APPLIED' }]; return new Error(`requête inattendue : ${sql}`); @@ -360,8 +361,40 @@ describe('ordonnanceur — états et refus', () => { step: 'ATTENTION', alert: { code: 'FIN_REFUND_FAILED', key: 'FAILED', errorCode: 'REFUND_FAILED' }, }); + // US-224f : marque et attente du choix d'un autre rail dans LA MÊME transaction, après l'alerte + expect(db.calls.slice(-2).map((c) => [c.sql.match(/core\.(\w+)/)?.[1], c.params])).toEqual([ + ['payment_cmd_refund_mark_alerted', [INSTANCE, 'FAILED']], + ['payment_cmd_refund_await_choice', [INSTANCE]], + ]); await s.process(due({ status: 'FAILED', operationStatus: 'FAILED', finAlert: 'FAILED' })); expect(alerts.sent.map((a) => a.code)).toEqual(['FIN_REFUND_FAILED']); + expect(db.called('payment_cmd_refund_await_choice')).toHaveLength(1); + }); + + it('US-224f : seule l’alerte d’un échec confirmé ouvre le choix du rail ; issue inconnue de la base ⇒ alerte rejouée au passage suivant', async () => { + const blocked = new FakeDb( + answers({ + payment_cmd_submit_refund: [{ outcome: 'BLOCKED', blocked_reason: 'ADVANCE_CAP_UNSET' }], + }), + ); + const s1 = new RefundScheduler({ + transactions: transactionsOf(blocked), + alerts: new Alerts(), + connectors: registryOf(new StubConnector(HONEST, () => new Error('jamais appelé'))), + }); + expect((await s1.process(due())).step).toBe('BLOCKED'); + expect(blocked.called('payment_cmd_refund_await_choice')).toEqual([]); + + const odd = new FakeDb(answers({ payment_cmd_refund_await_choice: [{ outcome: 'X' }] })); + const lines: string[] = []; + const s2 = new RefundScheduler({ + transactions: transactionsOf(odd), + alerts: new Alerts(), + connectors: registryOf(undefined), + log: (l) => lines.push(l), + }); + await s2.process(due({ status: 'FAILED', operationStatus: 'FAILED' })); + expect(lines.some((l) => l.includes('alert_deferred'))).toBe(true); }); it('issue inconnue : UNKNOWN appliqué, repris plus tard ; ordre en vol relu d’abord (aucun renvoi) puis SENT', async () => { diff --git a/apps/api/src/modules/stl/internal/refund-scheduler.ts b/apps/api/src/modules/stl/internal/refund-scheduler.ts index f1acaa0d..3af39dbf 100644 --- a/apps/api/src/modules/stl/internal/refund-scheduler.ts +++ b/apps/api/src/modules/stl/internal/refund-scheduler.ts @@ -19,8 +19,10 @@ * l'instance suit le statut de l'ordre (déclencheur de 0127 : `SENT`, `CONFIRMED`, `FAILED`) ; * 3. `CONFIRMED` prouvé : report sur les soldes des jambes (`core.settlement_cmd_apply_leg_movement`, * l'avance de Kmino décidée devient `OPEN`) ; - * 4. `FAILED` : alerte FIN `FIN_REFUND_FAILED` (une fois). Nouvelle tentative et choix du rail : - * suite (SM-8 `PENDING_CUSTOMER_CHOICE`). + * 4. `FAILED` : alerte FIN `FIN_REFUND_FAILED` (une fois) ; dans la transaction qui la marque, le + * rejet confirmé ouvre le choix d'un autre rail par le voyageur (SM-8 `PENDING_CUSTOMER_CHOICE`, + * `attempt_no` + 1, `core.payment_cmd_refund_await_choice`, US-224f, ADR-166) ; aucun autre rail + * n'est ouvert en bêta, rien n'est converti en crédit. * * Une instance ne bloque jamais les suivantes (`process` ne lève pas). Chaque état n'est signalé * qu'une fois (`fin_alert`, posé APRÈS l'envoi de l'alerte : une alerte perdue est rejouée). Les @@ -89,6 +91,9 @@ export interface RefundSchedulerDeps { readonly log?: (line: string) => void; } +/** Clé d'alerte d'une instance `FAILED` (rejet confirmé du PSP). */ +const FAILED_ALERT_KEY = 'FAILED'; + const attention = (code: RefundAlertCode, key: string, errorCode: string): RefundOutcome => ({ step: 'ATTENTION', alert: { code, key, errorCode }, @@ -126,9 +131,15 @@ export class RefundScheduler { counts: { refunds: 1 }, labels: { country: due.country, error_code: alert.errorCode }, }); - await this.#deps.transactions.run(PAYMENT_COMMAND_WORKER, (db) => - new PgRefundOrders(db).markAlerted(due.instanceId, alert.key), - ); + await this.#deps.transactions.run(PAYMENT_COMMAND_WORKER, async (db) => { + const orders = new PgRefundOrders(db); + await orders.markAlerted(due.instanceId, alert.key); + // US-224f (08 SM-8, E4) : rejet confirmé signalé ⇒ attente du choix d'un autre rail ; une + // marque sans la transition (ou l'inverse) n'est jamais validée + if (due.status === 'FAILED' && alert.key === FAILED_ALERT_KEY) { + await orders.awaitChoice(due.instanceId); + } + }); } catch (error) { // alerte ou marque impossible : rejouée au passage suivant (jamais perdue en silence) this.#log({ level: 'warn', event: 'alert_deferred', error_class: errorClass(error) }); @@ -190,7 +201,7 @@ export class RefundScheduler { return { step: outcome === 'APPLIED' ? 'REPORTED' : 'DUPLICATE' }; } case 'FAILED': - return attention('FIN_REFUND_FAILED', 'FAILED', 'REFUND_FAILED'); + return attention('FIN_REFUND_FAILED', FAILED_ALERT_KEY, 'REFUND_FAILED'); default: return { step: 'DUPLICATE' }; } diff --git a/apps/api/src/modules/stl/internal/trip-cancellation.test.ts b/apps/api/src/modules/stl/internal/trip-cancellation.test.ts index 461aed3b..496ec86e 100644 --- a/apps/api/src/modules/stl/internal/trip-cancellation.test.ts +++ b/apps/api/src/modules/stl/internal/trip-cancellation.test.ts @@ -29,9 +29,12 @@ import { cancellationParams, classify, orderKey, + ordersByTender, planCancellation, registerTripCancellations, + tenderKindOf, type CancellationFacts, + type CaptureTender, } from './trip-cancellation.js'; const golden = loadGoldenVectors(); @@ -184,6 +187,114 @@ describe('plan du règlement d’une demande (moteur unique, vecteurs de l’exp }); }); +/** + * US-224f (ADR-166) — ordres par moyen d'origine (08 E2 puis E7 règle 10). Attendus : export des + * oracles (TJ16a à TJ16d, TJ02b, TJ08b) ; montants par moyen de `check_legs.py` (`e2_refunds` : + * T33 → [150,00 ; 37,44 ; 0 ; 0], T07 → [138,22 ; 0 ; 0 ; 0]) et de `check_t49plus.py` (`allocate`, + * deux cartes : la plus récente absorbe d'abord : PYG {c2: 367, c1: 1 000 000}, USD {c2: 37,44, + * c1: 150,00}). + */ +const card = ( + id: string, + amountMinor: bigint, + committedMinor = 0n, + method = 'CARD', +): CaptureTender => ({ + operationId: id, + accountId: `acc-${id}`, + method, + amountMinor, + committedMinor, +}); +const refundsOf = (orders: ReturnType) => + orders.filter((o) => o.kind === 'REFUND'); + +describe('US-224f — remboursement réparti sur les moyens d’origine (08 E2, E7 règle 10)', () => { + it('devise sans décimale (critère 6) : D payé par deux cartes 1 000 000 et 438 050, T27 ⇒ ordres TJ16c puis TJ16d, natifs, rang 1 chacun ; Σ = TJ08b à l’unité', () => { + const { facts, trip } = factsOf('T27'); + const plan = planCancellation(facts, trip); + const orders = ordersByTender(plan, [card('c1', 1_000_000n), card('c2', 438_050n)]); + expect(orders.map((o) => [o.kind, o.tender.operationId, o.rail, o.instanceSeq])).toEqual([ + ['REFUND', 'c1', 'NATIVE_PARTIAL', 1], + ['REFUND', 'c2', 'NATIVE_PARTIAL', 1], + ]); + expect({ ...orders[0]?.legs }).toEqual(negate(legsOf('TJ16c'))); + expect({ ...orders[1]?.legs }).toEqual(negate(legsOf('TJ16d'))); + const sum = Object.fromEntries( + LEGS.map((k) => [k, (orders[0]?.legs[k] ?? 0n) + (orders[1]?.legs[k] ?? 0n)]), + ); + expect(sum).toEqual(negate(legsOf('TJ08b'))); + expect(orders.reduce((s, o) => s + o.amountMinor, 0n)).toBe(expected('T27').guestRefundMinor); + }); + + it('devise à deux décimales : A payé par deux cartes 150,00 et 106,66, T03 ⇒ ordres TJ16a puis TJ16b ; clé de chaque ordre sur son moyen', () => { + const { facts, trip } = factsOf('T03'); + const orders = ordersByTender(planCancellation(facts, trip), [ + card('c1', 15_000n), + card('c2', 10_666n), + ]); + expect({ ...orders[0]?.legs }).toEqual(negate(legsOf('TJ16a'))); + expect({ ...orders[1]?.legs }).toEqual(negate(legsOf('TJ16b'))); + expect(orders.map((o) => orderKey(facts, o, o.tender.operationId))).toEqual([ + `${TRIP_ID}:${SEGMENT_ID}:v1:REFUND:c1:i1:a1`, + `${TRIP_ID}:${SEGMENT_ID}:v1:REFUND:c2:i1:a1`, + ]); + }); + + it('moyens non natifs ENTIÈREMENT absorbés (T07 payé comme T33, E2 : [138,22 ; 0 ; 0 ; 0]) : un seul remboursement, sur la carte, du remboursement de T07', () => { + const { facts, trip } = factsOf('T07'); + const orders = ordersByTender(planCancellation(facts, trip), [ + card('card', 15_000n), + card('yappy', 5_666n, 0n, 'YAPPY'), + card('cash', 3_000n, 0n, 'CREDIT_CASH'), + card('promo', 2_000n, 0n, 'CREDIT_PROMO'), + ]); + expect(refundsOf(orders).map((o) => [o.tender.operationId, o.rail])).toEqual([ + ['card', 'NATIVE_PARTIAL'], + ]); + const refund = refundsOf(orders)[0]; + expect(refund?.amountMinor).toBe(expected('T07').guestRefundMinor); + expect(LEGS.reduce((s, k) => s + (refund?.legs[k] ?? 0n), 0n)).toBe(refund?.amountMinor); + }); + + it('fail-closed (bêta) : un moyen non natif ou un crédit cash qui doit rembourser ⇒ REFUND_RAIL_UNAVAILABLE (TJ16b Yappy, TJ16d crédit cash recréé)', () => { + const t03 = factsOf('T03'); + expect(() => + ordersByTender(planCancellation(t03.facts, t03.trip), [ + card('card', 15_000n), + card('yappy', 5_666n, 0n, 'YAPPY'), + card('cash', 3_000n, 0n, 'CREDIT_CASH'), + card('promo', 2_000n, 0n, 'CREDIT_PROMO'), + ]), + ).toThrow(new CancellationPlanError('REFUND_RAIL_UNAVAILABLE')); + const t27 = factsOf('T27'); + expect(() => + ordersByTender(planCancellation(t27.facts, t27.trip), [ + card('card', 1_000_000n), + card('cash', 438_050n, 0n, 'CREDIT_CASH'), + ]), + ).toThrow(new CancellationPlanError('REFUND_RAIL_UNAVAILABLE')); + }); + + it('aucun moyen ⇒ TRIP_NOT_CAPTURED ; moyen déjà engagé : jamais au-delà de son reliquat (REFUND_OUT_OF_RANGE)', () => { + const { facts, trip } = factsOf('T27'); + const plan = planCancellation(facts, trip); + expect(() => ordersByTender(plan, [])).toThrow(new CancellationPlanError('TRIP_NOT_CAPTURED')); + expect(() => + ordersByTender(plan, [card('c1', 1_000_000n, 1_000_000n), card('c2', 438_050n)]), + ).toThrow(SettlementError); + }); + + it('catégorie d’un moyen : la carte seule est native ; un moyen inconnu n’est jamais natif', () => { + expect(tenderKindOf('CARD')).toBe('NATIVE'); + expect(tenderKindOf('CREDIT_CASH')).toBe('CASH_CREDIT'); + expect(tenderKindOf('CREDIT_PROMO')).toBe('PROMO_CREDIT'); + for (const m of ['YAPPY', 'QR', 'CLAVE', 'PIX', 'BANK_TRANSFER', 'card', null]) { + expect(tenderKindOf(m)).toBe('NON_NATIVE'); + } + }); +}); + describe('classement des refus', () => { it('moteur, plan et base : FAILED ou FIN_REVIEW ; interblocage : RETRY ; erreur inconnue relancée', () => { expect(classify(new CancellationPlanError('QUOTE_UNAVAILABLE'))).toEqual({ @@ -281,7 +392,15 @@ describe('processeur trip_lifecycle', () => { if (sql.includes('booking_cmd_trip_settle_cancellation')) return [{ r: { costBearer: 'GUEST' } }]; if (sql.includes('payment_payment_operation')) - return [{ id: 'cap-1', psp_account_id: 'acc-1', method: 'CARD' }]; + return [ + { + id: 'cap-1', + psp_account_id: 'acc-1', + method: 'CARD', + amount_minor: '25666', + committed_minor: '0', + }, + ]; if (sql.includes('payment_cmd_plan_refund')) return [ { @@ -359,7 +478,15 @@ describe('processeur trip_lifecycle', () => { if (sql.includes('booking_cmd_trip_settle_cancellation')) return [{ r: { costBearer: 'GUEST' } }]; if (sql.includes('payment_payment_operation')) - return [{ id: 'cap-1', psp_account_id: 'acc-1', method: 'CARD' }]; + return [ + { + id: 'cap-1', + psp_account_id: 'acc-1', + method: 'CARD', + amount_minor: '25666', + committed_minor: '0', + }, + ]; if (sql.includes('payment_cmd_plan_refund')) return Object.assign(new Error('fin'), { code: '55000', @@ -381,7 +508,7 @@ describe('processeur trip_lifecycle', () => { expect(alerts.sent.map((a) => a.code)).toEqual(['FIN_SETTLEMENT_REVIEW']); }); - it('trip sans capture unique du loyer : FAILED (TRIP_NOT_CAPTURED), jamais un moyen deviné', async () => { + it('trip sans encaissement du loyer : FAILED (TRIP_NOT_CAPTURED), jamais un moyen deviné', async () => { const { facts, trip } = factsOf('T03'); const db = new FakeDb((sql) => { if (sql.includes('booking_trip_cancellation_begin')) return [beginRow(facts)]; diff --git a/apps/api/src/modules/stl/internal/trip-cancellation.ts b/apps/api/src/modules/stl/internal/trip-cancellation.ts index 85a797fd..65b27eb9 100644 --- a/apps/api/src/modules/stl/internal/trip-cancellation.ts +++ b/apps/api/src/modules/stl/internal/trip-cancellation.ts @@ -16,8 +16,9 @@ * 3. `core.settlement_cmd_record` (travailleur `settlement`), version 1 ; * 4. `core.booking_cmd_trip_settle_cancellation` (travailleur `trip_lifecycle`) : la base requalifie, * LIE le règlement à la demande et applique la transition avec `settlement_id` ; - * 5. ordres du règlement (`settlementOrders` : réaffectation d'abord, puis remboursement du moyen - * d'origine, montants explicites par jambe, jamais un prorata), rattachés à la version 1 et + * 5. ordres du règlement (`ordersByTender` : réaffectation d'abord, puis remboursement de chaque + * moyen d'origine décidé par 08 E2 et ventilé en cascade par la règle 10, US-224f, ADR-166 ; + * montants explicites par jambe, jamais un prorata), rattachés à la version 1 et * bornés par 0121 (travailleur `payment_command`) : réaffectation par la commande PAY à 15 * arguments, remboursement par l'instance `PLANNED` d'US-224b (`PgRefundPlanner.plan`) ; * la contrainte différée de 0124 exige Σ REFUND = remboursement du voyageur à la validation. @@ -38,15 +39,18 @@ import { money, settlementOrders, settlementRecordPayload, + tenderRefundOrders, type CancellationEvent, type Currency, type HostPenaltySchedule, type Leg, type Legs, type Money, + type PaidTender, type SettlementParams, type SettlementRecord, type SettlementTrip, + type TenderKind, } from '@rueda/money'; import type { AlertChannel, BusRegistry, SqlClient, WorkerTransactions } from '../../bus/index.js'; import { @@ -115,6 +119,8 @@ export interface CancellationOrder { export interface CancellationPlan { readonly record: SettlementRecord; + /** Devise du trip (configuration du pays), pour les ordres par moyen (US-224f). */ + readonly currency: Currency; readonly orders: readonly CancellationOrder[]; } @@ -217,13 +223,7 @@ export function planCancellation(f: CancellationFacts, trip: SettlementTrip): Ca const params = cancellationParams(f.params, trip.currency); const rec = buildSettlementRecord(trip, cancellationEvent(f), params); const currency = trip.currency; - const variationRow = Object.fromEntries( - rec.legs.map((l) => [l.leg, money(l.variationMinor, currency)]), - ) as Record; - const variation: Legs = Object.freeze({ - ...variationRow, - total: money(-rec.guestRefundMinor, currency), - }); + const variation = variationOf(rec, currency); const refund = money(rec.guestRefundMinor, currency); const orders = settlementOrders( variation, @@ -243,7 +243,120 @@ export function planCancellation(f: CancellationFacts, trip: SettlementTrip): Ca instanceSeq: i + 1, }); }); - return { record: rec, orders: out }; + return { record: rec, currency, orders: out }; +} + +/** Variation signée des jambes d'un règlement (`settlement_leg.variation_minor`, 08 E7 règle 3). */ +function variationOf(rec: SettlementRecord, currency: Currency): Legs { + const variationRow = Object.fromEntries( + rec.legs.map((l) => [l.leg, money(l.variationMinor, currency)]), + ) as Record; + return Object.freeze({ ...variationRow, total: money(-rec.guestRefundMinor, currency) }); +} + +/** + * Encaissement réussi du loyer d'un trip : un moyen d'origine de 08 E2 (US-224f, ADR-166), lu par + * `tendersOf` dans l'ordre des captures (la plus ancienne d'abord). + */ +export interface CaptureTender { + readonly operationId: string; + readonly accountId: string; + readonly method: string | null; + /** Payé par ce moyen, devise du trip. */ + readonly amountMinor: bigint; + /** Déjà engagé sur ce moyen : instances SM-8 hors `CANCELLED` et `SUPERSEDED` (08 E2). */ + readonly committedMinor: bigint; +} + +/** Rail de remboursement de bêta : natif seulement (08 E3 ; ADR-147, ADR-166). */ +export type BetaRefundRail = 'NATIVE_PARTIAL'; + +/** Ordre d'un règlement rattaché à son moyen d'origine (remboursement : avec son rail). */ +export interface TenderOrder extends CancellationOrder { + readonly tender: CaptureTender; + readonly rail: BetaRefundRail | null; +} + +/** Ordre de la cascade de 08 E7 règle 10 (natif → non natif → crédit cash → crédit promo). */ +const TENDER_ORDER: readonly TenderKind[] = ['NATIVE', 'NON_NATIVE', 'CASH_CREDIT', 'PROMO_CREDIT']; + +/** + * Catégorie de 08 E2 d'un moyen (PROPOSÉ, ADR-166) : la carte est le seul moyen natif de la bêta + * (`NATIVE_PARTIAL`, ADR-147) ; crédit cash et crédit promo sont des moyens de Kmino ; tout autre + * moyen (Yappy, QR, virement, inconnu) est non natif. Un moyen inconnu n'est jamais supposé natif. + */ +export function tenderKindOf(method: string | null): TenderKind { + if (method === 'CARD') return 'NATIVE'; + if (method === 'CREDIT_CASH') return 'CASH_CREDIT'; + if (method === 'CREDIT_PROMO') return 'PROMO_CREDIT'; + return 'NON_NATIVE'; +} + +/** + * Ordres d'un règlement sur les moyens d'origine (fonction pure, US-224f, ADR-166) : 08 E2 décide le + * montant de chaque moyen, la règle 10 ses jambes (`tenderRefundOrders`) ; réaffectation d'abord + * (règle 3), rattachée au premier moyen de la cascade. Rail de bêta (fail-closed, 08 E3, SM-8) : un + * moyen non natif ou un crédit qui doit rembourser quelque chose exige le choix du voyageur + * (`PENDING_CUSTOMER_CHOICE`) ou un crédit cash recréé, tous deux fermés en bêta (aucune coordonnée + * bancaire stockée, `funds_holding_enabled` = false) ⇒ `REFUND_RAIL_UNAVAILABLE` : rien n'est écrit, + * la demande est garée avec une alerte, jamais un remboursement partiel ni un autre moyen deviné. + */ +export function ordersByTender( + plan: CancellationPlan, + tenders: readonly CaptureTender[], +): readonly TenderOrder[] { + const currency = plan.currency; + const variation = variationOf(plan.record, currency); + if (!LEGS.some((leg) => variation[leg].amountMinor !== 0n)) return []; + if (tenders.length === 0) throw new CancellationPlanError('TRIP_NOT_CAPTURED'); + const paid: PaidTender[] = tenders.map((t, i) => ({ + id: t.operationId, + kind: tenderKindOf(t.method), + paid: money(t.amountMinor, currency), + committed: money(t.committedMinor, currency), + capturedRank: i + 1, + })); + const byId = new Map(tenders.map((t) => [t.operationId, t])); + const tenderOf = (id: string): CaptureTender => { + const t = byId.get(id); + if (t === undefined) throw new CancellationPlanError('ROW_SHAPE'); + return t; + }; + const orders = tenderRefundOrders(variation, paid); + const out: TenderOrder[] = []; + if (orders.reallocation !== null) { + // premier moyen de la cascade (catégorie, puis capture la plus ancienne) : clé et compte + const first = [...paid].sort( + (a, b) => + TENDER_ORDER.indexOf(a.kind) - TENDER_ORDER.indexOf(b.kind) || + a.capturedRank - b.capturedRank, + )[0]; + if (first === undefined) throw new CancellationPlanError('TRIP_NOT_CAPTURED'); + const legs = legAmounts(orders.reallocation); + const amount = LEGS.reduce((s, leg) => (legs[leg] > 0n ? s + legs[leg] : s), 0n); + out.push({ + kind: 'LEG_REALLOCATION', + amountMinor: amount, + legs, + instanceSeq: 1, + tender: tenderOf(first.id), + rail: null, + }); + } + for (const r of orders.refunds) { + if (r.kind !== 'NATIVE') throw new CancellationPlanError('REFUND_RAIL_UNAVAILABLE'); + out.push({ + kind: 'REFUND', + amountMinor: r.legs.total.amountMinor, + legs: legAmounts(r.legs), + // 08 E4 : rang de l'instance parmi celles du même (règlement, REFUND, moyen) ; une seule par + // moyen à la version 1 + instanceSeq: 1, + tender: tenderOf(r.id), + rail: 'NATIVE_PARTIAL', + }); + } + return out; } // ------------------------------------------------------------------ accès à la base (production) @@ -447,24 +560,29 @@ export class TripCancellationProcessor { [f.cancellationId, settlementId], ); const costBearer = text(settled[0]?.r.costBearer); + let count = 0; if (plan.orders.length > 0) { await asWorker(db, PAYMENT_COMMAND_WORKER); - const capture = await captureOf(db, f.tripId); + // US-224f (ADR-166) : chaque moyen d'origine rembourse ce que lui donne 08 E2, jambes en + // cascade (règle 10) ; Σ remboursements = remboursement du voyageur (contrainte différée 0124) + const orders = ordersByTender(plan, await tendersOf(db, f.tripId, f.currency)); + count = orders.length; const recorder = new PgOperationRecorder(db); const refunds = new PgRefundPlanner(db); - for (const o of plan.orders) { - const idemPlain = orderKey(f, o, capture.operationId); + for (const o of orders) { + const idemPlain = orderKey(f, o, o.tender.operationId); const idemSent = idempotencyKeyToSend(idemPlain, PSP_IDEMPOTENCY_MAX_LENGTH); if (o.kind === 'REFUND') { // US-224b (ADR-147) : un remboursement naît d'une instance PLANNED (SM-8), rail du moyen // d'origine ; son envoi au PSP est le service d'US-224 (aucun PSP réel avant le lot C) + if (o.rail === null) throw new CancellationPlanError('REFUND_RAIL_UNAVAILABLE'); await refunds.plan({ instanceId: randomUUID(), operationId: randomUUID(), settlementId, - refundedOperationId: capture.operationId, + refundedOperationId: o.tender.operationId, instanceSeq: o.instanceSeq, - rail: 'NATIVE_PARTIAL', + rail: o.rail, legs: o.legs, idemPlain, idemSent, @@ -475,8 +593,8 @@ export class TripCancellationProcessor { id: randomUUID(), holdId: null, tripId: f.tripId, - pspAccountId: capture.accountId, - method: capture.method, + pspAccountId: o.tender.accountId, + method: o.tender.method, kind: o.kind, purpose: 'RENT', amountMinor: o.amountMinor, @@ -489,7 +607,7 @@ export class TripCancellationProcessor { }); } } - return { outcome: 'SETTLED', costBearer, orders: plan.orders.length } as const; + return { outcome: 'SETTLED', costBearer, orders: count } as const; } async #park(cancellationId: string, status: 'FIN_REVIEW' | 'FAILED', code: string) { @@ -503,27 +621,50 @@ export class TripCancellationProcessor { } } -/** Capture réussie du loyer du trip (moyen et compte d'origine du remboursement). */ -async function captureOf( +/** + * Moyens d'origine du trip (US-224f, ADR-166) : encaissements RÉUSSIS du loyer dans la devise du + * trip (capture, débit MIT, recouvrement : mêmes natures que `core.payment_cmd_plan_refund`), dans + * l'ordre des captures, avec ce qui est déjà engagé sur chacun (instances SM-8 hors `CANCELLED` et + * `SUPERSEDED`, 08 E2). Un encaissement dans une autre devise n'est pas un moyen : le remboursement + * dépasse alors Σ payé et la demande est garée (fail-closed, aucune conversion en bêta). + */ +async function tendersOf( db: SqlClient, tripId: string, -): Promise<{ operationId: string; accountId: string; method: string | null }> { - const { rows } = await db.query<{ id: string; psp_account_id: string; method: string | null }>( - `SELECT o.id, o.psp_account_id, o.method + currency: string, +): Promise { + const { rows } = await db.query>( + `SELECT o.id, o.psp_account_id, o.method, o.amount_minor::text AS amount_minor, + COALESCE(e.engaged, 0)::text AS committed_minor FROM core.payment_payment_operation AS o - WHERE o.kind = 'CAPTURE' AND o.purpose = 'RENT' AND o.status = 'SUCCEEDED' + LEFT JOIN LATERAL (SELECT pg_catalog.sum(ri.amount_trip_minor) AS engaged + FROM core.payment_refund_instance AS ri + WHERE ri.refunded_operation_id = o.id + AND ri.status NOT IN ('CANCELLED', 'SUPERSEDED')) AS e ON true + WHERE o.kind IN ('CAPTURE', 'MIT_CHARGE', 'DEBT_COLLECTION') + AND o.purpose IN ('RENT', 'RENT_SHORTFALL', 'NO_SHOW_RETENTION') + AND o.status = 'SUCCEEDED' AND o.currency = $2 AND (o.trip_id = $1::uuid OR o.hold_id = (SELECT t.source_hold_id FROM core.booking_trip AS t - WHERE t.id = $1::uuid))`, - [tripId], + WHERE t.id = $1::uuid)) + ORDER BY o.created_at, o.id`, + [tripId, currency], ); - // bêta : une seule capture du loyer ; aucune ou plusieurs ⇒ refus (jamais un moyen deviné) - if (rows.length !== 1 || rows[0] === undefined) { - throw new CancellationPlanError('TRIP_NOT_CAPTURED'); - } - return { operationId: rows[0].id, accountId: rows[0].psp_account_id, method: rows[0].method }; + return rows.map((r) => ({ + operationId: text(r['id']), + accountId: text(r['psp_account_id']), + method: textOrNull(r['method']), + amountMinor: minorOf(r['amount_minor']), + committedMinor: minorOf(r['committed_minor']), + })); } +const minorOf = (v: unknown): bigint => { + const s = text(v); + if (!/^[0-9]{1,18}$/.test(s)) throw rowShape(); + return BigInt(s); +}; + /** * Clé d'idempotence d'un ordre (08 E4) : `{trip}:{segment}:v1:{opération}:{moyen}:i{n}:a1`, le * moyen étant la capture d'origine. La réaffectation n'est pas une opération du PSP de 08 E4 : sa @@ -575,6 +716,8 @@ export function classifyOrUnexpected(error: unknown): CancellationOutcome { const FIN_CONSTRAINTS = new Set([ 'operation_settlement_fin_review', 'refund_exceeds_collected', + // US-224f (08 E2) : jamais plus que le payé d'un moyen + 'refund_exceeds_tender', 'advance_decision_required', ]); /** Interblocage, sérialisation : reprise au passage suivant. */ diff --git a/apps/backoffice/app/console/cancel-view.test.tsx b/apps/backoffice/app/console/cancel-view.test.tsx index d8ebfd12..ee60806b 100644 --- a/apps/backoffice/app/console/cancel-view.test.tsx +++ b/apps/backoffice/app/console/cancel-view.test.tsx @@ -279,7 +279,9 @@ describe('annulation (215b) : étapes', () => { 'NOT_FOUND', ].sort(), ); - expect(Object.keys(CANCEL_OUTCOME_KEYS)).toHaveLength(13); + // US-224f (ADR-166) : trois codes ajoutés (REFUND_RAIL_UNAVAILABLE, REFUND_RAIL_NOT_NATIVE, + // REFUND_EXCEEDS_TENDER), chacun contrôlé ci-dessus dans les quatre langues + expect(Object.keys(CANCEL_OUTCOME_KEYS)).toHaveLength(16); }); }); diff --git a/apps/backoffice/app/console/cancel-view.tsx b/apps/backoffice/app/console/cancel-view.tsx index e1360e22..08fe9fb6 100644 --- a/apps/backoffice/app/console/cancel-view.tsx +++ b/apps/backoffice/app/console/cancel-view.tsx @@ -147,6 +147,10 @@ export const CANCEL_OUTCOME_KEYS: Readonly> = { REFUND_EXCEEDS_COLLECTED: 'backoffice.cancel.outcome.REFUND_EXCEEDS_COLLECTED', ADVANCE_DECISION_REQUIRED: 'backoffice.cancel.outcome.ADVANCE_DECISION_REQUIRED', SETTLEMENT_INPUT_INVALID: 'backoffice.cancel.outcome.SETTLEMENT_INPUT_INVALID', + // US-224f (ADR-166) : remboursement réparti sur les moyens d'origine + REFUND_RAIL_UNAVAILABLE: 'backoffice.cancel.outcome.REFUND_RAIL_UNAVAILABLE', + REFUND_RAIL_NOT_NATIVE: 'backoffice.cancel.outcome.REFUND_RAIL_NOT_NATIVE', + REFUND_EXCEEDS_TENDER: 'backoffice.cancel.outcome.REFUND_EXCEEDS_TENDER', }; /** Libellés des trois actions (catalogue de la console, US-101). */ diff --git a/apps/web/account/trip-refunds.test.ts b/apps/web/account/trip-refunds.test.ts index 6f751a03..4a0422cd 100644 --- a/apps/web/account/trip-refunds.test.ts +++ b/apps/web/account/trip-refunds.test.ts @@ -74,7 +74,8 @@ describe('tripRefundsOf', () => { expect(Object.fromEntries(REFUND_STATUSES.map((s) => [s, phaseOf(s)]))).toEqual({ PLANNED: 'PREPARING', BLOCKED_CHARGEBACK: 'ATTENTION', - PENDING_CUSTOMER_CHOICE: 'PREPARING', + // US-224f (ADR-166) : en bêta, attente d'un autre moyen après un rejet confirmé + PENDING_CUSTOMER_CHOICE: 'ATTENTION', PENDING_BANK_DETAILS: 'PREPARING', SUBMITTED: 'ISSUED', SENT: 'ISSUED', diff --git a/apps/web/account/trip-refunds.ts b/apps/web/account/trip-refunds.ts index 9af7fef3..954faa85 100644 --- a/apps/web/account/trip-refunds.ts +++ b/apps/web/account/trip-refunds.ts @@ -4,11 +4,14 @@ * inattendue ⇒ `null`, l'écran dit l'erreur, jamais un remboursement partiel ou deviné). Le voyageur * reçoit le montant, le rail et la date d'émission ; l'hôte la seule part de la jambe HOST. Les * états SM-8 sont regroupés pour la personne (jamais un état technique à l'écran) : - * - `PREPARING` : planifié ou en attente (PLANNED, PENDING_*), la date d'émission n'existe pas encore ; + * - `PREPARING` : planifié (PLANNED, PENDING_BANK_DETAILS), la date d'émission n'existe pas encore ; * - `ISSUED` : émission autorisée ou envoyée (SUBMITTED, SENT, CREDITED) : « Émis le … » ; * - `CONFIRMED` : le prestataire de paiement a confirmé (CONFIRMED) ; - * - `ATTENTION` : refus du prestataire ou contestation bancaire (FAILED, BLOCKED_CHARGEBACK) : - * l'équipe s'en occupe, aucune action demandée. + * - `ATTENTION` : refus du prestataire, contestation bancaire ou autre moyen à convenir (FAILED, + * BLOCKED_CHARGEBACK, PENDING_CUSTOMER_CHOICE) : l'équipe s'en occupe, aucune action demandée. + * US-224f (ADR-166) : en bêta, PENDING_CUSTOMER_CHOICE ne suit qu'un rejet confirmé du moyen + * d'origine et aucun autre rail n'est ouvert au voyageur : rien ne se « prépare », l'équipe le + * contacte (aucun choix proposé à l'écran tant que le virement et le crédit sont fermés). * Côté serveur seulement ; jamais de donnée personnelle dans une URL ni dans un journal. */ import type { ApiResult } from './api-client.ts'; @@ -42,7 +45,6 @@ export type RefundPhase = 'PREPARING' | 'ISSUED' | 'CONFIRMED' | 'ATTENTION'; export function phaseOf(status: RefundStatus): RefundPhase | null { switch (status) { case 'PLANNED': - case 'PENDING_CUSTOMER_CHOICE': case 'PENDING_BANK_DETAILS': return 'PREPARING'; case 'SUBMITTED': @@ -53,6 +55,7 @@ export function phaseOf(status: RefundStatus): RefundPhase | null { return 'CONFIRMED'; case 'FAILED': case 'BLOCKED_CHARGEBACK': + case 'PENDING_CUSTOMER_CHOICE': return 'ATTENTION'; case 'CANCELLED': case 'SUPERSEDED': diff --git a/changelog.d/US-224-multi-moyens.md b/changelog.d/US-224-multi-moyens.md new file mode 100644 index 00000000..9b6759f1 --- /dev/null +++ b/changelog.d/US-224-multi-moyens.md @@ -0,0 +1,6 @@ +lot: L2 +module: Règlement et finance + +- Ajouté : un trip payé en plusieurs fois est remboursé sur chacun de ses moyens d'origine, du montant que donne la règle d'imputation (la part retenue est prise d'abord sur les crédits et les moyens sans remboursement partiel, la carte est remboursée en priorité), chaque remboursement portant le montant exact de chaque jambe, jamais un prorata (US-224) +- Ajouté : après un refus confirmé du prestataire, le remboursement attend un autre moyen de remboursement (nouvelle tentative numérotée) ; en bêta, aucun autre moyen n'est ouvert : l'équipe s'en occupe et le voyageur voit « en cours de vérification » (US-224) +- Sécurité : la base refuse tout remboursement d'un moyen au-delà de ce qu'il a payé (remboursements en échec compris), un remboursement par carte sur un autre moyen, et ne recrée jamais de crédit tant que la détention de fonds est fermée ; une annulation qui l'exigerait est garée pour FINANCE, rien n'est écrit (US-224) diff --git a/docs/adr/ADR-166-remboursement-multi-moyens.md b/docs/adr/ADR-166-remboursement-multi-moyens.md new file mode 100644 index 00000000..360928d1 --- /dev/null +++ b/docs/adr/ADR-166-remboursement-multi-moyens.md @@ -0,0 +1,34 @@ +# ADR-166 — Remboursement réparti sur les moyens d'origine (TJ16) et reprise après un échec confirmé + +- **Statut** : PROPOSÉ (US-224 partie 224f, agent argent / back-end, claude-opus-5-5, 2026-11-18). Revues exigées : voir `check-story-reviews.mjs` (argent, RLS, rôles, `SECURITY DEFINER` et concurrence sur un autre modèle que l'auteur). À reporter dans 17 §3.2.7 (garde de l'instance), §4.3 (commandes) et 16 A.8 (codes garés). +- **Complète** : ADR-145 (ordres de règlement, 0121), ADR-147 (instance SM-8, rails de bêta, 0123), ADR-148 (annulations réglées dans la transition, 0124), ADR-150 (ordonnanceur, 0127), ADR-154 (lecture S10, 0130). +- **Sources** : 19 US-224 critère 6 ; 08 E1 (`refund_committed`), E2 (imputation incrémentale, ordre d'absorption), E3 (rails, `CREDIT_CASH` et `funds_holding_enabled`), E4 (`instance_seq`, `attempt_no`), E7 règle 10 (cascade, deux ordres distincts), SM-8 ; vecteurs T33, T66 b, TJ15a à TJ15d, TJ16a à TJ16d, TJ20a ; BOARD N-238. + +## Contexte + +Jusqu'à 224e, le processeur des annulations (STL, ADR-148) remboursait **une seule capture** (`captureOf` refusait un trip encaissé en plusieurs fois) et la base ne bornait un remboursement qu'au niveau du trip (0121). 08 prévoit au contraire un remboursement réparti par E2 sur les moyens d'origine, chaque moyen remboursé au plus de son reliquat, puis ventilé par jambe en cascade (règle 10, TJ16) ; un échec confirmé du rail ouvre le choix d'un autre rail par le voyageur (SM-8 `FAILED → PENDING_CUSTOMER_CHOICE`, `attempt_no` + 1). TJ16d est une **réémission de crédit cash** : un solde du voyageur détenu par Kmino, ouvert en production seulement si `funds_holding_enabled[pays]` = true (E3). + +## Décision + +1. **E2 dans `@rueda/money`** : `refundsByTender` (imputation incrémentale : `refundable[m] = max(0, payé[m] − engagé[m])` ; `K'` absorbé crédit promo → crédit cash → non natif → natif, la capture la plus récente d'abord ; chaque moyen reçoit `refundable[m] − absorbé[m]`) et `tenderRefundOrders` (E2 puis la cascade existante `settlementOrders`, identité du moyen conservée). Fonctions pures, sans division ; dépassement de Σ reliquats ⇒ `REFUND_OUT_OF_RANGE`. Les chargebacks perdus ne sont pas modélisés (aucun en bêta). +2. **STL** : `tendersOf` lit tous les encaissements réussis du loyer du trip (mêmes natures que `payment_cmd_plan_refund`, devise du trip, ordre des captures) avec ce qui est engagé sur chacun ; `ordersByTender` rattache chaque ordre à son moyen (clé `…:REFUND:{moyen}:i1:a1`), la réaffectation au premier moyen de la cascade. Catégorie d'un moyen (PROPOSÉ) : `CARD` = natif ; `CREDIT_CASH`, `CREDIT_PROMO` = crédits ; tout autre moyen ou un moyen inconnu = non natif (jamais supposé natif). +3. **Rail de bêta, fail-closed** : seul le remboursement natif d'une carte existe. Un moyen non natif ou un crédit qui doit rembourser quelque chose (TJ16b au PA, TJ16d au PY) ⇒ `REFUND_RAIL_UNAVAILABLE` : **rien n'est écrit** (ni règlement, ni ordre), la demande d'annulation est garée avec une alerte P1 et FINANCE la traite. Jamais un remboursement partiel silencieux (la contrainte différée de 0124 l'interdit), jamais un autre moyen deviné, jamais une conversion en crédit (08 E3). Un moyen non natif **entièrement absorbé** par E2 (T07 payé comme T33) ne bloque rien. +4. **Invariant de E2 en base, pour tout appelant** (0141, `payment_cmd_plan_refund`) : Σ instances du moyen, toutes versions, hors `CANCELLED` et `SUPERSEDED` (donc `FAILED` et `PENDING_CUSTOMER_CHOICE` compris : l'obligation subsiste) ≤ payé par ce moyen (`refund_exceeds_tender` ⇒ `REFUND_EXCEEDS_COLLECTED`, revue FIN) ; contrôlé après la garde du trip de 0121, sous le verrou du trip. Rail natif (`NATIVE_PARTIAL`, `ROLLBACK_AND_RECHARGE`) sur une carte seulement (`refund_rail_not_native`) ; moyen remboursé dans la devise du trip seulement. +5. **Reprise après un échec confirmé** : `core.payment_cmd_refund_await_choice` (`SECURITY DEFINER`, `cmd_money_owner`, EXECUTE `app_worker`, travailleur `payment_command`) fait passer une instance `FAILED` dont l'ordre est `FAILED` (rejet reçu, aucun fonds sorti) à `PENDING_CUSTOMER_CHOICE`, `attempt_no` + 1 ; un ordre `UNKNOWN` ou `SUBMITTED` garde sa clé (08 E4, EC-29). L'ordonnanceur l'appelle dans la transaction qui pose l'alerte `FIN_REFUND_FAILED`. La garde n'admet un changement d'`attempt_no` que sur cette transition (+1 exactement) ; `PENDING_CUSTOMER_CHOICE → SUPERSEDED` à la version n+1 (supersession étendue). Aucun autre rail n'est ouvert en bêta : l'instance attend (08 E3 : « aucune conversion automatique en crédit »). +6. **S10** : `PENDING_CUSTOMER_CHOICE` est montré au voyageur comme « en cours de vérification » (l'équipe s'en occupe), plus « en préparation » : en bêta, il ne suit qu'un rejet confirmé et aucun choix n'est proposé. Aucun nouveau texte visible du voyageur ; trois codes garés de la console (catalogue v81, quatre langues). + +## Alternatives écartées + +- **Rembourser la part carte et laisser le reliquat non natif en attente** : impossible sans écrire une instance sans ordre (contrainte différée de 0124 : Σ REFUND = remboursement du voyageur) ; un remboursement partiel validé masquerait l'obligation restante. Fail-closed : rien n'est écrit, FIN décide. +- **Crédit cash recréé en bêta** (TJ16d exécuté) : fonds de tiers détenus ; interdit tant que `funds_holding_enabled` = false (CLAUDE.md point 4, 0123 inchangé : refusé en bêta quelle que soit la valeur). +- **E2 recalculé en SQL** : double source du calcul ; la base tient l'invariant (jamais plus que le reliquat d'un moyen), le calcul reste unique dans `@rueda/money`. +- **Nouvelle instance `i2` après un échec** : 08 E4 réserve `instance_seq` + 1 à une nouvelle obligation ; une nouvelle tentative est `attempt_no` + 1 de la même instance. La base le refuse désormais (`refund_exceeds_tender`). +- **Passage automatique en `PENDING_CUSTOMER_CHOICE` dans le déclencheur de l'ordre** : l'alerte FIN de l'échec serait sautée ; la transition suit l'alerte, dans la même transaction que sa marque. + +## Limites et conséquences (suites) + +- Choix du rail par le voyageur sur S10 et virement vers un compte vérifié à son nom (OQ-BR-12, `PENDING_BANK_DETAILS`, lot C) ; l'instance garde son ordre `FAILED` d'origine jusque-là (un nouvel ordre `…:a2` naîtra avec le rail choisi). +- Crédit cash recréé (TJ16d exécuté) : seulement après l'ouverture de `funds_holding_enabled[pays]` par décision écrite du fondateur (commande à deux personnes de 17 v6). +- Relances J+1, J+3, J+7 et sort des sommes non réclamées (OQ-BR-44). +- Un encaissement par crédit (`CREDIT_CASH`, `CREDIT_PROMO`) peut être enregistré par `payment_cmd_record_operation` (aucun contrôle du moyen) alors que les crédits n'existent pas en bêta : refus à la capture à ajouter (US-223 ou lot C). +- Chargebacks perdus dans le reliquat d'un moyen (E5) ; FX entre devise de capture et devise du trip. diff --git a/docs/architecture/schema.md b/docs/architecture/schema.md index dae31b45..50cab9d1 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 -- 141 migrations ; 127 tables ; 3 vues ; 714 politiques RLS ; 284 fonctions `SECURITY DEFINER` ; 249 autres fonctions. +- 142 migrations ; 127 tables ; 3 vues ; 714 politiques RLS ; 285 fonctions `SECURITY DEFINER` ; 249 autres fonctions. - Tables sans RLS `ENABLE` + `FORCE` : aucune. - Rôles applicatifs avec `SUPERUSER` ou `BYPASSRLS` : aucun. @@ -156,6 +156,7 @@ Lu dans le catalogue (`pg_catalog`) d'une base jetable du banc, après les seule | `0138_booking_trip_constancia_read` | CTR / AVL : constancia d'arrendamiento d'un trip et recherche de l'hôte par plaque et date | | `0139_settlement_host_ledger_advance_receivable` | STL : créance de l'hôte de la règle 3 bis portée au `host_ledger` (avance de Kmino). | | `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 | ## Rôles @@ -6542,6 +6543,7 @@ Chacune a un propriétaire `NOLOGIN` dédié (ADR-053) et un `search_path` figé | `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_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 | | `core.payment_cmd_refund_mark_alerted(p_instance_id uuid, p_key text)` | `boolean` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `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 | diff --git a/docs/ops/GO_LIVE_CHECKLIST.md b/docs/ops/GO_LIVE_CHECKLIST.md index 3ef59ca3..ce71dd9b 100644 --- a/docs/ops/GO_LIVE_CHECKLIST.md +++ b/docs/ops/GO_LIVE_CHECKLIST.md @@ -67,6 +67,7 @@ | GL-38 | **Reçu des gains de l'hôte et facture du trip fee avant l'ouverture d'un pays** (US-217 partie 217a, ADR-161). **Existe** (bêta, sur `FAKE`) : reçu des gains par trip et relevé mensuel de l'hôte titulaire (jambe HOST de la version en tête du règlement ou de la capture, plan et part figés, frais retenus par Kmino, pénalité du `host_ledger` en ligne séparée), reçu du paiement et du trip fee du voyageur (taxe de ligne du devis figé), lus de l'état stocké ; invariant par jambe dans le rapprochement de nuit (`TRIP_CAPTURE_LEGS`, `TRIP_SETTLED_TOTAL`, `STATEMENT_HOST_LEG`, alerte P1). **Manque avant l'ouverture d'un pays** : entité qui facture le trip fee et ses mentions légales par pays (ADR-013, OQ-MK-06 ; `finance_legal_entity` vide, la production refuse de démarrer) ; facture électronique PAC / SIFEN réelle (US-604, lot C ; hors plateforme jusque-là, FIN-002 MANUEL) ; avis comptable sur la taxe du trip fee retenu après une annulation (OQ-BR-14) ; écrans A08 et S09 (Bêta L3) ; relevé annuel (FIN-018, lot 5). | | GL-39 | **Constancia, centre juridique et mention d'intermédiaire validés par l'avocat** (US-212, ADR-162 ; OQ-MK-01, OQ-BR-24, OQ-BR-19). **Existe** (bêta) : constancia d'arrendamiento rendue à la demande depuis le contrat figé (es fait foi + langue du lecteur, `ctr.constancia.*` version 1 **BROUILLON**), recherche de l'hôte par plaque et date, centre juridique `/legal` (`web.legalCenter.*` version 1 **BROUILLON** : intermédiaire entre particuliers, médiation puis voies externes, loi du lieu du trip). **À faire avant l'ouverture d'un pays** : textes validés par l'avocat et chargés (US-606 : `CONSTANCIA_TEMPLATE_DRAFT` et `LEGAL_CENTER_DRAFT` à `false`, nouvelle version) ; nom complet du conducteur sur la constancia si l'avocat l'exige ; voies externes nommées par pays ; contact du support (SUP-004) ; mention d'intermédiaire et hôte en prénom et initiale au checkout et sur le reçu (critère 3 d'US-212). | | 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`) | | # | 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 f2524688..cfd4eda6 100644 --- a/docs/team/COMME_TURO.md +++ b/docs/team/COMME_TURO.md @@ -11,6 +11,7 @@ Règles : | Date | Story | Question | Solution de Turo | Source | Adaptation Kmino | Statut | | ---------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| 2026-11-18 | US-224f | Trip payé avec plusieurs moyens et annulé : sur quel moyen, et combien sur chacun, rembourse-t-on ? | le remboursement revient sur les moyens d'origine ; ce qui avait été payé en crédit revient en crédit ; si le remboursement échoue, la plateforme convient d'un autre moyen avec le voyageur | 08 E2 (T33, T66), E3, SM-8, TJ16 | carte remboursée en priorité, chaque moyen au plus de ce qu'il a payé ; en bêta, seule la carte est remboursée automatiquement ; crédit jamais recréé tant que `funds_holding_enabled` = false ; refus du prestataire ⇒ attente d'un autre rail, l'équipe s'en occupe (ADR-166) | PROPOSÉ | | 2026-11-18 | US-224e | Kmino a avancé au voyageur la part d'un hôte déjà versé : quand et combien l'hôte doit-il ? | l'hôte doit exactement ce que la plateforme a avancé pour lui, retenu ensuite sur ses gains suivants | 08 E7 règle 3 bis, TJ18b / TJ18d | créance `RELEASED_LEG_ADVANCE` du montant de l'avance, écrite au `host_ledger` au moment où le remboursement est reporté (jamais avant la décision FINANCE), une par avance ; recouvrement : US-709 | PROPOSÉ | | 2026-11-18 | US-224e | Hôte défaillant : comment ses trips à venir sont-ils annulés et ses voyageurs remboursés ? | la plateforme suspend l'hôte, annule ses réservations à venir et rembourse chaque voyageur en entier ; l'hôte ne reçoit rien pour ces trips | 08 BR-TRUST-09, BR-CXL-14 (`HOST_ACCOUNT_CLOSED`, table n° 13) | action de console `CANCEL_HOST_TRIPS` sur un hôte déjà restreint : une annulation `HOST_ACCOUNT_CLOSED` par trip à venir, remboursement intégral par le règlement, sans pénalité (sanctions : fondateur) | PROPOSÉ | | 2026-11-18 | N-83 (US-113) | Classe de valeur d'un véhicule que le catalogue ne classe pas (douane, hors catalogue) : laquelle, sans le sous-assurer ? | la classe suit la valeur : la plupart des voitures sont standard ; les marques et modèles chers vont en classe haute (âge, caution propres) ; aucune démarche de l'hôte | 08 BR-ACC-05 (help:deluxe-class-and-super-deluxe-class-eligibility-Syv7H4lV5, cité par 08) | à la publication : classe de la variante, sinon règle de marque ou de modèle (valeur haute en PREMIUM ou LUXE, jamais en STANDARD), sinon défaut du pays `vehicle_default_value_class` = STANDARD ; provenance gardée ; aucun interrupteur touché ; à confirmer avec l'assureur (ADR-159) | PROPOSÉ | diff --git a/docs/team/POUR_LE_FONDATEUR.md b/docs/team/POUR_LE_FONDATEUR.md index 93f7d8ca..46113ffe 100644 --- a/docs/team/POUR_LE_FONDATEUR.md +++ b/docs/team/POUR_LE_FONDATEUR.md @@ -76,7 +76,7 @@ Pour chaque point : ce qu'on sait, puis **ma suggestion** (comme Turo, avec le m → **Suggestion** : la générer sur un poste hors ligne, sans l'envoyer à personne, garder deux copies chiffrées de la clé privée à deux endroits différents, et ne donner que l'empreinte publique à l'équipe. Aucune limite pour les hôtes : cela ne touche que la sortie des données de la plateforme. **2.10 Avance de Kmino au voyageur quand la part de l'hôte est déjà versée** (US-224, risque L2-PM-17). Si un trip est remboursé après que la part de l'hôte lui a été versée, il manque de l'argent pour rembourser le voyageur. Tant que tu n'as pas fixé de plafond (`host_advance_cap_minor`, `platform_reserve_minor`), le défaut prudent bloque : le remboursement attend une décision FINANCE à deux personnes, et le voyageur attend. -→ **Suggestion** (comme Turo, le moins de limites possible) : **le voyageur est toujours remboursé tout de suite** ; Kmino avance la somme et la reprend sur les versements suivants de l'hôte (déjà retenu : `COMME_TURO.md`, solde d'hôte négatif). Il te reste à fixer deux montants : le plafond d'avance par hôte, et la réserve totale que Kmino accepte d'avancer par pays. Au lancement, un plafond par hôte égal à un trip moyen et une petite réserve suffisent ; on les relève avec l'usage. _(État au 2026-11-17, US-224 partie 224b, PR #202 : l'avance est construite. Le voyageur reçoit toujours le montant complet ; mais tant que tu n'as pas fixé le plafond par hôte, et tant que le solde de Kmino chez le PSP n'est pas lisible (connecteur réel, lot C), **chaque avance attend une décision de deux personnes FINANCE** avant de partir : c'est le défaut prudent, il retarde le voyageur de quelques heures au plus. **À décider** : `host_advance_cap_minor` par pays (suggestion, comme Turo et avec le moins de limites possible : au moins le montant d'un trip moyen du pays, relevé avec l'usage) et `platform_reserve_minor` (réserve totale, utile seulement quand le solde PSP sera lu). Sans réponse, rien ne casse : le défaut reste la décision à deux. Depuis US-224 partie 224c (ADR-150), le remboursement planifié part tout seul dès qu'un connecteur PSP existe ; une avance encore à décider lève une alerte FIN unique (`FIN_REFUND_BLOCKED`). Rien de nouveau à décider. Depuis US-224 partie 224d (ADR-154), le voyageur voit son remboursement (montant, date d'émission), l'hôte la part retirée de ses gains, et la console (ops, FINANCE) le motif d'un blocage ; à faire relire par l'avocat avec les autres textes : la phrase « ta banque peut mettre quelques jours ouvrés à l'afficher » (GL-34). Rien de nouveau à décider.)_ +→ **Suggestion** (comme Turo, le moins de limites possible) : **le voyageur est toujours remboursé tout de suite** ; Kmino avance la somme et la reprend sur les versements suivants de l'hôte (déjà retenu : `COMME_TURO.md`, solde d'hôte négatif). Il te reste à fixer deux montants : le plafond d'avance par hôte, et la réserve totale que Kmino accepte d'avancer par pays. Au lancement, un plafond par hôte égal à un trip moyen et une petite réserve suffisent ; on les relève avec l'usage. _(État au 2026-11-17, US-224 partie 224b, PR #202 : l'avance est construite. Le voyageur reçoit toujours le montant complet ; mais tant que tu n'as pas fixé le plafond par hôte, et tant que le solde de Kmino chez le PSP n'est pas lisible (connecteur réel, lot C), **chaque avance attend une décision de deux personnes FINANCE** avant de partir : c'est le défaut prudent, il retarde le voyageur de quelques heures au plus. **À décider** : `host_advance_cap_minor` par pays (suggestion, comme Turo et avec le moins de limites possible : au moins le montant d'un trip moyen du pays, relevé avec l'usage) et `platform_reserve_minor` (réserve totale, utile seulement quand le solde PSP sera lu). Sans réponse, rien ne casse : le défaut reste la décision à deux. Depuis US-224 partie 224c (ADR-150), le remboursement planifié part tout seul dès qu'un connecteur PSP existe ; une avance encore à décider lève une alerte FIN unique (`FIN_REFUND_BLOCKED`). Rien de nouveau à décider. Depuis US-224 partie 224d (ADR-154), le voyageur voit son remboursement (montant, date d'émission), l'hôte la part retirée de ses gains, et la console (ops, FINANCE) le motif d'un blocage ; à faire relire par l'avocat avec les autres textes : la phrase « ta banque peut mettre quelques jours ouvrés à l'afficher » (GL-34). Rien de nouveau à décider. Depuis US-224 partie 224f (ADR-166), un trip payé en plusieurs fois est remboursé sur chacun de ses moyens, comme Turo (la carte d'abord, jamais plus que ce qu'un moyen a payé) ; un refus du prestataire met le remboursement en attente d'un autre moyen, que l'équipe règle avec le voyageur. Le crédit (solde gardé par Kmino) n'est jamais recréé tant que tu n'as pas ouvert la détention de fonds (`funds_holding_enabled`, décision déjà listée). Rien de nouveau à décider.)_ **2.11 Fond de carte des résultats de recherche** (Q-020, US-203). Les résultats s'affichent en liste et sur une carte ; sans fournisseur de cartes, la carte est un plan simplifié aux couleurs du thème, avec les prix placés sur les zones approximatives des voitures (jamais l'adresse). Un fournisseur verrait l'adresse IP de chaque visiteur. → **Suggestion** (comme Turo, le moins de limitations possible) : comme Turo, une **vraie carte interactive** à côté de la liste, ouverte à tout visiteur sans compte, qui montre la zone approximative de chaque voiture (jamais l'adresse, donnée seulement au voyageur après la réservation). Pour la bêta, garder le plan simplifié (aucun coût, aucun tiers) ; au lancement d'un pays, choisir un fournisseur de tuiles payé à l'usage, avec un budget mensuel plafonné, et l'inscrire au registre des sous-traitants. Aucune limite pour le voyageur ni pour l'hôte : seul le budget de la carte est à fixer. diff --git a/docs/team/handoffs/US-224.md b/docs/team/handoffs/US-224.md index 4742c306..e1f7c6d0 100644 --- a/docs/team/handoffs/US-224.md +++ b/docs/team/handoffs/US-224.md @@ -346,3 +346,66 @@ Export des oracles (`docs/specs/tools/golden_vectors.json`, `python -I -X utf8`) ## Prochaine commande exacte `gh pr checks --repo Noamgitpty/rueda` (le job « base de données » fait foi pour `schema.md` et les preuves L0) ; après chaque fusion de main : renuméroter 0139 / 0140. + +--- + +# Partie 224f — remboursement réparti sur les moyens d'origine (critère 6, TJ16c / TJ16d), reprise après un échec confirmé + +Agent de story (argent / back-end), claude-opus-5-5. Branche `story/US-224-multi-moyens`, partie d'`origin/main` (`b9dec048`, après #238), worktree `../wt/US-224f`. Décision : **ADR-166** (PROPOSÉ). PR en brouillon (voir « Prochaine commande exacte »). + +## Périmètre + +- **Fait** : N-238. 08 E2 (imputation incrémentale) dans `@rueda/money` ; processeur des annulations multi-moyens (un ordre par encaissement, jambes en cascade, clé sur le moyen) ; invariant de E2 en base pour tout appelant (jamais plus que le payé d'un moyen) ; rail natif sur la carte seulement ; reprise après un échec confirmé (`FAILED → PENDING_CUSTOMER_CHOICE`, `attempt_no` + 1) appelée par l'ordonnanceur ; supersession étendue ; S10 : `PENDING_CUSTOMER_CHOICE` montré « en cours de vérification ». +- **Critère 6** : TJ08b, TJ18c, TJ18d étaient prouvés en PYG (224b, 224c, 224e). TJ16c et TJ16d : montants de l'oracle à l'unité près, prouvés par `tender-refunds.golden.test.ts` (E2 et cascade), par le processeur (`trip-cancellation.test.ts`, deux cartes en PYG ⇒ ordres TJ16c puis TJ16d) et en base sous les rôles de production (`l0-us224f-multi-tender`, PA USD : TJ16a / TJ16b ; PY PYG : TJ16c / TJ16d). **TJ16d tel que 08 l'énonce (crédit cash recréé) n'est jamais exécuté en bêta** : refusé sur tout rail (`refund_credit_cash_closed`, `refund_rail_not_native`, `refund_rail_unavailable`), le règlement qui l'exigerait n'est pas écrit (`REFUND_RAIL_UNAVAILABLE`, demande garée, alerte P1) ; il le sera après l'ouverture de `funds_holding_enabled[pays]` par décision écrite du fondateur. Les montants de TJ16d (PLATFORM −367) sont exécutés en bêta sur une seconde carte (même cascade). + +## Numéros + +Consigne : migration 0144 réservée (prendre le suivant libre), ADR-166, catalogue v81, GL-43. La règle de numérotation (suite **contiguë** depuis `origin/main`, `numbering.test.ts`) impose **0141** au premier push (`0141_payment_refund_multi_tender.sql`) : à renuméroter à chaque fusion de main (#236 US-225 et #237 US-227 prennent 0141, peut-être 0142) — fichier, en-tête, `schema.md`, README db, ADR-166, cette passation. **ADR-166**, **catalogue v81** (79 et 80 réservées à US-225 et US-227), ligne **GL-43**. Aucune fixture nouvelle (9945 vérifiée libre, non utilisée). + +## Fait (224f) + +- **Migration 0141** (générée : corps de 0123 `payment_cmd_plan_refund`, de 0127 `payment_refund_instance_guard` et `payment_refund_instance_supersede` recopiés, blocs « US-224f ») : rail natif sur `CARD` seulement (`refund_rail_not_native`) ; moyen dans la devise du trip ; Σ instances du moyen hors `CANCELLED` / `SUPERSEDED` ≤ payé (`refund_exceeds_tender`, après la garde du trip) ; `core.payment_cmd_refund_await_choice(uuid)` (cmd_money_owner, EXECUTE app_worker, travailleur `payment_command` ; `refund_instance_not_failed`) ; garde : `attempt_no` + 1 sur `FAILED → PENDING_CUSTOMER_CHOICE` seulement, `PENDING_CUSTOMER_CHOICE → SUPERSEDED` ; `UPDATE (attempt_no)` à cmd_money_owner. Liste blanche `SECURITY DEFINER` : une entrée. +- **@rueda/money** : `refundsByTender`, `tenderRefundOrders` (`src/settlement/tender-refunds.ts`). +- **STL** : `tendersOf` (remplace `captureOf`), `ordersByTender`, `tenderKindOf` (exportés) ; `refund_exceeds_tender` ⇒ revue FIN ; `RefundScheduler` : marque de l'alerte `FAILED` et `awaitChoice` dans la même transaction. **PAY** : `PgRefundOrders.awaitChoice`. +- **Console** : codes garés `REFUND_RAIL_UNAVAILABLE`, `REFUND_RAIL_NOT_NATIVE`, `REFUND_EXCEEDS_TENDER` (es / en / fr / pt-BR, catalogue v81). **Site** : `phaseOf('PENDING_CUSTOMER_CHOICE')` = `ATTENTION`. +- **Codes** (`errors.ts`) : `refund_exceeds_tender` ⇒ `REFUND_EXCEEDS_COLLECTED` ; `refund_rail_not_native` ⇒ `PAYMENT_METHOD_UNAVAILABLE` ; `refund_instance_not_failed` ⇒ `INVALID_TRANSITION`. +- **Docs** : ADR-166, README db / STL / PAY, `changelog.d/US-224-multi-moyens.md`, `COMME_TURO.md` (1 entrée PROPOSÉ), `POUR_LE_FONDATEUR.md` §2.10 (rien de nouveau à décider), GL-43, `schema.md` (recopié du job « base de données »). + +## Valeurs attendues + +Export des oracles : TJ16a / TJ16b (USD), TJ16c / TJ16d (PYG), TJ15a à TJ15d, TJ02b, TJ08b. E2 : `check_legs.py` (`e2_refunds` : T33 → [15 000 ; 3 744 ; 0 ; 0], T07 → [13 822 ; 0 ; 0 ; 0], TJ16c-d → [1 000 000 ; 367] ; `e2_incremental` : T66 b → [0 ; 1 922 ; 3 000 ; 2 000]) ; deux moyens de même catégorie : `allocate` de `check_t49plus.py` (PYG {c2 : 367, c1 : 1 000 000} ; inversé {c1 : 562 317, c2 : 438 050} ; USD {c2 : 3 744, c1 : 15 000}) ; jambes des encaissements : `cascade` de `check_legs.py` (TJ01 en [15 000, 10 666] ⇒ {13 125, 1 875, 0, 0}, {0, 675, 0, 9 991} ; TJ08a en [1 000 000, 438 050] ⇒ {787 500, 105 000, 0, 107 500}, {0, 0, 0, 438 050}). Vérifié le 2026-11-18 (`python -I -X utf8`). + +## Tests existants modifiés (à examiner un par un par la revue sécurité) + +- `apps/api/src/modules/stl/internal/trip-cancellation.test.ts` : la ligne simulée de l'encaissement (deux tests du processeur) porte en plus `amount_minor` et `committed_minor` (colonnes lues par `tendersOf`) ; titre « trip sans capture unique du loyer » ⇒ « trip sans encaissement du loyer » (plusieurs encaissements sont désormais admis ; l'absence d'encaissement reste refusée, même code `TRIP_NOT_CAPTURED`) ; assertions inchangées ; bloc US-224f AJOUTÉ. +- `apps/api/src/modules/stl/internal/refund-scheduler.test.ts` : réponse simulée de `payment_cmd_refund_await_choice` AJOUTÉE aux réponses par défaut ; assertions AJOUTÉES au test du refus du PSP (marque puis attente du choix, une seule fois) ; test AJOUTÉ ; aucune assertion retirée. +- `apps/web/account/trip-refunds.test.ts` : `PENDING_CUSTOMER_CHOICE` attendu `ATTENTION` au lieu de `PREPARING` (décision 6 d'ADR-166 : en bêta, cet état ne suit qu'un rejet confirmé). +- `apps/backoffice/app/console/cancel-view.test.tsx` : nombre de codes garés 13 ⇒ 16 (les trois nouveaux sont contrôlés dans les quatre langues par la même boucle). +- `packages/db/test/support/pay.ts` : `recordOperation` accepte `method` (défaut `CARD`, identique à avant pour tout appel existant). +- Comportements changés sans modifier le code d'un test : `payment_cmd_plan_refund` refuse désormais un rail natif sur un encaissement qui n'est pas une carte, un encaissement dans une autre devise et un remboursement au-delà du payé du moyen (après la garde du trip : les refus existants gardent leur contrainte) ; la supersession remplace aussi les instances `PENDING_CUSTOMER_CHOICE`. + +## Décisions PROPOSÉ + +- Catégorie d'un moyen : `CARD` natif ; `CREDIT_CASH`, `CREDIT_PROMO` crédits ; tout autre ou inconnu non natif. À l'intérieur d'une catégorie : absorption par la capture la plus récente d'abord (08 E2), cascade par la plus ancienne d'abord (rang de capture ; 08 dit « `instance_seq` croissant », égal à 1 pour chaque moyen à la version 1). +- Bêta : un moyen non natif ou un crédit qui doit rembourser quelque chose ⇒ rien n'est écrit, demande garée (`REFUND_RAIL_UNAVAILABLE`) ; jamais un remboursement partiel. +- Réaffectation rattachée au premier moyen de la cascade (clé et compte). +- Reprise : transition automatique après l'alerte `FIN_REFUND_FAILED`, dans la transaction de sa marque ; aucun rail ouvert en bêta ; S10 « en cours de vérification ». +- `COMME_TURO.md` : une entrée. + +## Suites (à inscrire au BOARD) + +- **Choix du rail par le voyageur** (S10, `PENDING_CUSTOMER_CHOICE → PENDING_BANK_DETAILS`, virement vers un compte vérifié à son nom, OQ-BR-12) et nouvel ordre `…:a2` ; textes es / en / fr / pt-BR — lot C, **avant l'ouverture d'un pays** si un moyen non natif est proposé au checkout. +- **Crédit cash recréé (TJ16d exécuté)** : après l'ouverture de `funds_holding_enabled[pays]` (décision écrite du fondateur, commande à deux personnes). +- **Encaissement par crédit refusé tant que les crédits n'existent pas** : `payment_cmd_record_operation` ne contrôle pas le moyen (US-223 ou lot C). +- Relances J+1 / J+3 / J+7 et sort des sommes non réclamées (OQ-BR-44) ; chargebacks perdus dans le reliquat d'un moyen (E5) ; FX entre devise de capture et devise du trip. +- Inchangées : N-237 (files MISMATCH et `REFUND_OUT_OF_RANGE`), N-239 (instance exigée pour tout `REFUND` de règlement), N-354 à N-360. + +## Pièges + +- La migration est générée (corps de 0123 et 0127 recopiés par `split/join`, blocs « US-224f ») ; à la renumérotation, renommer le fichier et son en-tête seulement. +- `rueda/no-country-constants` lit « USD » et « PYG » dans un titre de test d'`apps/api` : titres en « devise sans décimale » / « à deux décimales ». +- Le contrôle du reliquat d'un moyen vient APRÈS la commande d'enregistrement (garde du trip d'abord) : l'instance vient d'être insérée, d'où `ri.id <> p_instance_id`. + +## Prochaine commande exacte + +`gh pr checks --repo Noamgitpty/rueda` (le job « base de données » fait foi pour `schema.md` et les preuves L0) ; après chaque fusion de main : renuméroter 0141. diff --git a/packages/db/README.md b/packages/db/README.md index 81b86608..369bfa16 100644 --- a/packages/db/README.md +++ b/packages/db/README.md @@ -1020,3 +1020,12 @@ Migrations `0139_settlement_host_ledger_advance_receivable` et `0140_booking_def - **Hôte défaillant** (N-236, critère 5) : action de console `CANCEL_HOST_TRIPS` (sujet ORGANIZATION, permission `ops.platform_cancel`, aucune saisie) liée à `core.booking_manual_action_cancel_host_trips` (cmd_hold_owner, EXECUTE iam_staff_owner) : restriction active du titulaire exigée (`HOST_NOT_RESTRICTED`), une demande `booking_trip_cancellation` PENDING par trip à venir du compte (`CANCEL_TRIP_PLATFORM`, motif dérivé `HOST_ACCOUNT_CLOSED`, initiateur PLATFORM), réglée par le travailleur `trip_lifecycle` comme toute annulation (remboursement intégral, aucune pénalité) ; `NO_TRIP_TO_CANCEL`, `SELF_FORBIDDEN`, `NOT_FOUND`. - **Codes** : `host_ledger_advance_unknown`, `host_ledger_advance_unique`, `host_ledger_entry_version_reason_unique` ⇒ `INVARIANT_VIOLATION`. - **Preuves** : `test/l0/l0-us224e-host-receivable.test.ts` (TJ18a à TJ18d, PA USD, PY PYG), `test/l0/l0-us224e-defaulted-host.test.ts` (T22, trip D de T48 ; PA, PY) ; groupe isolé ; catalogue de la console (`l0-us101-console-actions`). + +## Remboursement réparti sur les moyens d'origine (US-224 partie 224f ; 08 E2, E3, E4, E7 règle 10, SM-8 ; ADR-166) + +Migration `0141_payment_refund_multi_tender`. Aucune fixture nouvelle. + +- **Planification** (`core.payment_cmd_plan_refund`, corps de 0123 recopié) : rail natif (`NATIVE_PARTIAL`, `ROLLBACK_AND_RECHARGE`) sur une carte seulement (`refund_rail_not_native`) ; moyen remboursé dans la devise du trip ; **jamais plus que le payé d'un moyen** (08 E2) : Σ instances du moyen, toutes versions, hors `CANCELLED` et `SUPERSEDED` (`FAILED` et `PENDING_CUSTOMER_CHOICE` compris) ≤ montant de l'encaissement (`refund_exceeds_tender`), contrôlé après la garde du trip de 0121. +- **Reprise après un échec confirmé** : `core.payment_cmd_refund_await_choice(uuid)` (cmd_money_owner, EXECUTE app_worker, travailleur `payment_command`) : instance `FAILED` dont l'ordre est `FAILED` ⇒ `PENDING_CUSTOMER_CHOICE`, `attempt_no` + 1 (`refund_instance_not_failed` sinon) ; garde de l'instance (corps de 0127) : `attempt_no` ne change que sur cette transition, `PENDING_CUSTOMER_CHOICE → SUPERSEDED` ; supersession étendue à `PENDING_CUSTOMER_CHOICE`. Droit de colonne `UPDATE (attempt_no)` à cmd_money_owner. +- **Codes** : `refund_exceeds_tender` ⇒ `REFUND_EXCEEDS_COLLECTED` ; `refund_rail_not_native` ⇒ `PAYMENT_METHOD_UNAVAILABLE` ; `refund_instance_not_failed` ⇒ `INVALID_TRANSITION`. +- **Preuves** : `test/l0/l0-us224f-multi-tender.test.ts` (PA USD : TJ16a / TJ16b, moyens de T33 ; PY PYG : TJ16c / TJ16d ; refus de TJ16b / TJ16d sur tout rail en bêta ; reprise après échec ; supersession ; droits). `test/support/pay.ts` : `recordOperation` accepte un moyen (`method`, défaut `CARD`). diff --git a/packages/db/migrations/0141_payment_refund_multi_tender.sql b/packages/db/migrations/0141_payment_refund_multi_tender.sql new file mode 100644 index 00000000..188ec20f --- /dev/null +++ b/packages/db/migrations/0141_payment_refund_multi_tender.sql @@ -0,0 +1,398 @@ +-- 0141 — PAY : remboursement réparti sur les moyens d'origine (TJ16c / TJ16d) et reprise après un +-- échec confirmé (SM-8 FAILED → PENDING_CUSTOMER_CHOICE). +-- US-224 (partie 224f, argent / back-end) ; 19 US-224 critère 6 (« Given la variante PY, When TJ08b, +-- TJ16c, TJ16d et TJ18c, TJ18d sont rejoués, Then les montants viennent de l'oracle à l'unité +-- près ») ; BOARD N-238 ; 08 E2 (imputation incrémentale : « chaque moyen reçoit refundable[m] − +-- absorbé[m], donc jamais plus que son reliquat »), E3 (rails, `CREDIT_CASH` ouvert en production +-- seulement si `funds_holding_enabled[pays]` = true), E4 (`instance_seq`, `attempt_no` : « il +-- n'augmente que sur la transition FAILED → PENDING_CUSTOMER_CHOICE (ou un nouveau rail) après rejet +-- confirmé »), E7 règle 10 (cascade entre opérations, TJ16), SM-8 ; 17 v6 §3.2.7, §4.3 ; ADR-147, +-- ADR-150 ; ADR-166 (cette migration). Appliquée sous `migrator`, en une transaction. Générée en +-- partie : corps de 0123 (`payment_cmd_plan_refund`) et de 0127 (`payment_refund_instance_guard`, +-- `payment_refund_instance_supersede`) recopiés à l'identique, blocs marqués « US-224f ». +-- +-- Principes (ADR-166, PROPOSÉS, fail-closed) : +-- 1. le montant de chaque moyen est décidé par 08 E2 et ses jambes par la cascade de la règle 10 +-- dans `@rueda/money` (`tenderRefundOrders`), appelé par le processeur des annulations (STL) ; +-- la base tient, pour TOUT appelant, l'invariant de E2 « jamais plus que son reliquat » : +-- Σ instances du moyen (toutes versions, hors CANCELLED et SUPERSEDED, FAILED et +-- PENDING_CUSTOMER_CHOICE compris) ≤ payé par ce moyen (`refund_exceeds_tender`), en plus de la +-- garde du trip (0121, `refund_exceeds_collected`) et de la contrainte différée de 0124 +-- (Σ REFUND = remboursement du voyageur) ; +-- 2. rail natif (`NATIVE_PARTIAL`, `ROLLBACK_AND_RECHARGE`) sur une carte seulement +-- (`refund_rail_not_native`) ; un moyen non natif exige le choix du voyageur, un crédit cash +-- recréé exige `funds_holding_enabled` : tous deux fermés en bêta (0123 inchangé : +-- `refund_rail_unavailable`, `refund_credit_cash_closed`) ; TJ16d (crédit cash recréé) n'est +-- donc jamais exécuté en bêta et le règlement qui l'exigerait n'est pas écrit (garé, alerte) ; +-- 3. reprise après un échec CONFIRMÉ (ordre FAILED, aucun fonds sorti) : l'instance passe +-- PENDING_CUSTOMER_CHOICE avec attempt_no + 1 (`core.payment_cmd_refund_await_choice`, +-- travailleur payment_command, appelée par l'ordonnanceur après l'alerte FIN) ; aucune +-- conversion en crédit, aucun autre rail n'est ouvert en bêta (08 E3 : « sans réponse du guest +-- au choix du rail, aucune conversion automatique en crédit ») ; l'obligation reste engagée +-- (08 E1) et une version n+1 la remplace (SUPERSEDED). +-- +-- Hors de cette migration (ADR-166, passation docs/team/handoffs/US-224.md, partie 224f) : choix du +-- rail par le voyageur (S10) et virement vers un compte vérifié à son nom (OQ-BR-12, lot C) ; crédit +-- cash recréé (ouverture de `funds_holding_enabled` par décision écrite du fondateur) ; relances +-- J+1 / J+3 / J+7 et sort des sommes non réclamées (OQ-BR-44) ; chargebacks perdus dans le reliquat +-- d'un moyen (E5) ; refus d'un encaissement par crédit tant que les crédits n'existent pas. +-- +-- Expand / contract : une fonction AJOUTÉE, un droit de colonne AJOUTÉ (attempt_no) ; corps de trois +-- fonctions remplacés à signature, propriétaire et droits identiques ; rien n'est retiré. +-- +-- Retour arrière : +-- réappliquer les définitions de 0123 (payment_cmd_plan_refund, sous cmd_money_owner) et de 0127 +-- (payment_refund_instance_guard, payment_refund_instance_supersede) ; +-- DROP FUNCTION core.payment_cmd_refund_await_choice(uuid); +-- REVOKE UPDATE (attempt_no) ON core.payment_refund_instance FROM cmd_money_owner. + +-- 1. Garde de l'instance (corps de 0127, blocs marqués US-224f) --------------------------------- +CREATE OR REPLACE FUNCTION core.payment_refund_instance_guard() + RETURNS trigger + LANGUAGE plpgsql + SET search_path = pg_catalog, pg_temp +AS $fn$ +BEGIN + IF TG_OP = 'INSERT' THEN + IF NEW.status <> 'PLANNED' OR NEW.issued_at IS NOT NULL OR NEW.fin_alert IS NOT NULL THEN + RAISE EXCEPTION 'refund_instance: created PLANNED only' + USING ERRCODE = 'integrity_constraint_violation', CONSTRAINT = 'refund_instance_transition'; + END IF; + IF NEW.rail = 'CREDIT_CASH' AND NOT core.config_go_live('funds_holding_enabled', NEW.country_code) THEN + RAISE EXCEPTION 'refund_instance: cash credit closed while funds holding is disabled' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'refund_credit_cash_closed'; + END IF; + RETURN NEW; + END IF; + IF NEW.id IS DISTINCT FROM OLD.id OR NEW.origin_type IS DISTINCT FROM OLD.origin_type + OR NEW.origin_id IS DISTINCT FROM OLD.origin_id OR NEW.settlement_id IS DISTINCT FROM OLD.settlement_id + OR NEW.settlement_version IS DISTINCT FROM OLD.settlement_version + OR NEW.trip_id IS DISTINCT FROM OLD.trip_id OR NEW.country_code IS DISTINCT FROM OLD.country_code + OR NEW.currency IS DISTINCT FROM OLD.currency + OR NEW.refunded_operation_id IS DISTINCT FROM OLD.refunded_operation_id + OR NEW.instance_seq IS DISTINCT FROM OLD.instance_seq + -- US-224f (08 E4, SM-8) : attempt_no n'augmente que sur FAILED → PENDING_CUSTOMER_CHOICE + OR (NEW.attempt_no IS DISTINCT FROM OLD.attempt_no + AND NOT (OLD.status = 'FAILED' AND NEW.status = 'PENDING_CUSTOMER_CHOICE')) + OR NEW.executor IS DISTINCT FROM OLD.executor OR NEW.rail IS DISTINCT FROM OLD.rail + OR NEW.requested_legs IS DISTINCT FROM OLD.requested_legs + OR NEW.amount_trip_minor IS DISTINCT FROM OLD.amount_trip_minor + OR NEW.operation_id IS DISTINCT FROM OLD.operation_id OR NEW.advance_id IS DISTINCT FROM OLD.advance_id + OR NEW.created_at IS DISTINCT FROM OLD.created_at + OR (OLD.issued_at IS NOT NULL AND NEW.issued_at IS DISTINCT FROM OLD.issued_at) THEN + RAISE EXCEPTION 'refund_instance: identity is immutable' + USING ERRCODE = 'integrity_constraint_violation', CONSTRAINT = 'refund_instance_immutable'; + END IF; + IF NOT ((OLD.status = 'PLANNED' AND NEW.status IN ('PLANNED', 'SUBMITTED', 'SUPERSEDED')) + -- US-224c (08 SM-8) : l'ordre envoyé suit le PSP ; un échec n'est remplacé que par une + -- version n+1 ; aucun retour en arrière, aucun saut (CONFIRMED passe toujours par SENT) + OR (OLD.status = 'SUBMITTED' AND NEW.status IN ('SENT', 'FAILED')) + OR (OLD.status = 'SENT' AND NEW.status IN ('CONFIRMED', 'FAILED')) + OR (OLD.status = 'FAILED' AND NEW.status = 'SUPERSEDED') + -- US-224f (08 SM-8, E4) : rejet confirmé ⇒ choix d'un autre rail par le voyageur, nouvelle + -- tentative (attempt_no + 1, jamais un rejeu de la même clé) ; sans mouvement de fonds, + -- remplacée par une version n+1 + OR (OLD.status = 'FAILED' AND NEW.status = 'PENDING_CUSTOMER_CHOICE' + AND NEW.attempt_no = OLD.attempt_no + 1) + OR (OLD.status = 'PENDING_CUSTOMER_CHOICE' AND NEW.status = 'SUPERSEDED') + OR (OLD.status = NEW.status AND NEW.blocked_reason IS NOT DISTINCT FROM OLD.blocked_reason + AND NEW.issued_at IS NOT DISTINCT FROM OLD.issued_at)) THEN + RAISE EXCEPTION 'refund_instance: transition % -> % refused', OLD.status, NEW.status + USING ERRCODE = 'integrity_constraint_violation', CONSTRAINT = 'refund_instance_transition'; + END IF; + RETURN NEW; +END +$fn$; + +-- 2. Supersession (corps de 0127, bloc marqué US-224f) ------------------------------------------- +CREATE OR REPLACE FUNCTION core.payment_refund_instance_supersede() + RETURNS trigger + LANGUAGE plpgsql + SET search_path = pg_catalog, pg_temp +AS $fn$ +BEGIN + -- US-224c (08 SM-8) : PLANNED et FAILED (rejet confirmé) n'ont déplacé aucun fonds ; US-224f : + -- PENDING_CUSTOMER_CHOICE non plus (08 SM-8, supersession : « sans mouvement de fonds ») + UPDATE core.settlement_platform_advance AS a + SET status = 'CANCELLED' + WHERE a.status = 'PLANNED' + AND a.id IN (SELECT ri.advance_id FROM core.payment_refund_instance AS ri + WHERE ri.trip_id = NEW.trip_id AND ri.status IN ('PLANNED', 'FAILED', 'PENDING_CUSTOMER_CHOICE') + AND ri.advance_id IS NOT NULL); + UPDATE core.payment_refund_instance AS ri + SET status = 'SUPERSEDED', blocked_reason = NULL + WHERE ri.trip_id = NEW.trip_id AND ri.status IN ('PLANNED', 'FAILED', 'PENDING_CUSTOMER_CHOICE'); + RETURN NULL; +END +$fn$; + +-- 3. Commandes de cmd_money_owner (ADR-044 amendé : CREATE le temps du remplacement) ------------- +GRANT UPDATE (attempt_no) ON core.payment_refund_instance TO cmd_money_owner; +GRANT CREATE ON SCHEMA core TO cmd_money_owner; +SET LOCAL ROLE cmd_money_owner; + +-- 3.1 Planification (corps de 0123, blocs marqués US-224f) : rail natif sur la carte seulement ; +-- jamais plus que le payé d'un moyen (08 E2). Signature, propriétaire et droits inchangés. +CREATE OR REPLACE FUNCTION 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 +) + RETURNS TABLE (instance_id uuid, operation_id uuid, advance_id uuid, status text, + blocked_reason text, replayed boolean) + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +#variable_conflict use_column +DECLARE + v_stl record; + v_trip record; + v_src record; + v_prev record; + v_keys text[]; + v_leg text; + v_value text; + v_req numeric[] := ARRAY[0, 0, 0, 0]; + v_amount numeric := 0; + v_avail numeric; + v_released numeric; + v_shift numeric := 0; + v_adv uuid; + v_block text; + v_legs jsonb; + v_replayed boolean; + v_engaged numeric; + i integer; +BEGIN + IF app.actor_kind() IS DISTINCT FROM 'WORKER' + OR app.worker_name() IS DISTINCT FROM 'payment_command' THEN + RAISE EXCEPTION 'payment: plan_refund reserved to the payment_command worker' + USING ERRCODE = 'insufficient_privilege'; + END IF; + IF p_instance_id IS NULL OR p_operation_id IS NULL OR p_settlement_id IS NULL + OR p_refunded_operation_id IS NULL OR p_instance_seq IS NULL OR p_instance_seq < 1 + OR p_rail IS NULL + OR p_rail NOT IN ('NATIVE_PARTIAL', 'ROLLBACK_AND_RECHARGE', 'BANK_TRANSFER', 'CREDIT_CASH') THEN + RAISE EXCEPTION 'payment: invalid refund instance' USING ERRCODE = 'invalid_parameter_value'; + END IF; + -- jambes demandées : exactement HOST, INSURER, TAX_THIRD_PARTY, PLATFORM, entiers ≥ 0 en texte + IF p_legs IS NULL OR jsonb_typeof(p_legs) <> 'object' THEN + RAISE EXCEPTION 'payment: legs required' USING ERRCODE = 'invalid_parameter_value'; + END IF; + SELECT array_agg(k ORDER BY k) INTO v_keys FROM jsonb_object_keys(p_legs) AS k; + IF v_keys IS DISTINCT FROM ARRAY['HOST', 'INSURER', 'PLATFORM', 'TAX_THIRD_PARTY'] THEN + RAISE EXCEPTION 'payment: legs must be HOST, INSURER, TAX_THIRD_PARTY, PLATFORM' + USING ERRCODE = 'invalid_parameter_value'; + END IF; + FOR i IN 1..4 LOOP + v_leg := (ARRAY['HOST', 'INSURER', 'TAX_THIRD_PARTY', 'PLATFORM'])[i]; + IF jsonb_typeof(p_legs -> v_leg) <> 'string' THEN + RAISE EXCEPTION 'payment: leg % must be an integer string', v_leg + USING ERRCODE = 'invalid_parameter_value'; + END IF; + v_value := p_legs ->> v_leg; + IF v_value !~ '^[0-9]{1,18}$' THEN + RAISE EXCEPTION 'payment: leg % must be a non-negative integer string', v_leg + USING ERRCODE = 'invalid_parameter_value'; + END IF; + v_req[i] := v_value::numeric; + v_amount := v_amount + v_req[i]; + END LOOP; + IF v_amount <= 0 THEN + RAISE EXCEPTION 'payment: refund amount must be positive' USING ERRCODE = 'invalid_parameter_value'; + END IF; + + SELECT s.id, s.trip_id, s.version INTO v_stl + FROM core.settlement_settlement AS s WHERE s.id = p_settlement_id; + IF v_stl.id IS NULL THEN + RAISE EXCEPTION 'payment: refund instance without a known settlement' + USING ERRCODE = 'object_not_in_prerequisite_state', + CONSTRAINT = 'leg_refund_without_settlement'; + END IF; + -- verrou du trip AVANT toute écriture (même ordre que la garde et le report) + SELECT t.id, t.org_id, t.country_code, t.currency INTO v_trip + FROM core.booking_trip AS t WHERE t.id = v_stl.trip_id FOR UPDATE; + + -- rails (E3) : bêta, remboursement natif seulement ; crédit cash fermé tant que + -- funds_holding_enabled[pays] = false ; virement : aucune coordonnée bancaire stockée en bêta + IF p_rail = 'CREDIT_CASH' AND NOT core.config_go_live('funds_holding_enabled', v_trip.country_code) THEN + RAISE EXCEPTION 'payment: cash credit closed while funds holding is disabled' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'refund_credit_cash_closed'; + END IF; + IF p_rail IN ('BANK_TRANSFER', 'CREDIT_CASH') THEN + RAISE EXCEPTION 'payment: refund rail % not available in beta', p_rail + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'refund_rail_unavailable'; + END IF; + + -- rejeu : même clé (règlement, opération remboursée, rang) ⇒ même contenu exigé + SELECT ri.id, ri.operation_id, ri.advance_id, ri.status, ri.blocked_reason, ri.rail, + ri.requested_legs + INTO v_prev + FROM core.payment_refund_instance AS ri + WHERE ri.origin_type = 'SETTLEMENT' AND ri.origin_id = p_settlement_id + AND ri.refunded_operation_id = p_refunded_operation_id AND ri.instance_seq = p_instance_seq; + IF v_prev.id IS NOT NULL THEN + IF v_prev.id <> p_instance_id OR v_prev.operation_id <> p_operation_id + OR v_prev.rail <> p_rail OR v_prev.requested_legs <> p_legs + OR NOT EXISTS (SELECT 1 FROM core.payment_payment_operation AS o + WHERE o.id = v_prev.operation_id AND o.idem_plain = p_idem_plain + AND o.idem_sent = p_idem_sent) THEN + RAISE EXCEPTION 'payment: same refund instance key, different content' + USING ERRCODE = 'integrity_constraint_violation', + CONSTRAINT = 'refund_instance_idempotency_conflict'; + END IF; + RETURN QUERY SELECT v_prev.id, v_prev.operation_id, v_prev.advance_id, v_prev.status, + v_prev.blocked_reason, true; + RETURN; + END IF; + + -- opération remboursée : un encaissement réussi du loyer de ce trip (moyen et compte du PSP) + SELECT o.id, o.psp_account_id, o.method, o.amount_minor, o.currency INTO v_src + FROM core.payment_payment_operation AS o + WHERE o.id = p_refunded_operation_id AND o.trip_id = v_trip.id AND o.status = 'SUCCEEDED' + AND o.kind IN ('CAPTURE', 'MIT_CHARGE', 'DEBT_COLLECTION') + AND o.purpose IN ('RENT', 'RENT_SHORTFALL', 'NO_SHOW_RETENTION'); + IF v_src.id IS NULL THEN + RAISE EXCEPTION 'payment: refunded operation is not a succeeded rent collection of the trip' + USING ERRCODE = 'object_not_in_prerequisite_state', + CONSTRAINT = 'refund_instance_origin_invalid'; + END IF; + -- US-224f (08 E2, E3) : un moyen n'est remboursé que dans la devise du trip (aucune conversion en + -- bêta) ; un rail natif (remboursement partiel, rollback) n'existe que pour la carte, le seul + -- moyen natif de la bêta : un moyen non natif (Yappy, QR, virement) exige le choix du voyageur + -- (SM-8 PENDING_CUSTOMER_CHOICE), fermé en bêta + IF v_src.currency IS DISTINCT FROM v_trip.currency THEN + RAISE EXCEPTION 'payment: refunded operation is not in the trip currency' + USING ERRCODE = 'object_not_in_prerequisite_state', + CONSTRAINT = 'refund_instance_origin_invalid'; + END IF; + IF p_rail IN ('NATIVE_PARTIAL', 'ROLLBACK_AND_RECHARGE') AND v_src.method IS DISTINCT FROM 'CARD' THEN + RAISE EXCEPTION 'payment: native refund rail on a non-native payment method' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'refund_rail_not_native'; + END IF; + + -- 08 E7 règle 3 bis : la part HOST au-delà de ce que la jambe a encore (en-cours déduits), si la + -- jambe a été versée à l'hôte, est portée sur PLATFORM et avancée par Kmino ; le remboursement + -- du voyageur n'est jamais réduit + SELECT st.available - st.pending_debit, st.released INTO v_avail, v_released + FROM core.payment_trip_leg_state(v_trip.id) AS st WHERE st.leg = 'HOST'; + IF v_req[1] > GREATEST(COALESCE(v_avail, 0), 0) AND COALESCE(v_released, 0) > 0 THEN + v_shift := v_req[1] - GREATEST(COALESCE(v_avail, 0), 0); + END IF; + v_legs := jsonb_build_object('HOST', (v_req[1] - v_shift)::text, 'INSURER', v_req[2]::text, + 'TAX_THIRD_PARTY', v_req[3]::text, + 'PLATFORM', (v_req[4] + v_shift)::text); + IF v_shift > 0 THEN + v_adv := gen_random_uuid(); + INSERT INTO core.settlement_platform_advance + (id, country_code, currency, trip_id, org_id, cause, amount_minor, funded_from, + receivable_minor, status) + VALUES (v_adv, v_trip.country_code, v_trip.currency, v_trip.id, v_trip.org_id, 'RELEASED_LEG', + v_shift::bigint, 'COUNTRY_PLATFORM_BALANCE', v_shift::bigint, 'PLANNED'); + v_block := core.payment_refund_advance_block(v_adv); + END IF; + + INSERT INTO core.payment_refund_instance + (id, origin_type, origin_id, settlement_id, settlement_version, trip_id, country_code, + currency, refunded_operation_id, instance_seq, rail, requested_legs, amount_trip_minor, + operation_id, advance_id, blocked_reason) + VALUES (p_instance_id, 'SETTLEMENT', p_settlement_id, p_settlement_id, v_stl.version, v_trip.id, + v_trip.country_code, v_trip.currency, p_refunded_operation_id, p_instance_seq, p_rail, + p_legs, v_amount::bigint, p_operation_id, v_adv, v_block); + + -- ordre REFUND PENDING (jamais envoyé avant payment_cmd_submit_refund), gardé à l'enregistrement + SELECT r.replayed INTO v_replayed + FROM core.payment_cmd_record_operation(p_operation_id, NULL, v_trip.id, v_src.psp_account_id, + v_src.method, 'REFUND', 'RENT', v_amount::bigint, + v_trip.currency, 1, p_idem_plain, p_idem_sent, v_legs, + p_settlement_id, v_stl.version) AS r; + IF v_replayed THEN + -- clé d'idempotence déjà prise par un ordre sans cette instance + RAISE EXCEPTION 'payment: refund order key already used by another order' + USING ERRCODE = 'integrity_constraint_violation', + CONSTRAINT = 'refund_instance_idempotency_conflict'; + END IF; + + -- US-224f (08 E2 : « chaque moyen reçoit refundable[m] − absorbé[m], donc jamais plus que son + -- reliquat ») : Σ des instances du moyen, toutes versions, hors CANCELLED et SUPERSEDED (FAILED et + -- PENDING_CUSTOMER_CHOICE compris : l'obligation subsiste, seul le rail a échoué), ≤ payé par ce + -- moyen. Contrôlé APRÈS la garde du trip (les refus existants gardent leur contrainte), sous le + -- verrou du trip. + SELECT COALESCE(pg_catalog.sum(ri.amount_trip_minor), 0) INTO v_engaged + FROM core.payment_refund_instance AS ri + WHERE ri.refunded_operation_id = p_refunded_operation_id AND ri.id <> p_instance_id + AND ri.status NOT IN ('CANCELLED', 'SUPERSEDED'); + IF v_engaged + v_amount > v_src.amount_minor THEN + RAISE EXCEPTION 'payment: refund exceeds what this payment method paid' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'refund_exceeds_tender'; + END IF; + + RETURN QUERY SELECT p_instance_id, p_operation_id, v_adv, 'PLANNED'::text, v_block, false; +END +$fn$; + +-- 3.2 Reprise après un échec confirmé (08 SM-8 FAILED → PENDING_CUSTOMER_CHOICE, E4 attempt_no + 1) : +-- sous le verrou du trip, l'instance FAILED dont l'ordre est FAILED (rejet reçu, aucun fonds sorti) +-- attend le choix d'un autre rail par le voyageur. Rien n'est envoyé ni converti. +CREATE FUNCTION core.payment_cmd_refund_await_choice(p_instance_id uuid) + RETURNS text + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_trip uuid; + v_i record; +BEGIN + IF app.actor_kind() IS DISTINCT FROM 'WORKER' + OR app.worker_name() IS DISTINCT FROM 'payment_command' THEN + RAISE EXCEPTION 'payment: refund_await_choice reserved to the payment_command worker' + USING ERRCODE = 'insufficient_privilege'; + END IF; + IF p_instance_id IS NULL THEN + RAISE EXCEPTION 'payment: refund instance required' USING ERRCODE = 'invalid_parameter_value'; + END IF; + SELECT ri.trip_id INTO v_trip FROM core.payment_refund_instance AS ri WHERE ri.id = p_instance_id; + IF v_trip IS NULL THEN + RAISE EXCEPTION 'payment: unknown refund instance' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'refund_instance_unknown'; + END IF; + -- même ordre de verrous que la planification, l'envoi et le report ; relu sous le verrou + PERFORM 1 FROM core.booking_trip AS t WHERE t.id = v_trip FOR UPDATE; + SELECT ri.status, o.status AS operation_status INTO v_i + FROM core.payment_refund_instance AS ri + JOIN core.payment_payment_operation AS o ON o.id = ri.operation_id + WHERE ri.id = p_instance_id; + IF v_i.status = 'PENDING_CUSTOMER_CHOICE' THEN + RETURN 'DUPLICATE'; + END IF; + IF v_i.status = 'SUPERSEDED' THEN + RETURN 'SUPERSEDED'; + END IF; + -- seul un rejet CONFIRMÉ ouvre une nouvelle tentative : un ordre sans statut final (UNKNOWN, + -- SUBMITTED) garde la même clé (08 E4, EC-29) + IF v_i.status <> 'FAILED' OR v_i.operation_status IS DISTINCT FROM 'FAILED' THEN + RAISE EXCEPTION 'payment: refund instance % is not a confirmed failure', p_instance_id + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'refund_instance_not_failed'; + END IF; + UPDATE core.payment_refund_instance AS ri + SET status = 'PENDING_CUSTOMER_CHOICE', attempt_no = ri.attempt_no + 1 + WHERE ri.id = p_instance_id; + RETURN 'AWAITING_CHOICE'; +END +$fn$; +COMMENT ON FUNCTION core.payment_cmd_refund_await_choice(uuid) IS + 'SM-8 FAILED → PENDING_CUSTOMER_CHOICE (attempt_no + 1) après un rejet confirmé du PSP ; aucun ' + 'autre rail ouvert en bêta. Travailleur payment_command. US-224 (224f), ADR-166.'; +REVOKE ALL ON FUNCTION core.payment_cmd_refund_await_choice(uuid) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION core.payment_cmd_refund_await_choice(uuid) TO app_worker; + +RESET ROLE; +REVOKE CREATE ON SCHEMA core FROM cmd_money_owner; diff --git a/packages/db/security-definer-allowlist.json b/packages/db/security-definer-allowlist.json index cd4f82ed..b831d914 100644 --- a/packages/db/security-definer-allowlist.json +++ b/packages/db/security-definer-allowlist.json @@ -2001,6 +2001,13 @@ "owner": "cmd_hold_owner", "execute": ["iam_staff_owner"], "story": "US-224" + }, + { + "signature": "core.payment_cmd_refund_await_choice(uuid)", + "family": "cmd_money", + "owner": "cmd_money_owner", + "execute": ["app_worker"], + "story": "US-224" } ] } diff --git a/packages/db/src/errors.ts b/packages/db/src/errors.ts index 8e1cf4d7..f8def9ae 100644 --- a/packages/db/src/errors.ts +++ b/packages/db/src/errors.ts @@ -325,6 +325,11 @@ export const CONSTRAINT_CODES: Readonly legVector(golden, id); +const legsOf = (v: GoldenLegVector): Legs => ({ ...v.legsMinor }); +const negate = (l: Legs): Legs => + Object.fromEntries(LEGS.map((k) => [k, -l[k]])) as unknown as Legs; +const sum = (l: Legs): bigint => LEGS.reduce((s, k) => s + l[k], 0n); +const legs = (h: bigint, i: bigint, t: bigint, p: bigint): Legs => ({ + HOST: h, + INSURER: i, + TAX_THIRD_PARTY: t, + PLATFORM: p, +}); +const textLegs = (l: Legs): Record => + Object.fromEntries(LEGS.map((k) => [k, l[k].toString()])); + +interface Case { + readonly settlement: string; + readonly variation: string; + /** Deux encaissements (cascade de l'oracle) : première carte, second moyen. */ + readonly two: readonly [Legs, Legs]; + /** Remboursement de chaque moyen (export) : premier, second. */ + readonly refunds: readonly [string, string]; + /** Méthode du second moyen de l'énoncé de 08 (Yappy au PA par T33, crédit cash au PY). */ + readonly secondMethod: string; +} + +/** Vecteurs par devise (jamais par pays). */ +const CASES: Readonly> = { + USD: { + settlement: 'T03', + variation: 'TJ02b', + two: [legs(13125n, 1875n, 0n, 0n), legs(0n, 675n, 0n, 9991n)], + refunds: ['TJ16a', 'TJ16b'], + secondMethod: 'YAPPY', + }, + PYG: { + settlement: 'T27', + variation: 'TJ08b', + two: [legs(787500n, 105000n, 0n, 107500n), legs(0n, 0n, 0n, 438050n)], + refunds: ['TJ16c', 'TJ16d'], + secondMethod: 'CREDIT_CASH', + }, +}; +const caseOf = (c: CountryCase): Case => { + const k = CASES[c.currency]; + if (k === undefined) throw new Error(`aucun vecteur en ${c.currency}`); + expect(tj(k.variation).currency).toBe(c.currency); + return k; +}; + +const asPayments = (fn: (tx: Tx) => Promise): Promise => + withRole('app_worker', (client) => payTx(client, { worker: 'payment_command' }, fn)); + +const asWorker = (tx: Tx, workerName: string): Promise => + setSessionContext(tx, { kind: 'WORKER', workerName }); + +async function applyMovement(tx: Tx, operationId: string): Promise { + const { rows } = await tx.query<{ outcome: string }>( + 'SELECT core.settlement_cmd_apply_leg_movement($1) AS outcome', + [operationId], + ); + return rows[0]?.outcome ?? ''; +} + +interface World { + readonly trip: string; + readonly account: string; + /** Encaissements, dans l'ordre des captures. */ + readonly tenders: readonly string[]; +} + +/** Trip encaissé en plusieurs moyens (jambes données) par la vraie commande, prouvés et reportés. */ +async function paid( + tx: Tx, + c: CountryCase, + parts: readonly { readonly legs: Legs; readonly method: string }[], +): Promise { + const trip = await insertTrip(tx, c); + const account = await insertAccount(tx, { country: c.country }); + const tenders: string[] = []; + for (const p of parts) { + const { operation_id: op } = await recordOperation(tx, { + tripId: trip, + accountId: account, + kind: 'CAPTURE', + amountMinor: sum(p.legs), + currency: c.currency, + idemPlain: `trip:${trip}:CAPTURE:${uuid()}`, + legs: p.legs, + method: p.method, + }); + expect(await applySignedStatus(tx, op, 'SUCCEEDED')).toBe('APPLIED'); + expect(await applyMovement(tx, op)).toBe('APPLIED'); + tenders.push(op); + } + return { trip, account, tenders }; +} + +async function settle( + tx: Tx, + trip: string, + version: number, + record: ReturnType, + supersedesId?: string, +): Promise { + const id = await recordAsSettlementWorker( + tx, + { tripId: trip, version, ...(supersedesId === undefined ? {} : { supersedesId }) }, + record, + ); + await asWorker(tx, 'payment_command'); + return { id, version }; +} + +interface Planned { + readonly instance_id: string; + readonly operation_id: string; +} + +async function plan( + tx: Tx, + s: SettlementRef, + tender: string, + refund: Legs, + rail = 'NATIVE_PARTIAL', + seq = 1, +): Promise { + const idem = `trip:${tender}:v${s.version}:REFUND:${tender}:i${seq}:a1:${uuid()}`; + const { rows } = await tx.query( + `SELECT instance_id, operation_id + FROM core.payment_cmd_plan_refund($1, $2, $3, $4, $5, $6, $7::jsonb, $8, $8)`, + [uuid(), uuid(), s.id, tender, seq, rail, legsJson(refund), idem], + ); + const row = rows[0]; + if (row === undefined) throw new Error('plan_refund sans résultat'); + return row; +} + +async function orderLegs(tx: Tx, operationId: string): Promise> { + const { rows } = await tx.query<{ leg: string; amount: string }>( + `SELECT leg, amount_minor::text AS amount FROM core.payment_payment_operation_leg + WHERE operation_id = $1`, + [operationId], + ); + return Object.fromEntries(rows.map((r) => [r.leg, r.amount])); +} + +async function instance(tx: Tx, id: string) { + const { rows } = await tx.query<{ + status: string; + attempt_no: number; + amount: string; + refunded: string; + }>( + `SELECT status, attempt_no, amount_trip_minor::text AS amount, + refunded_operation_id::text AS refunded + FROM core.payment_refund_instance WHERE id = $1`, + [id], + ); + return rows[0]; +} + +async function submit(tx: Tx, instanceId: string): Promise { + const { rows } = await tx.query<{ outcome: string }>( + 'SELECT outcome FROM core.payment_cmd_submit_refund($1)', + [instanceId], + ); + return rows[0]?.outcome ?? ''; +} + +async function awaitChoice(tx: Tx, instanceId: string): Promise { + const { rows } = await tx.query<{ outcome: string }>( + 'SELECT core.payment_cmd_refund_await_choice($1) AS outcome', + [instanceId], + ); + return rows[0]?.outcome ?? ''; +} + +describe.each(COUNTRIES)( + 'US-224f — remboursement réparti sur les moyens d’origine (critère 6) — $country ($currency)', + (c) => { + const k = caseOf(c); + const first = negate(legsOf(tj(k.refunds[0]))); // TJ16a / TJ16c + const second = negate(legsOf(tj(k.refunds[1]))); // TJ16b / TJ16d + const owed = negate(legsOf(tj(k.variation))); // TJ02b / TJ08b + + it('deux cartes : une instance par moyen (rang 1 chacune), jambes explicites = TJ16a / TJ16b (TJ16c / TJ16d) ; Σ = TJ02b (TJ08b) à l’unité ; aucun prorata', async () => { + await asPayments(async (tx) => { + const w = await paid(tx, c, [ + { legs: k.two[0], method: 'CARD' }, + { legs: k.two[1], method: 'CARD' }, + ]); + const v1 = await settle(tx, w.trip, 1, recordOfVector(k.settlement)); + const a = await plan(tx, v1, w.tenders[0]!, first); + const b = await plan(tx, v1, w.tenders[1]!, second); + expect(await instance(tx, a.instance_id)).toEqual({ + status: 'PLANNED', + attempt_no: 1, + amount: sum(first).toString(), + refunded: w.tenders[0], + }); + expect(await instance(tx, b.instance_id)).toMatchObject({ + amount: sum(second).toString(), + refunded: w.tenders[1], + }); + // ordres REFUND : montant explicite de chaque jambe, tel que donné par l'oracle + expect(await orderLegs(tx, a.operation_id)).toEqual(textLegs(first)); + expect(await orderLegs(tx, b.operation_id)).toEqual(textLegs(second)); + for (const leg of LEGS) expect(first[leg] + second[leg]).toBe(owed[leg]); + // plus rien à rembourser : une unité de plus, sur l'un ou l'autre moyen, est refusée + const extra = await caught(tx, () => + plan(tx, v1, w.tenders[1]!, legs(0n, 0n, 0n, 1n), 'NATIVE_PARTIAL', 2), + ); + expect(extra?.code).toBe('55000'); + }); + }); + + it('08 E2 en base : jamais plus que le payé d’un moyen (refund_exceeds_tender), même quand le trip a encore de quoi rembourser ; même un remboursement en échec reste engagé', async () => { + await asPayments(async (tx) => { + const w = await paid(tx, c, [ + { legs: k.two[0], method: 'CARD' }, + { legs: k.two[1], method: 'CARD' }, + ]); + const v1 = await settle(tx, w.trip, 1, recordOfVector(k.settlement)); + // tout le remboursement sur le second moyen : dans la limite du règlement et de l'encaissé + // du trip, au-delà de ce que ce moyen a payé + expect(sum(owed) > sum(k.two[1])).toBe(true); + expect(await caught(tx, () => plan(tx, v1, w.tenders[1]!, owed))).toMatchObject({ + code: '55000', + constraint: 'refund_exceeds_tender', + }); + }); + }); + + it(`moyen d’origine réel de 08 (${k.secondMethod}) : TJ16a / TJ16c sur la carte planifiée ; TJ16b / TJ16d refusé sur tout rail en bêta (natif : refund_rail_not_native ; virement : refund_rail_unavailable ; crédit cash : refund_credit_cash_closed)`, async () => { + await asPayments(async (tx) => { + const w = await paid(tx, c, [ + { legs: k.two[0], method: 'CARD' }, + { legs: k.two[1], method: k.secondMethod }, + ]); + const v1 = await settle(tx, w.trip, 1, recordOfVector(k.settlement)); + const a = await plan(tx, v1, w.tenders[0]!, first); + expect(await orderLegs(tx, a.operation_id)).toEqual(textLegs(first)); + for (const [rail, constraint] of [ + ['NATIVE_PARTIAL', 'refund_rail_not_native'], + ['ROLLBACK_AND_RECHARGE', 'refund_rail_not_native'], + ['BANK_TRANSFER', 'refund_rail_unavailable'], + ['CREDIT_CASH', 'refund_credit_cash_closed'], + ] as const) { + expect(await caught(tx, () => plan(tx, v1, w.tenders[1]!, second, rail))).toMatchObject({ + code: '55000', + constraint, + }); + } + // rien d'autre n'est engagé : le reliquat dû (TJ16b / TJ16d) n'est jamais remboursé ailleurs + const { rows } = await tx.query<{ n: string; total: string }>( + `SELECT pg_catalog.count(*)::text AS n, + COALESCE(pg_catalog.sum(amount_trip_minor), 0)::text AS total + FROM core.payment_refund_instance WHERE trip_id = $1`, + [w.trip], + ); + expect(rows[0]).toEqual({ n: '1', total: sum(first).toString() }); + }); + }); + + it('SM-8 : rejet confirmé ⇒ PENDING_CUSTOMER_CHOICE, attempt_no 2 ; rejeu sans effet ; obligation toujours engagée ; hors de la file ; version n+1 ⇒ SUPERSEDED', async () => { + await asPayments(async (tx) => { + const w = await paid(tx, c, [ + { legs: k.two[0], method: 'CARD' }, + { legs: k.two[1], method: 'CARD' }, + ]); + const r1 = recordOfVector(k.settlement); + const v1 = await settle(tx, w.trip, 1, r1); + const a = await plan(tx, v1, w.tenders[0]!, first); + // pas encore un échec : refusé + expect(await caught(tx, () => awaitChoice(tx, a.instance_id))).toMatchObject({ + code: '55000', + constraint: 'refund_instance_not_failed', + }); + expect(await submit(tx, a.instance_id)).toBe('SUBMITTED'); + // issue inconnue : même clé, aucune nouvelle tentative (08 E4, EC-29) + expect(await applyStatus(tx, a.operation_id, 'UNKNOWN', 'API_RESPONSE')).toBe('APPLIED'); + expect(await caught(tx, () => awaitChoice(tx, a.instance_id))).toMatchObject({ + constraint: 'refund_instance_not_failed', + }); + expect(await applySignedStatus(tx, a.operation_id, 'FAILED')).toBe('APPLIED'); + expect(await instance(tx, a.instance_id)).toMatchObject({ + status: 'FAILED', + attempt_no: 1, + }); + expect(await awaitChoice(tx, a.instance_id)).toBe('AWAITING_CHOICE'); + expect(await instance(tx, a.instance_id)).toMatchObject({ + status: 'PENDING_CUSTOMER_CHOICE', + attempt_no: 2, + }); + expect(await awaitChoice(tx, a.instance_id)).toBe('DUPLICATE'); + expect((await instance(tx, a.instance_id))?.attempt_no).toBe(2); + // hors de la file de l'ordonnanceur : rien n'est envoyé ni converti + const { rows: due } = await tx.query<{ instance_id: string }>( + 'SELECT instance_id FROM core.payment_refunds_due(500)', + ); + expect(due.map((d) => d.instance_id)).not.toContain(a.instance_id); + // l'obligation reste engagée sur ce moyen (08 E1) : pas de seconde instance sur la carte + expect( + await caught(tx, () => plan(tx, v1, w.tenders[0]!, first, 'NATIVE_PARTIAL', 2)), + ).toMatchObject({ code: '55000', constraint: 'refund_exceeds_tender' }); + // version n+1 : sans mouvement de fonds, l'instance est remplacée + await settle( + tx, + w.trip, + 2, + recordOf(tripOfVector(k.settlement), eventOfVector('T08'), r1), + v1.id, + ); + expect(await instance(tx, a.instance_id)).toMatchObject({ + status: 'SUPERSEDED', + attempt_no: 2, + }); + expect(await awaitChoice(tx, a.instance_id)).toBe('SUPERSEDED'); + }); + }); + + it('identité figée : attempt_no et transitions hors SM-8 refusés ; commande réservée au travailleur payment_command ; instance inconnue refusée', async () => { + await asPayments(async (tx) => { + const w = await paid(tx, c, [ + { legs: k.two[0], method: 'CARD' }, + { legs: k.two[1], method: 'CARD' }, + ]); + const v1 = await settle(tx, w.trip, 1, recordOfVector(k.settlement)); + const a = await plan(tx, v1, w.tenders[0]!, first); + // app_worker n'écrit jamais l'instance directement + for (const sql of [ + `UPDATE core.payment_refund_instance SET attempt_no = 2 WHERE id = '${a.instance_id}'`, + `UPDATE core.payment_refund_instance SET status = 'PENDING_CUSTOMER_CHOICE' WHERE id = '${a.instance_id}'`, + ]) { + expect(await caught(tx, () => tx.query(sql))).toMatchObject({ code: '42501' }); + } + for (const other of ['settlement', 'webhook_ingest', 'reconciliation']) { + await asWorker(tx, other); + expect(await caught(tx, () => awaitChoice(tx, a.instance_id))).toMatchObject({ + code: '42501', + }); + } + await asWorker(tx, 'payment_command'); + expect(await caught(tx, () => awaitChoice(tx, uuid()))).toMatchObject({ + code: '55000', + constraint: 'refund_instance_unknown', + }); + expect((await instance(tx, a.instance_id))?.status).toBe('PLANNED'); + }); + }); + }, +); + +describe('US-224f — moyens de T33 (USD) : la part non remboursée est absorbée par les crédits et Yappy d’abord (08 E2)', () => { + const c = COUNTRIES.find((x) => x.currency === 'USD'); + it('carte, Yappy, crédit cash, crédit promo (TJ15a à TJ15d) : seule la carte reçoit TJ16a ; Yappy (TJ16b) exige un autre rail, fermé en bêta', async () => { + if (c === undefined) throw new Error('aucun pays en USD'); + await asPayments(async (tx) => { + const w = await paid(tx, c, [ + { legs: legsOf(tj('TJ15a')), method: 'CARD' }, + { legs: legsOf(tj('TJ15b')), method: 'YAPPY' }, + { legs: legsOf(tj('TJ15c')), method: 'CREDIT_CASH' }, + { legs: legsOf(tj('TJ15d')), method: 'CREDIT_PROMO' }, + ]); + const v1 = await settle(tx, w.trip, 1, recordOfVector('T03')); + const a = await plan(tx, v1, w.tenders[0]!, negate(legsOf(tj('TJ16a')))); + expect(await orderLegs(tx, a.operation_id)).toEqual(textLegs(negate(legsOf(tj('TJ16a'))))); + expect( + await caught(tx, () => plan(tx, v1, w.tenders[1]!, negate(legsOf(tj('TJ16b'))))), + ).toMatchObject({ code: '55000', constraint: 'refund_rail_not_native' }); + }); + }); +}); + +describe('US-224f — attente du choix du rail fermée à app_api', () => { + it('app_api n’a pas EXECUTE sur core.payment_cmd_refund_await_choice (42501)', async () => { + await withRole('app_api', async (client) => { + await expect( + client.query(`SELECT core.payment_cmd_refund_await_choice('${uuid()}')`), + ).rejects.toMatchObject({ code: '42501' }); + }); + }); +}); diff --git a/packages/db/test/support/pay.ts b/packages/db/test/support/pay.ts index d5b9e4cd..0bf9d8ab 100644 --- a/packages/db/test/support/pay.ts +++ b/packages/db/test/support/pay.ts @@ -130,6 +130,8 @@ export interface RecordInput { * tout appel passe par celle à 15 arguments. */ readonly settlement?: SettlementRef | null; + /** US-224f : moyen de l'encaissement (défaut `CARD`, comme avant). */ + readonly method?: string; } /** Version d'un règlement portée par un ordre (US-224). */ @@ -169,7 +171,7 @@ export async function recordOperation( ): Promise<{ operation_id: string; replayed: boolean }> { const { rows } = await tx.query<{ operation_id: string; replayed: boolean }>( `SELECT operation_id, replayed - FROM core.payment_cmd_record_operation($1, NULL, $2, $3, 'CARD', $4, $5, $6, $7, $8, $9, + FROM core.payment_cmd_record_operation($1, NULL, $2, $3, $14, $4, $5, $6, $7, $8, $9, $10, $11::jsonb, $12::uuid, $13::integer)`, [ r.id ?? uuid(), @@ -185,6 +187,7 @@ export async function recordOperation( r.legs === null ? null : legsJson(r.legs), r.settlement?.id ?? null, r.settlement?.version ?? null, + r.method ?? 'CARD', ], ); const row = rows[0]; diff --git a/packages/i18n/src/catalogs/en.ts b/packages/i18n/src/catalogs/en.ts index 0acd3a9d..b8fc37aa 100644 --- a/packages/i18n/src/catalogs/en.ts +++ b/packages/i18n/src/catalogs/en.ts @@ -2528,6 +2528,13 @@ export const EN_MESSAGES = { 'backoffice.cancel.outcome.ADVANCE_DECISION_REQUIRED': 'A FINANCE decision on a platform advance is needed.', 'backoffice.cancel.outcome.SETTLEMENT_INPUT_INVALID': 'The settlement data isn’t valid.', + // US-224f (ADR-166) : remboursement réparti sur les moyens d’origine (codes garés) + 'backoffice.cancel.outcome.REFUND_RAIL_UNAVAILABLE': + 'A refund would go to a payment method that can’t be refunded automatically yet. Nothing was recorded; FINANCE handles it.', + 'backoffice.cancel.outcome.REFUND_RAIL_NOT_NATIVE': + 'A card refund was requested on another payment method. Nothing was recorded.', + 'backoffice.cancel.outcome.REFUND_EXCEEDS_TENDER': + 'A refund exceeds what one payment method paid.', // US-214 (ADR-160) : « Mis viajes » (S08) et détail du trip du voyageur (S09) 'common.trips.notFound': 'We couldn’t find this trip.', 'common.trips.unavailable': diff --git a/packages/i18n/src/catalogs/es.ts b/packages/i18n/src/catalogs/es.ts index 7cd51afc..6a6e6a22 100644 --- a/packages/i18n/src/catalogs/es.ts +++ b/packages/i18n/src/catalogs/es.ts @@ -2594,6 +2594,13 @@ export const ES_MESSAGES = { 'Hace falta una decisión de FINANCE sobre un anticipo de la plataforma.', 'backoffice.cancel.outcome.SETTLEMENT_INPUT_INVALID': 'Los datos de la liquidación no son válidos.', + // US-224f (ADR-166) : remboursement réparti sur les moyens d’origine (codes garés) + 'backoffice.cancel.outcome.REFUND_RAIL_UNAVAILABLE': + 'Un reembolso iría a un medio de pago que todavía no se reembolsa automáticamente. No se registró nada; lo atiende FINANCE.', + 'backoffice.cancel.outcome.REFUND_RAIL_NOT_NATIVE': + 'Se pidió un reembolso a tarjeta sobre otro medio de pago. No se registró nada.', + 'backoffice.cancel.outcome.REFUND_EXCEEDS_TENDER': + 'Un reembolso supera lo que pagó un medio de pago.', // US-214 (ADR-160) : « Mis viajes » (S08) et détail du trip du voyageur (S09) 'common.trips.notFound': 'No encontramos este viaje.', 'common.trips.unavailable': diff --git a/packages/i18n/src/catalogs/fr.ts b/packages/i18n/src/catalogs/fr.ts index b6dc45b8..c9a0f0b0 100644 --- a/packages/i18n/src/catalogs/fr.ts +++ b/packages/i18n/src/catalogs/fr.ts @@ -2654,6 +2654,13 @@ export const FR_MESSAGES = { 'Une décision de FINANCE sur une avance de la plateforme est nécessaire.', 'backoffice.cancel.outcome.SETTLEMENT_INPUT_INVALID': 'Les données du règlement ne sont pas valides.', + // US-224f (ADR-166) : remboursement réparti sur les moyens d’origine (codes garés) + 'backoffice.cancel.outcome.REFUND_RAIL_UNAVAILABLE': + 'Un remboursement irait vers un moyen de paiement qui ne se rembourse pas encore automatiquement. Rien n’a été enregistré ; FINANCE s’en occupe.', + 'backoffice.cancel.outcome.REFUND_RAIL_NOT_NATIVE': + 'Un remboursement par carte a été demandé sur un autre moyen de paiement. Rien n’a été enregistré.', + 'backoffice.cancel.outcome.REFUND_EXCEEDS_TENDER': + 'Un remboursement dépasse ce qu’a payé un moyen de paiement.', // US-214 (ADR-160) : « Mis viajes » (S08) et détail du trip du voyageur (S09) 'common.trips.notFound': 'Nous ne trouvons pas ce voyage.', 'common.trips.unavailable': diff --git a/packages/i18n/src/catalogs/index.ts b/packages/i18n/src/catalogs/index.ts index 351c2d38..c853d910 100644 --- a/packages/i18n/src/catalogs/index.ts +++ b/packages/i18n/src/catalogs/index.ts @@ -248,8 +248,12 @@ export type { Catalog, Message, PluralCategory, PluralMessage, VersionedCatalog `web.contract.constanciaSearch`, `web.contract.legalCenter` (liens depuis S09 · contrat et A03), `web.legalCenter.*` (centre juridique : positionnement d’intermédiaire entre particuliers, documents publiés, documents de chaque voyage, désaccords et médiation, loi applicable). + Version 81 (79 et 80 réservées à US-225 et US-227, en cours ; la 78 est celle d’US-212) : + remboursement réparti sur les moyens d’origine (US-224 partie 224f, ADR-166) : + `backoffice.cancel.outcome.REFUND_RAIL_UNAVAILABLE`, `…REFUND_RAIL_NOT_NATIVE`, + `…REFUND_EXCEEDS_TENDER` (codes d’une demande d’annulation garée, console). */ -export const CATALOG_VERSION = 78; +export const CATALOG_VERSION = 81; /** 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 56565237..2b4e036e 100644 --- a/packages/i18n/src/catalogs/pt.ts +++ b/packages/i18n/src/catalogs/pt.ts @@ -2599,6 +2599,13 @@ export const PT_MESSAGES = { 'backoffice.cancel.outcome.ADVANCE_DECISION_REQUIRED': 'É preciso uma decisão de FINANCE sobre um adiantamento da plataforma.', 'backoffice.cancel.outcome.SETTLEMENT_INPUT_INVALID': 'Os dados da liquidação não são válidos.', + // US-224f (ADR-166) : remboursement réparti sur les moyens d’origine (codes garés) + 'backoffice.cancel.outcome.REFUND_RAIL_UNAVAILABLE': + 'Um reembolso iria para um meio de pagamento que ainda não é reembolsado automaticamente. Nada foi registrado; o FINANCE cuida disso.', + 'backoffice.cancel.outcome.REFUND_RAIL_NOT_NATIVE': + 'Foi pedido um reembolso no cartão sobre outro meio de pagamento. Nada foi registrado.', + 'backoffice.cancel.outcome.REFUND_EXCEEDS_TENDER': + 'Um reembolso supera o que um meio de pagamento pagou.', // US-214 (ADR-160) : « Mis viajes » (S08) et détail du trip du voyageur (S09) 'common.trips.notFound': 'Não encontramos esta viagem.', 'common.trips.unavailable': diff --git a/packages/money/src/settlement/index.ts b/packages/money/src/settlement/index.ts index 303610ca..78d42b5a 100644 --- a/packages/money/src/settlement/index.ts +++ b/packages/money/src/settlement/index.ts @@ -10,6 +10,14 @@ export { export { assertPayableAmounts, type PayableAmounts } from './amounts.ts'; export { computeCaptureLegs, computeLegs, legVariation } from './legs.ts'; export { settlementOrders, type SettlementOrders } from './refunds.ts'; +export { + refundsByTender, + tenderRefundOrders, + type PaidTender, + type TenderRefund, + type TenderRefundLegs, + type TenderRefundOrders, +} from './tender-refunds.ts'; export { TENDER_KINDS, cascadeTenders, diff --git a/packages/money/src/settlement/tender-refunds.ts b/packages/money/src/settlement/tender-refunds.ts new file mode 100644 index 00000000..03513d87 --- /dev/null +++ b/packages/money/src/settlement/tender-refunds.ts @@ -0,0 +1,189 @@ +/** + * Remboursement réparti entre les moyens d'origine (08 E2, règle d'imputation INCRÉMENTALE ; E7 + * règle 10 ; vecteurs T33, T66, TJ16a à TJ16d, TJ20a ; US-224 partie 224f, ADR-166). + * + * Deux ordres distincts (08 E7 règle 10, US-056) : + * - **combien** chaque moyen rembourse : E2. `refundable[m] = max(0, payé[m] − engagé[m])` (engagé : + * instances SM-8 du moyen, toutes versions, hors `CANCELLED` et `SUPERSEDED`) ; la part non + * remboursée de ce tour, `K' = Σ refundable − refund_total`, est absorbée dans l'ordre crédit + * promo → crédit cash → externes non natifs → externes natifs, la capture la plus récente d'abord + * à l'intérieur d'une catégorie ; chaque moyen reçoit `refundable[m] − absorbé[m]`, jamais plus + * que son reliquat ; + * - **quelles jambes** porte chaque remboursement : la cascade de la règle 10 (`settlementOrders`), + * moyens natif → non natif → crédit cash → crédit promo. + * + * Fonction pure, `bigint` en unités mineures, sans division ni arrondi (jamais de prorata). Les + * chargebacks perdus (`chargeback_perdu_net`) ne sont pas modélisés : aucun chargeback en bêta + * (fail-closed : un appelant qui en connaîtrait un doit les déduire de `committed`). Les attendus des + * tests viennent de 08 (T33, T66 b, TJ16c) et de l'export des oracles (`check_legs.py` : + * `e2_refunds`, `e2_incremental`, `cascade`), jamais de ce fichier. + */ +import { add, isNegative, min, subtract, type Money } from '../money.ts'; +import { SettlementError } from './errors.ts'; +import { settlementOrders } from './refunds.ts'; +import { TENDER_KINDS, type TenderKind } from './tenders.ts'; +import type { Legs } from './types.ts'; + +/** Ordre d'absorption de E2 (la part NON remboursée est prise d'abord sur le crédit promo). */ +const ABSORPTION: readonly TenderKind[] = ['PROMO_CREDIT', 'CASH_CREDIT', 'NON_NATIVE', 'NATIVE']; + +/** Un moyen payé du trip (une capture ou un encaissement réussi du loyer). */ +export interface PaidTender { + /** Identité du moyen (en base : l'encaissement remboursé). */ + readonly id: string; + readonly kind: TenderKind; + /** Payé par ce moyen, devise du trip. */ + readonly paid: Money; + /** Déjà engagé sur ce moyen (instances SM-8 hors `CANCELLED` et `SUPERSEDED`), ≥ 0. */ + readonly committed: Money; + /** Rang de la capture : plus grand = plus récente (E2 : la plus récente absorbe d'abord). */ + readonly capturedRank: number; +} + +/** Remboursement d'un moyen (E2), dans l'ordre de la cascade de la règle 10. */ +export interface TenderRefund { + readonly id: string; + readonly kind: TenderKind; + readonly amount: Money; +} + +/** Remboursement d'un moyen avec ses jambes (montants positifs = débits de chaque jambe). */ +export interface TenderRefundLegs { + readonly id: string; + readonly kind: TenderKind; + readonly legs: Legs; +} + +export interface TenderRefundOrders { + /** Réaffectation signée (Σ = 0) passée avant les remboursements, ou `null` (08 E7 règle 3). */ + readonly reallocation: Legs | null; + /** Un remboursement par moyen qui rembourse quelque chose, ordre de la cascade. */ + readonly refunds: readonly TenderRefundLegs[]; +} + +const kindRank = (kind: TenderKind): number => TENDER_KINDS.indexOf(kind); + +/** Ordre de la cascade : catégorie (natif d'abord), puis la capture la plus ancienne d'abord. */ +const byCascade = (a: PaidTender, b: PaidTender): number => + kindRank(a.kind) - kindRank(b.kind) || a.capturedRank - b.capturedRank; + +function checkTenders(refundTotal: Money, tenders: readonly PaidTender[]): void { + const currency = refundTotal.currency; + if (isNegative(refundTotal)) { + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'remboursement négatif'); + } + const ids = new Set(); + const ranks = new Set(); + for (const t of tenders) { + if (!TENDER_KINDS.includes(t.kind)) { + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'catégorie de moyen inconnue'); + } + if (t.paid.currency !== currency || t.committed.currency !== currency) { + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'devise de moyen différente'); + } + if (t.paid.amountMinor <= 0n || isNegative(t.committed)) { + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'payé ≤ 0 ou engagé négatif'); + } + if (!Number.isSafeInteger(t.capturedRank) || ranks.has(t.capturedRank) || ids.has(t.id)) { + // rang ou identité en double : l'ordre d'absorption ne serait plus déterministe + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'moyen ou rang de capture en double'); + } + ids.add(t.id); + ranks.add(t.capturedRank); + } +} + +/** + * 08 E2 (imputation incrémentale) : remboursement de chaque moyen, dans l'ordre de la cascade de la + * règle 10 ; un moyen absorbé en entier reçoit 0. Refus : `REFUND_OUT_OF_RANGE` si le remboursement + * dépasse Σ reliquats (jamais un moyen remboursé au-delà de ce qu'il a payé), `SETTLEMENT_INPUT_INVALID` + * pour une entrée incohérente. + */ +export function refundsByTender( + refundTotal: Money, + tenders: readonly PaidTender[], +): readonly TenderRefund[] { + checkTenders(refundTotal, tenders); + const nil = subtract(refundTotal, refundTotal); + const refundable = new Map(); + let pool = nil; + for (const t of tenders) { + const rest = subtract(t.paid, t.committed); + const r = isNegative(rest) ? nil : rest; + refundable.set(t.id, r); + pool = add(pool, r); + } + if (refundTotal.amountMinor > pool.amountMinor) { + throw new SettlementError( + 'REFUND_OUT_OF_RANGE', + 'remboursement au-delà de Σ reliquats remboursables (08 E2)', + { + refundMinor: refundTotal.amountMinor.toString(), + refundableMinor: pool.amountMinor.toString(), + }, + ); + } + // K' absorbé : crédit promo → crédit cash → non natif → natif, la capture la plus récente d'abord + let keep = subtract(pool, refundTotal); + const absorbed = new Map(); + const absorption = [...tenders].sort( + (a, b) => + ABSORPTION.indexOf(a.kind) - ABSORPTION.indexOf(b.kind) || b.capturedRank - a.capturedRank, + ); + for (const t of absorption) { + const a = min(keep, refundable.get(t.id) ?? nil); + absorbed.set(t.id, a); + keep = subtract(keep, a); + } + return Object.freeze( + [...tenders].sort(byCascade).map((t) => + Object.freeze({ + id: t.id, + kind: t.kind, + amount: subtract(refundable.get(t.id) ?? nil, absorbed.get(t.id) ?? nil), + }), + ), + ); +} + +/** + * Ordres d'un règlement sur plusieurs moyens : E2 décide le montant de chaque moyen, puis la + * cascade de la règle 10 (`settlementOrders`) ses jambes ; réaffectation d'abord (règle 3). + * Σ remboursements = − variation totale, jambe par jambe ; un moyen à 0 n'a pas d'ordre. + */ +export function tenderRefundOrders( + variation: Legs, + tenders: readonly PaidTender[], +): TenderRefundOrders { + const nil = subtract(variation.total, variation.total); + if (variation.total.amountMinor > 0n) { + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'variation totale positive'); + } + const refundTotal = subtract(nil, variation.total); + const refunds = refundsByTender(refundTotal, tenders).filter((r) => r.amount.amountMinor > 0n); + const orders = settlementOrders( + variation, + refunds.map((r) => ({ kind: r.kind, amount: r.amount })), + ); + // `cascadeTenders` trie par catégorie de façon stable : l'entrée est déjà dans l'ordre de la + // cascade, la i-ème sortie est donc le i-ème moyen (contrôlé, jamais supposé) + if (orders.refunds.length !== refunds.length) { + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'ordres et moyens en nombre différent'); + } + return Object.freeze({ + reallocation: orders.reallocation, + refunds: Object.freeze( + orders.refunds.map((o, i) => { + const r = refunds[i]; + if ( + r === undefined || + r.kind !== o.kind || + r.amount.amountMinor !== o.legs.total.amountMinor + ) { + throw new SettlementError('SETTLEMENT_INPUT_INVALID', 'ordre sans son moyen'); + } + return Object.freeze({ id: r.id, kind: r.kind, legs: o.legs }); + }), + ), + }); +} diff --git a/packages/money/test/settlement/tender-refunds.golden.test.ts b/packages/money/test/settlement/tender-refunds.golden.test.ts new file mode 100644 index 00000000..e7fb34b9 --- /dev/null +++ b/packages/money/test/settlement/tender-refunds.golden.test.ts @@ -0,0 +1,202 @@ +/** + * US-224 (partie 224f, ADR-166) — remboursement réparti entre les moyens d'origine : 08 E2 + * (imputation incrémentale) puis 08 E7 règle 10 (cascade). Attendus, jamais calculés par le code + * testé : + * - T33 (08 E2) et `check_legs.py` `e2_refunds` : carte 150,00, Yappy 37,44, crédit cash 0, crédit + * promo 0 (CROSS « TJ16 remboursements par moyen = T33 ») ; + * - TJ16c / TJ16d (08 E7, export des oracles) : D (PYG) payé par carte 1 000 000 + crédit cash + * 438 050, règlement T27 : carte 1 000 000, crédit cash 367 (CROSS « TJ16c-d ») ; + * - T66 (b) / TJ20a (08 E2, `e2_incremental`) : complément de 69,22 après TJ16a-b : carte 0, Yappy + * 19,22, crédit cash 30,00, crédit promo 20,00 ; + * - deux cartes (même catégorie) : `allocate` de `docs/specs/tools/check_t49plus.py` extraite telle + * quelle (la capture la plus récente absorbe d'abord) : + * + * cd docs/specs && python -I -X utf8 -c "…exec de CAT et allocate de tools/check_t49plus.py…; + * allocate([('c1','external_native',1000000,1),('c2','external_native',438050,2)], 437683); + * allocate([('c1','external_native',1000000,2),('c2','external_native',438050,1)], 437683)" + * → {c2: 367, c1: 1000000} ; {c1: 562317, c2: 438050} + */ +import { describe, expect, it } from 'vitest'; +import { + legVector, + loadGoldenVectors, + type GoldenLegVector, +} from '../../src/golden-vectors/index.ts'; +import { + isSettlementError, + money, + refundsByTender, + tenderRefundOrders, + type Currency, + type Legs, + type PaidTender, + type TenderKind, +} from '../../src/index.ts'; +import { PYG, USD } from '../fixtures.ts'; + +const set = loadGoldenVectors(); +const LEGS = ['HOST', 'INSURER', 'TAX_THIRD_PARTY', 'PLATFORM'] as const; + +const legsOf = (v: GoldenLegVector, currency: Currency, sign = 1n): Legs => + Object.freeze({ + HOST: money(sign * v.legsMinor.HOST, currency), + INSURER: money(sign * v.legsMinor.INSURER, currency), + TAX_THIRD_PARTY: money(sign * v.legsMinor.TAX_THIRD_PARTY, currency), + PLATFORM: money(sign * v.legsMinor.PLATFORM, currency), + total: money(sign * v.totalMinor, currency), + }); + +const minor = (l: Legs): Record => + Object.fromEntries([...LEGS, 'total' as const].map((k) => [k, l[k].amountMinor])); + +const tender = ( + id: string, + kind: TenderKind, + paid: bigint, + currency: Currency, + capturedRank: number, + committed = 0n, +): PaidTender => ({ + id, + kind, + paid: money(paid, currency), + committed: money(committed, currency), + capturedRank, +}); + +const amounts = (rs: readonly { id: string; amount: { amountMinor: bigint } }[]) => + rs.map((r) => [r.id, r.amount.amountMinor]); + +const caught = (fn: () => unknown): string => { + try { + fn(); + } catch (e) { + return isSettlementError(e) ? e.code : 'AUTRE'; + } + return 'AUCUNE'; +}; + +// T33 : carte 150,00, Yappy 56,66, crédit cash 30,00, crédit promo 20,00 (Σ 256,66 = TJ01) +const T33 = [ + tender('promo', 'PROMO_CREDIT', 2000n, USD, 4), + tender('yappy', 'NON_NATIVE', 5666n, USD, 2), + tender('card', 'NATIVE', 15000n, USD, 1), + tender('cash', 'CASH_CREDIT', 3000n, USD, 3), +]; + +describe('08 E2 — combien chaque moyen rembourse (USD et PYG)', () => { + it('T33 : 187,44 = carte 150,00, Yappy 37,44, crédit cash 0, crédit promo 0 ; ordre de la cascade', () => { + expect(amounts(refundsByTender(money(18744n, USD), T33))).toEqual([ + ['card', 15000n], + ['yappy', 3744n], + ['cash', 0n], + ['promo', 0n], + ]); + }); + + it('TJ16c-d (PYG) : 1 000 367 = carte 1 000 000 et crédit cash 367 ; retenue 437 683 absorbée par le crédit cash d’abord', () => { + const rs = refundsByTender(money(1000367n, PYG), [ + tender('cash', 'CASH_CREDIT', 438050n, PYG, 2), + tender('card', 'NATIVE', 1000000n, PYG, 1), + ]); + expect(amounts(rs)).toEqual([ + ['card', 1000000n], + ['cash', 367n], + ]); + }); + + it('T66 (b) incrémental : après TJ16a-b (carte 150,00, Yappy 37,44 engagés), complément 69,22 = carte 0, Yappy 19,22, cash 30,00, promo 20,00', () => { + const rs = refundsByTender( + money(6922n, USD), + T33.map((t) => + t.id === 'card' + ? { ...t, committed: money(15000n, USD) } + : t.id === 'yappy' + ? { ...t, committed: money(3744n, USD) } + : t, + ), + ); + expect(amounts(rs)).toEqual([ + ['card', 0n], + ['yappy', 1922n], + ['cash', 3000n], + ['promo', 2000n], + ]); + }); + + it('deux cartes : la capture la plus récente absorbe d’abord (oracle `allocate`)', () => { + const recentSecond = refundsByTender(money(1000367n, PYG), [ + tender('c1', 'NATIVE', 1000000n, PYG, 1), + tender('c2', 'NATIVE', 438050n, PYG, 2), + ]); + expect(amounts(recentSecond)).toEqual([ + ['c1', 1000000n], + ['c2', 367n], + ]); + const recentFirst = refundsByTender(money(1000367n, PYG), [ + tender('c1', 'NATIVE', 1000000n, PYG, 2), + tender('c2', 'NATIVE', 438050n, PYG, 1), + ]); + expect(amounts(recentFirst)).toEqual([ + ['c2', 438050n], + ['c1', 562317n], + ]); + }); +}); + +describe('08 E2 puis E7 règle 10 — ordres par moyen, jambes explicites (TJ16a à TJ16d)', () => { + it('USD : TJ02b ⇒ carte = TJ16a, Yappy = TJ16b ; crédits absorbés, sans ordre ; Σ = TJ02b', () => { + const o = tenderRefundOrders(legsOf(legVector(set, 'TJ02b'), USD), T33); + expect(o.reallocation).toBeNull(); + expect(o.refunds.map((r) => [r.id, r.kind])).toEqual([ + ['card', 'NATIVE'], + ['yappy', 'NON_NATIVE'], + ]); + expect(minor(o.refunds[0]!.legs)).toEqual(minor(legsOf(legVector(set, 'TJ16a'), USD, -1n))); + expect(minor(o.refunds[1]!.legs)).toEqual(minor(legsOf(legVector(set, 'TJ16b'), USD, -1n))); + }); + + it('PYG : TJ08b ⇒ carte = TJ16c, crédit cash recréé = TJ16d (PLATFORM seulement) ; Σ = TJ08b à l’unité', () => { + const o = tenderRefundOrders(legsOf(legVector(set, 'TJ08b'), PYG), [ + tender('cash', 'CASH_CREDIT', 438050n, PYG, 2), + tender('card', 'NATIVE', 1000000n, PYG, 1), + ]); + expect(o.refunds.map((r) => [r.id, r.kind])).toEqual([ + ['card', 'NATIVE'], + ['cash', 'CASH_CREDIT'], + ]); + const c = minor(o.refunds[0]!.legs); + const d = minor(o.refunds[1]!.legs); + expect(c).toEqual(minor(legsOf(legVector(set, 'TJ16c'), PYG, -1n))); + expect(d).toEqual(minor(legsOf(legVector(set, 'TJ16d'), PYG, -1n))); + const tj08b = minor(legsOf(legVector(set, 'TJ08b'), PYG, -1n)); + for (const k of [...LEGS, 'total'] as const) expect(c[k]! + d[k]!).toBe(tj08b[k]); + }); +}); + +describe('refus (fail-closed : jamais un moyen remboursé au-delà de son reliquat, jamais un prorata)', () => { + it('remboursement au-delà de Σ reliquats ⇒ REFUND_OUT_OF_RANGE', () => { + expect(caught(() => refundsByTender(money(25667n, USD), T33))).toBe('REFUND_OUT_OF_RANGE'); + const committed = T33.map((t) => ({ ...t, committed: t.paid })); + expect(caught(() => refundsByTender(money(1n, USD), committed))).toBe('REFUND_OUT_OF_RANGE'); + }); + + it('entrée incohérente ⇒ SETTLEMENT_INPUT_INVALID', () => { + const card = tender('card', 'NATIVE', 15000n, USD, 1); + for (const tenders of [ + [card, { ...card, capturedRank: 2 }], // moyen en double + [card, tender('other', 'NATIVE', 100n, USD, 1)], // rang en double + [tender('pyg', 'NATIVE', 100n, PYG, 1)], // devise différente + [tender('zero', 'NATIVE', 0n, USD, 1)], // payé nul + [{ ...card, committed: money(-1n, USD) }], // engagé négatif + [{ ...card, kind: 'GIFT' as TenderKind }], // catégorie inconnue + ]) { + expect(caught(() => refundsByTender(money(100n, USD), tenders))).toBe( + 'SETTLEMENT_INPUT_INVALID', + ); + } + expect(caught(() => refundsByTender(money(-1n, USD), [card]))).toBe('SETTLEMENT_INPUT_INVALID'); + const positive = legsOf(legVector(set, 'TJ02b'), USD, -1n); + expect(caught(() => tenderRefundOrders(positive, T33))).toBe('SETTLEMENT_INPUT_INVALID'); + }); +}); From 53f4946277d14f0471f1f38b5548380e61f5802a Mon Sep 17 00:00:00 2001 From: Projetapploccar <351336702+Projetapploccar@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:04:01 -0300 Subject: [PATCH 2/2] =?UTF-8?q?docs(US-224):=20six=20revues=20ind=C3=A9pen?= =?UTF-8?q?dantes=20de=20la=20partie=20224f=20(PR=20239)=20au=20SHA=204b43?= =?UTF-8?q?a2c0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verdicts : architecture, argent, code, qa, securite, ux APPROUVÉ (constats MINEUR : ordre de verrous markAlerted / awaitChoice, classement de REFUND_OUT_OF_RANGE, tests, textes pt-BR, version du catalogue). Agent-Role: revue-argent Agent-Model: claude-sonnet-5-5 Co-Authored-By: Claude Sonnet 5.5 --- .../reviews/US-224/architecture-2026-11-18b.md | 16 ++++++++++++++++ docs/team/reviews/US-224/argent-2026-11-18b.md | 18 ++++++++++++++++++ docs/team/reviews/US-224/code-2026-11-18b.md | 16 ++++++++++++++++ docs/team/reviews/US-224/qa-2026-11-18b.md | 15 +++++++++++++++ .../reviews/US-224/securite-2026-11-18b.md | 17 +++++++++++++++++ docs/team/reviews/US-224/ux-2026-11-18b.md | 14 ++++++++++++++ 6 files changed, 96 insertions(+) create mode 100644 docs/team/reviews/US-224/architecture-2026-11-18b.md create mode 100644 docs/team/reviews/US-224/argent-2026-11-18b.md create mode 100644 docs/team/reviews/US-224/code-2026-11-18b.md create mode 100644 docs/team/reviews/US-224/qa-2026-11-18b.md create mode 100644 docs/team/reviews/US-224/securite-2026-11-18b.md create mode 100644 docs/team/reviews/US-224/ux-2026-11-18b.md diff --git a/docs/team/reviews/US-224/architecture-2026-11-18b.md b/docs/team/reviews/US-224/architecture-2026-11-18b.md new file mode 100644 index 00000000..e9af73f0 --- /dev/null +++ b/docs/team/reviews/US-224/architecture-2026-11-18b.md @@ -0,0 +1,16 @@ +# Revue architecture — US-224 « remboursements multi-moyens, TJ16 (224f) » (PR n° 239) — 2026-11-18 + +Relecteur : revue-architecture / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : b9dec048df4f061fb0bdb6244dcb9c62eb8adbea..4b43a2c0397b1938c7233a19c4232933cdcc0c57 + +Contexte : lu ADR-166 (PROPOSÉ ; complète ADR-145 / 147 / 148 / 150 / 154), 0141, `schema.md`, README db / STL / PAY, GL-43, passation 224f, 17 v6 (§3.2.7, §4.3, §0.1). `origin/main` (b9dec048) est ancêtre de la tête. Non exécuté : test `schema-doc` (CI verte). + +| # | Gravité | Constat | +| --- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Numérotation 0141 contiguë avec main (0140) ; fichier, en-tête, README db, ADR et passation alignés ; expand / contract respecté (une fonction et un droit de colonne ajoutés, trois corps remplacés à signature et droits identiques, retour arrière décrit). `schema.md` recopié du job base de données (142 migrations, 285 `SECURITY DEFINER`). | +| 2 | INFO | Frontières de modules respectées : STL n'importe que `@rueda/money` et l'index public de PAY (`awaitChoice` via `PgRefundOrders`) ; fonction pure dans `@rueda/money` sans constante de pays ; aucune modification de `docs/specs/`, `.github/` ni `scripts/`. | +| 3 | MINEUR | `CATALOG_VERSION` passe de 78 à 81 avec 79 et 80 « réservées » à US-225 et US-227 : trou tant que ces PR ne sont pas fusionnées, conflit probable sur la même ligne ; GL-41 et GL-42 de même absents (réservés). Sans effet fonctionnel. | +| 4 | INFO | Suites bien tracées (choix du rail sur S10 et virement OQ-BR-12, TJ16d après `funds_holding_enabled`, `payment_cmd_record_operation` acceptant un encaissement crédit, OQ-BR-44, E5, change) dans ADR-166, GL-43 et la passation ; `COMME_TURO.md` : une entrée PROPOSÉ ; aucune décision du fondateur prise à sa place. | +| 5 | MINEUR | Inversion de verrous `markAlerted` puis `awaitChoice` (revue sécurité n° 4) : contredit l'ordre trip → instance posé par 224c / 224e et affirmé dans le commentaire de 0141:367. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-224/argent-2026-11-18b.md b/docs/team/reviews/US-224/argent-2026-11-18b.md new file mode 100644 index 00000000..9642ce86 --- /dev/null +++ b/docs/team/reviews/US-224/argent-2026-11-18b.md @@ -0,0 +1,18 @@ +# Revue argent — US-224 « remboursements multi-moyens, TJ16 (224f) » (PR n° 239) — 2026-11-18 + +Relecteur : revue-argent / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5 ; revue dégradée : famille B indisponible, TECH-007) +Entrées : b9dec048df4f061fb0bdb6244dcb9c62eb8adbea..4b43a2c0397b1938c7233a19c4232933cdcc0c57 + +Contexte : lu `tender-refunds.ts`, `tender-refunds.golden.test.ts`, `trip-cancellation.ts` (`ordersByTender`, `tendersOf`, `orderKey`), 0141 (`payment_cmd_plan_refund`), ADR-166, passation 224f, 08 E2 / règle 10 / TJ16a-d / T66. Oracles relancés (`python -I -X utf8 docs/specs/tools/check_legs.py` : RÉSULTAT OK ; `e2_refunds` T33 → [15 000 ; 3 744 ; 0 ; 0], TJ16c-d → [1 000 000 ; 367], `e2_incremental` T66 b → [0 ; 1 922 ; 3 000 ; 2 000] ; TJ16a / b en USD et TJ16c / d en PYG ligne à ligne). `allocate` à deux cartes recalculé à la main (c1 1 000 000 rang 1, c2 438 050 rang 2, K = 437 683 absorbé par c2 : c2 = 367, c1 = 1 000 000 ; USD 15 000 / 10 666, K = 6 922 : 15 000 et 3 744) : identique aux attendus. Non exécuté ici : vitest et L0 (CI 44337411628 verte). + +| # | Gravité | Constat | +| --- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | E2 incrémental conforme à 08 : `refundable = max(0, payé − engagé)`, K' = Σ reliquats − remboursement, absorption promo → cash → non natif → natif (la capture la plus récente d'abord), reçu = reliquat − absorbé ; puis cascade de la règle 10 par jambe (`settlementOrders`), jamais de prorata ni de division, `bigint` seul (`tender-refunds.ts`, `refundsByTender`, `tenderRefundOrders`). Σ remboursements = −variation, recoupé moyen par moyen. | +| 2 | INFO | Vecteurs TJ16a-d (USD, PYG sans décimale), T33, T66 b, TJ20a : attendus de l'export des oracles, égaux à mon recalcul à l'unité ; Σ TJ16c + TJ16d = TJ08b jambe par jambe (test PYG). | +| 3 | INFO | Fail-closed de bêta : seule la carte est native ; moyen non natif, crédit cash ou promo devant rembourser ⇒ `REFUND_RAIL_UNAVAILABLE` levé AVANT toute écriture (`trip-cancellation.ts:347`, `:578`), transaction annulée, demande garée, alerte P1, jamais de remboursement partiel (contrainte différée 0124). TJ16d (cash recréé) refusé sur tout rail, même si `funds_holding_enabled` valait true (0141 : `BANK_TRANSFER` et `CREDIT_CASH` ⇒ `refund_rail_unavailable`) ; aucun interrupteur écrit, seulement lu (`config_go_live`). | +| 4 | INFO | Clé d'idempotence par moyen `{trip}:{segment}:v1:REFUND:{opération du moyen}:i1:a1` ; la réaffectation porte `LEG_REALLOCATION` (aucune collision avec le remboursement du même moyen). Rejeu en base : même contenu exigé (`refund_instance_idempotency_conflict`). | +| 5 | INFO | Décisions PROPOSÉ (absorption la plus récente d'abord, cascade la plus ancienne d'abord, réaffectation sur le premier moyen de la cascade) cohérentes avec 08 E2 et la règle 10, inscrites (ADR-166, COMME_TURO). Chargebacks perdus (E5), change et OQ-BR-44 reportés : explicites dans ADR-166 et GL-43, sans effet en bêta. | +| 6 | MINEUR | Un remboursement qui dépasse Σ reliquats (`REFUND_OUT_OF_RANGE`, moyens déjà engagés) est désormais levé dans `#apply`, donc classé FAILED (alerte `TRIP_CANCELLATION_FAILED`) et non FIN_REVIEW comme le dit l'en-tête (`trip-cancellation.ts:15`) ; sans conséquence monétaire (rien écrit, P1), mais le routage vers FINANCE diffère. À aligner (commentaire ou classement). | +| 7 | INFO | Base : Σ instances d'un moyen (hors CANCELLED et SUPERSEDED, FAILED et PENDING_CUSTOMER_CHOICE comptés) ≤ payé, sous le verrou du trip, après la garde 0121 (0141:316-334) ; devise du moyen = devise du trip ; montants entiers en texte `^[0-9]{1,18}$`, aucun décimal. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-224/code-2026-11-18b.md b/docs/team/reviews/US-224/code-2026-11-18b.md new file mode 100644 index 00000000..775ca95e --- /dev/null +++ b/docs/team/reviews/US-224/code-2026-11-18b.md @@ -0,0 +1,16 @@ +# Revue code — US-224 « remboursements multi-moyens, TJ16 (224f) » (PR n° 239) — 2026-11-18 + +Relecteur : revue-code / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : b9dec048df4f061fb0bdb6244dcb9c62eb8adbea..4b43a2c0397b1938c7233a19c4232933cdcc0c57 + +Contexte : lu le diff complet (`tender-refunds.ts`, `trip-cancellation.ts`, `refund-scheduler.ts`, `pg-stores.ts`, 0141, S10, console, i18n). Pas d'exécution locale (CI 44337411628 verte). + +| # | Gravité | Constat | +| --- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Fonctions pures, entrées validées (`checkTenders` : devise, payé ≤ 0, rangs et identités en double), sorties gelées ; le recoupement ordre ↔ moyen de `tenderRefundOrders` est contrôlé, pas supposé. `ordersByTender` calcule tous les ordres avant la première écriture. | +| 2 | MINEUR | `trip-cancellation.ts:15` (en-tête) dit `REFUND_OUT_OF_RANGE` ⇒ revue FIN ; depuis 224f l'erreur sort de `#apply` et est classée FAILED (revue argent n° 6). Commentaire périmé ou classement à aligner. | +| 3 | MINEUR | Inversion de l'ordre de verrous `markAlerted` puis `awaitChoice` (`refund-scheduler.ts:136-140`), voir revue sécurité n° 4. | +| 4 | INFO | `tendersOf` lit le reliquat sans verrou explicite avant `plan_refund` ; le verrou du trip est déjà pris par la transition d'annulation et la base reste l'arbitre (`refund_exceeds_tender` ⇒ FIN_REVIEW). `tenderKindOf` : moyen inconnu ou `null` ⇒ non natif (jamais supposé natif). | +| 5 | INFO | `phaseOf('PENDING_CUSTOMER_CHOICE') = ATTENTION` et suppression du cas `PREPARING` cohérentes ; commentaire de `trip-refunds.ts` mis à jour. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-224/qa-2026-11-18b.md b/docs/team/reviews/US-224/qa-2026-11-18b.md new file mode 100644 index 00000000..5b8cb5f3 --- /dev/null +++ b/docs/team/reviews/US-224/qa-2026-11-18b.md @@ -0,0 +1,15 @@ +# Revue qa — US-224 « remboursements multi-moyens, TJ16 (224f) » (PR n° 239) — 2026-11-18 + +Relecteur : revue-qa / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : b9dec048df4f061fb0bdb6244dcb9c62eb8adbea..4b43a2c0397b1938c7233a19c4232933cdcc0c57 + +Contexte : lu `l0-us224f-multi-tender.test.ts` (12 tests : 5 par pays × 2, plus 1, plus 1), `tender-refunds.golden.test.ts`, bloc US-224f de `trip-cancellation.test.ts`, `refund-scheduler.test.ts`, `trip-refunds.test.ts`, `cancel-view.test.tsx`, `support/pay.ts`. L0 sous `app_worker` / `app_api` via `withRole` (assertion L0-05), PA en USD (TJ16a / b) et PY en PYG (TJ16c / d), transactions annulées ; attendus issus de l'export des oracles, jamais du code testé. Aucune exécution locale (CI verte). + +| # | Gravité | Constat | +| --- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Tests existants modifiés, examinés un par un : `trip-cancellation.test.ts` (colonnes `amount_minor` et `committed_minor` ajoutées aux lignes simulées, titre « capture unique » ⇒ « encaissement » ; assertions inchangées, bloc ajouté) ; `refund-scheduler.test.ts` (réponse simulée et assertions AJOUTÉES, rien retiré) ; `trip-refunds.test.ts` (PENDING_CUSTOMER_CHOICE PREPARING ⇒ ATTENTION : changement de comportement voulu, justifié par ADR-166 décision 6, pas un affaiblissement) ; `cancel-view.test.tsx` (13 ⇒ 16, la boucle contrôle les 4 langues) ; `support/pay.ts` (paramètre `method`, défaut `CARD` : appels existants inchangés). | +| 2 | MINEUR | L0 « deux cartes » : le dépassement d'une unité n'asserte que le SQLSTATE `55000` (`l0-us224f-multi-tender.test.ts:262`), pas la contrainte `refund_exceeds_collected` : « les refus existants gardent leur contrainte » n'est pas épinglé. Ajouter `constraint`. | +| 3 | MINEUR | Aucun test du rattachement de la réaffectation au premier moyen de la cascade (décision PROPOSÉ, `trip-cancellation.ts:330-345`) ni de concurrence pour `await_choice` / `markAlerted` (revue sécurité n° 4). | +| 4 | INFO | Preuves complètes de l'énoncé : refus de TJ16b / TJ16d sur tout rail (natif, `ROLLBACK_AND_RECHARGE`, virement, crédit cash), reprise `attempt_no` 2, rejeu `DUPLICATE`, hors file `payment_refunds_due`, supersession, droits (42501) ; Σ jambes = TJ02b / TJ08b à l'unité ; `REFUND_RAIL_UNAVAILABLE` et rien écrit testés côté processeur. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-224/securite-2026-11-18b.md b/docs/team/reviews/US-224/securite-2026-11-18b.md new file mode 100644 index 00000000..41246bc9 --- /dev/null +++ b/docs/team/reviews/US-224/securite-2026-11-18b.md @@ -0,0 +1,17 @@ +# Revue securite — US-224 « remboursements multi-moyens, TJ16 (224f) » (PR n° 239) — 2026-11-18 + +Relecteur : revue-securite / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5 ; revue dégradée : famille B indisponible, TECH-007) +Entrées : b9dec048df4f061fb0bdb6244dcb9c62eb8adbea..4b43a2c0397b1938c7233a19c4232933cdcc0c57 + +Contexte : lu 0141 en entier (garde, supersession, `payment_cmd_plan_refund`, `payment_cmd_refund_await_choice`), allowlist `SECURITY DEFINER`, `errors.ts`, ordonnanceur et `PgRefundOrders.awaitChoice`, L0 `l0-us224f-multi-tender`. Aucun fichier de matrice ni d'inventaire de droits applicatifs modifié (le diff ne touche que l'allowlist, `errors.ts` et `schema.md` généré). Non exécuté ici : L0 et CI (run 44337411628 vert). + +| # | Gravité | Constat | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | `payment_cmd_refund_await_choice` : `SECURITY DEFINER`, propriétaire `cmd_money_owner`, `search_path = pg_catalog, pg_temp`, objets qualifiés, `REVOKE ALL FROM PUBLIC`, EXECUTE `app_worker` seul (L0 : `app_api` ⇒ 42501 ; travailleurs `settlement`, `webhook_ingest`, `reconciliation` ⇒ 42501 ; instance inconnue refusée). Une seule transition (FAILED → PENDING_CUSTOMER_CHOICE), et seulement si l'ordre est FAILED (rejet confirmé ; UNKNOWN et SUBMITTED refusés). | +| 2 | INFO | Garde (0141, bloc US-224f) : `attempt_no` ne change que sur FAILED → PENDING_CUSTOMER_CHOICE avec + 1 exactement ; `PENDING_CUSTOMER_CHOICE → SUPERSEDED` est le seul autre départ. Le droit de colonne `UPDATE (attempt_no)` va à `cmd_money_owner` seulement ; `app_worker` ne peut pas écrire l'instance (L0 : 42501). Aucun droit applicatif ajouté, aucun interrupteur écrit. | +| 3 | INFO | Contraintes de `plan_refund` : `refund_exceeds_tender` est contrôlé APRÈS `payment_cmd_record_operation` (garde du trip 0121), donc les refus existants gardent leur contrainte ; `refund_rail_not_native` et la devise sont contrôlés avant, après le rejeu (un rejeu identique reste rejoué). FAILED et PENDING_CUSTOMER_CHOICE comptés : une obligation échouée n'ouvre pas de double remboursement. | +| 4 | MINEUR | Ordre des verrous : l'ordonnanceur appelle `markAlerted` (UPDATE de la ligne d'instance) PUIS `awaitChoice` (verrou du trip `FOR UPDATE`, 0141:368) dans la même transaction (`refund-scheduler.ts:136-140`), alors que planification, envoi, report et supersession prennent le trip d'abord puis l'instance : inversion instance → trip, interblocage possible (40P01) avec une supersession ou une planification concurrente. Détecté et repris (40P01 classé RETRY côté annulation ; côté ordonnanceur l'alerte déjà émise serait rejouée : doublon d'alerte seulement). Correction simple : appeler `awaitChoice` avant `markAlerted`. | +| 5 | MINEUR | Le commentaire de 0141:367 (« même ordre de verrous que la planification ») est inexact tant que le constat précédent n'est pas corrigé côté TypeScript. | +| 6 | INFO | Rien de sensible journalisé ou affiché : codes seulement, messages de console sans identifiant, aucun secret. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-224/ux-2026-11-18b.md b/docs/team/reviews/US-224/ux-2026-11-18b.md new file mode 100644 index 00000000..3543f26c --- /dev/null +++ b/docs/team/reviews/US-224/ux-2026-11-18b.md @@ -0,0 +1,14 @@ +# Revue ux — US-224 « remboursements multi-moyens, TJ16 (224f) » (PR n° 239) — 2026-11-18 + +Relecteur : revue-ux / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : b9dec048df4f061fb0bdb6244dcb9c62eb8adbea..4b43a2c0397b1938c7233a19c4232933cdcc0c57 + +Contexte : lu `trip-refunds.ts`, `refund-phase.tsx`, catalogues `web.refund.*` et les trois nouveaux textes de console dans les quatre langues. Pas de rendu navigateur (aucun écran nouveau). + +| # | Gravité | Constat | +| --- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | S10 : PENDING_CUSTOMER_CHOICE ⇒ badge « En cours de vérification / En revisión / Under review / Em análise » et phrase « notre équipe s'en occupe, tu n'as rien à faire » (déjà livrée en quatre langues) : cohérent, aucune action fausse demandée tant que le choix du rail n'est pas ouvert ; pas de date d'émission affichée. | +| 2 | MINEUR | pt-BR `REFUND_RAIL_NOT_NATIVE` : « um reembolso no cartão sobre outro meio de pagamento » est raide ; préférer « em outro meio de pagamento ». es : « sobre otro medio » est correct mais lourd. Console seulement, non bloquant. | +| 3 | INFO | Les trois textes de console es / en / fr / pt-BR sont naturels et disent ce qui s'est passé (« rien n'a été enregistré », « FINANCE s'en occupe ») ; `REFUND_EXCEEDS_TENDER` n'indique pas l'étape suivante (INFO). Clés présentes dans les quatre catalogues (test de la console). | + +Verdict : APPROUVÉ