diff --git a/apps/api/src/modules/cfg/data/params.json b/apps/api/src/modules/cfg/data/params.json index af56146fa..cdb379673 100644 --- a/apps/api/src/modules/cfg/data/params.json +++ b/apps/api/src/modules/cfg/data/params.json @@ -2094,6 +2094,99 @@ "decision": "PROPOSED", "decisionRef": "ADR-146 PROPOSÉ (US-223c) ; COMME_TURO", "values": { "PA": false, "PY": false } + }, + { + "key": "deposit_always_required", + "type": "BOOL", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 (déclencheur COUNTRY : caution imposée à tout trip du pays) ; 17 §7.2 ; ADR-108 ; absent ou illisible : déclencheur vrai, caution exigée (fail-closed)", + "status": "PROPOSÉ comme Turo (ADR-108) : aucune caution par défaut", + "decision": "PROPOSED", + "decisionRef": "17 §7.2 PROPOSÉ (ADR-108 ; COMME_TURO OQ-P2P-04)", + "values": { "PA": false, "PY": false } + }, + { + "key": "deposit_trigger_classes", + "type": "JSON", + "unit": "value_class_set", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 (déclencheur CLASS : classe de valeur du véhicule, ADR-159) ; 17 §7.2 ; ADR-108 ; absent : toutes les classes déclenchent (fail-closed)", + "status": "PROPOSÉ comme Turo ({LUXE}, équivalent Super Deluxe) ; à confirmer par le fondateur avant la mise en ligne", + "decision": "TO_DECIDE", + "decisionRef": "OQ-P2P-04 ; décision du fondateur du 2026-11-12 (hésitation sur le luxe) ; ADR-108", + "values": { "PA": ["LUXE"], "PY": ["LUXE"] } + }, + { + "key": "deposit_young_driver_age", + "type": "INT", + "unit": "years", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 (déclencheur AGE, seuil strict, plus jeune conducteur approuvé) ; 17 §7.2 ; ADR-108 ; absent : tout âge déclenche (fail-closed)", + "status": "PROPOSÉ comme Turo (30 ans) ; sans effet tant que deposit_young_driver_classes est vide", + "decision": "PROPOSED", + "decisionRef": "17 §7.2 PROPOSÉ (ADR-108)", + "values": { "PA": 30, "PY": 30 } + }, + { + "key": "deposit_young_driver_classes", + "type": "JSON", + "unit": "value_class_set", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 (déclencheur AGE : classes du catalogue concernées) ; 17 §7.2 ; absent : toutes les classes (fail-closed)", + "status": "décidé (DEC-FONDATEUR-21, 2026-11-12) : ensemble vide, aucune caution liée à l’âge au PA et au PY", + "decision": "DECIDED", + "decisionRef": "DEC-FONDATEUR-21 (2026-11-12) ; 17 §7.2", + "values": { "PA": [], "PY": [] } + }, + { + "key": "deposit_on_risk_flag", + "type": "BOOL", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 (déclencheur RISK : trip signalé par le contrôle de risque, BR-VERIF-09, ADM-029) ; 17 §7.2 ; absent : déclencheur vrai (fail-closed)", + "status": "PROPOSÉ comme Turo (vrai) ; sans effet tant que risk_control_deployed est faux", + "decision": "PROPOSED", + "decisionRef": "17 §7.2 PROPOSÉ (ADR-108)", + "values": { "PA": true, "PY": true } + }, + { + "key": "risk_control_deployed", + "type": "BOOL", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 (« contrôle non déployé ≠ en panne », risk_control_deployed) ; ADR-108 point 3 bis ; faux : RISK non évalué (risk_evaluated = false) ; absent : contrôle tenu pour déployé, une panne rend RISK vrai (fail-closed)", + "status": "PROPOSÉ (faux tant que la caution sur signal de risque n’est pas branchée au contrôle de risque de US-209 ; changé seulement par l’administration avec journal)", + "decision": "PROPOSED", + "decisionRef": "ADR-108 point 3 bis ; 08 BR-PAY-06 (à reporter dans 17 §7.2)", + "values": { "PA": false, "PY": false } + }, + { + "key": "deposit_reauth_lead_h", + "type": "DURATION", + "unit": "h", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 « Mécanisme » rail (a) : ré-autorisation planifiée à auth_expiry − 24 h", + "status": "PROPOSÉ (08 BR-PAY-06 ; la capacité SUPPORTS_REAUTH reste à valider avec le PSP)", + "decision": "PROPOSED", + "decisionRef": "08 BR-PAY-06 ; ADR-164 (à reporter dans 17 §7.2)", + "values": { "PA": 24, "PY": 24 } + }, + { + "key": "deposit_fee_notice_h", + "type": "DURATION", + "unit": "h", + "scopes": ["COUNTRY"], + "failMode": "BLOCK", + "source": "08 BR-PAY-06 « Libération à heure fixe » : un frais annexe n’est capturé sur la caution que s’il a été notifié au voyageur au moins 48 h avant la décision (délai BR-REIMB-03) ; sinon débit MIT séparé", + "status": "PROPOSÉ (08 BR-PAY-06, BR-REIMB-03)", + "decision": "PROPOSED", + "decisionRef": "08 BR-PAY-06 ; ADR-164 (à reporter dans 17 §7.2)", + "values": { "PA": 48, "PY": 48 } } ] } diff --git a/apps/api/src/modules/cfg/internal/defaults.test.ts b/apps/api/src/modules/cfg/internal/defaults.test.ts index 6d3922cab..e09c8c47f 100644 --- a/apps/api/src/modules/cfg/internal/defaults.test.ts +++ b/apps/api/src/modules/cfg/internal/defaults.test.ts @@ -99,6 +99,7 @@ const EXPECTED_TO_DECIDE: Readonly> = { deposit_charge_cap: '17 statut OQ-PAY-06, OQ-PAY-19', deposit_max: '17 statut J-ADM-031', deposit_safety_h: '17 statut OQ-PAY-02', + deposit_trigger_classes: '17 statut « à confirmer par le fondateur » (OQ-P2P-04 ; US-225)', elig_age_years_ceiling: '16 HST-019 (« valeurs À DÉCIDER dans ADM-031 ») ; 22 OQ-P2P-02 (US-124)', elig_doc_compulsory_insurance: '16 HST-039 ; 22 OQ-P2P-02 (US-124)', elig_doc_inspection: '16 HST-039 ; 22 OQ-P2P-02 (US-124)', diff --git a/apps/api/src/modules/cfg/internal/model.ts b/apps/api/src/modules/cfg/internal/model.ts index b121b4f51..067aa8701 100644 --- a/apps/api/src/modules/cfg/internal/model.ts +++ b/apps/api/src/modules/cfg/internal/model.ts @@ -19,6 +19,13 @@ export type ParamScope = (typeof PARAM_SCOPES)[number]; export const FAIL_MODES = ['BLOCK', 'FALSE', 'ZERO'] as const; export type FailMode = (typeof FAIL_MODES)[number]; +/** + * Classes de valeur d'un véhicule (08 BR-ACC-05 ; 17 §3.2.3 `vehicle.value_class`), vocabulaire + * fermé commun à tous les pays : forme des paramètres d'unité `value_class_set` (US-225). + */ +export const VALUE_CLASSES = ['STANDARD', 'PREMIUM', 'LUXE'] as const; +export type ValueClass = (typeof VALUE_CLASSES)[number]; + /** Types de ligne d'un devis (17 §3.2 `quote_line.line_type`, 08 `LINES`) : `tax_line_config` les couvre tous. */ export const TAX_LINE_TYPES = [ 'TRIP_PRICE', diff --git a/apps/api/src/modules/cfg/internal/parse.ts b/apps/api/src/modules/cfg/internal/parse.ts index b760d2c67..d9b82ea98 100644 --- a/apps/api/src/modules/cfg/internal/parse.ts +++ b/apps/api/src/modules/cfg/internal/parse.ts @@ -16,6 +16,7 @@ import { PARAM_SCOPES, PARAM_TYPES, TAX_LINE_TYPES, + VALUE_CLASSES, } from './model.js'; import type { CountryConfig, @@ -36,6 +37,7 @@ import type { TaxLineConfig, TaxLineType, TimeZoneCheck, + ValueClass, PhoneNumberingConfig, RegulatoryNotice, } from './model.js'; @@ -735,6 +737,16 @@ function checkJsonShape(c: Collector, path: string, def: ParamDefinition, value: c.add(path, 'part « n/d » dans [0 ; 1] attendue'); return false; } + if (unit === 'value_class_set') { + // US-225 (ADR-164) : ensemble de classes de valeur (08 BR-ACC-05) ; vide permis (aucune + // classe, DEC-FONDATEUR-21) ; sans doublon, dans l'ordre du vocabulaire fermé + const rank = (v: unknown): number => VALUE_CLASSES.indexOf(v as ValueClass); + const ok = + Array.isArray(value) && + value.every((v, i) => rank(v) >= 0 && (i === 0 || rank(v) > rank(value[i - 1]))); + if (!ok) c.add(path, `ensemble de classes attendu, ordonné : ${VALUE_CLASSES.join(', ')}`); + return ok; + } if (unit.endsWith('_list')) { const ok = Array.isArray(value) && diff --git a/apps/api/src/modules/cfg/internal/seed-sql.test.ts b/apps/api/src/modules/cfg/internal/seed-sql.test.ts index c7ba2be74..62dd961ca 100644 --- a/apps/api/src/modules/cfg/internal/seed-sql.test.ts +++ b/apps/api/src/modules/cfg/internal/seed-sql.test.ts @@ -84,17 +84,24 @@ describe('migration de graines', () => { ); it('0009 reste rendue sans les paramètres ajoutés après elle (immuable, ADR-044, ADR-075)', () => { - for (const { prefix } of POST_SEED_PARAMS) expect(rendered).not.toContain(`'${prefix}`); + for (const { prefix, extraKeys } of POST_SEED_PARAMS) { + expect(rendered).not.toContain(`'${prefix}`); + for (const key of extraKeys ?? []) expect(rendered).not.toContain(`'${key}'`); + } }); it.each(POST_SEED_PARAMS)( 'graine complémentaire $file identique au rendu des paramètres $prefix*', - ({ prefix, file }) => { + ({ prefix, file, extraKeys }) => { const delta = renderParamSeedSql(config, prefix); if (process.env['RUEDA_WRITE_CFG_SEED'] === '1') writeFileSync(migrationUrl(file), delta, 'utf8'); expect(readFileSync(migrationUrl(file), 'utf8').replaceAll('\r\n', '\n')).toBe(delta); - const keys = [...config.definitions.keys()].filter((k) => k.startsWith(prefix)); + const keys = [...config.definitions.keys()].filter( + (k) => k.startsWith(prefix) || (extraKeys ?? []).includes(k), + ); + // US-225 : chaque clé nouvelle nommée existe dans le registre + for (const key of extraKeys ?? []) expect(keys).toContain(key); expect(keys.length).toBeGreaterThan(0); for (const key of keys) { expect(delta).toContain(`('${key}', '`); diff --git a/apps/api/src/modules/cfg/internal/seed-sql.ts b/apps/api/src/modules/cfg/internal/seed-sql.ts index a13d33bf7..1922c653a 100644 --- a/apps/api/src/modules/cfg/internal/seed-sql.ts +++ b/apps/api/src/modules/cfg/internal/seed-sql.ts @@ -38,6 +38,11 @@ export const POST_SEED_PARAMS: readonly { readonly refs?: string; /** Clés définies dans 0009 dont les valeurs sont insérées par ce groupe (US-226). */ readonly valueKeys?: readonly string[]; + /** + * Clés NOUVELLES du groupe hors du préfixe (US-225, ADR-164) : noms de 17 §7.2 sans préfixe + * commun (`deposit_*` couvre des clés de 0009). Le préfixe reste l'identifiant du groupe. + */ + readonly extraKeys?: readonly string[]; }[] = [ { prefix: 'rate_limit_', file: '0046_config_rate_limit_params.sql', story: 'US-052' }, { prefix: 'otp_rate_', file: '0065_config_otp_rate_params.sql', story: 'US-104' }, @@ -144,11 +149,31 @@ export const POST_SEED_PARAMS: readonly { story: 'US-113', refs: '08 BR-ACC-05 ; BOARD N-83 ; ADR-159', }, + { + prefix: 'deposit_always_required', + file: '0142_config_deposit_rail_params.sql', + story: 'US-225', + refs: '08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164', + extraKeys: [ + 'deposit_fee_notice_h', + 'deposit_on_risk_flag', + 'deposit_reauth_lead_h', + 'deposit_trigger_classes', + 'deposit_young_driver_age', + 'deposit_young_driver_classes', + 'risk_control_deployed', + ], + }, ]; +/** La clé appartient au groupe : préfixe ou clé nouvelle nommée (`extraKeys`). */ +export function inPostSeedGroup(step: (typeof POST_SEED_PARAMS)[number], key: string): boolean { + return key.startsWith(step.prefix) || (step.extraKeys?.includes(key) ?? false); +} + /** La clé appartient à un groupe de paramètres ajouté après 0009. */ export function isPostSeedParam(key: string): boolean { - return POST_SEED_PARAMS.some((p) => key.startsWith(p.prefix)); + return POST_SEED_PARAMS.some((p) => inPostSeedGroup(p, key)); } /** Les valeurs de la clé (définie dans 0009) sont insérées par un groupe ajouté après 0009. */ @@ -466,11 +491,16 @@ export function renderParamSeedSql(config: CountryConfig, prefix: string): strin const step = POST_SEED_PARAMS.find((p) => p.prefix === prefix); if (!step) throw new Error(`groupe de paramètres « ${prefix} » absent de POST_SEED_PARAMS`); const definitions = [...config.definitions.values()] - .filter((d) => d.key.startsWith(prefix)) + .filter((d) => inPostSeedGroup(step, d.key)) .sort((a, b) => a.key.localeCompare(b.key)); - const values = sortValues(config.values.filter((v) => v.key.startsWith(prefix))); + const values = sortValues(config.values.filter((v) => inPostSeedGroup(step, v.key))); const number = step.file.slice(0, 4); const like = `${prefix.replaceAll('_', '\\_')}%`; + const extra = step.extraKeys ?? []; + const where = + extra.length === 0 + ? ` WHERE d.key LIKE ${lit(like)}` + : ` WHERE (d.key LIKE ${lit(like)} OR d.key = ANY (${textArray(extra)}))`; return [ [ `-- ${number} — graine complémentaire : paramètres « ${prefix}* » (${step.story} ; 17 §7.2).`, @@ -480,7 +510,10 @@ export function renderParamSeedSql(config: CountryConfig, prefix: string): strin '-- Valeurs PROPOSÉES ; valid_from posé par la garde (platform.now()).', '--', `-- Retour arrière (base sans dépendance) : DELETE des valeurs puis des définitions dont la clé`, - `-- commence par « ${prefix} » ; jamais en production : nouvelle migration à la place.`, + extra.length === 0 + ? `-- commence par « ${prefix} » ; jamais en production : nouvelle migration à la place.` + : `-- commence par « ${prefix} » ou vaut ${extra.join(', ')} ;\n` + + '-- jamais en production : nouvelle migration à la place.', '', ].join('\n'), definitionInsert(definitions), @@ -497,7 +530,7 @@ export function renderParamSeedSql(config: CountryConfig, prefix: string): strin 'BEGIN', ' IF EXISTS (SELECT 1 FROM core.config_param_definition AS d', ' CROSS JOIN core.config_country AS c', - ` WHERE d.key LIKE ${lit(like)}`, + where, ' AND NOT EXISTS (SELECT 1 FROM core.config_param_value AS v', ' WHERE v.key = d.key AND v.country_code = c.code)) THEN', ` RAISE EXCEPTION 'graine : paramètre ${prefix}* sans valeur pour un pays' USING ERRCODE = 'check_violation';`, diff --git a/apps/api/src/modules/pay/README.md b/apps/api/src/modules/pay/README.md index c80f73413..5b5233b89 100644 --- a/apps/api/src/modules/pay/README.md +++ b/apps/api/src/modules/pay/README.md @@ -34,7 +34,7 @@ Entités de 17 §3.2.7 : | `mit_consent` | cible 17, pas encore créée | | `tender` | cible 17, pas encore créée | | `refund_instance` | cible 17, pas encore créée | -| `deposit_hold` | cible 17, pas encore créée | +| `deposit_hold` | cible 17, pas encore créée (US-701) ; rails et décision prêts en fonctions pures (US-225) | | `chargeback` | cible 17, pas encore créée | | `debt_balance` | cible 17, pas encore créée | | `payment_plan` | cible 17, pas encore créée | @@ -43,6 +43,10 @@ Entités de 17 §3.2.7 : Hors entités de 17 : `core.payment_psp_capability_catalog` (catalogue des capacités, migration 0039 ; `SUPPORTS_PAYOUT_WITHOUT_HOST_TAX_ID` ajoutée par 0087, non bloquante, lue par le KYC de l'hôte : inconnue ⇒ numéro fiscal exigé avant l'activation, ADR-115). Commandes `SECURITY DEFINER` (famille `cmd_money`) : `core.payment_cmd_record_operation`, `payment_cmd_apply_operation_status`, `payment_cmd_receive_webhook` (0028), `payment_cmd_register_submerchant`, `payment_cmd_record_submerchant_status` (0039). Détail : `packages/db/README.md`, sections « Port PaymentProvider » et « Port de place de marché ». +## Caution « comme Turo » (US-225 ; 08 BR-PAY-06 ; ADR-108, ADR-164) + +**Aucune caution par défaut.** Une caution n'existe que si un déclencheur paramétré par pays est vrai (`deposit_always_required`, `deposit_trigger_classes` = {LUXE}, âge sur `deposit_young_driver_classes` = vide au PA et au PY, signal de risque si `risk_control_deployed`) : graine `0142`, valeurs PROPOSÉES. Au checkout, avant le paiement, `decideDepositGate` rend `NOT_REQUIRED` (aucun rail évalué), `REQUIRED` avec le rail choisi par configuration, ou un refus (`PARAM_MISSING` si `deposit_amount` manque, `DEPOSIT_RAIL_UNAVAILABLE` avec les jours possibles). Le rail « débit puis remboursement » reste fermé tant que `funds_holding_enabled[pays]` = `false` (aucun fonds de tiers détenu) ; une capacité PSP inconnue vaut « non ». `planDepositDecision` et `DepositRailExecutor` exécutent la décision sur le port (FAKE seulement) avec le montant explicite de chaque commande. **Non branché** au checkout ni à un travailleur dans cette story : `deposit_hold`, l'écriture au checkout, les minuteries et l'écran S05 sont à US-701 / US-702 (voir `docs/team/handoffs/US-225.md`). + ## Événements Aucun événement de domaine n'est émis ni consommé par le code de PAY aujourd'hui. Chaque statut reçu est écrit dans `core.payment_payment_operation_event` (pas un événement d'outbox). La commande `CANCEL_ORDER` est écrite dans `core.payment_payment_command` par les commandes du hold (AVL, migration 0040), pas par un événement. diff --git a/apps/api/src/modules/pay/index.ts b/apps/api/src/modules/pay/index.ts index 83c75ecd6..ed3508d6b 100644 --- a/apps/api/src/modules/pay/index.ts +++ b/apps/api/src/modules/pay/index.ts @@ -105,6 +105,72 @@ export type { export { COMMAND_KINDS, MoneyCommandSender } from './internal/money-command-sender.js'; export type { CommandKind, MoneyCommand, SendOutcome } from './internal/money-command-sender.js'; +export { depositOperationKey, DEPOSIT_OPERATION_TYPES } from './internal/idempotency.js'; +export type { DepositOperationType } from './internal/idempotency.js'; + +// Caution « comme Turo » : déclencheurs, rails, décision, exécution (US-225, ADR-164) +export { + DEPOSIT_TRIGGERS, + DEPOSIT_VALUE_CLASSES, + depositAmountFor, + evaluateDepositTriggers, +} from './internal/deposit-triggers.js'; +export type { + DepositStage, + DepositTrigger, + DepositTriggerContext, + DepositTriggerDecision, + DepositTriggerParams, + DepositValueClass, +} from './internal/deposit-triggers.js'; +export { + chargeLegs, + completeRailParams, + decideDepositGate, + DEPOSIT_EVENTS, + DEPOSIT_HOLD_STATUSES, + DEPOSIT_MECHANISMS, + depositAuthAt, + depositAuthExpiry, + depositDecisionAt, + depositHoldValidityHours, + depositReauthDueAt, + depositReleaseAt, + isCapturableOnDeposit, + nextDepositStatus, + planDepositDecision, + requiredHoldMinutes, + selectDepositRail, +} from './internal/deposit-rails.js'; +export type { + DepositDecisionInput, + DepositDecisionPlan, + DepositEvent, + DepositFeePart, + DepositGateDecision, + DepositGateInput, + DepositHoldStatus, + DepositIncidentalFee, + DepositMechanism, + DepositRail, + DepositRailCapabilities, + DepositRailParams, + DepositRailRequest, + DepositRailSelection, + DepositStep, +} from './internal/deposit-rails.js'; +export { DepositRailExecutor } from './internal/deposit-executor.js'; +export type { + DepositExecution, + DepositPaymentProvider, + DepositReauthOutcome, + DepositReference, + DepositStepResult, + PlaceDepositRequest, +} from './internal/deposit-executor.js'; +export { DEPOSIT_CONFIG_KEYS, PgDepositRailConfigReader } from './internal/pg-deposit-config.js'; +export type { DepositRailConfig } from './internal/pg-deposit-config.js'; + // Webhooks (17 §4.4) export { WEBHOOK_MAX_BODY_BYTES, diff --git a/apps/api/src/modules/pay/internal/README.md b/apps/api/src/modules/pay/internal/README.md index 0deee0634..6cd66dd98 100644 --- a/apps/api/src/modules/pay/internal/README.md +++ b/apps/api/src/modules/pay/internal/README.md @@ -14,6 +14,10 @@ Aucun code métier ne connaît un PSP. Jusqu'au lot C, seul l'adaptateur **FAKE* | `webhook-processor.ts` | travailleur `webhook_ingest` : rattachement (quarantaine 15 min), **lire puis appliquer**, rangs des statuts (ordre de livraison jamais supposé). Un webhook à horodatage signé hors de ± 5 min (`QUARANTINED`, `SIGNED_TIMESTAMP_OUT_OF_TOLERANCE`) n'est appliqué qu'après une lecture réussie du PSP (preuve `POLL`) ; sans lecture, il passe `FAILED` (`SIGNED_TIMESTAMP_UNVERIFIED`) avec une alerte, jamais une preuve `WEBHOOK_SIGNED`. Un élément mis en quarantaine parce que l'opération était introuvable (reçu dans la fenêtre) garde la preuve du webhook (US-049, RT-CONC-53). En base (0055), un statut terminal de source `WEBHOOK` n'est appliqué que si `raw_ref` désigne un webhook signé reçu et rattaché à l'opération ; sinon l'issue est `UNPROVEN` (journalisée par le travailleur). | | `pan.ts` | détecteur et masque de PAN (même définition que la contrainte `webhook_inbox_no_pan`, migration 0029 : UUID écartés, 13 à 19 chiffres tout groupage, premier chiffre non nul de 2 à 8, Luhn ; temps linéaire ; vecteurs `packages/db/test/support/pan-vectors.json`). | | `pg-stores.ts` | adaptateurs PostgreSQL : commandes `core.payment_*` (migration 0028) sous `app_api` ou un travailleur nommé (`withPaymentWorker`). | +| `deposit-triggers.ts` | caution « comme Turo » (US-225, ADR-108, ADR-164) : **aucune caution par défaut** ; déclencheurs `COUNTRY`, `CLASS`, `AGE`, `RISK` (08 BR-PAY-06) ; avant le checkout seuls `COUNTRY` et `CLASS` ; fail-closed (paramètre absent, classe ou âge inconnus, contrôle déployé en panne ⇒ vrai ; contrôle non déployé ⇒ `RISK` non évalué) ; montant unique `deposit_amount[pays][classe]`, absent ⇒ `null` (`PARAM_MISSING`). Résultat [C2], jamais rendu au voyageur ni à l'hôte. | +| `deposit-rails.ts` | rails de la caution : `decideDepositGate` (checkout, avant le paiement : `NOT_REQUIRED`, `REQUIRED` + rail, refus `PARAM_MISSING` / `DEPOSIT_RAIL_UNAVAILABLE` avec les jours possibles) ; rail choisi par configuration (pré-autorisation unique si `H_requise ≤ V`, ré-autorisation si `SUPPORTS_REAUTH`, débit puis remboursement seulement si `funds_holding_enabled` et `deposit_charge_cap` ≥ montant, sinon refus) ; échéancier (`auth_at`, `auth_expiry`, ré-autorisation, `release_at`, `decision_at`) ; `planDepositDecision` (T57 capture puis VOID, T58 VOID puis MIT, montants et jambes explicites) ; machine d'état de `deposit_hold.status`. | +| `deposit-executor.ts` | `DepositRailExecutor` : pose, ré-autorisation (refus ⇒ `DEPOSIT_REAUTH_FAILED` pour l'ops, aucun débit), exécution de la décision par le port, clés `deposit:{id}:{op}:i{n}:a{m}` ; « débit puis remboursement » refusé sans appel si `funds_holding_enabled` = false. FAKE seulement (aucun travailleur de production). | +| `pg-deposit-config.ts` | `PgDepositRailConfigReader` : paramètres de la caution du pays (graines 0009 et 0142), interrupteur `funds_holding_enabled` (`core.config_go_live`) et capacités du fournisseur, lecture seule sous `app_api` ou `app_worker`. | | `startup-guard.ts`, `production.ts` | refus de démarrage (variable `*_ADAPTER=FAKE` en production, compte FAKE en base de production, application et base discordantes) ; adaptateurs de production : **registre des PSP vide** jusqu'au lot C, aucun coffre de secrets avant US-003 (503). | ## FAKE (répertoire `testing/`, tests seulement) @@ -23,6 +27,7 @@ Aucun code métier ne connaît un PSP. Jusqu'au lot C, seul l'adaptateur **FAKE* - `fake-payment-provider.ts` : adaptateur du port au-dessus de `FakePsp` (mêmes contrôles qu'un connecteur réel) ; - `contract.ts` : **suite de contrat** du port, à rejouer telle quelle sur le connecteur réel en bac à sable (US-601) ; `describeMarketplaceContract` (US-061) : fidélité par jambe (`perLegDiscrepancies`, TJ10 ; un PSP au prorata est détecté), jambe libérée (TJ18), idempotence de chaque écriture de place de marché ; - `fake-stack.ts`, `memory-stores.ts` : montage complet et magasins en mémoire (mêmes règles que les commandes SQL) ; +- `deposit-rails.fake.test.ts` (US-225) : rails de la caution sur le FAKE (T57, T58, ré-autorisation refusée sans débit, rail b refusé sans appel) ; `deposit-rail-config.int.test.ts` : lecture de la configuration sous `app_api` (PA, PY) ; - `marketplace.test.ts` (US-061) : chaque capacité bloquante `UNKNOWN` ⇒ `HOST_PAYOUT_RAIL_UNAVAILABLE` (hôte et paiement), variante B, mode « prorata » (écarts exacts TJ10c), libération rejouée après une réponse perdue, KYC refusé, jambe gelée, reprise sans `SUPPORTS_NEGATIVE_BALANCE_RECOVERY` ; - mode hostile scriptable : délais dépassés avant ou après succès, réponses illisibles, panne, refus (dont « ne pas réessayer »), webhooks en double, hors d'ordre, retardés, perdus, rejoués, ordres Yappy de 300 s, liens réutilisables, capacités absentes ou seulement `DOCUMENTED`. diff --git a/apps/api/src/modules/pay/internal/deposit-executor.ts b/apps/api/src/modules/pay/internal/deposit-executor.ts new file mode 100644 index 000000000..3439270e5 --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-executor.ts @@ -0,0 +1,289 @@ +/** + * Exécution des rails de la caution par le port `PaymentProvider` (17 §2.8 ; 08 BR-PAY-06 ; + * US-225, ADR-164). Jusqu'au lot C, seul l'adaptateur FAKE existe (C19) : cette classe n'est + * branchée à aucun travailleur de production dans cette story. + * + * - Chaque commande porte son **montant explicite** et, si elle déplace des fonds, ses jambes + * (`chargeLegs` pour la pose, jambes des frais pour une capture ou un débit MIT) ; l'adaptateur les + * revérifie avant tout appel (`LEG_SUM_MISMATCH`). + * - Clé d'idempotence par tentative (`depositOperationKey`), transmise telle quelle ou condensée selon + * `IDEMPOTENCY_KEY_MAX_LEN` : un rejeu avec la même tentative ne crée jamais un second mouvement. + * - **Aucun fonds de tiers détenu** : le rail « débit puis remboursement » est refusé sans appel tant + * que `funds_holding_enabled[pays]` = `false` (relu par l'appelant, jamais déduit ici). + * - Ré-autorisation refusée (ou capacité non validée) : signal ops `DEPOSIT_REAUTH_FAILED`, **aucun + * débit** de remplacement. + */ +import { PaymentError, isPaymentError } from './errors.js'; +import { depositOperationKey, idempotencyKeyToSend } from './idempotency.js'; +import type { DepositOperationType } from './idempotency.js'; +import type { HostedPayment, OperationResult, OperationStatus, PaymentProvider } from './port.js'; +import { chargeLegs, fallbackAfterCaptureFailure } from './deposit-rails.js'; +import type { DepositDecisionPlan, DepositRail, DepositStep } from './deposit-rails.js'; +import { money } from '@rueda/money'; +import type { Currency } from '@rueda/money'; + +/** Méthodes du port utilisées par les rails de la caution. */ +export type DepositPaymentProvider = Pick< + PaymentProvider, + | 'capabilities' + | 'createHostedPayment' + | 'capture' + | 'void' + | 'refund' + | 'chargeMIT' + | 'reauthorize' +>; + +export interface DepositReference { + /** `deposit_hold.id`. */ + readonly depositId: string; + /** Trip dont le PSP tient les jambes. */ + readonly tripReference: string; + readonly currency: Currency; +} + +export interface PlaceDepositRequest { + readonly mechanism: DepositRail; + readonly amountMinor: bigint; + /** `funds_holding_enabled[pays]`, relu au moment de la pose. */ + readonly fundsHoldingEnabled: boolean; + readonly attemptNo: number; +} + +export type DepositReauthOutcome = + | { readonly kind: 'REAUTHORIZED'; readonly result: OperationResult } + | { + readonly kind: 'REAUTH_REFUSED'; + /** Le trip est signalé à l'ops ; aucun débit. */ + readonly opsSignal: 'DEPOSIT_REAUTH_FAILED'; + readonly reason: 'DECLINED' | 'UNSUPPORTED_CAPABILITY'; + }; + +export interface DepositStepResult { + readonly step: DepositStep; + /** `null` : étape sans appel au PSP (`LET_EXPIRE`, `DEBT`). */ + readonly result: OperationResult | null; +} + +/** Étape où l'exécution s'est arrêtée. */ +export interface DepositStepFailure { + readonly step: DepositStep; + /** Exception du port (refus, issue inconnue, capacité absente) ; `null` si un statut a été rendu. */ + readonly error: unknown; + /** Statut rendu par le port autre que `SUCCEEDED` ; `null` si une exception a été levée. */ + readonly status: OperationStatus | null; + /** + * Issue inconnue ou en cours (`UNKNOWN_OUTCOME`, `UNKNOWN`, `PENDING`, `SUBMITTED`) : l'appelant + * lit l'état faisant foi (`getOperation`) AVANT tout rejeu, qui garde les MÊMES clés (17 §4.3). + */ + readonly needsLookup: boolean; +} + +export interface DepositExecution { + readonly completed: readonly DepositStepResult[]; + /** + * Première étape qui n'a pas abouti (exception ou statut autre que `SUCCEEDED`) : l'exécution + * s'arrête, AUCUNE étape suivante ne part (un VOID n'est jamais envoyé après une capture non + * prouvée) ; un rejeu reprend avec les mêmes clés. + */ + readonly failed: DepositStepFailure | null; + /** Repli exécuté après un REFUS de capture (08 E3 repli 2 : VOID total puis MIT) ; sinon `null`. */ + readonly fallback: DepositDecisionPlan | null; +} + +type Target = { + readonly providerReference: string; + readonly instrumentToken: string; + readonly attemptNo: number; +}; + +const UNSETTLED: ReadonlySet = new Set([ + 'PENDING', + 'SUBMITTED', + 'UNKNOWN', +]); + +export class DepositRailExecutor { + readonly #provider: DepositPaymentProvider; + + constructor(provider: DepositPaymentProvider) { + this.#provider = provider; + } + + #key(ref: DepositReference, op: DepositOperationType, instanceSeq: number, attemptNo: number) { + const plain = depositOperationKey(ref.depositId, op, instanceSeq, attemptNo); + return idempotencyKeyToSend( + plain, + this.#provider.capabilities().int('IDEMPOTENCY_KEY_MAX_LEN'), + ); + } + + /** + * Pose de la caution à `auth_at` : pré-autorisation (`MANUAL`) pour les rails PREAUTH_SINGLE et + * REAUTH, débit (`AUTO`) pour le rail CHARGE_THEN_REFUND, toujours sur la page hébergée du PSP + * (le port n'a pas d'autorisation sans le voyageur : suite S-1 d'ADR-164). + */ + async place(ref: DepositReference, req: PlaceDepositRequest): Promise { + if (req.mechanism === 'CHARGE_THEN_REFUND' && !req.fundsHoldingEnabled) { + throw new PaymentError( + 'INVALID_REQUEST', + 'caution débitée puis remboursée : funds_holding_enabled = false (aucun fonds de tiers détenu)', + ); + } + const amount = money(req.amountMinor, ref.currency); + const charge = req.mechanism === 'CHARGE_THEN_REFUND'; + return this.#provider.createHostedPayment({ + idempotencyKey: this.#key(ref, charge ? 'CHARGE' : 'AUTH', 1, req.attemptNo), + tripReference: ref.tripReference, + method: 'CARD', + amountMinor: amount.amountMinor, + currency: amount.currency, + legs: chargeLegs(amount), + capture: charge ? 'AUTO' : 'MANUAL', + }); + } + + /** + * Ré-autorisation (rail a), demandée avant l'échéance. Refus reçu ou capacité non validée ⇒ + * `REAUTH_REFUSED` (trip signalé à l'ops, sans débit). Issue inconnue : l'erreur remonte, la + * même clé est rejouée après lecture de l'état (17 §4.3 point 3). + */ + async reauthorize( + ref: DepositReference, + providerReference: string, + instanceSeq: number, + attemptNo: number, + ): Promise { + try { + const result = await this.#provider.reauthorize({ + idempotencyKey: this.#key(ref, 'REAUTH', instanceSeq, attemptNo), + providerReference, + }); + if (result.status === 'FAILED') { + return { kind: 'REAUTH_REFUSED', opsSignal: 'DEPOSIT_REAUTH_FAILED', reason: 'DECLINED' }; + } + return { kind: 'REAUTHORIZED', result }; + } catch (error) { + if (isPaymentError(error, 'DECLINED') || isPaymentError(error, 'UNSUPPORTED_CAPABILITY')) { + return { + kind: 'REAUTH_REFUSED', + opsSignal: 'DEPOSIT_REAUTH_FAILED', + reason: error.code === 'DECLINED' ? 'DECLINED' : 'UNSUPPORTED_CAPABILITY', + }; + } + throw error; + } + } + + /** Exécute les commandes de la décision dans l'ordre (T57 : capture puis VOID ; T58 : VOID puis MIT). */ + async execute( + ref: DepositReference, + plan: DepositDecisionPlan, + target: { + /** Référence PSP de la pose (autorisation ou débit). */ + readonly providerReference: string; + /** Jeton de la carte enregistrée (consentement MIT du checkout). */ + readonly instrumentToken: string; + readonly attemptNo: number; + }, + ): Promise { + const completed: DepositStepResult[] = []; + const first = await this.#steps(ref, plan.steps, 1, target, completed); + if (first === null) return { completed, failed: null, fallback: null }; + if (!first.captureRefused) return { completed, failed: first.failure, fallback: null }; + // 08 E3 repli 2 : capture refusée ⇒ aucun frais sur la caution, VOID total puis MIT de tous les + // frais ; clés de rang i2 (le plan d'origine n'a envoyé que la capture refusée) + const fallback = fallbackAfterCaptureFailure(plan, { + capabilities: this.#provider.capabilities(), + }); + if (fallback === null) return { completed, failed: first.failure, fallback: null }; + const second = await this.#steps(ref, fallback.steps, 2, target, completed); + return { completed, failed: second === null ? null : second.failure, fallback }; + } + + /** Étapes dans l'ordre ; `null` si toutes ont abouti, sinon la première qui n'a pas abouti. */ + async #steps( + ref: DepositReference, + steps: readonly DepositStep[], + instanceSeq: number, + target: Target, + completed: DepositStepResult[], + ): Promise<{ readonly failure: DepositStepFailure; readonly captureRefused: boolean } | null> { + const code = ref.currency.code; + for (const step of steps) { + let result: OperationResult | null; + try { + result = await this.#run(ref, step, code, target, instanceSeq); + } catch (error) { + return { + failure: { + step, + error, + status: null, + needsLookup: isPaymentError(error, 'UNKNOWN_OUTCOME'), + }, + captureRefused: step.op === 'CAPTURE' && isPaymentError(error, 'DECLINED'), + }; + } + if (result !== null && result.status !== 'SUCCEEDED') { + return { + failure: { + step, + error: null, + status: result.status, + needsLookup: UNSETTLED.has(result.status), + }, + captureRefused: step.op === 'CAPTURE' && result.status === 'FAILED', + }; + } + completed.push({ step, result }); + } + return null; + } + + async #run( + ref: DepositReference, + step: DepositStep, + currency: string, + target: Target, + i: number, + ): Promise { + const a = target.attemptNo; + switch (step.op) { + case 'CAPTURE': + return this.#provider.capture({ + idempotencyKey: this.#key(ref, 'CAPTURE', i, a), + providerReference: target.providerReference, + amountMinor: step.amountMinor, + currency, + legs: step.legs, + }); + case 'VOID': + return this.#provider.void({ + idempotencyKey: this.#key(ref, 'VOID', i, a), + providerReference: target.providerReference, + }); + case 'REFUND': + return this.#provider.refund({ + idempotencyKey: this.#key(ref, 'REFUND', i, a), + providerReference: target.providerReference, + amountMinor: step.amountMinor, + currency, + legs: step.legs, + }); + case 'MIT_CHARGE': + return this.#provider.chargeMIT({ + idempotencyKey: this.#key(ref, 'MIT_CHARGE', i, a), + tripReference: ref.tripReference, + reason: step.reason, + instrumentToken: target.instrumentToken, + amountMinor: step.amountMinor, + currency, + legs: step.legs, + }); + case 'LET_EXPIRE': + case 'DEBT': + return null; + } + } +} diff --git a/apps/api/src/modules/pay/internal/deposit-rails.test.ts b/apps/api/src/modules/pay/internal/deposit-rails.test.ts new file mode 100644 index 000000000..5e345e328 --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-rails.test.ts @@ -0,0 +1,462 @@ +/** + * Rails de la caution (US-225 ; 08 BR-PAY-06 « Mécanisme », « Libération à heure fixe » ; E3). + * Attendus : contrôles de l'oracle `docs/specs/tools/check_t49plus.py` (T57, T58, T59, T69, T70 ; + * `@rueda/money/golden-vectors`) et, pour le Paraguay, le même calcul de 08 refait à la main sur les + * montants de test de T73 (1 500 000 PYG) — jamais le code testé. Chaque cas en USD et en PYG. + */ +import { readFileSync } from 'node:fs'; +import { allocHost, createCurrencyRegistry, money, ratio } from '@rueda/money'; +import { checksFor, loadGoldenVectors } from '@rueda/money/golden-vectors'; +import type { GoldenValue } from '@rueda/money/golden-vectors'; +import { describe, expect, it } from 'vitest'; +import { CapabilitySet } from './capabilities.js'; +import type { CapabilityRecord } from './capabilities.js'; +import { + decideDepositGate, + depositAuthExpiry, + depositDecisionAt, + depositReauthDueAt, + depositReleaseAt, + nextDepositStatus, + planDepositDecision, + fallbackAfterCaptureFailure, + selectDepositRail, +} from './deposit-rails.js'; +import type { DepositGateInput, DepositRailParams } from './deposit-rails.js'; +import type { DepositTriggerParams } from './deposit-triggers.js'; +import { countryCases } from '../../../../test/support/countries.js'; + +const set = loadGoldenVectors(); +const check = (vectorId: string, label: RegExp): GoldenValue => { + const found = checksFor(set, vectorId).find((c) => label.test(c.label)); + if (found === undefined) throw new Error(`contrôle ${vectorId} ${label} absent`); + return found.expected; +}; + +const read = (file: string): unknown => + JSON.parse(readFileSync(new URL(`../../cfg/data/${file}`, import.meta.url), 'utf8')); +const CURRENCIES = createCurrencyRegistry( + (read('currencies.json') as { currencies: { code: string; exponent: number }[] }).currencies, +); +const PARAMS = ( + read('params.json') as { params: { key: string; values: Record }[] } +).params; +const p = (key: string, country: string): unknown => + PARAMS.find((x) => x.key === key)?.values[country]; + +const H = 3_600_000; +const T = Date.parse('2031-07-10T10:00:00.000Z'); +const at = (hours: number, minutes = 0): Date => new Date(T + hours * H + minutes * 60_000); + +/** + * Cas par pays configuré (CLAUDE.md point 3, lus dans la configuration, jamais en constantes) : + * les vecteurs T57–T58 de 08 (caution 300,00, carburant 12,00, en unités MAJEURES) rejoués dans la + * devise du pays ; l'oracle les exporte en centimes (exposant 2) : `scale` les ramène à l'exposant + * de la devise (USD : identiques ; PYG sans décimale : 300 et 12). Les opérations de BR-PAY-06 + * (minimum, différence, part de 100 %) sont linéaires : l'attendu se met à la même échelle. + */ +const CASES = countryCases().map((c) => { + const cur = CURRENCIES.get(c.currency); + const scale = (cents: bigint): bigint => (cents * 10n ** BigInt(cur.exponent)) / 100n; + return { ...c, cur, scale, deposit: scale(30_000n), fuel: scale(1_200n) }; +}); + +const rec = (capability: string, value: unknown): CapabilityRecord => ({ + capability, + method: '*', + value, + status: 'VALIDATED_SANDBOX', +}); + +/** PSP « à 7 j » de T57 : pré-autorisation, capture partielle, VOID, MIT ; V = 168 h. */ +function caps(options: { without?: string[]; extra?: CapabilityRecord[] } = {}): CapabilitySet { + const base = [ + rec('SUPPORTS_PREAUTH', true), + rec('MAX_HOLD_HOURS', 168), + rec('SUPPORTS_PARTIAL_CAPTURE', true), + rec('SUPPORTS_VOID', true), + rec('SUPPORTS_MIT', true), + rec('SUPPORTS_REFUND', true), + ].filter((r) => !(options.without ?? []).includes(r.capability)); + return new CapabilitySet([...base, ...(options.extra ?? [])]); +} + +/** Paramètres de rail de la graine (params.json) + validité du PSP de test (lot C : par PSP). */ +function railParams(country: string, over: Partial = {}): DepositRailParams { + return { + authLeadH: p('auth_lead_h', country) as number, + releaseDelayH: p('release_delay_h', country) as number, + marginH: p('marge_h', country) as number, + safetyH: p('deposit_safety_h', country) as number, + reauthLeadH: p('deposit_reauth_lead_h', country) as number, + providerMaxHoldH: 168, + chargeCapMinor: 0n, + fundsHoldingEnabled: p('funds_holding_enabled', country) as boolean, + ...over, + }; +} + +function triggerParams(country: string): DepositTriggerParams { + return { + alwaysRequired: p('deposit_always_required', country) as boolean, + triggerClasses: p('deposit_trigger_classes', country) as ['LUXE'], + youngDriverAge: p('deposit_young_driver_age', country) as number, + youngDriverClasses: p('deposit_young_driver_classes', country) as [], + onRiskFlag: p('deposit_on_risk_flag', country) as boolean, + riskControlDeployed: p('risk_control_deployed', country) as boolean, + }; +} + +function gate( + c: (typeof CASES)[number], + over: { + valueClass?: 'STANDARD' | 'PREMIUM' | 'LUXE'; + tripMinutes?: number; + caps?: CapabilitySet; + rail?: Partial; + amounts?: DepositGateInput['amounts']; + } = {}, +) { + return decideDepositGate({ + triggerParams: triggerParams(c.country), + amounts: 'amounts' in over ? over.amounts : { LUXE: c.deposit }, + railParams: railParams(c.country, over.rail), + caps: { capabilities: over.caps ?? caps() }, + context: { valueClass: over.valueClass ?? 'LUXE', driverAges: [40], riskFlagged: false }, + // réservé bien avant : auth_at = T − 24 h + bookedAt: at(-24 * 10), + scheduledStart: at(0), + scheduledEnd: at(0, over.tripMinutes ?? 72 * 60), + }); +} + +describe.each(CASES)('$country ($currency) — choix du rail au checkout, avant le paiement', (c) => { + it('T57 : 3 jours chez un PSP à 7 j ⇒ pré-autorisation unique (H_requise = 168 h ≤ V)', () => { + const t57 = check('T57', /^T57$/) as { single: boolean }; + const g = gate(c); + expect(g.kind).toBe('REQUIRED'); + if (g.kind !== 'REQUIRED') return; + expect(g.rail.mechanism === 'PREAUTH_SINGLE').toBe(t57.single); + expect([g.amountMinor, g.rail.hRequiredHours, g.rail.vHours]).toEqual([c.deposit, 168, 168]); + expect(g.rail.authAt).toEqual(at(-24)); + }); + + it('T59 (critère 1) : 3 j + 25 min, SUPPORTS_REAUTH absente, funds_holding_enabled = false ⇒ DEPOSIT_RAIL_UNAVAILABLE avant le paiement, 3 jours possibles', () => { + const [single, overMinutes, daysForm, railB] = check('T59', /forme heures/) as [ + boolean, + bigint, + boolean, + boolean, + ]; + const g = gate(c, { tripMinutes: 72 * 60 + 25 }); + expect(g.kind).toBe('REFUSED'); + if (g.kind !== 'REFUSED') return; + expect(g.code).toBe('DEPOSIT_RAIL_UNAVAILABLE'); + expect(g.rail?.mechanism === 'PREAUTH_SINGLE').toBe(single); + expect(BigInt((g.rail?.hRequiredMinutes ?? 0) - 168 * 60)).toBe(overMinutes); + expect(3 + 4 <= 7).toBe(daysForm); // la forme en jours disait oui : la forme en heures prévaut + expect(railB).toBe(false); // deposit_charge_cap inconnu ⇒ 0 ⇒ rail (b) interdit + // durées possibles : 168 − 24 − 72 − 0 = 72 h = 3 jours + expect(g.maxBookableDays).toBe(3); + }); + + it('T70 (critère 2) : même trip sur un STANDARD ⇒ aucun rail évalué, réservation possible, même sans aucune capacité', () => { + const [none] = check('T70', /sans caution/) as [boolean]; + const g = gate(c, { + valueClass: 'STANDARD', + tripMinutes: 72 * 60 + 25, + caps: new CapabilitySet([]), + amounts: undefined, + }); + expect(g.kind === 'REQUIRED').toBe(none); + expect(g.kind).toBe('NOT_REQUIRED'); + expect('rail' in g).toBe(false); + }); + + it('critère 3 : SUPPORTS_REAUTH validée ⇒ rail de ré-autorisation, demandée à auth_expiry − 24 h, avant l’échéance', () => { + const g = gate(c, { + tripMinutes: 72 * 60 + 25, + caps: caps({ extra: [rec('SUPPORTS_REAUTH', true)] }), + }); + expect(g.kind === 'REQUIRED' && g.rail.mechanism).toBe('REAUTH'); + const params = railParams(c.country); + const expiry = depositAuthExpiry(at(-24), 168, null); // = T + 144 h + const release = depositReleaseAt(null, at(0, 72 * 60 + 25), params.releaseDelayH ?? -1); + const due = depositReauthDueAt(expiry, release, params.safetyH ?? -1, params.reauthLeadH ?? -1); + expect(due).toEqual(at(120)); + expect((due?.getTime() ?? Infinity) < expiry.getTime()).toBe(true); + }); + + it('critère 4 : rail « débit puis remboursement » plafonné, funds_holding_enabled = false ⇒ fermé, refus avant le paiement', () => { + const closed = gate(c, { tripMinutes: 72 * 60 + 25, rail: { chargeCapMinor: c.deposit } }); + expect(closed.kind === 'REFUSED' && closed.code).toBe('DEPOSIT_RAIL_UNAVAILABLE'); + // plafond inconnu (0) ou inférieur au montant : fermé même interrupteur ouvert + for (const cap of [0n, c.deposit - 1n]) { + const g = gate(c, { + tripMinutes: 72 * 60 + 25, + rail: { chargeCapMinor: cap, fundsHoldingEnabled: true }, + }); + expect(g.kind === 'REFUSED' && g.code).toBe('DEPOSIT_RAIL_UNAVAILABLE'); + } + // seulement interrupteur ouvert (décision écrite du fondateur) ET plafond suffisant + const open = gate(c, { + tripMinutes: 72 * 60 + 25, + rail: { chargeCapMinor: c.deposit, fundsHoldingEnabled: true }, + }); + expect(open.kind === 'REQUIRED' && open.rail.mechanism).toBe('CHARGE_THEN_REFUND'); + }); + + it('capacité inconnue = « non » : pré-autorisation DOCUMENTED, V absente ou paramètre de durée absent', () => { + const documented = new CapabilitySet([ + { ...rec('SUPPORTS_PREAUTH', true), status: 'DOCUMENTED' }, + rec('MAX_HOLD_HOURS', 168), + ]); + expect(gate(c, { caps: documented }).kind).toBe('REFUSED'); + expect(gate(c, { caps: caps({ without: ['MAX_HOLD_HOURS'] }) }).kind).toBe('REFUSED'); + expect(gate(c, { rail: { providerMaxHoldH: 0 } }).kind).toBe('REFUSED'); + const g = gate(c, { rail: { releaseDelayH: null } }); + expect(g.kind === 'REFUSED' && g.code).toBe('PARAM_MISSING'); + }); + + it('T72 c : caution exigée sans deposit_amount ⇒ PARAM_MISSING (jamais une caution de 0)', () => { + const g = gate(c, { amounts: undefined }); + expect(g.kind === 'REFUSED' && g.code).toBe('PARAM_MISSING'); + }); + + it('réservation tardive : auth_at = instant de la réservation (pose immédiate), H_requise recalculée', () => { + const s = selectDepositRail( + { amountMinor: c.deposit, bookedAt: at(-2), scheduledStart: at(0), scheduledEnd: at(96) }, + { + ...railParams(c.country), + authLeadH: 24, + releaseDelayH: 72, + marginH: 0, + safetyH: 2, + reauthLeadH: 24, + }, + { capabilities: caps() }, + ); + // 2 + 96 + 72 = 170 h > 168 h : plus de pré-autorisation unique + expect([s.authAt, s.hRequiredHours, s.mechanism]).toEqual([at(-2), 170, 'REFUSED']); + }); +}); + +describe.each(CASES)('$country ($currency) — décision à fin + 70 h, commandes au PSP', (c) => { + const cur = c.cur; + const end = at(72); + const fuel = { + id: 'fuel', + amount: money(c.fuel, cur), + hostShare: ratio(1n, 1n), // carburant : 100 % à l'hôte (BR-PROT-08) + proven: true, + notifiedAt: new Date(end.getTime() + H), + disputed: false, + }; + const decisionAt = depositDecisionAt( + depositReleaseAt(null, end, 72), + depositAuthExpiry(at(-24), 168, null), + 2, + ); + + it('T57 : décision à fin + 70 h ; capture des frais (jambe HOST), VOID du reste, aucune MIT', () => { + const t57 = check('T57', /^T57$/) as Record; + const [, , hostLeg, platformLeg] = check('T69', /caution/) as bigint[]; + expect(BigInt((decisionAt.getTime() - end.getTime()) / H)).toBe(t57['decision_h']); + const plan = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, cur), + decisionAt, + feeNoticeH: p('deposit_fee_notice_h', c.country) as number, + fees: [fuel], + caps: { capabilities: caps() }, + }); + expect(plan.steps.map((s) => s.op)).toEqual(['CAPTURE', 'VOID']); + expect([plan.capturedMinor, plan.releasedMinor, plan.mitMinor]).toEqual([ + c.scale(t57['capture'] ?? -1n), + c.scale(t57['void'] ?? -1n), + c.scale(t57['mit'] ?? -1n), + ]); + const capture = plan.steps[0]; + // T69 : carburant à 100 % pour l'hôte, PLATFORM 0 + expect(capture?.op === 'CAPTURE' && [capture.legs.HOST, capture.legs.PLATFORM]).toEqual([ + c.scale(hostLeg ?? -1n), + c.scale(platformLeg ?? -1n), + ]); + expect(plan.finalStatus).toBe('PARTIALLY_CAPTURED'); + }); + + it('T58 (critère 5) : PSP sans capture partielle ⇒ VOID de la caution entière PUIS débit MIT des frais', () => { + const t58 = check('T58', /^T58$/) as Record; + const plan = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, cur), + decisionAt, + feeNoticeH: 48, + fees: [fuel], + caps: { capabilities: caps({ without: ['SUPPORTS_PARTIAL_CAPTURE'] }) }, + }); + expect(plan.steps.map((s) => s.op)).toEqual(['VOID', 'MIT_CHARGE']); + const expected = [t58['capture'], t58['void'], t58['mit']].map((v) => c.scale(v ?? -1n)); + expect([plan.capturedMinor, plan.releasedMinor, plan.mitMinor]).toEqual(expected); + expect(plan.finalStatus).toBe('VOIDED'); + }); + + it('frais notifié moins de 48 h avant la décision, contesté ou sans preuve ⇒ débit MIT séparé ; la caution est libérée en entier', () => { + for (const fee of [ + { ...fuel, notifiedAt: new Date(decisionAt.getTime() - 47 * H) }, + { ...fuel, disputed: true }, + { ...fuel, proven: false }, + ]) { + const plan = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, cur), + decisionAt, + feeNoticeH: 48, + fees: [fee], + caps: { capabilities: caps() }, + }); + expect(plan.steps.map((s) => s.op)).toEqual(['VOID', 'MIT_CHARGE']); + expect([plan.releasedMinor, plan.mitMinor]).toEqual([c.deposit, c.fuel]); + } + }); + + it('frais au-delà de la caution : capture plafonnée au montant, le reste par MIT', () => { + const big = { ...fuel, amount: money(c.deposit + c.fuel, cur) }; + const plan = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, cur), + decisionAt, + feeNoticeH: 48, + fees: [big], + caps: { capabilities: caps() }, + }); + expect(plan.steps.map((s) => s.op)).toEqual(['CAPTURE', 'MIT_CHARGE']); + expect([plan.capturedMinor, plan.releasedMinor, plan.mitMinor]).toEqual([ + c.deposit, + 0n, + c.fuel, + ]); + }); + + it('sans VOID validée : l’autorisation expire seule (aucune capture) ; sans MIT : dette, jamais prise sur la caution', () => { + const plan = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, cur), + decisionAt, + feeNoticeH: 48, + fees: [fuel], + caps: { + capabilities: caps({ + without: ['SUPPORTS_PARTIAL_CAPTURE', 'SUPPORTS_VOID', 'SUPPORTS_MIT'], + }), + }, + }); + expect(plan.steps.map((s) => s.op)).toEqual(['LET_EXPIRE', 'DEBT']); + expect(plan.finalStatus).toBe('EXPIRED'); + }); + + it('débit puis remboursement : remboursement TOTAL émis à la décision, frais par MIT (aucune retenue sur des fonds détenus)', () => { + const plan = planDepositDecision({ + mechanism: 'CHARGE_THEN_REFUND', + amount: money(c.deposit, cur), + decisionAt, + feeNoticeH: 48, + fees: [fuel], + caps: { capabilities: caps() }, + }); + expect(plan.steps.map((s) => s.op)).toEqual(['REFUND', 'MIT_CHARGE']); + const refund = plan.steps[0]; + expect(refund?.op === 'REFUND' && refund.amountMinor).toBe(c.deposit); + expect([plan.finalStatus, plan.mitMinor]).toEqual(['REFUNDED', c.fuel]); + }); +}); + +describe('machine d’état de deposit_hold.status (16 PAY-011)', () => { + it('PLANNED → AUTHORIZED → (ré-autorisation refusée : reste AUTHORIZED) → VOIDED ; états finaux sans sortie', () => { + let s = nextDepositStatus('PLANNED', 'AUTH_FAILED'); + expect(s).toBe('PLANNED'); + s = nextDepositStatus(s, 'AUTHORIZED'); + s = nextDepositStatus(s, 'REAUTH_REFUSED'); + expect(s).toBe('AUTHORIZED'); + s = nextDepositStatus(s, 'VOIDED'); + expect(s).toBe('VOIDED'); + for (const final of ['PARTIALLY_CAPTURED', 'VOIDED', 'REFUNDED', 'EXPIRED'] as const) { + expect(() => nextDepositStatus(final, 'CAPTURED')).toThrow(/transition/); + } + expect(() => nextDepositStatus('PLANNED', 'CAPTURED')).toThrow(/transition/); + }); +}); + +describe.each(CASES)( + '$country ($currency) — repli et arrondi des frais scindés (revues de la PR 236)', + (c) => { + const decisionAt = new Date(T + 142 * H); + const fee = (amountMinor: bigint, share: [bigint, bigint]) => ({ + id: 'late', + amount: money(amountMinor, c.cur), + hostShare: ratio(share[0], share[1]), + proven: true, + notifiedAt: new Date(decisionAt.getTime() - 50 * H), + disputed: false, + }); + + it('frais scindé au plafond : part HOST arrondie une fois sur la ligne entière (allocHost par ligne, 08 BR-PAY-06)', () => { + for (const [deposit, amount, share] of [ + [1001n, 1003n, [3n, 4n]], + [7n, 9n, [1n, 3n]], + [5n, 6n, [1n, 2n]], + [c.deposit, c.deposit + 1n, [3n, 4n]], + ] as const) { + const f = fee(amount, [share[0], share[1]]); + const plan = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(deposit, c.cur), + decisionAt, + feeNoticeH: 48, + fees: [f], + caps: { capabilities: caps() }, + }); + const legs = plan.steps.flatMap((x) => + x.op === 'CAPTURE' || x.op === 'MIT_CHARGE' ? [x.legs] : [], + ); + const host = legs.reduce((a, l) => a + l.HOST, 0n); + const platform = legs.reduce((a, l) => a + l.PLATFORM, 0n); + expect([host, host + platform]).toEqual([ + allocHost(f.amount, f.hostShare).amountMinor, + amount, + ]); + for (const l of legs) expect(l.HOST >= 0n && l.PLATFORM >= 0n).toBe(true); + } + }); + + it('repli après refus de capture : VOID de la caution entière, tous les frais par MIT (T58) ; sans capture : rien à replier', () => { + const f = { ...fee(c.fuel, [1n, 1n]), id: 'fuel' }; + const base = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, c.cur), + decisionAt, + feeNoticeH: 48, + fees: [f, { ...f, id: 'late', notifiedAt: decisionAt }], + caps: { capabilities: caps() }, + }); + expect(base.steps.map((x) => x.op)).toEqual(['CAPTURE', 'VOID', 'MIT_CHARGE']); + const fb = fallbackAfterCaptureFailure(base, { capabilities: caps() }); + expect(fb?.steps.map((x) => x.op)).toEqual(['VOID', 'MIT_CHARGE']); + expect([fb?.capturedMinor, fb?.releasedMinor, fb?.mitMinor, fb?.finalStatus]).toEqual([ + 0n, + c.deposit, + 2n * c.fuel, + 'VOIDED', + ]); + const noCapture = planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, c.cur), + decisionAt, + feeNoticeH: 48, + fees: [], + caps: { capabilities: caps() }, + }); + expect(fallbackAfterCaptureFailure(noCapture, { capabilities: caps() })).toBeNull(); + }); + }, +); diff --git a/apps/api/src/modules/pay/internal/deposit-rails.ts b/apps/api/src/modules/pay/internal/deposit-rails.ts new file mode 100644 index 000000000..97cc2b692 --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-rails.ts @@ -0,0 +1,680 @@ +/** + * Rails de la caution (08 BR-PAY-06 « Mécanisme », « Libération à heure fixe », « Débit puis + * remboursement » ; 08 E3 « Capacités d'autorisation » ; 16 fiche PAY-011 / PAY-012 / PAY-036 ; + * 17 §3.2.7 `deposit_hold`, ADR-016 ; 19 US-225 ; ADR-164). + * + * Fonctions pures (aucune horloge : l'instant de décision vient de la base, `platform.now()`) : + * 1. `decideDepositGate` : au checkout, AVANT le paiement — déclencheurs, montant, puis rail. Aucun + * déclencheur ⇒ `NOT_REQUIRED`, aucun rail évalué (T70) ; caution exigée sans montant ⇒ + * `PARAM_MISSING` (T72 c) ; aucun rail valide ⇒ `DEPOSIT_RAIL_UNAVAILABLE` avec la durée + * possible (T59). Jamais de rétention de fonds : rien n'est autorisé ici. + * 2. `selectDepositRail` : le rail est choisi par **configuration** (`psp_capability`, + * `provider_max_hold_h`, `deposit_charge_cap`, `funds_holding_enabled`), jamais par une branche + * propre à un PSP ou à un pays. Une capacité inconnue vaut « non ». + * 3. Échéancier : `auth_at`, `H_requise` (forme en heures, qui prévaut), `auth_expiry`, ré-autorisation + * à `auth_expiry − 24 h`, `release_at`, `decision_at = min(release_at, auth_expiry − safety)`. + * 4. `planDepositDecision` : commandes au PSP de la décision, chacune avec son **montant explicite** + * et, pour celles qui déplacent des fonds, ses jambes (`allocHost` par ligne, 08 BR-PAY-06 + * « Jambes des frais annexes ») : capture partielle puis VOID du reste (T57), VOID total puis + * débit MIT (T58), remboursement total puis MIT (rail « débit puis remboursement »). + * 5. Machine d'état de `deposit_hold.status` (16 PAY-011 « États »). + */ +import { allocHost, isZero, subtract } from '@rueda/money'; +import type { Money, Ratio } from '@rueda/money'; +import type { CapabilitySet } from './capabilities.js'; +import { PaymentError } from './errors.js'; +import type { LegAmounts } from './legs.js'; +import { depositAmountFor, evaluateDepositTriggers } from './deposit-triggers.js'; +import type { + DepositTriggerContext, + DepositTriggerDecision, + DepositTriggerParams, + DepositValueClass, +} from './deposit-triggers.js'; + +const MINUTE_MS = 60_000; +const HOUR_MS = 3_600_000; +const DAY_MINUTES = 1_440; + +/** `deposit_hold.mechanism` (17 §3.2.7) ; `COUNTER_AGENCY` historique, sans objet. */ +export const DEPOSIT_MECHANISMS = [ + 'NOT_REQUIRED', + 'PREAUTH_SINGLE', + 'REAUTH', + 'CHARGE_THEN_REFUND', + 'REFUSED', +] as const; +export type DepositMechanism = (typeof DEPOSIT_MECHANISMS)[number]; + +/** Rails qui posent effectivement une caution. */ +export type DepositRail = 'PREAUTH_SINGLE' | 'REAUTH' | 'CHARGE_THEN_REFUND'; + +/** Paramètres de rail d'un pays (17 §7.2) ; `null` : absent ou illisible. */ +export interface DepositRailParams { + /** `auth_lead_h` (24 h) : la caution est posée à `scheduled_start − auth_lead_h`. */ + readonly authLeadH: number | null; + /** `release_delay_h` (72 h). */ + readonly releaseDelayH: number | null; + /** `marge_h` (0 h) de `H_requise`. */ + readonly marginH: number | null; + /** `deposit_safety_h` (2 h, À VALIDER par PSP). */ + readonly safetyH: number | null; + /** `deposit_reauth_lead_h` (24 h) : ré-autorisation à `auth_expiry − 24 h`. */ + readonly reauthLeadH: number | null; + /** `provider_max_hold_h[psp][pays][réseau]` ; absent ⇒ 0 (`failMode` ZERO). */ + readonly providerMaxHoldH: number; + /** `deposit_charge_cap[pays]`, unités mineures ; absent ⇒ 0 : rail (b) interdit. */ + readonly chargeCapMinor: bigint; + /** Interrupteur `funds_holding_enabled[pays]` (false en production, 17 §0.1). */ + readonly fundsHoldingEnabled: boolean; +} + +/** Capacités et réseau du moyen de la caution (carte). */ +export interface DepositRailCapabilities { + readonly capabilities: CapabilitySet; + /** Réseau de la carte enregistrée si connu, sinon `*`. */ + readonly network?: string; +} + +const CARD = 'CARD'; + +const isHours = (h: number | null): h is number => h !== null && Number.isSafeInteger(h) && h >= 0; + +/** + * Validité `V` (heures) d'une pré-autorisation de caution : `SUPPORTS_PREAUTH` validée, puis le + * plus petit de `MAX_HOLD_HOURS` (capacité) et `provider_max_hold_h` (paramètre) — même grandeur + * (17 §2.8), chacune inconnue ⇒ 0 : fail-closed, aucune pré-autorisation sans les deux. + */ +export function depositHoldValidityHours( + params: Pick, + caps: DepositRailCapabilities, +): number { + const network = caps.network ?? '*'; + if (!caps.capabilities.bool('SUPPORTS_PREAUTH', CARD, network)) return 0; + const cap = caps.capabilities.int('MAX_HOLD_HOURS', CARD, network); + const param = isHours(params.providerMaxHoldH) ? params.providerMaxHoldH : 0; + return Math.min(cap, param); +} + +/** `auth_at` : `scheduled_start − auth_lead_h`, jamais avant l'instant de la réservation. */ +export function depositAuthAt(bookedAt: Date, scheduledStart: Date, authLeadH: number): Date { + const planned = scheduledStart.getTime() - authLeadH * HOUR_MS; + return new Date(Math.max(bookedAt.getTime(), planned)); +} + +/** + * `H_requise` en MINUTES, arrondie au-dessus (fail-closed) : `(start − auth_at) + (end − start) + + * release_delay + marge` (08 BR-PAY-06 ; la forme en heures prévaut sur la forme en jours, T59). + */ +export function requiredHoldMinutes( + authAt: Date, + scheduledStart: Date, + scheduledEnd: Date, + releaseDelayH: number, + marginH: number, +): number { + const lead = scheduledStart.getTime() - authAt.getTime(); + const trip = scheduledEnd.getTime() - scheduledStart.getTime(); + const ms = lead + trip + (releaseDelayH + marginH) * HOUR_MS; + return Math.ceil(ms / MINUTE_MS); +} + +export interface DepositRailSelection { + readonly mechanism: DepositRail | 'REFUSED'; + /** `deposit_hold.h_required_hours` (arrondi au-dessus). */ + readonly hRequiredHours: number; + readonly hRequiredMinutes: number; + /** `deposit_hold.v_hours_snapshot`. */ + readonly vHours: number; + readonly authAt: Date; + /** + * Durée de trip la plus longue couverte par une pré-autorisation unique pour ce départ + * (minutes, ≥ 0) : « durées possibles » du message `DEPOSIT_RAIL_UNAVAILABLE`. + */ + readonly maxSingleTripMinutes: number; +} + +export interface DepositRailRequest { + readonly amountMinor: bigint; + /** Instant de la décision (horloge de la base). */ + readonly bookedAt: Date; + readonly scheduledStart: Date; + readonly scheduledEnd: Date; +} + +type CompleteRailParams = DepositRailParams & { + readonly authLeadH: number; + readonly releaseDelayH: number; + readonly marginH: number; + readonly safetyH: number; + readonly reauthLeadH: number; +}; + +/** Paramètres de durée tous présents (`failMode` BLOCK) ; sinon `null` ⇒ `PARAM_MISSING`. */ +export function completeRailParams(p: DepositRailParams): CompleteRailParams | null { + return isHours(p.authLeadH) && + isHours(p.releaseDelayH) && + isHours(p.marginH) && + isHours(p.safetyH) && + isHours(p.reauthLeadH) + ? (p as CompleteRailParams) + : null; +} + +/** + * Choix du rail, dans l'ordre de 08 BR-PAY-06 « Mécanisme » : pré-autorisation unique si + * `H_requise ≤ V` ; sinon (a) ré-autorisation si `SUPPORTS_REAUTH` est validée ; sinon (b) débit + * puis remboursement si `funds_holding_enabled[pays]`, `deposit_charge_cap[pays]` ≥ montant et + * remboursement validé ; sinon refus (`DEPOSIT_RAIL_UNAVAILABLE`). L'ancien rail du comptoir est + * supprimé (pivot P2P). + */ +export function selectDepositRail( + request: DepositRailRequest, + params: CompleteRailParams, + caps: DepositRailCapabilities, +): DepositRailSelection { + if (request.scheduledEnd.getTime() <= request.scheduledStart.getTime()) { + throw new PaymentError('INVALID_REQUEST', 'caution : fin du trip avant son début'); + } + if (request.amountMinor <= 0n) { + throw new PaymentError('INVALID_REQUEST', 'caution : montant strictement positif attendu'); + } + const network = caps.network ?? '*'; + const has = (name: 'SUPPORTS_REAUTH' | 'SUPPORTS_REFUND'): boolean => + caps.capabilities.bool(name, CARD, network); + const vHours = depositHoldValidityHours(params, caps); + const authAt = depositAuthAt(request.bookedAt, request.scheduledStart, params.authLeadH); + const hRequiredMinutes = requiredHoldMinutes( + authAt, + request.scheduledStart, + request.scheduledEnd, + params.releaseDelayH, + params.marginH, + ); + const leadMinutes = Math.ceil((request.scheduledStart.getTime() - authAt.getTime()) / MINUTE_MS); + const maxSingleTripMinutes = Math.max( + 0, + vHours * 60 - leadMinutes - (params.releaseDelayH + params.marginH) * 60, + ); + const base = { + hRequiredHours: Math.ceil(hRequiredMinutes / 60), + hRequiredMinutes, + vHours, + authAt, + maxSingleTripMinutes, + }; + if (vHours > 0 && hRequiredMinutes <= vHours * 60) { + return { ...base, mechanism: 'PREAUTH_SINGLE' }; + } + // (a) ré-autorisation : une autorisation valide plus longtemps que l'avance de ré-autorisation + if (vHours > params.reauthLeadH && has('SUPPORTS_REAUTH')) { + return { ...base, mechanism: 'REAUTH' }; + } + // (b) débit puis remboursement : fonds du voyageur détenus jusqu'à la restitution ⇒ fermé tant + // que funds_holding_enabled[pays] = false (17 §0.1) ; plafond inconnu ⇒ 0 ⇒ fermé + if ( + params.fundsHoldingEnabled && + params.chargeCapMinor > 0n && + request.amountMinor <= params.chargeCapMinor && + has('SUPPORTS_REFUND') + ) { + return { ...base, mechanism: 'CHARGE_THEN_REFUND' }; + } + return { ...base, mechanism: 'REFUSED' }; +} + +// --- porte du checkout --------------------------------------------------------------------------- + +export interface DepositGateInput { + readonly triggerParams: DepositTriggerParams; + /** `deposit_amount[pays]` par classe (unités mineures) ; `undefined` : absent. */ + readonly amounts: Readonly>> | undefined; + readonly railParams: DepositRailParams; + readonly caps: DepositRailCapabilities; + readonly context: DepositTriggerContext; + readonly bookedAt: Date; + readonly scheduledStart: Date; + readonly scheduledEnd: Date; +} + +/** + * Décision du checkout, avant tout paiement. `triggers` et l'âge restent [C2] (ops seulement) ; + * le voyageur ne reçoit que `amountMinor` ou le refus et sa durée possible. + */ +export type DepositGateDecision = + | { readonly kind: 'NOT_REQUIRED'; readonly triggers: DepositTriggerDecision } + | { + readonly kind: 'REQUIRED'; + readonly triggers: DepositTriggerDecision; + readonly amountMinor: bigint; + readonly rail: DepositRailSelection & { readonly mechanism: DepositRail }; + } + | { + readonly kind: 'REFUSED'; + readonly code: 'PARAM_MISSING' | 'DEPOSIT_RAIL_UNAVAILABLE'; + readonly triggers: DepositTriggerDecision; + /** Jours entiers réservables avec une pré-autorisation unique (`web.deposit.unavailable`). */ + readonly maxBookableDays: number | null; + readonly rail: DepositRailSelection | null; + }; + +export function decideDepositGate(input: DepositGateInput): DepositGateDecision { + const triggers = evaluateDepositTriggers(input.triggerParams, input.context, 'CHECKOUT'); + // sans déclencheur : aucun rail évalué, aucune H_requise, jamais DEPOSIT_RAIL_UNAVAILABLE (T70) + if (!triggers.required) return { kind: 'NOT_REQUIRED', triggers }; + const amountMinor = depositAmountFor(input.amounts, input.context.valueClass); + const params = completeRailParams(input.railParams); + if (amountMinor === null || params === null) { + return { kind: 'REFUSED', code: 'PARAM_MISSING', triggers, maxBookableDays: null, rail: null }; + } + const rail = selectDepositRail( + { + amountMinor, + bookedAt: input.bookedAt, + scheduledStart: input.scheduledStart, + scheduledEnd: input.scheduledEnd, + }, + params, + input.caps, + ); + if (rail.mechanism === 'REFUSED') { + return { + kind: 'REFUSED', + code: 'DEPOSIT_RAIL_UNAVAILABLE', + triggers, + maxBookableDays: Math.floor(rail.maxSingleTripMinutes / DAY_MINUTES), + rail, + }; + } + return { kind: 'REQUIRED', triggers, amountMinor, rail: { ...rail, mechanism: rail.mechanism } }; +} + +// --- échéancier ---------------------------------------------------------------------------------- + +/** + * `auth_expiry` : l'expiration RENVOYÉE par le PSP si elle existe, sinon `auth_at_réel + V` + * (08 BR-PAY-06, VERIF_12-F7). `auth_at_réel` = heure d'acceptation de l'autorisation. + */ +export function depositAuthExpiry( + authorizedAt: Date, + vHours: number, + returnedExpiry: Date | null, +): Date { + const computed = new Date(authorizedAt.getTime() + vHours * HOUR_MS); + if (returnedExpiry === null) return computed; + // jamais au-delà de la validité contractuelle connue (lecture prudente) + return new Date(Math.min(returnedExpiry.getTime(), computed.getTime())); +} + +/** `release_at = (checkout_at ?? scheduled_end) + release_delay_h`. */ +export function depositReleaseAt( + checkoutAt: Date | null, + scheduledEnd: Date, + releaseDelayH: number, +): Date { + return new Date((checkoutAt ?? scheduledEnd).getTime() + releaseDelayH * HOUR_MS); +} + +/** `deposit_decision_at = min(release_at, auth_expiry − deposit_safety_h)` ; jamais après l'expiration. */ +export function depositDecisionAt(releaseAt: Date, authExpiry: Date, safetyH: number): Date { + return new Date(Math.min(releaseAt.getTime(), authExpiry.getTime() - safetyH * HOUR_MS)); +} + +/** + * Ré-autorisation (rail a) planifiée à `auth_expiry − deposit_reauth_lead_h`, seulement si + * l'autorisation en cours ne tient pas jusqu'à `release_at` (marge `deposit_safety_h` comprise) ; + * `null` sinon. Après une ré-autorisation acceptée, l'appelant recalcule avec la nouvelle expiration. + */ +export function depositReauthDueAt( + authExpiry: Date, + releaseAt: Date, + safetyH: number, + reauthLeadH: number, +): Date | null { + if (releaseAt.getTime() <= authExpiry.getTime() - safetyH * HOUR_MS) return null; + return new Date(authExpiry.getTime() - reauthLeadH * HOUR_MS); +} + +// --- décision : commandes au PSP ------------------------------------------------------------------ + +/** Frais annexe de la liste fermée acceptée au checkout (08 BR-PAY-06 « Finalité »). */ +export interface DepositIncidentalFee { + readonly id: string; + readonly amount: Money; + /** Part de l'hôte de la ligne (BR-PROT-08 : 100 % carburant, péages, nettoyage ; plan sinon). */ + readonly hostShare: Ratio; + /** Preuve photo ou relevé horodaté (CLM-034). */ + readonly proven: boolean; + /** Notifié au voyageur à cet instant. */ + readonly notifiedAt: Date; + readonly disputed: boolean; +} + +export interface DepositDecisionInput { + readonly mechanism: DepositRail; + readonly amount: Money; + readonly decisionAt: Date; + /** `deposit_fee_notice_h` (48 h, BR-REIMB-03). */ + readonly feeNoticeH: number; + readonly fees: readonly DepositIncidentalFee[]; + readonly caps: DepositRailCapabilities; +} + +/** Une part d'un frais : capturée sur la caution ou débitée par MIT. */ +export interface DepositFeePart { + readonly feeId: string; + readonly amount: Money; + readonly legs: LegAmounts; +} + +export type DepositStep = + | { + readonly op: 'CAPTURE'; + readonly amountMinor: bigint; + readonly legs: LegAmounts; + readonly parts: readonly DepositFeePart[]; + } + | { readonly op: 'VOID'; readonly releasedMinor: bigint } + /** Aucune annulation possible (`SUPPORTS_VOID` inconnue) : l'autorisation expire seule. */ + | { readonly op: 'LET_EXPIRE'; readonly releasedMinor: bigint } + | { readonly op: 'REFUND'; readonly amountMinor: bigint; readonly legs: LegAmounts } + | { + readonly op: 'MIT_CHARGE'; + readonly reason: 'DELAYED_CHARGES'; + readonly amountMinor: bigint; + readonly legs: LegAmounts; + readonly parts: readonly DepositFeePart[]; + } + /** MIT non validée : les frais deviennent une dette (BR-PAY-10), jamais pris sur la caution. */ + | { + readonly op: 'DEBT'; + readonly amountMinor: bigint; + readonly parts: readonly DepositFeePart[]; + }; + +export interface DepositDecisionPlan { + readonly steps: readonly DepositStep[]; + /** Statut final de `deposit_hold`. */ + readonly finalStatus: DepositHoldStatus; + readonly capturedMinor: bigint; + readonly releasedMinor: bigint; + readonly mitMinor: bigint; +} + +const ZERO_LEGS: LegAmounts = { HOST: 0n, INSURER: 0n, TAX_THIRD_PARTY: 0n, PLATFORM: 0n }; + +const addLegs = (a: LegAmounts, b: LegAmounts): LegAmounts => ({ + HOST: a.HOST + b.HOST, + INSURER: a.INSURER + b.INSURER, + TAX_THIRD_PARTY: a.TAX_THIRD_PARTY + b.TAX_THIRD_PARTY, + PLATFORM: a.PLATFORM + b.PLATFORM, +}); + +/** Jambes d'une part de frais : `allocHost` par ligne, la plateforme prend le complément (E7). */ +function feeLegs(amount: Money, hostShare: Ratio): LegAmounts { + const host = allocHost(amount, hostShare); + return { ...ZERO_LEGS, HOST: host.amountMinor, PLATFORM: subtract(amount, host).amountMinor }; +} + +const part = (fee: DepositIncidentalFee, amount: Money): DepositFeePart => ({ + feeId: fee.id, + amount, + legs: feeLegs(amount, fee.hostShare), +}); + +/** + * Reste d'un frais scindé (plafond de la caution) : la part de l'hôte est arrondie UNE fois sur la + * ligne entière (`allocHost` par ligne, 08 BR-PAY-06 « Jambes des frais annexes »), la part capturée + * prend `allocHost` de son montant et le reste le complément, borné à [0 ; reste] : Σ des deux parts + * = jambes de la ligne entière (aucun écart d'arrondi en faveur de l'un ou de l'autre). + */ +function restPart(fee: DepositIncidentalFee, taken: Money, rest: Money): DepositFeePart { + const wholeHost = allocHost(fee.amount, fee.hostShare).amountMinor; + const takenHost = allocHost(taken, fee.hostShare).amountMinor; + let host = wholeHost - takenHost; + if (host < 0n) host = 0n; + if (host > rest.amountMinor) host = rest.amountMinor; + return { + feeId: fee.id, + amount: rest, + legs: { ...ZERO_LEGS, HOST: host, PLATFORM: rest.amountMinor - host }, + }; +} + +const sumParts = (parts: readonly DepositFeePart[]): { amountMinor: bigint; legs: LegAmounts } => + parts.reduce( + (acc, p) => ({ + amountMinor: acc.amountMinor + p.amount.amountMinor, + legs: addLegs(acc.legs, p.legs), + }), + { amountMinor: 0n, legs: ZERO_LEGS }, + ); + +/** Frais capturable sur la caution : prouvé, non contesté, notifié ≥ `feeNoticeH` avant la décision. */ +export function isCapturableOnDeposit( + fee: DepositIncidentalFee, + decisionAt: Date, + feeNoticeH: number, +): boolean { + return ( + fee.proven && + !fee.disputed && + fee.notifiedAt.getTime() + feeNoticeH * HOUR_MS <= decisionAt.getTime() + ); +} + +/** + * Commandes de la décision de caution (08 BR-PAY-06 « Libération à heure fixe » ; E3 replis 1, 2 + * et 4 ; T57, T58). Une Claim, une Invoice ou des frais d'assistance ne la suspendent jamais (ils + * ne sont pas des entrées). Les frais capturables sont pris dans l'ordre reçu, plafonnés au montant + * de la caution ; le dépassement et les autres frais passent par MIT `DELAYED_CHARGES` séparée. + */ +export function planDepositDecision(input: DepositDecisionInput): DepositDecisionPlan { + const { amount, caps } = input; + if (!Number.isSafeInteger(input.feeNoticeH) || input.feeNoticeH < 0) { + throw new PaymentError('INVALID_REQUEST', 'caution : délai de notification invalide'); + } + const currency = amount.currency; + for (const fee of input.fees) { + if (fee.amount.currency !== currency || fee.amount.amountMinor <= 0n) { + throw new PaymentError('INVALID_REQUEST', `frais ${fee.id} : montant ou devise invalides`); + } + } + const network = caps.network ?? '*'; + const has = (name: 'SUPPORTS_PARTIAL_CAPTURE' | 'SUPPORTS_VOID' | 'SUPPORTS_MIT'): boolean => + caps.capabilities.bool(name, CARD, network); + + // répartition : capturable sur la caution (dans la limite du montant) / débit séparé + let room: Money = amount; + const onDeposit: DepositFeePart[] = []; + const separate: DepositFeePart[] = []; + for (const fee of input.fees) { + if (!isCapturableOnDeposit(fee, input.decisionAt, input.feeNoticeH) || isZero(room)) { + separate.push(part(fee, fee.amount)); + continue; + } + const taken = fee.amount.amountMinor <= room.amountMinor ? fee.amount : room; + onDeposit.push(part(fee, taken)); + room = subtract(room, taken); + const rest = subtract(fee.amount, taken); + if (!isZero(rest)) separate.push(restPart(fee, taken, rest)); + } + + const steps: DepositStep[] = []; + let captured = 0n; + let released = 0n; + let finalStatus: DepositHoldStatus; + const mitParts: DepositFeePart[] = []; + + if (input.mechanism === 'CHARGE_THEN_REFUND') { + // remboursement total émis à la décision, frais en MIT (08 BR-PAY-06 « Débit puis + // remboursement », branche sans retenue) : aucune retenue sur des fonds détenus + steps.push({ op: 'REFUND', amountMinor: amount.amountMinor, legs: chargeLegs(amount) }); + mitParts.push(...onDeposit, ...separate); + finalStatus = 'REFUNDED'; + } else { + const x = sumParts(onDeposit); + const full = x.amountMinor === amount.amountMinor; + if (x.amountMinor > 0n && (full || has('SUPPORTS_PARTIAL_CAPTURE'))) { + // repli 1 : capture partielle (ou totale) des seuls frais dus, puis VOID du reste + steps.push({ op: 'CAPTURE', amountMinor: x.amountMinor, legs: x.legs, parts: onDeposit }); + captured = x.amountMinor; + mitParts.push(...separate); + finalStatus = 'PARTIALLY_CAPTURED'; + } else { + // repli 2 (T58) : aucun frais capturé sur la caution ; tout passe par MIT séparée + mitParts.push(...onDeposit, ...separate); + finalStatus = 'VOIDED'; + } + const rest = amount.amountMinor - captured; + if (rest > 0n) { + if (has('SUPPORTS_VOID')) { + steps.push({ op: 'VOID', releasedMinor: rest }); + } else { + // repli 4 : annulation impossible ⇒ l'autorisation expire seule (message au voyageur) + steps.push({ op: 'LET_EXPIRE', releasedMinor: rest }); + if (captured === 0n) finalStatus = 'EXPIRED'; + } + released = rest; + } + } + + const mit = sumParts(mitParts); + if (mit.amountMinor > 0n) { + steps.push( + has('SUPPORTS_MIT') + ? { + op: 'MIT_CHARGE', + reason: 'DELAYED_CHARGES', + amountMinor: mit.amountMinor, + legs: mit.legs, + parts: mitParts, + } + : { op: 'DEBT', amountMinor: mit.amountMinor, parts: mitParts }, + ); + } + if (input.mechanism === 'CHARGE_THEN_REFUND') released = amount.amountMinor; + return { + steps, + finalStatus, + capturedMinor: captured, + releasedMinor: released, + mitMinor: mit.amountMinor, + }; +} + +/** + * Repli quand la CAPTURE des frais sur la caution est refusée (statut `FAILED` ou refus reçu) : + * 08 E3 repli 2 — aucun frais n'est pris sur la caution ; elle est libérée en entier (`VOID`, ou + * expiration sans `SUPPORTS_VOID`) et TOUS les frais passent par MIT `DELAYED_CHARGES` (ou dette + * sans MIT). Sans étape de capture dans le plan : `null` (rien à replier). + */ +export function fallbackAfterCaptureFailure( + plan: DepositDecisionPlan, + caps: DepositRailCapabilities, +): DepositDecisionPlan | null { + const capture = plan.steps.find((s) => s.op === 'CAPTURE'); + if (capture === undefined || capture.op !== 'CAPTURE') return null; + const network = caps.network ?? '*'; + const has = (name: 'SUPPORTS_VOID' | 'SUPPORTS_MIT'): boolean => + caps.capabilities.bool(name, CARD, network); + const amountMinor = plan.capturedMinor + plan.releasedMinor; + const mitParts: DepositFeePart[] = [...capture.parts]; + for (const s of plan.steps) { + if (s.op === 'MIT_CHARGE' || s.op === 'DEBT') mitParts.push(...s.parts); + } + const mit = sumParts(mitParts); + const steps: DepositStep[] = [ + has('SUPPORTS_VOID') + ? { op: 'VOID', releasedMinor: amountMinor } + : { op: 'LET_EXPIRE', releasedMinor: amountMinor }, + ]; + if (mit.amountMinor > 0n) { + steps.push( + has('SUPPORTS_MIT') + ? { + op: 'MIT_CHARGE', + reason: 'DELAYED_CHARGES', + amountMinor: mit.amountMinor, + legs: mit.legs, + parts: mitParts, + } + : { op: 'DEBT', amountMinor: mit.amountMinor, parts: mitParts }, + ); + } + return { + steps, + finalStatus: has('SUPPORTS_VOID') ? 'VOIDED' : 'EXPIRED', + capturedMinor: 0n, + releasedMinor: amountMinor, + mitMinor: mit.amountMinor, + }; +} + +/** + * Jambes de l'ordre qui pose la caution (autorisation ou débit) : la caution n'est pas une jambe + * (08 BR-PAY-06) ; l'ordre est porté en entier sur `PLATFORM`, le compte marchand de Kmino, et + * chaque capture de frais porte ensuite ses propres jambes. + */ +export function chargeLegs(amount: Money): LegAmounts { + return { ...ZERO_LEGS, PLATFORM: amount.amountMinor }; +} + +// --- machine d'état de deposit_hold.status --------------------------------------------------------- + +export const DEPOSIT_HOLD_STATUSES = [ + 'PLANNED', + 'AUTHORIZED', + 'PARTIALLY_CAPTURED', + 'VOIDED', + 'REFUNDED', + 'EXPIRED', +] as const; +export type DepositHoldStatus = (typeof DEPOSIT_HOLD_STATUSES)[number]; + +export const DEPOSIT_EVENTS = [ + 'AUTHORIZED', + 'AUTH_FAILED', + 'REAUTHORIZED', + 'REAUTH_REFUSED', + 'CAPTURED', + 'VOIDED', + 'REFUNDED', + 'EXPIRED', +] as const; +export type DepositEvent = (typeof DEPOSIT_EVENTS)[number]; + +/** + * Transitions (16 PAY-011 « États ») : `PLANNED → AUTHORIZED → PARTIALLY_CAPTURED / VOIDED / + * REFUNDED / EXPIRED`. Une ré-autorisation (acceptée ou refusée) laisse `AUTHORIZED` : un refus est + * signalé à l'ops, sans débit. Un refus d'autorisation laisse `PLANNED` (EC-27). Les états finaux + * n'ont aucune sortie. `NOT_REQUIRED` n'a ni statut actif ni minuterie (17 §3.2.7). + */ +const TRANSITIONS: Readonly< + Record>> +> = { + PLANNED: { AUTHORIZED: 'AUTHORIZED', AUTH_FAILED: 'PLANNED' }, + AUTHORIZED: { + REAUTHORIZED: 'AUTHORIZED', + REAUTH_REFUSED: 'AUTHORIZED', + CAPTURED: 'PARTIALLY_CAPTURED', + VOIDED: 'VOIDED', + REFUNDED: 'REFUNDED', + EXPIRED: 'EXPIRED', + }, + PARTIALLY_CAPTURED: {}, + VOIDED: {}, + REFUNDED: {}, + EXPIRED: {}, +}; + +export function nextDepositStatus( + status: DepositHoldStatus, + event: DepositEvent, +): DepositHoldStatus { + const next = TRANSITIONS[status][event]; + if (next === undefined) { + throw new PaymentError('INVALID_REQUEST', `caution : transition ${status} → ${event} refusée`); + } + return next; +} diff --git a/apps/api/src/modules/pay/internal/deposit-triggers.test.ts b/apps/api/src/modules/pay/internal/deposit-triggers.test.ts new file mode 100644 index 000000000..6692c9d22 --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-triggers.test.ts @@ -0,0 +1,276 @@ +/** + * Déclencheurs de la caution « comme Turo » (US-225 ; 08 BR-PAY-06, ADR-108). Attendus tirés des + * contrôles de l'oracle `docs/specs/tools/check_t49plus.py` (T69–T73, export + * `@rueda/money/golden-vectors`), jamais du code testé ; paramètres PROPOSÉS = ceux de la graine + * 0142 (relus dans `params.json`, sans importer le module CFG). + */ +import { readFileSync } from 'node:fs'; +import { checksFor, loadGoldenVectors } from '@rueda/money/golden-vectors'; +import type { GoldenValue } from '@rueda/money/golden-vectors'; +import { describe, expect, it } from 'vitest'; +import { countryCases } from '../../../../test/support/countries.js'; +import { depositAmountFor, evaluateDepositTriggers } from './deposit-triggers.js'; +import type { + DepositTriggerDecision, + DepositTriggerParams, + DepositValueClass, +} from './deposit-triggers.js'; + +const set = loadGoldenVectors(); +/** Pays configurés (CLAUDE.md point 3), lus dans la configuration. */ +const COUNTRIES = countryCases().map((c) => c.country); +const check = (vectorId: string, label: RegExp): GoldenValue => { + const found = checksFor(set, vectorId).find((c) => label.test(c.label)); + if (found === undefined) throw new Error(`contrôle ${vectorId} ${label} absent`); + return found.expected; +}; + +interface ParamDoc { + params: Array<{ key: string; values: Record }>; +} +const PARAMS = JSON.parse( + readFileSync(new URL('../../cfg/data/params.json', import.meta.url), 'utf8'), +) as ParamDoc; +const valueOf = (key: string, country: string): unknown => + PARAMS.params.find((p) => p.key === key)?.values[country]; + +/** Paramètres PROPOSÉS du pays, tels que la graine 0142 les charge. */ +function proposed(country: string): DepositTriggerParams { + return { + alwaysRequired: valueOf('deposit_always_required', country) as boolean, + triggerClasses: valueOf('deposit_trigger_classes', country) as DepositValueClass[], + youngDriverAge: valueOf('deposit_young_driver_age', country) as number, + youngDriverClasses: valueOf('deposit_young_driver_classes', country) as DepositValueClass[], + onRiskFlag: valueOf('deposit_on_risk_flag', country) as boolean, + riskControlDeployed: valueOf('risk_control_deployed', country) as boolean, + }; +} + +/** Forme de l'oracle : (exigée, déclencheurs triés). */ +const pair = (d: DepositTriggerDecision): [boolean, string[]] => [d.required, [...d.triggers]]; + +describe('paramètres PROPOSÉS (ADR-108) : aucune caution par défaut, P et P', () => { + it.each(COUNTRIES)( + '%s : pays faux, {LUXE}, âge 30 sur aucune classe, risque non déployé', + (c) => { + expect(proposed(c)).toEqual({ + alwaysRequired: false, + triggerClasses: ['LUXE'], + youngDriverAge: 30, + youngDriverClasses: [], + onRiskFlag: true, + riskControlDeployed: false, + }); + }, + ); +}); + +// paramètres PROPOSÉS identiques dans chaque pays : chaque vecteur (P ou P dans 08) est rejoué +// dans chaque pays configuré +describe.each(COUNTRIES)( + '%s — T69–T73 (oracle check_t49plus.py, fonction deposit_required)', + (country) => { + const P = proposed(country); + + it('T69 : P, STANDARD, 35 ans, aucun signal ⇒ aucune caution', () => { + const expected = check('T69', /caution/) as GoldenValue[]; + const d = evaluateDepositTriggers( + P, + { valueClass: 'STANDARD', driverAges: [35], riskFlagged: false }, + 'CHECKOUT', + ); + expect(d.required).toBe(expected[0]); + expect(d.triggers).toEqual([]); + }); + + it('T70 a / b : trip de T59 en STANDARD ⇒ aucune caution ; en LUXE ⇒ {CLASS}', () => { + const [none, luxe] = check('T70', /sans caution/) as [boolean, [boolean, string[]]]; + expect( + evaluateDepositTriggers( + P, + { valueClass: 'STANDARD', driverAges: [40], riskFlagged: false }, + 'CHECKOUT', + ).required, + ).toBe(none); + expect( + pair( + evaluateDepositTriggers( + P, + { valueClass: 'LUXE', driverAges: [40], riskFlagged: false }, + 'CHECKOUT', + ), + ), + ).toEqual(luxe); + }); + + it('T70 c : avant le checkout, AGE et RISK inconnus ne valent pas « vrai » ; LUXE affiche son montant', () => { + const [premium, luxe, amount] = check('T70', /avant checkout/) as [ + [boolean, string[]], + [boolean, string[]], + bigint, + ]; + expect(pair(evaluateDepositTriggers(P, { valueClass: 'PREMIUM' }, 'PRE_CHECKOUT'))).toEqual( + premium, + ); + const l = evaluateDepositTriggers(P, { valueClass: 'LUXE' }, 'PRE_CHECKOUT'); + expect(pair(l)).toEqual(luxe); + expect(l.riskEvaluated).toBe(false); + expect(depositAmountFor({ LUXE: 30_000n }, 'LUXE')).toBe(amount); + }); + + it('T71 a / b / c : valeurs PROPOSÉES, l’âge seul ne déclenche jamais (DEC-FONDATEUR-21)', () => { + const expected = check('T71', /PROPOSEES/) as [boolean, string[]][]; + expect([ + pair( + evaluateDepositTriggers( + P, + { valueClass: 'PREMIUM', driverAges: [29], riskFlagged: false }, + 'CHECKOUT', + ), + ), + pair( + evaluateDepositTriggers( + P, + { valueClass: 'PREMIUM', driverAges: [45, 26], riskFlagged: false }, + 'CHECKOUT', + ), + ), + pair( + evaluateDepositTriggers( + P, + { valueClass: 'LUXE', driverAges: [25], riskFlagged: false }, + 'CHECKOUT', + ), + ), + ]).toEqual(expected); + }); + + it('T71 d / e / f / g : pays qui active l’âge ; seuil strict ; paramètre absent ⇒ toutes les classes', () => { + const expected = check('T71', /age active/) as [boolean, string[]][]; + const on: DepositTriggerParams = { ...P, youngDriverClasses: ['PREMIUM', 'LUXE'] }; + const absent: DepositTriggerParams = { ...P, youngDriverClasses: undefined }; + expect([ + pair( + evaluateDepositTriggers( + on, + { valueClass: 'PREMIUM', driverAges: [29], riskFlagged: false }, + 'CHECKOUT', + ), + ), + pair( + evaluateDepositTriggers( + on, + { valueClass: 'PREMIUM', driverAges: [30], riskFlagged: false }, + 'CHECKOUT', + ), + ), + pair( + evaluateDepositTriggers( + on, + { valueClass: 'STANDARD', driverAges: [22], riskFlagged: false }, + 'CHECKOUT', + ), + ), + pair( + evaluateDepositTriggers( + absent, + { valueClass: 'STANDARD', driverAges: [22], riskFlagged: false }, + 'CHECKOUT', + ), + ), + ]).toEqual(expected); + }); + + it('T72 a / b / c / d : fail-closed ; contrôle non déployé ≠ en panne', () => { + const [a, b, c, d] = check('T72', /a\/b\/c\/d/) as [ + [boolean, string[]], + [boolean, string[]], + string, + [boolean, string[]], + ]; + const deployed: DepositTriggerParams = { ...P, riskControlDeployed: true }; + const ctx = { valueClass: 'STANDARD' as const, driverAges: [45], riskFlagged: false }; + const ra = evaluateDepositTriggers({ ...deployed, onRiskFlag: undefined }, ctx, 'CHECKOUT'); + expect(pair(ra)).toEqual(a); + expect( + pair(evaluateDepositTriggers(deployed, { ...ctx, riskFlagged: null }, 'CHECKOUT')), + ).toEqual(b); + // (c) caution exigée sans deposit_amount[P][STANDARD] ⇒ PARAM_MISSING, jamais 0 + expect(depositAmountFor({ LUXE: 1_500_000n }, 'STANDARD')).toBeNull(); + expect(c).toBe('PARAM_MISSING'); + const rd = evaluateDepositTriggers(P, { ...ctx, riskFlagged: null }, 'CHECKOUT'); + expect(pair(rd)).toEqual(d); + expect(rd.riskEvaluated).toBe(false); + expect(ra.riskEvaluated).toBe(true); + }); + + it('T73 a / b : une seule caution, montant de la classe, jamais cumulé (montants de test de T73)', () => { + const [a, amountA, b, amountB] = check('T73', /a\/b/) as [ + [boolean, string[]], + bigint, + [boolean, string[]], + bigint, + ]; + const amounts = { LUXE: 1_500_000n, STANDARD: 500_000n }; + const deployed: DepositTriggerParams = { ...P, riskControlDeployed: true }; + expect( + pair( + evaluateDepositTriggers( + deployed, + { valueClass: 'LUXE', driverAges: [27], riskFlagged: true }, + 'CHECKOUT', + ), + ), + ).toEqual(a); + expect(depositAmountFor(amounts, 'LUXE')).toBe(amountA); + expect( + pair( + evaluateDepositTriggers( + { ...P, alwaysRequired: true }, + { valueClass: 'STANDARD', driverAges: [45], riskFlagged: false }, + 'CHECKOUT', + ), + ), + ).toEqual(b); + expect(depositAmountFor(amounts, 'STANDARD')).toBe(amountB); + }); + }, +); + +describe.each(COUNTRIES)('%s — fail-closed hors vecteurs', (country) => { + const P = proposed(country); + it('classe inconnue ⇒ CLASS vrai (et AGE si les classes de l’âge sont absentes) ; montant introuvable', () => { + const d = evaluateDepositTriggers( + P, + { valueClass: null, driverAges: [40], riskFlagged: false }, + 'CHECKOUT', + ); + expect(d.triggers).toEqual(['CLASS']); + expect(depositAmountFor({ LUXE: 30_000n }, null)).toBeNull(); + }); + + it('paramètre du pays absent ⇒ COUNTRY vrai ; âge inconnu ou liste vide ⇒ AGE vrai si la classe en relève', () => { + expect( + evaluateDepositTriggers( + { ...P, alwaysRequired: undefined }, + { valueClass: 'STANDARD', driverAges: [40], riskFlagged: false }, + 'CHECKOUT', + ).triggers, + ).toEqual(['COUNTRY']); + const on: DepositTriggerParams = { ...P, youngDriverClasses: ['STANDARD'] }; + for (const ages of [null, [], [40, null]]) { + expect( + evaluateDepositTriggers( + on, + { valueClass: 'STANDARD', driverAges: ages, riskFlagged: false }, + 'CHECKOUT', + ).triggers, + ).toEqual(['AGE']); + } + }); + + it('montant nul ou absent ⇒ null (refus avant le paiement, jamais une caution de 0)', () => { + expect(depositAmountFor({ LUXE: 0n }, 'LUXE')).toBeNull(); + expect(depositAmountFor(undefined, 'LUXE')).toBeNull(); + }); +}); diff --git a/apps/api/src/modules/pay/internal/deposit-triggers.ts b/apps/api/src/modules/pay/internal/deposit-triggers.ts new file mode 100644 index 000000000..546bca51e --- /dev/null +++ b/apps/api/src/modules/pay/internal/deposit-triggers.ts @@ -0,0 +1,145 @@ +/** + * Déclencheurs de la caution conditionnelle « comme Turo » (08 BR-PAY-06 « Caution conditionnelle », + * « Fail-closed », « Montant unique », « Moment de l'évaluation » ; ADR-108 ; US-225, ADR-164). + * + * **Aucune caution par défaut** : un trip n'a de caution que si un déclencheur est vrai. Fonction + * pure, sans horloge ni base : les paramètres du pays sont lus par `PgDepositRailConfigReader` + * (17 §7.2 ; graine 0142) et passés ici. Aucune constante de pays. + * + * Fail-closed (l'erreur sûre est de PRENDRE une caution, jamais de l'omettre) : un paramètre absent + * ou illisible (`undefined`), une classe inconnue (`null`), un âge inconnu ou un contrôle de risque + * déployé mais sans réponse (`riskFlagged = null`) rendent le déclencheur correspondant VRAI. + * `riskControlDeployed = false` (contrôle non déployé ≠ en panne) : `RISK` n'est pas évalué. + * Avant le checkout, seuls `COUNTRY` et `CLASS` (connus du véhicule) sont évalués. + * + * Le résultat (`triggers`, âge, `riskEvaluated`) est **[C2]** : réservé à SYSTEM et à l'ops + * (17 §3.2.7 `deposit_hold.triggers`, `params_snapshot`), jamais rendu au voyageur ni à l'hôte. + */ + +/** Déclencheurs, liste fermée (17 §3.2.7 `deposit_hold.triggers`), dans l'ordre alphabétique. */ +export const DEPOSIT_TRIGGERS = ['AGE', 'CLASS', 'COUNTRY', 'RISK'] as const; +export type DepositTrigger = (typeof DEPOSIT_TRIGGERS)[number]; + +/** Classes de valeur du catalogue (08 BR-ACC-05 ; ADR-159). */ +export const DEPOSIT_VALUE_CLASSES = ['STANDARD', 'PREMIUM', 'LUXE'] as const; +export type DepositValueClass = (typeof DEPOSIT_VALUE_CLASSES)[number]; + +/** Moment de l'évaluation (08 BR-PAY-06) : fiche, recherche, devis d'un visiteur ; checkout. */ +export type DepositStage = 'PRE_CHECKOUT' | 'CHECKOUT'; + +/** + * Paramètres de déclencheur d'un pays (17 §7.2). `undefined` : absent ou illisible (fail-closed : + * le déclencheur correspondant est vrai, sauf `riskControlDeployed`, absent ⇒ contrôle déployé). + */ +export interface DepositTriggerParams { + /** `deposit_always_required[pays]`. */ + readonly alwaysRequired?: boolean | undefined; + /** `deposit_trigger_classes[pays]`. */ + readonly triggerClasses?: readonly DepositValueClass[] | undefined; + /** `deposit_young_driver_age[pays]` (seuil strict). */ + readonly youngDriverAge?: number | undefined; + /** `deposit_young_driver_classes[pays]` (vide au PA et au PY : DEC-FONDATEUR-21). */ + readonly youngDriverClasses?: readonly DepositValueClass[] | undefined; + /** `deposit_on_risk_flag[pays]`. */ + readonly onRiskFlag?: boolean | undefined; + /** `risk_control_deployed[pays]` : `false` ⇒ RISK non évalué. */ + readonly riskControlDeployed?: boolean | undefined; +} + +export interface DepositTriggerContext { + /** `value_class` du véhicule (catalogue, ADR-159) ; `null` : inconnue. */ + readonly valueClass: DepositValueClass | null; + /** + * Âges entiers des conducteurs approuvés à la date de réservation (BR-ACC-04), depuis le document + * vérifié ; `null` (ou un âge `null`, ou une liste vide) : inconnu. Ignoré avant le checkout. + */ + readonly driverAges?: readonly (number | null)[] | null; + /** Signal du contrôle de risque ; `null` : panne, délai dépassé ou réponse illisible. */ + readonly riskFlagged?: boolean | null; +} + +export interface DepositTriggerDecision { + readonly required: boolean; + /** Déclencheurs vrais, triés ; vide ⇔ aucune caution. [C2] */ + readonly triggers: readonly DepositTrigger[]; + /** Âge entier du plus jeune conducteur approuvé (`params_snapshot`) ; `null` : inconnu ou non lu. */ + readonly youngestDriverAge: number | null; + /** `params_snapshot.risk_evaluated` : faux avant le checkout ou si le contrôle n'est pas déployé. */ + readonly riskEvaluated: boolean; +} + +const isAge = (a: unknown): a is number => Number.isSafeInteger(a) && (a as number) >= 0; + +/** Plus jeune âge connu ; `null` si la liste est absente, vide ou contient un âge inconnu. */ +function youngestOf(ages: readonly (number | null)[] | null | undefined): number | null { + if (ages === null || ages === undefined || ages.length === 0) return null; + let youngest: number | null = null; + for (const a of ages) { + if (!isAge(a)) return null; + youngest = youngest === null ? a : Math.min(youngest, a); + } + return youngest; +} + +/** Classe dans une liste de paramètre ; liste absente ou classe inconnue ⇒ vrai (fail-closed). */ +const inClasses = ( + list: readonly DepositValueClass[] | undefined, + cls: DepositValueClass | null, +): boolean => list === undefined || cls === null || list.includes(cls); + +/** + * Déclencheurs vrais au moment `stage` (08 BR-PAY-06 ; vecteurs T69–T73, T70 c ; oracle + * `docs/specs/tools/check_t49plus.py`, fonction `deposit_required`). + */ +export function evaluateDepositTriggers( + params: DepositTriggerParams, + context: DepositTriggerContext, + stage: DepositStage, +): DepositTriggerDecision { + const triggers = new Set(); + if (params.alwaysRequired !== false) triggers.add('COUNTRY'); + if (inClasses(params.triggerClasses, context.valueClass)) triggers.add('CLASS'); + if (stage === 'PRE_CHECKOUT') { + // AGE et RISK ne sont jamais évalués avant le checkout : leur inconnu n'est pas un « vrai » + return done(triggers, null, false); + } + const youngest = youngestOf(context.driverAges); + const age = params.youngDriverAge; + if ( + inClasses(params.youngDriverClasses, context.valueClass) && + (!isAge(age) || youngest === null || youngest < age) + ) { + triggers.add('AGE'); + } + const riskEvaluated = params.riskControlDeployed !== false; + if (riskEvaluated) { + const flagged = context.riskFlagged; + // paramètre absent ⇒ vrai quel que soit le signal (T72 a) ; signal inconnu ⇒ vrai (T72 b) + const signal = flagged === null || flagged === undefined || flagged; + if (params.onRiskFlag === undefined || (params.onRiskFlag && signal)) triggers.add('RISK'); + } + return done(triggers, youngest, riskEvaluated); +} + +function done( + triggers: ReadonlySet, + youngestDriverAge: number | null, + riskEvaluated: boolean, +): DepositTriggerDecision { + const sorted = DEPOSIT_TRIGGERS.filter((t) => triggers.has(t)); + return { required: sorted.length > 0, triggers: sorted, youngestDriverAge, riskEvaluated }; +} + +/** + * Montant unique de la caution (08 BR-PAY-06 « Montant unique », T73) : `deposit_amount[pays][classe]`, + * jamais cumulé, jamais inventé ni ramené à 0. Absent, nul, illisible ou classe inconnue ⇒ + * `null` : l'appelant refuse la réservation AVANT le paiement (`PARAM_MISSING`, T72 c). + */ +export function depositAmountFor( + amounts: Readonly>> | undefined, + valueClass: DepositValueClass | null, +): bigint | null { + if (amounts === undefined || valueClass === null) return null; + const amount = amounts[valueClass]; + return typeof amount === 'bigint' && amount > 0n ? amount : null; +} diff --git a/apps/api/src/modules/pay/internal/idempotency.ts b/apps/api/src/modules/pay/internal/idempotency.ts index 4f007a807..e399d1ed2 100644 --- a/apps/api/src/modules/pay/internal/idempotency.ts +++ b/apps/api/src/modules/pay/internal/idempotency.ts @@ -82,6 +82,44 @@ export function holdAttemptKey( return `hold:${part('hold_id', holdId)}:${operation}:a${rank('attempt_no', attemptNo)}`; } +/** + * Opérations d'une caution (US-225, ADR-164 ; PROPOSÉ, à reporter dans 08 E4) : pose (`AUTH` + * pré-autorisation, `CHARGE` débit du rail « débit puis remboursement »), ré-autorisation, capture + * des frais, annulation, remboursement du débit, débit MIT des frais non capturés. + */ +export const DEPOSIT_OPERATION_TYPES = [ + 'AUTH', + 'CHARGE', + 'REAUTH', + 'CAPTURE', + 'VOID', + 'REFUND', + 'MIT_CHARGE', +] as const; +export type DepositOperationType = (typeof DEPOSIT_OPERATION_TYPES)[number]; + +/** + * `deposit:{deposit_id}:{opération}:i{instance_seq}:a{attempt_no}` : une clé par tentative, comme + * la variante pré-trip ; `i{n}` distingue deux ré-autorisations successives. + */ +export function depositOperationKey( + depositId: string, + operation: DepositOperationType, + instanceSeq: number, + attemptNo: number, +): string { + if (!(DEPOSIT_OPERATION_TYPES as readonly string[]).includes(operation)) { + throw new PaymentError('INVALID_REQUEST', `opération de caution inconnue : ${operation}`); + } + return [ + 'deposit', + part('deposit_id', depositId), + operation, + `i${rank('instance_seq', instanceSeq)}`, + `a${rank('attempt_no', attemptNo)}`, + ].join(':'); +} + /** * Variante hors règlement (caution, surfacturation de dommage, révision d'un frais annexe) : * `{trip_id}:{segment_id}:v0-{origin_type}-{origin_id}:REFUND:{tender_id}:i{n}:a{m}` ; le segment diff --git a/apps/api/src/modules/pay/internal/pg-deposit-config.ts b/apps/api/src/modules/pay/internal/pg-deposit-config.ts new file mode 100644 index 000000000..793c8f03b --- /dev/null +++ b/apps/api/src/modules/pay/internal/pg-deposit-config.ts @@ -0,0 +1,167 @@ +/** + * Lecture de la configuration des rails de la caution (US-225, ADR-164) sous un rôle de production + * (`app_api` au checkout, `app_worker` pour les minuteries) : paramètres du pays (17 §7.2 ; graines + * 0009 et 0142), interrupteur `funds_holding_enabled` (`core.config_go_live`, fail-closed) et + * matrice `psp_capability` du fournisseur (seule une ligne `VALIDATED_*` compte, `CapabilitySet`). + * + * Lecture seule, aucune écriture : le rail se choisit par configuration (19 US-225, notes + * techniques). Une valeur absente, mal typée ou hors vocabulaire est rendue ABSENTE : la fonction + * pure appelante applique le fail-closed (déclencheur vrai, `PARAM_MISSING`, capacité « non »). + */ +import { CapabilitySet } from './capabilities.js'; +import type { CapabilityRecord, CapabilityStatus } from './capabilities.js'; +import { DEPOSIT_VALUE_CLASSES } from './deposit-triggers.js'; +import type { DepositTriggerParams, DepositValueClass } from './deposit-triggers.js'; +import type { DepositRailParams } from './deposit-rails.js'; +import type { SqlExecutor } from './pg-stores.js'; + +/** Clés lues (portée pays, sauf `provider_max_hold_h` : réseau > PSP > pays, 17 §7.1 point 6). */ +export const DEPOSIT_CONFIG_KEYS = [ + 'deposit_always_required', + 'deposit_trigger_classes', + 'deposit_young_driver_age', + 'deposit_young_driver_classes', + 'deposit_on_risk_flag', + 'risk_control_deployed', + 'deposit_amount', + 'deposit_charge_cap', + 'deposit_safety_h', + 'deposit_reauth_lead_h', + 'deposit_fee_notice_h', + 'auth_lead_h', + 'release_delay_h', + 'marge_h', + 'provider_max_hold_h', +] as const; +type ConfigKey = (typeof DEPOSIT_CONFIG_KEYS)[number]; + +export interface DepositRailConfig { + readonly triggerParams: DepositTriggerParams; + /** `deposit_amount[pays]` par classe ; `undefined` : absent (aujourd'hui `TO_DECIDE`). */ + readonly amounts: Readonly>> | undefined; + readonly railParams: DepositRailParams; + /** `deposit_fee_notice_h` ; `null` : absent. */ + readonly feeNoticeH: number | null; + readonly capabilities: CapabilitySet; +} + +const boolOf = (v: unknown): boolean | undefined => (typeof v === 'boolean' ? v : undefined); + +const hoursOf = (v: unknown): number | null => + typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 ? v : null; + +const MINOR = /^(0|[1-9][0-9]{0,18})$/; +const minorOf = (v: unknown): bigint | null => + typeof v === 'string' && MINOR.test(v) ? BigInt(v) : null; + +/** Ensemble de classes du vocabulaire fermé ; autre forme ⇒ absent (toutes les classes). */ +function classesOf(v: unknown): readonly DepositValueClass[] | undefined { + if (!Array.isArray(v)) return undefined; + const out: DepositValueClass[] = []; + for (const c of v) { + if (!(DEPOSIT_VALUE_CLASSES as readonly unknown[]).includes(c)) return undefined; + out.push(c as DepositValueClass); + } + return out; +} + +/** `deposit_amount` : `{ classe: "unités mineures" }` ; entrée illisible ⇒ classe absente. */ +function amountsOf(v: unknown): Partial> | undefined { + if (v === null || typeof v !== 'object' || Array.isArray(v)) return undefined; + const out: Partial> = {}; + for (const cls of DEPOSIT_VALUE_CLASSES) { + const m = minorOf((v as Record)[cls]); + if (m !== null && m > 0n) out[cls] = m; + } + return out; +} + +const CAP_STATUSES: readonly CapabilityStatus[] = [ + 'VALIDATED_SANDBOX', + 'VALIDATED_CONTRACT', + 'DOCUMENTED', + 'UNKNOWN', +]; + +export class PgDepositRailConfigReader { + readonly #db: SqlExecutor; + + constructor(db: SqlExecutor) { + this.#db = db; + } + + /** + * Configuration du pays et du fournisseur à l'heure de la base (`platform.now()`). `network` : + * réseau de la carte si connu (`provider_max_hold_h` et capacités les plus précises d'abord). + */ + async read(country: string, provider: string, network = '*'): Promise { + const { rows } = await this.#db.query<{ key: ConfigKey; value: unknown }>( + `WITH t AS (SELECT platform.now() AS ts) + SELECT DISTINCT ON (v.key) v.key, v.value + FROM core.config_param_value AS v CROSS JOIN t + WHERE v.key = ANY ($3::text[]) + AND v.country_code = $1 + AND v.valid_from <= t.ts + AND (v.valid_to IS NULL OR v.valid_to > t.ts) + AND (v.scope_type = 'COUNTRY' + OR (v.scope_type = 'PSP' AND v.scope_id = $2) + OR (v.scope_type = 'NETWORK' AND v.network = $4)) + ORDER BY v.key, + CASE v.scope_type WHEN 'NETWORK' THEN 0 WHEN 'PSP' THEN 1 ELSE 2 END, + v.valid_from DESC`, + [country, provider, [...DEPOSIT_CONFIG_KEYS], network], + ); + const value = (key: ConfigKey): unknown => rows.find((r) => r.key === key)?.value; + const funds = await this.#db.query<{ enabled: boolean | null }>( + `SELECT core.config_go_live('funds_holding_enabled', $1) AS enabled`, + [country], + ); + const caps = await this.#db.query<{ + capability: string; + method: string; + network: string; + value: unknown; + status: string; + }>( + `SELECT DISTINCT ON (c.capability, c.method, c.network) + c.capability, c.method, c.network, c.value, c.status + FROM core.payment_psp_capability AS c + WHERE c.provider = $1 AND c.country_code = $2 AND c.valid_from <= platform.now() + ORDER BY c.capability, c.method, c.network, c.valid_from DESC`, + [provider, country], + ); + const records: CapabilityRecord[] = caps.rows + .filter((r) => (CAP_STATUSES as readonly string[]).includes(r.status)) + .map((r) => ({ + capability: r.capability, + method: r.method, + network: r.network, + value: r.value, + status: r.status as CapabilityStatus, + })); + return { + triggerParams: { + alwaysRequired: boolOf(value('deposit_always_required')), + triggerClasses: classesOf(value('deposit_trigger_classes')), + youngDriverAge: hoursOf(value('deposit_young_driver_age')) ?? undefined, + youngDriverClasses: classesOf(value('deposit_young_driver_classes')), + onRiskFlag: boolOf(value('deposit_on_risk_flag')), + riskControlDeployed: boolOf(value('risk_control_deployed')), + }, + amounts: amountsOf(value('deposit_amount')), + railParams: { + authLeadH: hoursOf(value('auth_lead_h')), + releaseDelayH: hoursOf(value('release_delay_h')), + marginH: hoursOf(value('marge_h')), + safetyH: hoursOf(value('deposit_safety_h')), + reauthLeadH: hoursOf(value('deposit_reauth_lead_h')), + // failMode ZERO : absent ⇒ 0 (aucune pré-autorisation ; rail b interdit) + providerMaxHoldH: hoursOf(value('provider_max_hold_h')) ?? 0, + chargeCapMinor: minorOf(value('deposit_charge_cap')) ?? 0n, + fundsHoldingEnabled: funds.rows[0]?.enabled === true, + }, + feeNoticeH: hoursOf(value('deposit_fee_notice_h')), + capabilities: new CapabilitySet(records), + }; + } +} diff --git a/apps/api/src/modules/pay/testing/deposit-rail-config.int.test.ts b/apps/api/src/modules/pay/testing/deposit-rail-config.int.test.ts new file mode 100644 index 000000000..cc7196fc1 --- /dev/null +++ b/apps/api/src/modules/pay/testing/deposit-rail-config.int.test.ts @@ -0,0 +1,207 @@ +/** + * US-225 — configuration des rails de la caution lue sur PostgreSQL réel sous le rôle de production + * `app_api` (`connectAs` exécute l'assertion L0-05 en tête de chaque test), dans chaque pays + * configuré (USD, PYG sans décimale), transactions ANNULÉES : + * - graine 0142 (défauts PROPOSÉS) : aucune caution par défaut — un STANDARD n'évalue aucun rail + * (T70) ; un LUXE est refusé avant le paiement tant que `deposit_amount` n'est pas fixé + * (`PARAM_MISSING`, T72 c) ; capacités inconnues ⇒ aucune pré-autorisation ; + * - valeurs de test de 08 posées dans la transaction (fixture 9943, capacités par 9800) : T57 ⇒ + * pré-autorisation unique ; T59 ⇒ `DEPOSIT_RAIL_UNAVAILABLE` (3 jours possibles) ; plafond du + * rail « débit puis remboursement » posé mais `funds_holding_enabled` = false ⇒ toujours refusé + * (critère 4) ; `SUPPORTS_REAUTH` validée ⇒ rail de ré-autorisation (critère 3) ; + * - `app_api` n'écrit aucun paramètre ni aucune capacité (lecture seule). + * Attendus : 08 BR-PAY-06, vecteurs T57 / T59 / T70 / T72, `params.json` (lu comme donnée), jamais + * le code testé. + */ +import { readFileSync } from 'node:fs'; +import { connectAs, releaseClient } from '@rueda/db/testing'; +import type {} from '@rueda/db/testing/global-setup'; +import type pg from 'pg'; +import { afterEach, describe, expect, it } from 'vitest'; +import { decideDepositGate, PgDepositRailConfigReader } from '../index.js'; +import type { DepositGateDecision, DepositRailConfig, DepositValueClass } from '../index.js'; +import { countryCases } from '../../../../test/support/countries.js'; + +/** Fournisseur propre à ce fichier : aucune capacité d'un autre test ne s'y mêle. */ +const PROVIDER = 'FAKE_US225'; +const H = 3_600_000; + +const read = (file: string): unknown => + JSON.parse(readFileSync(new URL(`../../cfg/data/${file}`, import.meta.url), 'utf8')); +const PARAMS = ( + read('params.json') as { params: { key: string; values: Record }[] } +).params; +const EXPONENTS = new Map( + (read('currencies.json') as { currencies: { code: string; exponent: number }[] }).currencies.map( + (c) => [c.code, c.exponent], + ), +); +const seeded = (key: string, country: string): unknown => + PARAMS.find((p) => p.key === key)?.values[country]; + +const opened: pg.Client[] = []; +afterEach(async () => { + for (const c of opened.splice(0)) await releaseClient(c); +}); + +async function inApiTx(fn: (client: pg.Client) => Promise): Promise { + const client = await connectAs('app_api'); // assertion L0-05 + opened.push(client); + await client.query('BEGIN'); + try { + return await fn(client); + } finally { + await client.query('ROLLBACK'); + } +} + +async function dbNow(client: pg.Client): Promise { + const { rows } = await client.query<{ now: Date }>('SELECT platform.now() AS now'); + const now = rows[0]?.now; + if (now === undefined) throw new Error('platform.now() absent'); + return now; +} + +const setParam = (client: pg.Client, key: string, country: string, value: unknown) => + client.query('SELECT test_fixture.us225_param_version($1, $2, $3::jsonb)', [ + key, + country, + JSON.stringify(value), + ]); + +const setCapability = ( + client: pg.Client, + country: string, + name: string, + value: unknown, + from: Date, +) => + client.query( + `SELECT test_fixture.us024_set_capability($1, $2, '*', $3, $4::jsonb, 'VALIDATED_SANDBOX', $5::timestamptz)`, + [PROVIDER, country, name, JSON.stringify(value), from.toISOString()], + ); + +/** Décision du checkout pour un trip de `tripMinutes` qui part dans 10 jours. */ +function gateFor( + config: DepositRailConfig, + now: Date, + valueClass: DepositValueClass, + tripMinutes: number, +): DepositGateDecision { + const start = new Date(now.getTime() + 240 * H); + return decideDepositGate({ + triggerParams: config.triggerParams, + amounts: config.amounts, + railParams: config.railParams, + caps: { capabilities: config.capabilities }, + context: { valueClass, driverAges: [40], riskFlagged: false }, + bookedAt: now, + scheduledStart: start, + scheduledEnd: new Date(start.getTime() + tripMinutes * 60_000), + }); +} + +describe.each(countryCases())('$country ($currency) — rails de la caution sous app_api', (c) => { + const major = (units: bigint): bigint => units * 10n ** BigInt(EXPONENTS.get(c.currency) ?? -1); + + it('graine 0142 : paramètres PROPOSÉS lus tels que params.json ; aucune caution par défaut', async () => { + await inApiTx(async (client) => { + const config = await new PgDepositRailConfigReader(client).read(c.country, PROVIDER); + expect(config.triggerParams).toEqual({ + alwaysRequired: seeded('deposit_always_required', c.country), + triggerClasses: seeded('deposit_trigger_classes', c.country), + youngDriverAge: seeded('deposit_young_driver_age', c.country), + youngDriverClasses: seeded('deposit_young_driver_classes', c.country), + onRiskFlag: seeded('deposit_on_risk_flag', c.country), + riskControlDeployed: seeded('risk_control_deployed', c.country), + }); + // ADR-108 : pays faux, {LUXE}, aucune classe pour l'âge, contrôle de risque non déployé + expect(config.triggerParams).toMatchObject({ + alwaysRequired: false, + triggerClasses: ['LUXE'], + youngDriverClasses: [], + riskControlDeployed: false, + }); + expect(config.railParams).toEqual({ + authLeadH: seeded('auth_lead_h', c.country), + releaseDelayH: seeded('release_delay_h', c.country), + marginH: seeded('marge_h', c.country), + safetyH: seeded('deposit_safety_h', c.country), + reauthLeadH: seeded('deposit_reauth_lead_h', c.country), + providerMaxHoldH: 0, // à fixer par PSP au lot C (absent ⇒ 0) + chargeCapMinor: 0n, // absent ⇒ 0 : rail (b) interdit + fundsHoldingEnabled: false, // interrupteur, false en production (17 §0.1) + }); + expect(config.amounts).toBeUndefined(); // deposit_amount : TO_DECIDE (J-ADM-031) + expect(config.feeNoticeH).toBe(seeded('deposit_fee_notice_h', c.country)); + + const now = await dbNow(client); + // T70 : STANDARD ⇒ aucun rail évalué, réservation possible + expect(gateFor(config, now, 'STANDARD', 72 * 60 + 25).kind).toBe('NOT_REQUIRED'); + // T72 c : LUXE exige une caution dont le montant n'est pas fixé ⇒ refus avant le paiement + const luxe = gateFor(config, now, 'LUXE', 72 * 60); + expect(luxe.kind === 'REFUSED' && luxe.code).toBe('PARAM_MISSING'); + }); + }); + + it('valeurs de test de 08 : T57 pré-autorisation unique ; T59 refusé (3 jours) ; rail (b) fermé par funds_holding_enabled ; ré-autorisation', async () => { + await inApiTx(async (client) => { + const now = await dbNow(client); + await setParam(client, 'deposit_amount', c.country, { LUXE: major(300n).toString() }); + await setParam(client, 'provider_max_hold_h', c.country, 168); + await setCapability(client, c.country, 'SUPPORTS_PREAUTH', true, now); + await setCapability(client, c.country, 'MAX_HOLD_HOURS', 168, now); + const reader = new PgDepositRailConfigReader(client); + + const t57 = gateFor(await reader.read(c.country, PROVIDER), now, 'LUXE', 72 * 60); + expect(t57.kind === 'REQUIRED' && [t57.amountMinor, t57.rail.mechanism]).toEqual([ + major(300n), + 'PREAUTH_SINGLE', + ]); + + const t59 = gateFor(await reader.read(c.country, PROVIDER), now, 'LUXE', 72 * 60 + 25); + expect(t59.kind === 'REFUSED' && [t59.code, t59.maxBookableDays]).toEqual([ + 'DEPOSIT_RAIL_UNAVAILABLE', + 3, + ]); + + // critère 4 : plafond du débit puis remboursement posé, interrupteur fermé ⇒ toujours refusé + await setParam(client, 'deposit_charge_cap', c.country, major(300n).toString()); + await setCapability(client, c.country, 'SUPPORTS_REFUND', true, now); + const capped = await reader.read(c.country, PROVIDER); + expect(capped.railParams).toMatchObject({ + chargeCapMinor: major(300n), + fundsHoldingEnabled: false, + }); + const b = gateFor(capped, now, 'LUXE', 72 * 60 + 25); + expect(b.kind === 'REFUSED' && b.code).toBe('DEPOSIT_RAIL_UNAVAILABLE'); + + // critère 3 : SUPPORTS_REAUTH validée ⇒ rail de ré-autorisation + await setCapability(client, c.country, 'SUPPORTS_REAUTH', true, now); + const a = gateFor(await reader.read(c.country, PROVIDER), now, 'LUXE', 72 * 60 + 25); + expect(a.kind === 'REQUIRED' && a.rail.mechanism).toBe('REAUTH'); + }); + }); + + it('app_api ne modifie ni un paramètre de la caution ni une capacité (lecture seule)', async () => { + await inApiTx(async (client) => { + const write = await client + .query( + `INSERT INTO core.config_param_value (key, country_code, scope_type, value, change_reason) + VALUES ('deposit_always_required', $1, 'COUNTRY', 'true'::jsonb, 'test')`, + [c.country], + ) + .catch((e: unknown) => e as { code?: string }); + expect((write as { code?: string }).code).toBe('42501'); + }); + await inApiTx(async (client) => { + const write = await client + .query( + `UPDATE core.payment_psp_capability SET status = 'VALIDATED_SANDBOX' WHERE country_code = $1`, + [c.country], + ) + .catch((e: unknown) => e as { code?: string }); + expect((write as { code?: string }).code).toBe('42501'); + }); + }); +}); diff --git a/apps/api/src/modules/pay/testing/deposit-rails.fake.test.ts b/apps/api/src/modules/pay/testing/deposit-rails.fake.test.ts new file mode 100644 index 000000000..8de838449 --- /dev/null +++ b/apps/api/src/modules/pay/testing/deposit-rails.fake.test.ts @@ -0,0 +1,302 @@ +/** + * US-225 — rails de la caution exécutés par le port `PaymentProvider` sur le PSP simulé (FAKE + * seulement, C19), en USD (PA) et en PYG sans décimale (PY) : pose par pré-autorisation, décision + * T57 (capture des frais puis VOID du reste) et T58 (VOID puis MIT), ré-autorisation acceptée ou + * refusée (trip signalé à l'ops, AUCUN débit), rail « débit puis remboursement » refusé sans appel + * tant que `funds_holding_enabled` = false. Attendus : vecteurs T57 / T58 (oracle + * `check_t49plus.py`) et, pour PY, le calcul de 08 BR-PAY-06 refait à la main. + */ +import { readFileSync } from 'node:fs'; +import { createCurrencyRegistry, money, ratio } from '@rueda/money'; +import { describe, expect, it } from 'vitest'; +import { CapabilitySet } from '../internal/capabilities.js'; +import { DepositRailExecutor } from '../internal/deposit-executor.js'; +import type { DepositPaymentProvider } from '../internal/deposit-executor.js'; +import type { OperationStatus } from '../internal/port.js'; +import { planDepositDecision } from '../internal/deposit-rails.js'; +import { isPaymentError } from '../internal/errors.js'; +import { countryCases } from '../../../../test/support/countries.js'; +import { fakeStack } from './fake-stack.js'; +import type { FakeStackOptions } from './fake-stack.js'; + +const CURRENCIES = createCurrencyRegistry( + ( + JSON.parse( + readFileSync(new URL('../../cfg/data/currencies.json', import.meta.url), 'utf8'), + ) as { currencies: { code: string; exponent: number }[] } + ).currencies, +); + +/** + * Pays configurés (lus dans la configuration) ; vecteurs T57–T58 (300,00 et 12,00 en unités + * majeures) à l'exposant de la devise : USD 30 000 et 1 200 centimes ; PYG 300 et 12. + */ +const CASES = countryCases().map((c) => { + const exp = 10n ** BigInt(CURRENCIES.get(c.currency).exponent); + return { ...c, deposit: 300n * exp, fuel: 12n * exp }; +}); + +const H = 3_600_000; +const DECISION = new Date(Date.parse('2031-07-16T08:00:00.000Z')); + +function setup(c: (typeof CASES)[number], options: FakeStackOptions = {}) { + const stack = fakeStack(options); + const executor = new DepositRailExecutor(stack.provider); + const ref = { + depositId: `dep-${c.country}`, + tripReference: `trip-${c.country}`, + currency: CURRENCIES.get(c.currency), + }; + return { stack, executor, ref }; +} + +async function authorized(c: (typeof CASES)[number], s: ReturnType): Promise { + const order = await s.executor.place(s.ref, { + mechanism: 'PREAUTH_SINGLE', + amountMinor: c.deposit, + fundsHoldingEnabled: false, + attemptNo: 1, + }); + s.stack.psp.customerPays(order.providerReference); + return order.providerReference; +} + +function plan(c: (typeof CASES)[number], caps: CapabilitySet) { + return planDepositDecision({ + mechanism: 'PREAUTH_SINGLE', + amount: money(c.deposit, CURRENCIES.get(c.currency)), + decisionAt: DECISION, + feeNoticeH: 48, + fees: [ + { + id: 'fuel', + amount: money(c.fuel, CURRENCIES.get(c.currency)), + hostShare: ratio(1n, 1n), + proven: true, + notifiedAt: new Date(DECISION.getTime() - 69 * H), + disputed: false, + }, + ], + caps: { capabilities: caps }, + }); +} + +describe.each(CASES)('$country ($currency) — exécution sur le FAKE', (c) => { + it('pose : pré-autorisation MANUAL du montant explicite, sur PLATFORM (compte marchand de Kmino), aucun mouvement', async () => { + const s = setup(c); + await authorized(c, s); + const [auth] = s.stack.psp.transactions(); + expect([auth?.captureMode, auth?.status, auth?.amountMinor, auth?.legs?.PLATFORM]).toEqual([ + 'MANUAL', + 'AUTHORIZED', + c.deposit, + c.deposit, + ]); + expect(s.stack.psp.movements()).toEqual([]); + }); + + it('T57 : capture des frais (jambe HOST, montant explicite) puis VOID du reste ; rejeu sans second mouvement', async () => { + const s = setup(c); + const reference = await authorized(c, s); + const p = plan(c, new CapabilitySet(s.stack.capabilities)); + const target = { providerReference: reference, instrumentToken: 'tok_card', attemptNo: 1 }; + const run = await s.executor.execute(s.ref, p, target); + expect(run.failed).toBeNull(); + expect(run.completed.map((r) => [r.step.op, r.result?.status])).toEqual([ + ['CAPTURE', 'SUCCEEDED'], + ['VOID', 'SUCCEEDED'], + ]); + expect(s.stack.psp.movements().map((m) => [m.operation, m.amountMinor, m.legs?.HOST])).toEqual([ + ['CAPTURE', c.fuel, c.fuel], + ]); + // même tentative rejouée : clés identiques, aucun nouveau mouvement + await s.executor.execute(s.ref, p, target); + expect(s.stack.psp.movements()).toHaveLength(1); + }); + + it('T58 (critère 5) : sans capture partielle ⇒ VOID de la caution entière puis débit MIT des frais', async () => { + // capacité bloquante de la place de marché (17 §2.8) : validée pour le compte (`*`), absente + // pour la carte (moyen de la caution) — le cas de T58 pour ce moyen + const s = setup(c, { + override: [ + { + capability: 'SUPPORTS_PARTIAL_CAPTURE', + method: '*', + value: true, + status: 'VALIDATED_SANDBOX', + }, + { + capability: 'SUPPORTS_PARTIAL_CAPTURE', + method: 'CARD', + value: false, + status: 'VALIDATED_SANDBOX', + }, + ], + }); + const reference = await authorized(c, s); + const p = plan(c, new CapabilitySet(s.stack.capabilities)); + const run = await s.executor.execute(s.ref, p, { + providerReference: reference, + instrumentToken: 'tok_card', + attemptNo: 1, + }); + expect(run.failed).toBeNull(); + expect(run.completed.map((r) => r.step.op)).toEqual(['VOID', 'MIT_CHARGE']); + expect(s.stack.psp.movements().map((m) => [m.operation, m.amountMinor, m.legs?.HOST])).toEqual([ + ['MIT_CHARGE', c.fuel, c.fuel], + ]); + }); + + it('critère 3 : ré-autorisation acceptée ; refusée ⇒ trip signalé à l’ops, AUCUN débit', async () => { + const ok = setup(c); + const r1 = await authorized(c, ok); + expect((await ok.executor.reauthorize(ok.ref, r1, 1, 1)).kind).toBe('REAUTHORIZED'); + + const refused = setup(c, { + scenario: { responses: { REAUTHORIZE: [{ kind: 'DECLINE', code: 'do_not_honor' }] } }, + }); + const r2 = await authorized(c, refused); + expect(await refused.executor.reauthorize(refused.ref, r2, 1, 1)).toEqual({ + kind: 'REAUTH_REFUSED', + opsSignal: 'DEPOSIT_REAUTH_FAILED', + reason: 'DECLINED', + }); + expect(refused.stack.psp.calls('MIT_CHARGE')).toBe(0); + expect(refused.stack.psp.movements()).toEqual([]); + + // capacité non validée : refus sans appel au PSP, même signal, aucun débit + const unvalidated = setup(c, { without: ['SUPPORTS_REAUTH'] }); + const r3 = await authorized(c, unvalidated); + expect(await unvalidated.executor.reauthorize(unvalidated.ref, r3, 1, 1)).toMatchObject({ + kind: 'REAUTH_REFUSED', + reason: 'UNSUPPORTED_CAPABILITY', + }); + expect(unvalidated.stack.psp.calls('REAUTHORIZE')).toBe(0); + }); + + it('critère 4 / 17 §0.1 : « débit puis remboursement » refusé SANS appel tant que funds_holding_enabled = false', async () => { + const s = setup(c); + const refused = await s.executor + .place(s.ref, { + mechanism: 'CHARGE_THEN_REFUND', + amountMinor: c.deposit, + fundsHoldingEnabled: false, + attemptNo: 1, + }) + .catch((e: unknown) => e); + expect(isPaymentError(refused, 'INVALID_REQUEST')).toBe(true); + expect(s.stack.psp.totalCalls()).toBe(0); + }); + + it('sans pré-autorisation validée : la pose est refusée sans appel (capacité inconnue = non)', async () => { + const s = setup(c, { without: ['SUPPORTS_PREAUTH'] }); + const refused = await s.executor + .place(s.ref, { + mechanism: 'PREAUTH_SINGLE', + amountMinor: c.deposit, + fundsHoldingEnabled: false, + attemptNo: 1, + }) + .catch((e: unknown) => e); + expect(isPaymentError(refused, 'UNSUPPORTED_CAPABILITY')).toBe(true); + expect(s.stack.psp.calls('CREATE_ORDER')).toBe(0); + }); +}); + +/** + * Port FAKE dont la capture rend un statut imposé (revues argent, code, qa de la PR 236) : tous les + * autres appels passent au PSP simulé. + */ +function captureReturning( + s: ReturnType, + status: OperationStatus, +): DepositRailExecutor { + const p = s.stack.provider; + const port: DepositPaymentProvider = { + capabilities: () => p.capabilities(), + createHostedPayment: (r) => p.createHostedPayment(r), + capture: (r) => Promise.resolve({ providerReference: r.providerReference, status }), + void: (r) => p.void(r), + refund: (r) => p.refund(r), + chargeMIT: (r) => p.chargeMIT(r), + reauthorize: (r) => p.reauthorize(r), + }; + return new DepositRailExecutor(port); +} + +describe.each(CASES)( + '$country ($currency) — capture non aboutie : arrêt ou repli, jamais un VOID du reste', + (c) => { + const target = (providerReference: string) => ({ + providerReference, + instrumentToken: 'tok_card', + attemptNo: 1, + }); + + it('capture REFUSÉE (exception) ⇒ repli 08 E3 : VOID de la caution ENTIÈRE puis MIT du carburant (jambe HOST) ; rejeu sans second mouvement', async () => { + const s = setup(c, { + scenario: { responses: { CAPTURE: [{ kind: 'DECLINE', code: 'do_not_honor' }] } }, + }); + const reference = await authorized(c, s); + const p = plan(c, new CapabilitySet(s.stack.capabilities)); + const run = await s.executor.execute(s.ref, p, target(reference)); + expect(run.failed).toBeNull(); + expect(run.fallback?.steps.map((x) => x.op)).toEqual(['VOID', 'MIT_CHARGE']); + expect(run.fallback?.releasedMinor).toBe(c.deposit); + expect(run.completed.map((r) => r.step.op)).toEqual(['VOID', 'MIT_CHARGE']); + const moves = () => + s.stack.psp.movements().map((m) => [m.operation, m.amountMinor, m.legs?.HOST]); + expect(moves()).toEqual([['MIT_CHARGE', c.fuel, c.fuel]]); + // rejeu de la même tentative : mêmes clés ⇒ aucun nouveau mouvement + const again = await s.executor.execute(s.ref, p, target(reference)); + expect(again.failed).toBeNull(); + expect(moves()).toEqual([['MIT_CHARGE', c.fuel, c.fuel]]); + }); + + it('capture rendue FAILED (statut) ⇒ même repli, aucun VOID partiel du reste', async () => { + const s = setup(c); + const reference = await authorized(c, s); + const p = plan(c, new CapabilitySet(s.stack.capabilities)); + const run = await captureReturning(s, 'FAILED').execute(s.ref, p, target(reference)); + expect(run.failed).toBeNull(); + expect(run.completed.map((r) => r.step.op)).toEqual(['VOID', 'MIT_CHARGE']); + expect(s.stack.psp.movements().map((m) => [m.operation, m.amountMinor])).toEqual([ + ['MIT_CHARGE', c.fuel], + ]); + }); + + it.each(['PENDING', 'SUBMITTED', 'UNKNOWN'] as const)( + 'capture rendue %s ⇒ arrêt : ni VOID ni MIT, lecture de l’état exigée avant tout rejeu', + async (status) => { + const s = setup(c); + const reference = await authorized(c, s); + const p = plan(c, new CapabilitySet(s.stack.capabilities)); + const run = await captureReturning(s, status).execute(s.ref, p, target(reference)); + expect(run.failed).toMatchObject({ status, needsLookup: true, error: null }); + expect(run.failed?.step.op).toBe('CAPTURE'); + expect(run.completed).toEqual([]); + expect(run.fallback).toBeNull(); + expect([s.stack.psp.calls('VOID'), s.stack.psp.calls('MIT_CHARGE')]).toEqual([0, 0]); + expect(s.stack.psp.movements()).toEqual([]); + }, + ); + + it('capture en issue inconnue (réponse perdue après succès) ⇒ arrêt sans VOID ; rejeu avec les mêmes clés ⇒ une seule capture, puis VOID du reste', async () => { + const s = setup(c, { + scenario: { responses: { CAPTURE: [{ kind: 'TIMEOUT_AFTER_SUCCESS' }] } }, + }); + const reference = await authorized(c, s); + const p = plan(c, new CapabilitySet(s.stack.capabilities)); + const run = await s.executor.execute(s.ref, p, target(reference)); + expect(run.failed?.needsLookup).toBe(true); + expect(isPaymentError(run.failed?.error, 'UNKNOWN_OUTCOME')).toBe(true); + expect(s.stack.psp.calls('VOID')).toBe(0); + const again = await s.executor.execute(s.ref, p, target(reference)); + expect(again.failed).toBeNull(); + expect(again.completed.map((r) => r.step.op)).toEqual(['CAPTURE', 'VOID']); + expect(s.stack.psp.movements().map((m) => [m.operation, m.amountMinor])).toEqual([ + ['CAPTURE', c.fuel], + ]); + }); + }, +); diff --git a/apps/api/src/modules/pay/testing/fake-payment-provider.test.ts b/apps/api/src/modules/pay/testing/fake-payment-provider.test.ts index e17c8b6c0..df45f7776 100644 --- a/apps/api/src/modules/pay/testing/fake-payment-provider.test.ts +++ b/apps/api/src/modules/pay/testing/fake-payment-provider.test.ts @@ -178,7 +178,10 @@ describe.each(PAIRS)('FAKE hostile — $capture.currency', (pair) => { expect(types).toEqual(['order.created', 'order.expired']); }); - it('pré-autorisation : capture partielle aux jambes réglées (08 E7 règle 2), VOID du reste interdit après capture', async () => { + // US-225 : ce test exigeait un refus du VOID après une capture partielle ; 08 E3 (repli 1 : + // « capture partielle de need, puis VOID du reste ») et T57 (capture 12,00, VOID 288,00) le + // demandent : le VOID libère le reste, une seconde capture est alors refusée (ADR-164) + it('pré-autorisation : capture partielle aux jambes réglées (08 E7 règle 2), puis VOID du reste (08 E3 repli 1)', async () => { const retained = pair.capture.currency === legVector(set, 'TJ03').currency ? legVector(set, 'TJ03') : null; const { stack } = harness(pair); @@ -200,10 +203,19 @@ describe.each(PAIRS)('FAKE hostile — $capture.currency', (pair) => { legs: legsOf(retained), }); expect(cap.status).toBe('SUCCEEDED'); + const voided = await stack.provider.void({ + idempotencyKey: 'A:1:v1:VOID:card:i1:a1', + providerReference: auth.providerReference, + }); + expect(voided.status).toBe('SUCCEEDED'); + // reste libéré : plus aucune capture possible sur cette autorisation await expectCode( - stack.provider.void({ - idempotencyKey: 'A:1:v1:VOID:card:i1:a1', + stack.provider.capture({ + idempotencyKey: 'A:1:v1:CAPTURE:card:i2:a1', + currency, providerReference: auth.providerReference, + amountMinor: 1n, + legs: { HOST: 1n, INSURER: 0n, TAX_THIRD_PARTY: 0n, PLATFORM: 0n }, }), 'INVALID_REQUEST', ); diff --git a/apps/web/app/proto/copy/en.ts b/apps/web/app/proto/copy/en.ts index 2399cf02a..7278e5f32 100644 --- a/apps/web/app/proto/copy/en.ts +++ b/apps/web/app/proto/copy/en.ts @@ -83,11 +83,6 @@ export const EN_PROTO = { "You'll need a valid driver's license, a passport or ID card, and a selfie. It takes about 3 minutes.", 'web.s03.kyc.90days': 'You can drive with your foreign license until {date_limit}. Your rental ends on {date_end}.', - 'web.deposit.unavailable': { - one: "We can't place the deposit on your card for these dates. You can book up to {count} day.", - other: - "We can't place the deposit on your card for these dates. You can book up to {count} days.", - }, 'web.s04.status.question': "What's your status in {country}?", 'web.s04.status.tourist': 'You entered {country} less than 90 days ago with a passport', 'web.s04.status.resident': 'You have a {country} ID document', diff --git a/apps/web/app/proto/copy/es.ts b/apps/web/app/proto/copy/es.ts index 6423cc5be..424f7d345 100644 --- a/apps/web/app/proto/copy/es.ts +++ b/apps/web/app/proto/copy/es.ts @@ -94,11 +94,6 @@ export const ES_PROTO = { 'Necesitarás: licencia vigente, pasaporte o cédula y una selfie. Tarda unos 3 minutos.', 'web.s03.kyc.90days': 'Puedes manejar con tu licencia extranjera hasta el {date_limit}. Tu alquiler termina el {date_end}.', - 'web.deposit.unavailable': { - one: 'Para estas fechas no podemos tomar el depósito en tu tarjeta. Puedes reservar hasta {count} día.', - other: - 'Para estas fechas no podemos tomar el depósito en tu tarjeta. Puedes reservar hasta {count} días.', - }, 'web.s04.status.question': '¿Cuál es tu situación en {country}?', 'web.s04.status.tourist': 'Entraste a {country} hace menos de 90 días con pasaporte', 'web.s04.status.resident': 'Tienes un documento de identidad de {country}', diff --git a/apps/web/app/proto/copy/fr.ts b/apps/web/app/proto/copy/fr.ts index 374bc713c..55093fe60 100644 --- a/apps/web/app/proto/copy/fr.ts +++ b/apps/web/app/proto/copy/fr.ts @@ -90,11 +90,6 @@ export const FR_PROTO = { 'Il te faudra : un permis de conduire valide, un passeport ou une carte d’identité, et un selfie. Compte environ 3 minutes.', 'web.s03.kyc.90days': 'Tu peux conduire avec ton permis étranger jusqu’au {date_limit}. Ta location se termine le {date_end}.', - 'web.deposit.unavailable': { - one: 'Pour ces dates, nous ne pouvons pas bloquer le dépôt sur ta carte. Tu peux réserver jusqu’à {count} jour.', - other: - 'Pour ces dates, nous ne pouvons pas bloquer le dépôt sur ta carte. Tu peux réserver jusqu’à {count} jours.', - }, 'web.s04.status.question': 'Quelle est ta situation au {country} ?', 'web.s04.status.tourist': 'Tu es au {country} depuis moins de 90 jours, avec un passeport', 'web.s04.status.resident': 'Tu as une pièce d’identité du {country}', diff --git a/apps/web/app/proto/copy/pt.ts b/apps/web/app/proto/copy/pt.ts index 8f23a733b..33eb46654 100644 --- a/apps/web/app/proto/copy/pt.ts +++ b/apps/web/app/proto/copy/pt.ts @@ -87,11 +87,6 @@ export const PT_PROTO = { 'Você vai precisar de: carteira de motorista válida, passaporte ou documento de identidade e uma selfie. Leva uns 3 minutos.', 'web.s03.kyc.90days': 'Você pode dirigir com sua carteira estrangeira até {date_limit}. Seu aluguel termina em {date_end}.', - 'web.deposit.unavailable': { - one: 'Para essas datas não conseguimos bloquear a caução no seu cartão. Você pode reservar até {count} dia.', - other: - 'Para essas datas não conseguimos bloquear a caução no seu cartão. Você pode reservar até {count} dias.', - }, 'web.s04.status.question': 'Qual é a sua situação como visitante ou morador ({country})?', 'web.s04.status.tourist': 'Você entrou no território ({country}) há menos de 90 dias com passaporte', diff --git a/changelog.d/US-225-caution.md b/changelog.d/US-225-caution.md new file mode 100644 index 000000000..b9d1cd499 --- /dev/null +++ b/changelog.d/US-225-caution.md @@ -0,0 +1,10 @@ +lot: L2 +module: Paiements + +- Ajouté : paramètres des déclencheurs de la caution « comme Turo » par pays, aucune caution par défaut (pays faux, classe LUXE seulement, aucune classe pour l'âge, contrôle de risque non déployé), avec l'avance de ré-autorisation et le délai de notification des frais (migration 0142, US-225, ADR-164) +- Ajouté : décision de la caution au checkout avant tout paiement — sans déclencheur aucun rail n'est évalué ; caution exigée sans montant refusée (`PARAM_MISSING`) ; aucun rail valide refusé avec le nombre de jours possibles (`DEPOSIT_RAIL_UNAVAILABLE`) ; rail choisi par configuration, « débit puis remboursement » fermé tant que la détention de fonds est fermée (US-225) +- Ajouté : décision de libération de la caution avec des commandes au montant explicite — capture des frais puis annulation du reste (T57), annulation puis débit séparé sans capture partielle (T58) — et exécution par le port de paiement, sur le PSP simulé seulement ; ré-autorisation refusée signalée à l'ops sans débit (US-225) +- Ajouté : textes du refus de la caution avant le paiement en espagnol, anglais, français et portugais du Brésil (catalogue v82, US-225) +- Modifié : le PSP simulé accepte l'annulation du reste d'une autorisation après une capture partielle (08 E3, US-225) +- Corrigé : l'exécution de la décision de caution s'arrête à toute commande qui n'aboutit pas ; une capture refusée bascule sur l'annulation de la caution entière puis le débit séparé des frais, une capture en cours ou d'issue inconnue n'envoie jamais l'annulation du reste (revues de la PR, US-225) +- Corrigé : la part de l'hôte d'un frais annexe scindé au plafond de la caution est arrondie une fois sur la ligne entière (US-225) diff --git a/docs/adr/ADR-164-rails-de-la-caution.md b/docs/adr/ADR-164-rails-de-la-caution.md new file mode 100644 index 000000000..df76fa98d --- /dev/null +++ b/docs/adr/ADR-164-rails-de-la-caution.md @@ -0,0 +1,31 @@ +# ADR-164 — Rails de la caution : décision avant le paiement, rail choisi par configuration, exécution sur le port + +- **Statut** : PROPOSÉ (US-225, agent de story back-end, claude-opus-5-5, 2026-11-18). Revues exigées : celles de `node scripts/ci/check-story-reviews.mjs` ; argent et concurrence sur un autre modèle que l'auteur. À reporter par une PR revue de `docs/specs/` : 17 §7.2 (`deposit_reauth_lead_h`, `deposit_fee_notice_h`, `risk_control_deployed`), 08 E4 (clés `deposit:`), 17 §2.8 (pose sans le voyageur, suite S-1). +- **Complète** : ADR-108 (caution conditionnelle « comme Turo »), ADR-016 (17 §9), ADR-139 et ADR-145 (montants explicites par jambe), ADR-159 (classe de valeur qui déclenche la caution `LUXE`). +- **Sources** : 08 BR-PAY-06 (« Caution conditionnelle », « Fail-closed », « Montant unique », « Moment de l'évaluation », « Mécanisme », « Libération à heure fixe », « Débit puis remboursement », « Jambes des frais annexes »), E3 (« Capacités d'autorisation », replis 1 à 4), vecteurs T57, T58, T59, T69–T73 ; 16 fiche PAY-011 / PAY-012 / PAY-036 ; 17 §0.1, §2.8, §3.2.7 (`deposit_hold`), §7.2 ; 19 US-225 ; oracle `docs/specs/tools/check_t49plus.py`. + +## Contexte + +ADR-108 a posé la règle (aucune caution par défaut, déclencheurs par pays, fail-closed « prendre la caution, jamais l'omettre »), sans code. US-701 (caution, `deposit_hold`, écriture au checkout) n'est pas commencée ; US-225 porte les rails : faisabilité avant le paiement, ré-autorisation, débit puis remboursement, refus. Les six paramètres de déclencheur n'étaient pas dans le registre (N-155). Le port `PaymentProvider` a déjà `createHostedPayment(MANUAL)`, `capture`, `void`, `reauthorize`, `refund`, `chargeMIT` ; le PSP simulé refusait un `VOID` après une capture partielle, alors que 08 E3 (repli 1) et T57 le demandent. + +## Décision + +1. **Paramètres** (graine générée `0142`, valeurs PROPOSÉES identiques au PA et au PY, `failMode` BLOCK, portée pays) : `deposit_always_required` = faux, `deposit_trigger_classes` = {LUXE} (À DÉCIDER : le fondateur hésite pour le luxe), `deposit_young_driver_age` = 30, `deposit_young_driver_classes` = {} (DEC-FONDATEUR-21), `deposit_on_risk_flag` = vrai, `risk_control_deployed` = faux, plus `deposit_reauth_lead_h` = 24 (08 : « auth_expiry − 24 h ») et `deposit_fee_notice_h` = 48 (08 : frais notifié au moins 48 h avant la décision). Nouvelle unité JSON `value_class_set` (ensemble ordonné, vide permis). Le générateur de graines accepte un groupe de clés nommées (`extraKeys`) : les noms de 17 §7.2 n'ont pas de préfixe commun. Aucun interrupteur touché. +2. **Décision du checkout, avant tout paiement** (`decideDepositGate`, fonction pure) : déclencheurs (oracle `deposit_required`) ; aucun vrai ⇒ `NOT_REQUIRED`, **aucun rail évalué**, aucune `H_requise` (T70) ; caution exigée sans `deposit_amount[pays][classe]` ou sans paramètre de durée ⇒ `PARAM_MISSING` (T72 c) ; sinon rail, ou `DEPOSIT_RAIL_UNAVAILABLE` avec le nombre de **jours entiers** possibles (`web.deposit.unavailable`, T59). Triggers et âge restent [C2]. +3. **Rail choisi par configuration**, dans l'ordre de BR-PAY-06 : `V` = min(`MAX_HOLD_HOURS` validée, `provider_max_hold_h`), 0 sans `SUPPORTS_PREAUTH` validée (même grandeur en deux sources : la plus prudente) ; pré-autorisation unique si `H_requise` (minutes, arrondie au-dessus ; `auth_at` = max(réservation, départ − `auth_lead_h`)) ≤ `V` ; (a) ré-autorisation si `SUPPORTS_REAUTH` validée et `V` > `deposit_reauth_lead_h` ; (b) débit puis remboursement si `funds_holding_enabled[pays]`, `deposit_charge_cap` ≥ montant (inconnu ⇒ 0) et `SUPPORTS_REFUND` validée ; sinon refus. Aucune branche par PSP ou par pays. +4. **Décision de la caution** (`planDepositDecision`) : frais capturables = prouvés, non contestés, notifiés ≥ `deposit_fee_notice_h` avant `decision_at`, pris dans l'ordre et plafonnés au montant ; capture (partielle si `SUPPORTS_PARTIAL_CAPTURE`, totale toujours permise) puis `VOID` du reste (T57) ; sans capture partielle : `VOID` total puis MIT `DELAYED_CHARGES` (T58) ; sans `VOID` : l'autorisation expire seule (repli 4) ; sans MIT : dette, jamais prise sur la caution. Rail (b) : **remboursement total** à la décision puis MIT des frais (branche « sinon remboursement total » de BR-PAY-06 : aucune retenue sur des fonds détenus). Jambes d'une part de frais : `allocHost` par ligne, la plateforme prend le complément ; la pose porte le montant entier sur `PLATFORM` (compte marchand de Kmino : la caution n'est pas une jambe). +5. **Exécution** (`DepositRailExecutor`, port seulement, FAKE jusqu'au lot C) : clés `deposit:{deposit_id}:{AUTH|CHARGE|REAUTH|CAPTURE|VOID|REFUND|MIT_CHARGE}:i{n}:a{m}` ; arrêt à la première étape en échec, rejeu avec les mêmes clés ; ré-autorisation refusée ou non validée ⇒ `DEPOSIT_REAUTH_FAILED` pour l'ops, **aucun débit** ; « débit puis remboursement » refusé sans appel si `funds_holding_enabled` = faux. +6. **Machine d'état** de `deposit_hold.status` : `PLANNED → AUTHORIZED → PARTIALLY_CAPTURED | VOIDED | REFUNDED | EXPIRED` ; ré-autorisation (acceptée ou refusée) et refus d'autorisation sans changement d'état ; états finaux sans sortie. +7. **PSP simulé** : `VOID` permis après une capture partielle (libère le reste), refusé après une capture totale. + +## Options écartées + +- Évaluer les rails sans déclencheur (caution systématique) : contraire à ADR-108 et à T70. +- Rail (b) avec retenue partielle sur le débit : demande une réaffectation de jambes sur des fonds détenus ; inutile tant que le rail est fermé ; reportée (suite S-3). +- Rail choisi par le nom du PSP : interdit (19 US-225, notes techniques). + +## Conséquences + +- Au PA et au PY aujourd'hui : un trip STANDARD ou PREMIUM n'a aucune caution ; un trip LUXE est refusé avant le paiement (`PARAM_MISSING`) tant que `deposit_amount` n'est pas fixé, puis `DEPOSIT_RAIL_UNAVAILABLE` tant que la validité du PSP n'est pas validée. C'est le fail-closed voulu ; aucun fonds n'est jamais bloqué faute de rail. +- Preuves : `apps/api/src/modules/pay/internal/deposit-triggers.test.ts`, `deposit-rails.test.ts` (T57–T59, T69–T73, chaque devise), `testing/deposit-rails.fake.test.ts` (FAKE), `testing/deposit-rail-config.int.test.ts` (PostgreSQL, `app_api`, PA et PY), `packages/db/test/l0/l0-us225-deposit-rails.test.ts`. +- **Suites** : S-1 pose à `auth_at` sans le voyageur (autorisation sur la carte enregistrée : méthode absente du port, à valider avec le PSP, lot C) ; S-2 `deposit_hold`, écriture au checkout, appel de `decideDepositGate` dans le parcours S05 et minuteries de ré-autorisation et de décision (US-701, US-702) ; S-3 retenue partielle sur le rail (b) ; S-4 taxes éventuelles d'un frais annexe (jambe `TAX_THIRD_PARTY`) ; S-5 report des clés et paramètres nouveaux dans 08 E4 et 17 §7.2. diff --git a/docs/architecture/schema.md b/docs/architecture/schema.md index 50cab9d16..ba7762c0b 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 -- 142 migrations ; 127 tables ; 3 vues ; 714 politiques RLS ; 285 fonctions `SECURITY DEFINER` ; 249 autres fonctions. +- 143 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. @@ -157,6 +157,7 @@ Lu dans le catalogue (`pg_catalog`) d'une base jetable du banc, après les seule | `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 | +| `0142_config_deposit_rail_params` | graine complémentaire : paramètres « deposit_always_required* » (US-225 ; 17 §7.2). | ## Rôles diff --git a/docs/ops/GO_LIVE_CHECKLIST.md b/docs/ops/GO_LIVE_CHECKLIST.md index ce71dd9b0..43bfa6e76 100644 --- a/docs/ops/GO_LIVE_CHECKLIST.md +++ b/docs/ops/GO_LIVE_CHECKLIST.md @@ -68,6 +68,7 @@ | 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`) | +| GL-41 | **Caution « comme Turo » prête avant l'ouverture d'un pays** (US-225, ADR-108, ADR-164 ; 08 BR-PAY-06). **Existe** (bêta, fonctions pures et FAKE) : aucune caution par défaut (graine 0142 : `deposit_always_required` faux, `deposit_trigger_classes` = {LUXE}, aucune classe pour l'âge, `risk_control_deployed` faux) ; décision du checkout avant le paiement (`PARAM_MISSING`, `DEPOSIT_RAIL_UNAVAILABLE` avec les jours possibles) ; rail choisi par configuration ; « débit puis remboursement » fermé par `funds_holding_enabled`. **À faire** : (1) `deposit_amount[pays][LUXE]` fixé et `deposit_trigger_classes` confirmé par le fondateur (sinon tout trip LUXE est refusé avant le paiement) ; (2) `provider_max_hold_h`, `MAX_HOLD_HOURS`, `SUPPORTS_PREAUTH`, `SUPPORTS_VOID`, `SUPPORTS_PARTIAL_CAPTURE`, `deposit_safety_h` validés en bac à sable (OQ-PAY-02 ; `SUPPORTS_REAUTH` OQ-PAY-17) ; (3) `deposit_hold`, écriture au checkout, minuteries de ré-autorisation et de décision, écran S05 (US-701, US-702) ; (4) pose à `auth_at` sans le voyageur validée avec le PSP | `l0-us225-deposit-rails.test.ts` et `deposit-rail-config.int.test.ts` verts au SHA déployé ; valeurs relues dans `core.config_param_value` et `core.payment_psp_capability` | fondateur (montants), US-701, US-702, lot C (PSP) | | | # | 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 cfd4eda63..f7806140c 100644 --- a/docs/team/COMME_TURO.md +++ b/docs/team/COMME_TURO.md @@ -214,3 +214,5 @@ Règles : | 2026-11-18 | US-212 | Comment prouver une location entre particuliers lors d'un contrôle, ou pour une amende reçue après le trip ? | un justificatif de location téléchargeable par le voyageur et l'hôte (voiture, plaque, période, parties) depuis le trip ; l'hôte retrouve le trip d'une amende par sa voiture et sa date ; les amendes du trip incombent au voyageur | aide publique de Turo (justificatif de location, amendes et péages) ; 08 BR-TT-03 | constancia tirée du contrat figé (jamais recalculée), es + langue du lecteur, rendue à la demande sans stockage ; recherche par plaque et date jusqu'au lendemain de la fin (BR-TT-03) | PROPOSÉ | | 2026-11-18 | US-212 | Que dit-on du rôle de la plateforme ? | place de marché qui met en relation hôtes et voyageurs, ni loueur ni propriétaire des voitures ; contrat entre l'hôte et le voyageur ; protection fournie par l'assureur partenaire | conditions publiques de Turo (rôle de place de marché) ; 16 LEG-014 | centre juridique `/legal`, mention répétée dans la constancia et le contrat ; marchand de référence pour le paiement | PROPOSÉ | | 2026-11-18 | US-212 | Comment se règle un désaccord entre l'hôte et le voyageur ? | les parties échangent d'abord par la messagerie ; à défaut, le support examine le cas avec les deux parties et tranche (médiation) ; les recours légaux restent ouverts | aide publique de Turo (litiges entre hôte et voyageur) ; 16 LEG-015 | messagerie, support avec le numéro du trip et médiation, puis protection du consommateur ou tribunaux du lieu du trip ; aucune clause « definitiva e inapelable » ni arbitrage obligatoire (OQ-BR-24) | PROPOSÉ | +| 2026-11-18 | US-225 | Si la durée du trip dépasse la validité d'une pré-autorisation, que fait-on de la caution ? | la caution n'existe que pour certains trips ; elle est affichée au checkout avant la réservation, puis rendue automatiquement après le trip ; les frais constatés ensuite sont débités sur la carte enregistrée | 08 BR-PAY-06 (pages d'aide de Turo sur les cautions, relues pour ADR-108) ; 10b UX-24 | aucune caution sans déclencheur : un trip sans caution n'est jamais refusé pour sa durée ; avec caution, ré-autorisation si le PSP la valide, sinon « débit puis remboursement » seulement si la détention de fonds est ouverte, sinon refus **avant le paiement** avec le nombre de jours possibles ; jamais de fonds bloqués faute de rail (ADR-164) | PROPOSÉ | +| 2026-11-18 | US-225 | À la libération, comment prend-on les frais annexes sur la caution ? | la caution est rendue automatiquement ; les frais après le trip passent par la carte enregistrée | 08 BR-PAY-06 « Libération à heure fixe », E3 ; T57, T58 | frais prouvés, non contestés et notifiés au moins 48 h avant la décision capturés sur la caution (dans sa limite) puis le reste libéré ; sans capture partielle : caution entièrement libérée puis débit séparé ; « débit puis remboursement » : remboursement total puis débit séparé des frais (aucune retenue sur des fonds détenus) (ADR-164) | PROPOSÉ | diff --git a/docs/team/POUR_LE_FONDATEUR.md b/docs/team/POUR_LE_FONDATEUR.md index 46113ffe7..a0deec3f5 100644 --- a/docs/team/POUR_LE_FONDATEUR.md +++ b/docs/team/POUR_LE_FONDATEUR.md @@ -100,6 +100,7 @@ Je te présenterai une liste unique ; pour chaque réglage, ma valeur suggérée | Préavis de réservation par défaut | 3 h | Turo ne publie pas de valeur par défaut (page d'aide relue le 2026-11-13) : on garde 3 h ; chaque hôte la change par lieu (ADR-115) | | Pièces du véhicule, revue de l'hôte et des annonces, RUC à l'inscription | désactivés (règle « jamais plus lourd que Turo ») | **Les laisser désactivés** ; ne les activer que si l'assureur, le PSP ou la loi l'impose | | Caution des véhicules de luxe et montant | caution pour la classe LUXE (PROPOSÉ), montant à décider | Aucune caution au lancement ; à réactiver par pays si les sinistres l'exigent | +| Caution : ce qui se passe tant que le montant n'est pas fixé, et durée maximale d'un trip avec caution (US-225, ADR-164) | aucune caution sans déclencheur (tous les véhicules sauf LUXE) ; une voiture LUXE est **refusée avant le paiement** tant que `deposit_amount` n'est pas fixé, puis tant que le PSP n'a pas validé la durée d'un blocage sur carte (7 jours chez la plupart : trips LUXE de 3 jours maximum, plus longs si le PSP sait renouveler le blocage) ; jamais de débit puis remboursement tant que la détention de fonds est fermée | comme Turo, le moins de limitations possible : soit retirer LUXE de la liste (aucune caution au lancement, ta suggestion), soit fixer un montant LUXE ; demander au PSP retenu la durée de blocage et s'il peut renouveler un blocage et bloquer sur la carte enregistrée sans le voyageur | | Délai uniforme avant approbation automatique d'un hôte | 24 h | 24 h, comparable à Turo ; il protège la discrétion des contrôles de sanctions | | Classe de valeur d'un véhicule non classé (douane, hors catalogue ; détail §2.3 sexies ; N-83, ADR-159) | classe attribuée à la publication : celle du catalogue, sinon une règle de marque ou de modèle (Porsche, Ferrari, Range Rover, Land Cruiser… en luxe ; Mercedes, BMW, Audi, Lexus, Land Rover, Volvo… en premium), sinon **Standard** par défaut dans chaque pays (PROPOSÉ) ; sans contrat d'assureur, aucune annonce n'est publiable | **Comme Turo, le moins de limitations possible** : Standard par défaut, classes hautes seulement pour les marques et modèles chers, jamais une voiture chère rangée en Standard. À faire confirmer par l'assureur : classes couvertes par le contrat et cette liste de marques et de modèles (**bloquant avant ouverture**, GL-35) | | Conservation des données (US-111) | demandes d'accès 10 jours ; preuves de paiement 15 mois (plancher) ; engagements de l'hôte 60 mois ; 4 durées sans valeur au Paraguay | Valider avec l'avocat ; aligner le Paraguay sur le Panama | diff --git a/docs/team/handoffs/US-225.md b/docs/team/handoffs/US-225.md new file mode 100644 index 000000000..522e9f889 --- /dev/null +++ b/docs/team/handoffs/US-225.md @@ -0,0 +1,42 @@ +# Passation US-225 — Caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus + +- **Branche** : `story/US-225-caution` ; agent de story back-end, claude-opus-5-5 ; ADR-164 (PROPOSÉ). +- **Numéros pris** : migration `0142_config_deposit_rail_params` (générée ; 0138 à 0141 prises par US-212, US-224e et US-224f), fixture `9943_test_us225_deposit_rail_fixtures.sql`, catalogue **v82**, ADR-164, GL-41. + +## Livré (partie serveur, sans écran ni travailleur) + +1. **Paramètres** (graine 0142, PA et PY, PROPOSÉS, `failMode` BLOCK) : `deposit_always_required` faux, `deposit_trigger_classes` {LUXE} (À DÉCIDER), `deposit_young_driver_age` 30, `deposit_young_driver_classes` {} (DEC-FONDATEUR-21), `deposit_on_risk_flag` vrai, `risk_control_deployed` faux, `deposit_reauth_lead_h` 24, `deposit_fee_notice_h` 48 ⇒ **aucune caution par défaut**. Ferme N-155 (paramètres de déclencheur). Générateur : groupes à clés nommées (`extraKeys`) ; unité JSON `value_class_set`. +2. **PAY** (`internal/deposit-triggers.ts`, `deposit-rails.ts`, `deposit-executor.ts`, `pg-deposit-config.ts`, exportés par `index.ts`) : déclencheurs (oracle `deposit_required`, T69–T73) ; `decideDepositGate` au checkout avant le paiement (`NOT_REQUIRED` sans aucun rail évalué, `PARAM_MISSING`, `DEPOSIT_RAIL_UNAVAILABLE` + jours possibles) ; rail par configuration ; échéancier ; `planDepositDecision` (T57, T58) ; machine d'état ; exécutant sur le port (FAKE) ; lecteur de configuration (`app_api` / `app_worker`). +3. **Textes** `web.deposit.unavailable` (10b UX-24) et `web.deposit.unavailableNone` (PROPOSÉ) en es, en, fr, pt-BR. +4. **PSP simulé** : `VOID` permis après capture partielle (08 E3 repli 1, T57). + +## Critères de 19 + +| Critère | Preuve | +| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| T59 + `SUPPORTS_REAUTH` non validée ⇒ `DEPOSIT_RAIL_UNAVAILABLE` avant le paiement, 4 langues | `deposit-rails.test.ts`, `deposit-rail-config.int.test.ts` ; textes v82. **Affichage dans S05 : suite (US-701)** | +| T70 STANDARD ⇒ aucun rail évalué | idem + L0 | +| Ré-autorisation demandée avant l'échéance ; refusée ⇒ ops, sans débit | `depositReauthDueAt` ; `deposit-rails.fake.test.ts` (`DEPOSIT_REAUTH_FAILED`, 0 MIT). **Minuterie : suite** | +| Rail (b) plafonné, `funds_holding_enabled` = false ⇒ fermé, refus avant le paiement | pur, FAKE (refus sans appel), int sous `app_api` | +| T58 ⇒ VOID 300,00 puis MIT 12,00 | pur + FAKE, USD et PYG | + +## Test existant modifié (justification ligne à ligne) + +`apps/api/src/modules/pay/testing/fake-payment-provider.test.ts`, cas « pré-autorisation : capture partielle… » : il exigeait `INVALID_REQUEST` pour un `VOID` après capture partielle. 08 E3 repli 1 (« capture partielle de need, puis VOID du reste ») et T57 (VOID 288,00) exigent l'inverse. Remplacé par : VOID du reste `SUCCEEDED`, puis une seconde capture refusée (`INVALID_REQUEST`). Un VOID après capture **totale** reste refusé (`packages/fake-adapters/test/psp/fake-psp.test.ts`). Pas un test de sécurité. `seed-sql.test.ts` et `defaults.test.ts` : extension au groupe à clés nommées et à `deposit_trigger_classes` (À DÉCIDER). + +## Décisions PROPOSÉ + +COMME_TURO (deux lignes US-225) ; ADR-164 : V = min(capacité, paramètre) ; rail (b) = remboursement total puis MIT ; pose sur `PLATFORM` ; clés `deposit:` ; jours possibles affichés en jours entiers. POUR_LE_FONDATEUR §3 : montant LUXE ou retrait de LUXE ; questions au PSP. + +## Suites (pour l'orchestrateur) + +- **S-1** pose à `auth_at` sans le voyageur (autorisation sur carte enregistrée : absente du port 17 §2.8 ; lot C, PSP). +- **S-2** (US-701 / US-702) : table `deposit_hold`, appel de `decideDepositGate` dans `booking_cmd_checkout_pay` / S05 et affichage des textes v82, minuteries de ré-autorisation et de décision, signal ops `DEPOSIT_REAUTH_FAILED`. +- **S-3** retenue partielle sur le rail (b) ; **S-4** taxe d'un frais annexe (`TAX_THIRD_PARTY`) ; **S-5** report dans 08 E4 et 17 §7.2 (`deposit_reauth_lead_h`, `deposit_fee_notice_h`, `risk_control_deployed`, clés `deposit:`, unité `value_class_set`). +- BOARD : N-155 faite ; N-89 en partie (paramètres ; `catalog_deposit_policy.amount_minor` toujours à contracter par US-701). + +## Après les revues de la tête 94177336 (argent, code, qa : CHANGEMENTS DEMANDÉS) + +- **Corrigé (MAJEUR)** `deposit-executor.ts` : `execute` s'arrête sur toute exception ET tout statut autre que `SUCCEEDED` ; `PENDING` / `SUBMITTED` / `UNKNOWN` / `UNKNOWN_OUTCOME` ⇒ `needsLookup` (lire `getOperation` avant le rejeu, mêmes clés) ; capture refusée (`DECLINED` ou `FAILED`) ⇒ repli `fallbackAfterCaptureFailure` (08 E3 repli 2 : VOID de la caution entière puis MIT de tous les frais, clés `i2`). Tests FAKE : refus, `FAILED`, `PENDING` / `SUBMITTED` / `UNKNOWN`, issue inconnue puis rejeu, aucun second mouvement. +- **Corrigé (mineur)** : part HOST d'un frais scindé au plafond arrondie une fois sur la ligne entière ; changelog (catalogue, aujourd’hui v82). +- **Suites ajoutées** : S-6 clés `deposit:` à aligner sur 08 E4 (ou 08 E4 à compléter) ; S-7 vue voyageur de `deposit_hold` sans champs [C2] (`triggers`, `params_snapshot`) à livrer avec la table (US-701) ; S-8 `web.deposit.unavailableNone` à brancher dans S05 (cas « 0 jour possible »). diff --git a/docs/team/reviews/US-225/architecture-2026-11-18.md b/docs/team/reviews/US-225/architecture-2026-11-18.md new file mode 100644 index 000000000..fa3ef7dc1 --- /dev/null +++ b/docs/team/reviews/US-225/architecture-2026-11-18.md @@ -0,0 +1,22 @@ +# Revue architecture — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236) — 2026-11-18 + +Relecteur : revue-architecture / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..941773363062e6afe1aefcd2b758a2cf8707c892 + +Contexte : tête 94177336 (CI 17/17 verte) ; lu : CLAUDE.md, ADR-164 et ADR-108, 08 BR-PAY-06 / E3 / E4, 17 §0.1 / §2.8 / §3.2.7, US-225 dans 19, passation. Base : `main` à b9dec048 ; la branche est fusionnée avec #234 et #235 ; entre le point de fusion 46ca6a54 et `main`, seuls `BOARD.md` et la migration 0140 (déjà dans la branche) ont bougé : pas de conflit attendu. + +| # | Gravité | Constat | +| --- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Frontières : PAY ne dépend que de ses propres fichiers, de `@rueda/money` et du port ; il lit la configuration par SQL (`core.config_param_value`, `core.config_go_live`, `core.payment_psp_capability`) comme les autres lecteurs de PAY (`PgDepositRailConfigReader`), sans importer l'intérieur de CFG ; CFG ne reçoit que de nouvelles clés (`params.json`) et l'unité `value_class_set` (`model.ts`, `parse.ts`). Exports par `pay/index.ts` seulement. | +| 2 | INFO | Conformité au modèle « comme Turo » : défaut « aucune caution » (déclencheurs ciblés, LUXE À DÉCIDER, âge vide, risque non déployé), décision au checkout avant le paiement, rail par configuration (`psp_capability`, `provider_max_hold_h`, `deposit_charge_cap`, `funds_holding_enabled`) et jamais par PSP ou pays, rail du comptoir absent, aucun interrupteur de mise en service écrit ou lu en écriture. | +| 3 | INFO | Numérotation : 0141 contiguë avec `main` (0140), fixture 9943, catalogue v79 (main : 78), ADR-164, GL-41 ; migration générée par `seed-sql.ts` (`extraKeys`, `inPostSeedGroup` cohérents avec `isPostSeedParam` ; 0009 reste immuable et rendue sans ces clés, ADR-044 / ADR-075). `schema.md` édité à la main : cohérent (142 migrations, ligne 0141 de la forme des voisines), test `schema-doc` vert en CI. | +| 4 | MINEUR | Écart avec 08 E4 : les clés `deposit:{id}:{op}:i{n}:a{m}` (`idempotency.ts:85-120`) remplacent le format de E4 (`{trip_id}:{segment_id}:v…:{DEPOSIT_CAPTURE, DEPOSIT_VOID…}`) et doublent `offSettlementRefundKey` (origine `DEPOSIT`) pour le remboursement du rail (b). Déclaré PROPOSÉ, report en suite S-5 (08 E4, 17 §7.2) : acceptable pour du code sans persistance, mais US-701 doit trancher et reporter dans `docs/specs/` (PR revue) avant d'écrire ces clés dans `payment_command`, sinon deux formats coexisteront pour une même opération. | +| 5 | MINEUR | `V` = min(capacité `MAX_HOLD_HOURS`, paramètre `provider_max_hold_h`) (`deposit-rails.ts:88-97`) : plus prudent que 08, qui ne lit que le paramètre ; deux sources pour une même grandeur à entretenir au lot C (US-601). Choix explicité par ADR-164 ; à reporter dans 17 §7.2 avec les nouvelles clés. | +| 6 | INFO | Périmètre de la story : partie serveur seulement (fonctions pures, exécutant FAKE, lecteur) ; table `deposit_hold`, appel de `decideDepositGate` dans le checkout, minuteries et affichage S05 renvoyés à US-701 / US-702, alors que 19 déclare US-701 comme dépendance de US-225 : découpage assumé et listé (S-1 à S-5 dans la passation et ADR-164). BOARD non modifié par la branche (N-155 faite, N-89 en partie, annoncés dans la passation) : à tenir par l'orchestrateur. Les critères 1 et 3 de US-225 ne sont complets qu'avec ces suites. | +| 7 | INFO | Jambe de la pose sur `PLATFORM` et jambes des frais par `allocHost` : choix PROPOSÉ, cohérent avec « la caution n'est pas une jambe » ; à valider avec le PSP de place de marché au lot C (capture à jambes différentes de l'autorisation). | +| 8 | INFO | Montant LUXE : tant que `deposit_amount` est absent, un trip LUXE est refusé avant le paiement (`PARAM_MISSING`) puis `DEPOSIT_RAIL_UNAVAILABLE` tant que la validité du PSP n'est pas validée : fail-closed voulu, documenté dans POUR_LE_FONDATEUR §3, GL-41 et l'ADR (conséquences) ; la décision (montant ou retrait de LUXE) est celle du fondateur. | +| 9 | INFO | Constat défaut d'exécutant (arrêt sur statut non `SUCCEEDED`) : traité par les revues code et argent comme MAJEUR ; sans incidence sur l'architecture, la correction reste dans `deposit-executor.ts`. | + +Aucun défaut majeur ni bloquant d'architecture. + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/architecture-2026-11-18b.md b/docs/team/reviews/US-225/architecture-2026-11-18b.md new file mode 100644 index 000000000..f0465fdec --- /dev/null +++ b/docs/team/reviews/US-225/architecture-2026-11-18b.md @@ -0,0 +1,18 @@ +# Revue architecture — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236), seconde passe — 2026-11-18 + +Relecteur : revue-architecture / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..0b7a8eb76c1460be5b7d8a381147840521a85a08 + +Contexte : tête 0b7a8eb7 de `story/US-225-caution` (CI verte) ; les revues de première passe (tête 94177336) sont périmées. Relu : `git diff cc016c91..0b7a8eb7` (correction 29f4796b, libellés 6abd5455, fusion de `main` #239 US-224f en 0b7a8eb7) et `git diff origin/main...0b7a8eb7`. Tests non réexécutés ici (CI de la tête). + +| # | Gravité | Constat | +| --- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Frontières respectées après correction : le repli est une fonction pure de `deposit-rails.ts` (`fallbackAfterCaptureFailure`), l'exécutant ne fait que l'appliquer par le port `PaymentProvider` (rang d'instance 2) ; aucun import interne d'un autre module, aucune constante de pays, aucune horloge. Le constat 9 de la première passe (la correction reste dans `deposit-executor.ts`) est confirmé ; `DepositExecution` gagne `fallback` et `DepositStepFailure` gagne `status` / `needsLookup`, additifs, sans appelant existant. | +| 2 | INFO | Conformité à 08 : repli de l'autorisation (E3, repli 2, T64 : VOID total puis MIT) étendu à la capture refusée de la caution, PROPOSÉ et dans la passation ; la phrase « même repli pour la caution » de 08 le permet sans le dire exactement : à reporter dans 08 / `COMME_TURO.md` par une PR revue (hors de cette story, `docs/specs/` intouché). Contrat d'idempotence (17 §4.3) : issue inconnue ⇒ lecture de l'état puis rejeu avec les mêmes clés. | +| 3 | INFO | Renumérotation : migration 0142 contiguë avec `main` (0141 = US-224f), fichier généré par `seed-sql.ts` (nom mis à jour), fixture 9943, ADR-164, GL-41 sans doublon avec GL-40 et GL-43 de `main`, README db et `country-data-allowlist.json` à jour ; catalogue **v82** accepté (`main` à v81 depuis US-224f, `CATALOG_VERSION` ne redescend pas ; passation et changelog disent v82) ; `schema.md` : 143 migrations, ligne 0142, compteurs de `main` conservés (aucune table ajoutée), test `schema-doc` vert. Conflits GO_LIVE, README db, catalogues résolus sans perte côté `main` (ADR-166 et GL-43 présents). | +| 4 | MINEUR | Toujours ouverts, déclarés : clés d'idempotence `deposit:{id}:…` différentes de 08 E4 (report S-5, à trancher avant que US-701 ne persiste) ; `V` = min(capacité, paramètre) plus prudent que 08 ; `reauthorize` ne signale pas `needsLookup` pour `PENDING` / `UNKNOWN`, à aligner sur `execute` avant US-702. | +| 5 | INFO | Découpage de la story (partie serveur ; US-701 / US-702 portent table, checkout, minuteries, S05) inchangé, rails fermés tant que les interrupteurs valent `false`, graine « aucune caution par défaut » inchangée. | + +Aucun défaut majeur ni bloquant d'architecture. + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/argent-2026-11-18.md b/docs/team/reviews/US-225/argent-2026-11-18.md new file mode 100644 index 000000000..c974e2db5 --- /dev/null +++ b/docs/team/reviews/US-225/argent-2026-11-18.md @@ -0,0 +1,22 @@ +# Revue argent — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236) — 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 : 46ca6a54..941773363062e6afe1aefcd2b758a2cf8707c892 + +Contexte : tête 94177336 de `story/US-225-caution` (CI 17/17 verte) ; diff `origin/main...94177336` (42 fichiers) relu pour l'argent : graine 0141, `deposit-triggers.ts`, `deposit-rails.ts`, `deposit-executor.ts`, `pg-deposit-config.ts`, PSP simulé. Oracle `docs/specs/tools/check_t49plus.py` relancé (`python -I -X utf8`) : T57, T58, T59, T69 à T73 sans écart ; les valeurs attendues des tests sont lues dans l'oracle, jamais dans le code testé. Tests non réexécutés ici (CI de la tête). + +| # | Gravité | Constat | +| --- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Graine PA / PY (0141, `params.json`) : `deposit_always_required` = faux, `deposit_trigger_classes` = {LUXE} (À DÉCIDER, déclaré dans `EXPECTED_TO_DECIDE` et POUR_LE_FONDATEUR §3), `deposit_young_driver_classes` = {} (DEC-FONDATEUR-21), `deposit_on_risk_flag` = vrai avec `risk_control_deployed` = faux (RISK non évalué), `failMode` BLOCK, aucun interrupteur. Défaut = aucune caution sauf LUXE, conforme à « comme Turo » (ADR-108, révision caution de 08). Un paramètre absent rend le déclencheur vrai (`deposit-triggers.ts:100-119`), jamais l'inverse : fail-closed. | +| 2 | INFO | `decideDepositGate` (`deposit-rails.ts:261-290`) : aucun déclencheur ⇒ `NOT_REQUIRED` sans `selectDepositRail` ni `H_requise` (T70) ; montant absent ou nul, ou durée absente ⇒ `PARAM_MISSING` (T72 c, jamais une caution de 0) ; sinon rail ou `DEPOSIT_RAIL_UNAVAILABLE`. T59 refait à la main : `H_requise` = 24 + 72 h 25 + 72 = 168 h 25 > 168 h, pas de pré-autorisation unique ; jours possibles = ⌊(168 × 60 − 1 440 − 4 320) / 1 440⌋ = 3, égal à l'oracle. `V` = min(`MAX_HOLD_HOURS` validée, `provider_max_hold_h`), inconnue ⇒ 0 : plus prudent que 08, qui ne lit que le paramètre ; accepté et documenté (ADR-164 point 3). | +| 3 | INFO | Aucun fonds de tiers détenu : rail « débit puis remboursement » refusé dans `selectDepositRail` si `funds_holding_enabled` = faux, plafond ≤ 0 ou remboursement non validé (`deposit-rails.ts:215-222`), puis une seconde fois sans appel dans `DepositRailExecutor.place` (`deposit-executor.ts:95-100`). Le lecteur lit l'interrupteur par `core.config_go_live` (`pg-deposit-config.ts:115-118`), absent ⇒ faux (`=== true`). Le booléen de `place` vient de l'appelant (US-701 devra y passer la valeur du lecteur) : défense en profondeur correcte. | +| 4 | INFO | Valeurs chiffrées (oracle) : USD, caution 30 000 centimes, carburant 1 200 (T57 : capture 1 200 puis VOID du reste 28 800 ; T58 : VOID 30 000 puis MIT 1 200) ; PYG sans décimale, 300 et 12 (VOID 288 puis MIT 12). Chaque commande porte son montant explicite et ses jambes, jamais un prorata ; la somme des jambes d'une capture égale le montant (`sumParts`, `deposit-rails.ts:425-432`). `bigint` partout. | +| 5 | **MAJEUR** | `DepositRailExecutor.execute` ne s'arrête que sur une exception (`deposit-executor.ts:160-166`) : un résultat du port dont le `status` vaut `FAILED`, `PENDING`, `SUBMITTED` ou `UNKNOWN` (`port.ts:39-45`) est rangé dans `completed` et l'exécution continue. Scénario chiffré (USD) : caution 30 000, carburant 1 200 ; la capture de 1 200 revient `FAILED` (ou `PENDING`), le `VOID` de 28 800 est tout de même envoyé : la caution est libérée en entier, le carburant n'est ni capturé ni passé en MIT (le plan, `deposit-rails.ts:497-509`, ne prévoit pas ce repli), `failed` vaut `null`. L'exécutant se contredit : sa documentation promet l'arrêt « à la première étape en échec » (`:70`) et `reauthorize` traite bien `FAILED` (`:130`). Le FAKE ne renvoie jamais ce statut sans exception, d'où des tests verts. Correction : arrêter sur tout statut autre que `SUCCEEDED` (`UNKNOWN` / `PENDING` : lire `getOperation` avant de poursuivre ; `FAILED` d'une capture : replanifier en MIT) et le prouver avec un port simulé qui renvoie ces statuts. | +| 6 | MINEUR | Frais scindé : `part()` applique `allocHost` à la part capturée puis au reste (`deposit-rails.ts:414-423, 477-481`), alors que 08 dit « `allocHost` par ligne ». Exemple : ligne de 6 unités mineures à 50 % en parts 3 + 3 : HOST 2 + 2 = 4, contre 3 pour la ligne entière. L'hôte peut recevoir une unité mineure de plus ou de moins selon le plafonnement. Rare (plafond de caution atteint avec une part de plan différente de 100 %) ; allouer la ligne entière puis répartir, ou le tester. | +| 7 | MINEUR | Pose portée en entier par la jambe `PLATFORM` (`chargeLegs`, `deposit-rails.ts:552-554`), puis capture avec ses propres jambes HOST / PLATFORM : cohérent avec 08 (« la caution n'est pas une jambe », marchand de référence Kmino) et PROPOSÉ ; un PSP de place de marché réel doit accepter une capture dont les jambes diffèrent de celles de l'autorisation : à ajouter aux questions au PSP (lot C). La capture d'un frais sur la caution n'écrit encore ni `host_ledger` ni règlement (suite S-2, US-701). | +| 8 | INFO | PSP simulé : `VOID` permis après capture partielle (`fake-psp.ts:273-279`), refusé après capture totale, seconde capture refusée après VOID. Conforme à 08 E3 repli 1, à T57 et à 17 §4.3 (« VOID du reliquat après une capture partielle »). Le `VOID` ne déplace aucun fonds (le test lit `movements()` : seule la capture de 4 apparaît). Aucune garantie d'argent affaiblie ; un PSP réel qui refuserait ce `VOID` lèverait une erreur, l'exécutant s'arrête (`failed`) et le reliquat expire seul. | +| 9 | MINEUR | Format d'idempotence `deposit:{id}:{op}:i{n}:a{m}` (`idempotency.ts:85-120`) différent de 08 E4 (`{trip_id}:{segment_id}:v…:{DEPOSIT_CAPTURE, DEPOSIT_VOID…}`) et de `offSettlementRefundKey`, déjà prévue pour le remboursement d'une caution (origine `DEPOSIT`) : deux clés possibles pour une même opération `REFUND`. Unicité garantie (`deposit_id` unique) et PROPOSÉ avec report S-5 ; à réconcilier avant que US-701 ne persiste ces clés. | + +Aucun défaut bloquant. Un défaut majeur (n° 5). + +Verdict : CHANGEMENTS DEMANDÉS diff --git a/docs/team/reviews/US-225/argent-2026-11-18b.md b/docs/team/reviews/US-225/argent-2026-11-18b.md new file mode 100644 index 000000000..4a066fd5f --- /dev/null +++ b/docs/team/reviews/US-225/argent-2026-11-18b.md @@ -0,0 +1,20 @@ +# Revue argent — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236), seconde passe — 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 : 46ca6a54..0b7a8eb76c1460be5b7d8a381147840521a85a08 + +Contexte : tête 0b7a8eb7 de `story/US-225-caution` (CI verte) ; les revues de première passe (tête 94177336) sont périmées. Relu : `git diff cc016c91..0b7a8eb7` (correction 29f4796b, libellés 6abd5455, fusion de `main` #239 US-224f en 0b7a8eb7) et `git diff origin/main...0b7a8eb7`. Tests non réexécutés ici (CI de la tête). + +| # | Gravité | Constat | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Défaut majeur de la première passe (n° 5) **corrigé** : `#steps` (`deposit-executor.ts`) s'arrête sur toute exception et sur tout statut autre que `SUCCEEDED` ; aucune étape suivante ne part (aucun VOID après une capture non prouvée). `PENDING` / `SUBMITTED` / `UNKNOWN` et l'exception `UNKNOWN_OUTCOME` donnent `needsLookup: true` (lecture de `getOperation`, puis rejeu avec les mêmes clés de rang i1, 17 §4.3). Le scénario chiffré de la première passe (USD : caution 30 000, carburant 1 200, capture `FAILED`) ne libère plus la caution sans prendre le carburant. | +| 2 | INFO | Repli après capture refusée (`DECLINED` ou `FAILED`) : `fallbackAfterCaptureFailure` rend VOID de `capturedMinor + releasedMinor` (la caution entière) puis MIT `DELAYED_CHARGES` de **tous** les frais (parts de la capture, du MIT et de la dette du plan), montant et jambes explicites (somme des parts, jamais un prorata) ; sans `SUPPORTS_VOID` : `LET_EXPIRE` ; sans `SUPPORTS_MIT` : `DEBT` ; capacité inconnue = non. Conforme à 08 E3 (repli 2, T64) et à la phrase « même repli pour la caution : aucun frais n'est capturé sur la caution, il passe en MIT ». Extension assumée : 08 cadre ce repli pour un PSP sans capture partielle ; le code l'applique aussi à une capture refusée, solution la plus prudente (aucun frais pris sur une caution contestée, rien de perdu pour l'hôte), PROPOSÉE et inscrite en passation. Clés de rang i2 : aucune collision avec les clés i1 de la capture refusée ; aucun double débit (le plan d'origine n'a envoyé que la capture refusée). | +| 3 | INFO | Rejeu idempotent prouvé sur le FAKE : après repli, un second `execute` avec les mêmes clés ne crée aucun mouvement (le FAKE rejoue le refus enregistré de la capture i1, puis VOID et MIT i2 rejoués) ; après une réponse perdue (`TIMEOUT_AFTER_SUCCESS`), le rejeu donne une seule capture, puis le VOID du reste. Valeurs en USD (30 000 / 1 200) et en PYG sans décimale (300 / 12), cohérentes avec T57 / T58 de l'oracle `check_t49plus.py` (relancé avec `python -I -X utf8` : `T49-T65 : ecarts = 0`, T69 à T73 OK). | +| 4 | INFO | Arrondi (première passe n° 6) **corrigé** : `restPart` arrondit la part HOST une fois sur la ligne entière (`allocHost` de la ligne), la part capturée garde `allocHost(taken)`, le reste prend le complément borné à [0 ; reste] ; Σ des jambes des deux parts = jambes de la ligne entière. Refait à la main sur `allocHost` (demi vers le bas à égalité, `money.ts:320-327`) : 1003 à 3/4 : 752 (avant : 751 + 2 = 753) ; 6 à 1/2 : 3 (avant : 3 + 1 = 4). Le test qui échouait avant la correction : cas 1001 / 1003 à 3/4 et 5 / 6 à 1/2. | +| 5 | MINEUR | `DepositRailExecutor.reauthorize` (`deposit-executor.ts:127-135`) ne traite que `FAILED` : un résultat `PENDING` / `SUBMITTED` / `UNKNOWN` est rendu `REAUTHORIZED` avec son statut dans `result`, sans `needsLookup`. Même famille que le défaut corrigé mais sans conséquence monétaire (aucune commande suivante, aucun débit) ; l'appelant d'US-702 doit lire `result.status`, ou un correctif doit rendre un état « en attente ». À inscrire dans la passation d'US-702. | +| 6 | MINEUR | Première passe n° 9 toujours vrai : format d'idempotence `deposit:{id}:{op}:i{n}:a{m}` différent de 08 E4 et de `offSettlementRefundKey` (origine `DEPOSIT`), report S-5 déjà prévu ; à réconcilier avant que US-701 ne persiste ces clés. | +| 7 | INFO | Inchangé et toujours vrai (première passe n° 1 à 4, 7, 8) : graine sans caution par défaut (LUXE à décider), `decideDepositGate`, rail « débit puis remboursement » refusé tant que `funds_holding_enabled` = faux (dans `selectDepositRail` et dans `place`, sans appel au PSP), adaptateur FAKE **inchangé** par la correction (son seul changement, VOID après capture partielle, date de la première passe), aucun fonds de tiers détenu. Renumérotation sans effet monétaire. | + +Aucun défaut majeur ni bloquant ; un mineur nouveau (n° 5). + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/code-2026-11-18.md b/docs/team/reviews/US-225/code-2026-11-18.md new file mode 100644 index 000000000..331c5a0ef --- /dev/null +++ b/docs/team/reviews/US-225/code-2026-11-18.md @@ -0,0 +1,20 @@ +# Revue code — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236) — 2026-11-18 + +Relecteur : revue-code / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..941773363062e6afe1aefcd2b758a2cf8707c892 + +Contexte : tête 94177336 (CI 17/17 verte : qualité, base de données, revues, e2e) ; diff `origin/main...94177336` relu en entier. Concurrence : toutes les fonctions sont pures (aucune horloge, aucune base) ; l'exécutant n'écrit rien et s'appuie sur l'idempotence du port ; le lecteur est en lecture seule. + +| # | Gravité | Constat | +| --- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | **MAJEUR** | `execute` (`deposit-executor.ts:147-168`) traite l'échec comme une exception seulement : un `OperationResult` dont le `status` n'est pas `SUCCEEDED` (`FAILED`, `PENDING`, `SUBMITTED`, `UNKNOWN`, `port.ts:39-45`) est ajouté à `completed` et la boucle enchaîne l'étape suivante. Séquence réelle : `CAPTURE` renvoie `PENDING` ou `FAILED`, puis `VOID` du reste part quand même ; `failed` reste `null`, l'appelant croit à un succès. Contredit le commentaire de contrat (`:70` « première étape en échec ») et la gestion de `FAILED` faite dans `reauthorize` (`:130`). Correction : après chaque étape, arrêter et rendre `failed` (ou un état « en attente ») si `status !== 'SUCCEEDED'` ; `UNKNOWN` / `PENDING` ⇒ lire `getOperation` avant de reprendre avec la même clé. Détails chiffrés dans la revue argent n° 5. | +| 2 | MINEUR | `#run` n'a pas de repli quand le `VOID` lève `INVALID_REQUEST` après une capture partielle (PSP qui ne libère pas le reste) : l'exécution s'arrête avec `failed`, la décision reste à rejouer sans fin. Prévoir, pour l'appelant d'US-702, le passage de l'étape en `LET_EXPIRE` après refus définitif (ADR-164 point 4 le prévoit seulement quand `SUPPORTS_VOID` est inconnue). | +| 3 | MINEUR | `selectDepositRail` lève `PaymentError('INVALID_REQUEST')` si fin ≤ début (`deposit-rails.ts:176-178`) alors que `decideDepositGate` rend sinon des décisions typées : une réservation incohérente fait remonter une exception au lieu d'un refus fermé. Fail-closed quand même ; à documenter ou à convertir en `REFUSED` au point d'appel d'US-701. | +| 4 | MINEUR | `part()` applique `allocHost` à chaque morceau d'un frais scindé (`deposit-rails.ts:414-423, 477-481`) : l'arrondi de la somme peut différer d'une unité mineure de celui de la ligne entière (6 unités à 50 % en 3 + 3 : HOST 4 au lieu de 3). Voir revue argent n° 6. | +| 5 | MINEUR | `PgDepositRailConfigReader.read` exécute trois requêtes sans transaction ni instantané commun (`pg-deposit-config.ts:98-132`) : une valeur de paramètre et l'interrupteur peuvent provenir de deux instants. Sans conséquence aujourd'hui (aucun appelant) ; l'appelant d'US-701 doit l'exécuter dans la transaction du checkout. `network` doit aussi être le même pour le lecteur et pour `DepositRailCapabilities.network` (deux sources du même réseau, `:97` et `deposit-rails.ts:76`). | +| 6 | INFO | Qualité : modules `pay` bien découpés (`deposit-triggers` pur, `deposit-rails` pur, exécutant sur le port, lecteur SQL), exports par `index.ts` seulement, aucun `now()` SQL métier, aucune constante de pays, types fermés (`DEPOSIT_*`), `bigint` ; commentaires et README à jour. Générateur de graines : `extraKeys` et `inPostSeedGroup` sont cohérents entre `renderParamSeedSql`, `isPostSeedParam` et le test ; unité `value_class_set` validée par `parse.ts:740-749` (ensemble ordonné, sans doublon, vide permis). | +| 7 | MINEUR | Documentation : `changelog.d/US-225-caution.md` (ligne 7) annonce « catalogue v78 » alors que la story prend la v79 (`catalogs/index.ts`, passation) ; corriger en v79. | + +Un défaut majeur (n° 1), sans bloquant. + +Verdict : CHANGEMENTS DEMANDÉS diff --git a/docs/team/reviews/US-225/code-2026-11-18b.md b/docs/team/reviews/US-225/code-2026-11-18b.md new file mode 100644 index 000000000..b1dfdd10a --- /dev/null +++ b/docs/team/reviews/US-225/code-2026-11-18b.md @@ -0,0 +1,19 @@ +# Revue code — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236), seconde passe — 2026-11-18 + +Relecteur : revue-code / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..0b7a8eb76c1460be5b7d8a381147840521a85a08 + +Contexte : tête 0b7a8eb7 de `story/US-225-caution` (CI verte) ; les revues de première passe (tête 94177336) sont périmées. Relu : `git diff cc016c91..0b7a8eb7` (correction 29f4796b, libellés 6abd5455, fusion de `main` #239 US-224f en 0b7a8eb7) et `git diff origin/main...0b7a8eb7`. Tests non réexécutés ici (CI de la tête). + +| # | Gravité | Constat | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Défaut majeur de la première passe (n° 1) **corrigé** : `#steps` rend `{ failure, captureRefused }` à la première exception ou au premier statut autre que `SUCCEEDED`, sans exécuter la suite ; `DepositStepFailure` porte `step`, `error`, `status`, `needsLookup` (vrai pour `UNKNOWN_OUTCOME`, `PENDING`, `SUBMITTED`, `UNKNOWN`). `execute` n'enchaîne le repli que si la capture est refusée (`DECLINED` ou `FAILED`) ; sinon `failed` est rendu et `fallback` reste `null`. Le contrat du commentaire (« première étape en échec ») est maintenant vrai ; `completed` ne contient que des étapes abouties (`completed.push` après les deux contrôles). | +| 2 | INFO | Lecture du code : `LET_EXPIRE` et `DEBT` rendent `null` (aucun appel) et sont rangés dans `completed` ; une exception du repli (VOID ou MIT) est rendue par `failed: second.failure` avec `fallback` renseigné, donc l'appelant sait quel plan a été joué ; clés de rang 2 distinctes de celles du plan d'origine, rejeu déterministe (même plan ⇒ capture i1 rejouée, puis repli i2 rejoué). `fallbackAfterCaptureFailure` est pure, sans horloge, typée, exportée par `index.ts` ; aucune dépendance interdite. | +| 3 | INFO | Tests : `deposit-rails.fake.test.ts` couvre, en USD et en PYG (`describe.each(CASES)`), capture refusée par exception (repli, une seule MIT, rejeu sans mouvement), `FAILED` par statut (port de test enveloppant le FAKE : `capture` imposé, le reste délégué ; l'adaptateur FAKE n'est pas modifié), `PENDING` / `SUBMITTED` / `UNKNOWN` (arrêt, `needsLookup`, zéro VOID et zéro MIT, aucun mouvement), réponse perdue puis rejeu (une capture). `deposit-rails.test.ts` : arrondi par ligne et repli pur (T58, `null` sans capture). Ces tests échouent sur le code de la première passe (VOID envoyé après `PENDING` ou `FAILED`). | +| 4 | MINEUR | `reauthorize` (`deposit-executor.ts:127-135`) ne traite que `FAILED` ; `PENDING` / `SUBMITTED` / `UNKNOWN` ressortent en `REAUTHORIZED` sans `needsLookup`, alors que `execute` les traite désormais. Incohérence de contrat entre deux méthodes de la même classe, sans conséquence aujourd'hui (aucun appelant) ; à aligner ou à documenter avant US-702. | +| 5 | MINEUR | Première passe n° 2, 3, 5 toujours vrais : pas de repli `LET_EXPIRE` après refus définitif du VOID, `selectDepositRail` lève `INVALID_REQUEST` si fin ≤ début, lecteur sans instantané commun ; tous sans appelant, à régler au branchement d'US-701 / US-702. | +| 6 | INFO | Renumérotation et documentation : migration `0142_config_deposit_rail_params.sql` contiguë avec `main` (0141 = US-224f), `seed-sql.ts`, `country-data-allowlist.json`, README db, fixture 9943, ADR-164, GL-41 (à côté de GL-40 et GL-43), `changelog.d` (catalogue v82, première passe n° 7 corrigée) cohérents entre eux ; `schema.md` : 143 migrations (142 de `main` + 1), ligne 0142 ajoutée, autres compteurs ceux de `main` (aucune table ni politique ajoutée) ; fusion sans perte côté `main`. Libellés de test sans « #236 » : sans effet de fond. | + +Aucun défaut majeur ni bloquant ; deux mineurs résiduels sans appelant. + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/qa-2026-11-18.md b/docs/team/reviews/US-225/qa-2026-11-18.md new file mode 100644 index 000000000..054355356 --- /dev/null +++ b/docs/team/reviews/US-225/qa-2026-11-18.md @@ -0,0 +1,20 @@ +# Revue qa — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236) — 2026-11-18 + +Relecteur : revue-qa / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..941773363062e6afe1aefcd2b758a2cf8707c892 + +Contexte : tête 94177336 (CI 17/17 verte) ; diff relu en entier avec les cinq critères de US-225 dans 19 (`19_DEVELOPMENT_BACKLOG.md`, ligne 2151). Oracle `check_t49plus.py` relancé : T57 à T59 et T69 à T73 sans écart ; les tests appellent l'oracle (`check('T57', …)`) et ne tirent aucune valeur attendue du code testé. Chaque cas tourne en USD (PA) et en PYG sans décimale (PY) (`describe.each(CASES)`, `countryCases()`). Tests non réexécutés ici. + +| # | Gravité | Constat | +| --- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | **MAJEUR** | Chemin d'échec de l'exécutant non testé : `deposit-rails.fake.test.ts` n'a aucun cas où `execute` rend `failed` non nul, ni où un résultat de port a un `status` `FAILED`, `PENDING` ou `UNKNOWN` (seuls `run.failed` = `null` aux lignes 102 et 141). Le défaut correspondant (`deposit-executor.ts:160-166`, un `VOID` envoyé après une capture non confirmée, revue argent n° 5) passe donc la CI. À ajouter avec la correction : (a) capture refusée par exception ⇒ aucun `VOID` émis, `failed.step.op` = `CAPTURE` ; (b) capture renvoyée `FAILED` / `PENDING` ⇒ même arrêt ; (c) rejeu avec les mêmes clés après arrêt ⇒ aucun second mouvement. | +| 2 | MINEUR | Rail « débit puis remboursement » : exécution sur le FAKE avec `funds_holding_enabled` = vrai non couverte (seul le refus à faux l'est, `deposit-rails.fake.test.ts:175`) ; le plan est testé en pur (`deposit-rails.test.ts:357`) mais ni la pose en `AUTO`, ni le remboursement total, ni la MIT des frais ne sont exécutés bout en bout. Le rail étant fermé en production, MINEUR ; à ajouter avant l'ouverture de `funds_holding_enabled` (GL-41). | +| 3 | INFO | Critères de 19 : (1) T59 + `SUPPORTS_REAUTH` non validée ⇒ `DEPOSIT_RAIL_UNAVAILABLE` avant le paiement, 3 jours possibles : prouvé en pur et sur PostgreSQL sous `app_api` (`deposit-rail-config.int.test.ts`), textes en 4 langues ; **l'affichage dans S05 reste une suite (US-701)**, annoncé dans la passation ; (2) T70 : aucun rail évalué, y compris sans capacité ; (3) ré-autorisation refusée ⇒ `DEPOSIT_REAUTH_FAILED`, aucun mouvement MIT ; **la minuterie « avant l'échéance » reste une suite (S-2)** ; (4) rail plafonné fermé, refus avant paiement : pur, FAKE (aucune commande) et PostgreSQL ; (5) T58 : VOID 300,00 puis MIT 12,00, USD et PYG. Les critères 1 et 3 sont donc livrés à moitié : décision du serveur, pas le parcours ; à tenir au tableau jusqu'à US-701 / US-702. | +| 4 | INFO | Tests existants modifiés, justifiés ligne à ligne dans la passation : `fake-payment-provider.test.ts` (VOID après capture partielle, contraire de l'ancien cas ; remplaçant plus strict : seconde capture refusée) ; `fake-psp.test.ts` (ajouts : VOID après capture totale refusé, mouvements = capture seule) ; `seed-sql.test.ts` (clés `extraKeys`, 0009 toujours sans ces clés) ; `defaults.test.ts` (`deposit_trigger_classes` À DÉCIDER). Aucune assertion affaiblie ; aucun test supprimé. | +| 5 | INFO | Couverture des déclencheurs : T69 à T73 et fail-closed hors vecteurs (classe inconnue, paramètre absent, âge inconnu, liste vide, montant nul) dans `deposit-triggers.test.ts` ; machine d'état (`deposit-rails.test.ts:373`), frais notifié trop tard / contesté / sans preuve, plafonné au montant, sans VOID, sans MIT. L0 `l0-us225-deposit-rails` sous `app_api` / `app_worker` / `app_anon` en PA et PY (L0-05 par `withRole`). Pas de test de propriété sur `allocHost` d'un frais scindé (revue argent n° 6). | +| 6 | INFO | Hygiène : aucun script ni fichier temporaire dans le diff net (`.tmp-wait.sh` ajouté puis retiré) ; `schema.md` édité à la main (142 migrations, ligne 0141) cohérent avec la forme des lignes voisines et validé par le test `schema-doc` dans le job base de données (vert) ; migration 0141 contiguë avec `main` (0140), générée et identique au rendu. | +| 7 | MINEUR | `changelog.d/US-225-caution.md` annonce le catalogue v78 au lieu de v79 (`catalogs/index.ts`). | + +Un défaut majeur (n° 1), sans bloquant. + +Verdict : CHANGEMENTS DEMANDÉS diff --git a/docs/team/reviews/US-225/qa-2026-11-18b.md b/docs/team/reviews/US-225/qa-2026-11-18b.md new file mode 100644 index 000000000..77dc283f2 --- /dev/null +++ b/docs/team/reviews/US-225/qa-2026-11-18b.md @@ -0,0 +1,19 @@ +# Revue qa — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236), seconde passe — 2026-11-18 + +Relecteur : revue-qa / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..0b7a8eb76c1460be5b7d8a381147840521a85a08 + +Contexte : tête 0b7a8eb7 de `story/US-225-caution` (CI verte) ; les revues de première passe (tête 94177336) sont périmées. Relu : `git diff cc016c91..0b7a8eb7` (correction 29f4796b, libellés 6abd5455, fusion de `main` #239 US-224f en 0b7a8eb7) et `git diff origin/main...0b7a8eb7`. Tests non réexécutés ici (CI de la tête). + +| # | Gravité | Constat | +| --- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Défaut majeur de la première passe (n° 1, chemin d'échec non testé) **corrigé** : quatre blocs de tests sous `describe.each(CASES)` (USD pour le PA, PYG sans décimale pour le PY) : (a) capture refusée par exception ⇒ repli VOID de la caution entière puis MIT du carburant (mouvements lus sur `movements()` : seule la MIT apparaît), rejeu avec les mêmes clés sans nouveau mouvement ; (b) capture `FAILED` par statut ⇒ même repli ; (c) `PENDING` / `SUBMITTED` / `UNKNOWN` ⇒ `failed` = `{ status, needsLookup: true, error: null }`, étape `CAPTURE`, `completed` vide, aucun VOID ni MIT, aucun mouvement ; (d) `TIMEOUT_AFTER_SUCCESS` ⇒ arrêt sans VOID (`UNKNOWN_OUTCOME`), rejeu ⇒ une seule capture puis VOID du reste. Les attendus viennent du scénario et des montants du pays, pas du code testé. | +| 2 | INFO | Les tests auraient échoué avant la correction : sur l'ancien `execute`, (b) et (c) envoyaient un VOID après la capture non aboutie (`failed` = `null`, `completed` non vide) ; (a) enchaînait le VOID partiel sans MIT. Le port de test enveloppe le FAKE (`captureReturning`) et ne touche pas l'adaptateur : `packages/fake-adapters` inchangé par la correction. | +| 3 | INFO | Arrondi : le test d'allocation par ligne (1001 / 1003 à 3/4, 7 / 9 à 1/3, 5 / 6 à 1/2 et le montant du pays + 1) échoue sur l'ancien `part()` (753 contre 752 ; 4 contre 3) ; borne [0 ; reste] vérifiée sur chaque jambe. L'attendu vient de `allocHost` de `@rueda/money` (primitive unique, elle-même sous vecteurs d'or), pas du code de la caution ; recalcul à la main identique. Le test ne couvre que le rail PREAUTH_SINGLE : suffisant, le même `planDepositDecision` sert les autres rails. | +| 4 | INFO | Oracles : `check_t49plus.py` relancé (`python -I -X utf8`) : T57 à T59 et T69 à T73 sans écart, `T49-T65 : ecarts = 0` ; les tests de T57 / T58 appellent l'oracle. Repli pur testé aussi sans étape de capture (rend `null`). Libellés reformulés sans « #236 » : le contrôle des styles passe, aucune assertion changée. | +| 5 | MINEUR | Lacunes restantes, sans appelant : rejeu après repli sur statut `FAILED` (seul le rejeu après exception `DECLINED` est prouvé) ; `reauthorize` avec `PENDING` / `UNKNOWN` non testé (le code les rend `REAUTHORIZED`) ; rail « débit puis remboursement » non exécuté avec `funds_holding_enabled` = vrai (première passe n° 2, fermé en production, à ajouter avant GL-41). | +| 6 | INFO | Renumérotation : migration 0142 contiguë avec `main`, graine régénérée (test `seed-sql` : identique au rendu), fixture 9943 et L0 `l0-us225-deposit-rails` inchangés au fond (rôles de production, L0-05 en tête) ; `schema.md` à la main : 143 migrations (142 de `main` + 1) et ligne 0142, test `schema-doc` vert en CI ; catalogue v82 (`main` à v81, la constante ne peut pas redescendre) accepté ; le L0 `l0-us224f-multi-tender` de `main` arrive sans modification. Le reste de la première passe (graine sans caution par défaut, test FAKE de US-019 modifié et justifié, textes) reste vrai. | + +Aucun défaut majeur ni bloquant ; lacunes mineures sans appelant. + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/securite-2026-11-18.md b/docs/team/reviews/US-225/securite-2026-11-18.md new file mode 100644 index 000000000..ab8eb28d9 --- /dev/null +++ b/docs/team/reviews/US-225/securite-2026-11-18.md @@ -0,0 +1,21 @@ +# Revue securite — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236) — 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 : 46ca6a54..941773363062e6afe1aefcd2b758a2cf8707c892 + +Contexte : tête 94177336 (CI 17/17 verte, dont gitleaks, pnpm audit, base de données, revues) ; diff `origin/main...94177336` relu en entier. Vérifié : aucun fichier de `.github/`, `scripts/`, `docs/team/review-requirements.json` ni `docs/specs/` dans le diff net. Le script d'attente de CI `.tmp-wait.sh` (ajouté en 601a9759, retiré en 94177336) n'est plus dans le diff net ; il ne subsiste que dans l'historique, contenu relu : aucun secret, jeton ni identifiant. Aucun contrôleur, aucune route, aucun interrupteur. + +| # | Gravité | Constat | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 1 | INFO | Migration 0141 : uniquement des `INSERT` de définitions (`go_live_switch` = faux, `fail_mode` BLOCK, portée `COUNTRY`) et de valeurs, plus un contrôle `DO` ; aucun `GRANT`, aucune fonction, aucun `SECURITY DEFINER`, aucun changement de RLS ni de rôle. Générée (`seed-sql.test.ts` : identique au rendu), allowlist de pays justifiée. Aucun des huit paramètres n'est un interrupteur ; `funds_holding_enabled`, `insurer_contract_active`, `payouts_enabled`, `p2p_private_hosts_enabled` intacts. | +| 2 | INFO | `PgDepositRailConfigReader` : trois `SELECT` paramétrés, lecture seule, sous `app_api` ou `app_worker`, horloge `platform.now()`, aucune écriture. L0 `l0-us225-deposit-rails.test.ts` : rôles de production (`withRole`, assertion L0-05 en tête), PA (USD) et PY (PYG) ; `app_api` n'écrit aucun paramètre (42501), `app_anon` ne lit rien (42501), `funds_holding_enabled` fermé, aucune capacité `SUPPORTS_REAUTH` ou `MAX_HOLD_HOURS` validée en graine. Test d'intégration sous `app_api` via `connectAs` (L0-05). Aucun droit nouveau. | +| 3 | INFO | Fixture 9943 (`test-migrations/`, appliquée à la seule base jetable de test) : `SECURITY DEFINER`, `search_path = pg_catalog, pg_temp`, liste fermée de clés, exécution accordée à `app_api` seul, transaction annulée par le test, aucun interrupteur de mise en service : même patron que `us124_param_version`. Acceptable. | +| 4 | INFO | Test existant modifié (`fake-payment-provider.test.ts:181-222`, cas « capture partielle ») : ce n'est pas un test de sécurité ; il exigeait un refus que 08 E3 repli 1, T57 et 17 §4.3 (VOID du reliquat) contredisent. Le remplaçant est plus strict : VOID du reste accepté, puis seconde capture refusée (`INVALID_REQUEST`) ; un VOID après capture totale reste refusé (nouveau test de `fake-psp.test.ts`) ; le VOID ne déplace aucun fonds. Aucune garantie affaiblie. Un PSP réel qui refuse ce VOID lève une erreur, l'exécutant s'arrête sur l'étape (`failed`) ; capacités exigées : `SUPPORTS_VOID` et, pour la capture partielle, `SUPPORTS_PARTIAL_CAPTURE`, inconnue ⇒ non, sans appel. | +| 5 | INFO | Capacité PSP inconnue = non : `CapabilitySet` ne retient que `VALIDATED_*` (`capabilities.ts`), `int` inconnu = 0, `bool` inconnu = faux ; `depositHoldValidityHours` exige `SUPPORTS_PREAUTH` ; rail (b) refusé tant que `funds_holding_enabled` = faux, y compris dans l'exécutant avant tout appel (test FAKE : aucune commande émise). Aucun fonds de tiers détenu. | +| 6 | MINEUR | La décision du checkout (`DepositGateDecision`, `deposit-rails.ts:244-259`) expose `triggers`, l'âge et `riskEvaluated`, données [C2] (ops seulement). Rien ne les sérialise aujourd'hui (aucune route) ; US-701 devra construire une vue voyageur qui ne porte que `amountMinor` ou le refus et les jours possibles, avec un test d'absence de ces champs dans la réponse. À inscrire dans la passation d'US-701. | +| 7 | MINEUR | `DepositRailExecutor.execute` ne s'arrête pas sur un résultat `FAILED` / `PENDING` / `UNKNOWN` renvoyé sans exception (`deposit-executor.ts:160-166`) : un `VOID` peut suivre une capture non confirmée. Porté en MAJEUR par les revues argent, code et qa ; sans effet de sécurité propre (ni fuite ni élévation), rappelé ici par cohérence. | +| 8 | INFO | Clés d'idempotence : construites par `part()` et `rank()` (même validation de caractères que les autres clés), `deposit_id` fourni par l'appelant, aucune entrée utilisateur directe ; longueur adaptée au PSP par `idempotencyKeyToSend`. Un rejeu reprend les mêmes clés (règle 3 du port). Aucun secret, jeton ni PAN journalisé ou commité (gitleaks vert) ; `instrumentToken` transmis tel quel au port, jamais écrit. | + +Aucun défaut majeur ni bloquant propre à la sécurité (le constat 7 est porté en majeur par les revues argent, code et qa). + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/securite-2026-11-18b.md b/docs/team/reviews/US-225/securite-2026-11-18b.md new file mode 100644 index 000000000..a0a6bafe9 --- /dev/null +++ b/docs/team/reviews/US-225/securite-2026-11-18b.md @@ -0,0 +1,18 @@ +# Revue securite — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236), seconde passe — 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 : 46ca6a54..0b7a8eb76c1460be5b7d8a381147840521a85a08 + +Contexte : tête 0b7a8eb7 de `story/US-225-caution` (CI verte) ; les revues de première passe (tête 94177336) sont périmées. Relu : `git diff cc016c91..0b7a8eb7` (correction 29f4796b, libellés 6abd5455, fusion de `main` #239 US-224f en 0b7a8eb7) et `git diff origin/main...0b7a8eb7`. Tests non réexécutés ici (CI de la tête). + +| # | Gravité | Constat | +| --- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | Périmètre de sécurité inchangé par la correction : hors fusion de `main`, `git diff cc016c91..0b7a8eb7` ne touche que `deposit-executor.ts`, `deposit-rails.ts` (fonctions pures), leurs tests et la documentation ; aucun fichier de `.github/`, `scripts/`, `docs/team/review-requirements.json` ni `docs/specs/` dans le diff net `origin/main...HEAD`. Aucune route, aucun contrôleur, aucun `GRANT`, aucune fonction `SECURITY DEFINER` nouvelle dans US-225 ; les fonctions de `main` (US-224f, allowlist `security-definer-allowlist.json`) ne sont pas modifiées par la branche. | +| 2 | INFO | Le défaut de la première passe (n° 7, arrêt sur statut non `SUCCEEDED`) est corrigé : aucun VOID après une capture non prouvée ; l'issue inconnue impose la lecture de l'état avant rejeu avec les mêmes clés d'idempotence, donc aucun double débit possible sur la carte du voyageur. Aucune fuite : l'erreur du port est rendue telle quelle à l'appelant (jamais journalisée ici), `instrumentToken` transmis au port sans écriture, aucun PAN. | +| 3 | INFO | Repli après refus : montants explicites, jambes bornées et revérifiées par l'adaptateur (`LEG_SUM_MISMATCH`), MIT seulement sur le jeton enregistré au checkout, clés de rang i2 sans collision ; capacité inconnue = non (`SUPPORTS_VOID` / `SUPPORTS_MIT` absentes ⇒ expiration ou dette, jamais un appel non validé). Aucun fonds de tiers détenu : le rail « débit puis remboursement » reste refusé tant que `funds_holding_enabled` = faux. Aucun interrupteur touché ; graine et L0 sous `app_api` / `app_worker` / `app_anon` inchangés au fond. | +| 4 | INFO | Renumérotation en 0142 : migration toujours générée, uniquement des `INSERT` de définitions et de valeurs (`go_live_switch` faux, `fail_mode` BLOCK), liste blanche des données de pays à jour (`country-data-allowlist.json`) ; fixture 9943 (base jetable, `search_path` fixé, exécution à `app_api` seul) inchangée au fond. Rien de perdu côté `main` à la fusion (allowlists et fonctions d'US-224f présentes). | +| 5 | MINEUR | Première passe n° 6 toujours vrai : `DepositGateDecision` expose déclencheurs, âge et signal de risque [C2] ; US-701 devra construire une vue voyageur sans ces champs, avec un test d'absence. `reauthorize` rend `REAUTHORIZED` pour `PENDING` / `UNKNOWN` (sans effet de sécurité, aucun débit) : à aligner avant US-702. | + +Aucun défaut majeur ni bloquant. + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/ux-2026-11-18.md b/docs/team/reviews/US-225/ux-2026-11-18.md new file mode 100644 index 000000000..670626bd0 --- /dev/null +++ b/docs/team/reviews/US-225/ux-2026-11-18.md @@ -0,0 +1,18 @@ +# Revue ux — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236) — 2026-11-18 + +Relecteur : revue-ux / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..941773363062e6afe1aefcd2b758a2cf8707c892 + +Contexte : tête 94177336 ; lu : `packages/i18n/src/catalogs/{es,en,fr,pt}.ts`, `catalogs/index.ts` (v79), `apps/web/app/proto/copy/*` et `screens/checkout.tsx`, 10b UX-24, `POUR_LE_FONDATEUR.md` §3. Aucun écran nouveau ; seuls deux textes sont livrés. + +| # | Gravité | Constat | +| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | `web.deposit.unavailable` et `web.deposit.unavailableNone` présents en es, en, fr et pt-BR (catalogue v79) ; la clé existante garde son texte et ses formes (`one` / `other`, `{count}`) : es « no podemos tomar el depósito en tu tarjeta », en « place the deposit », fr « bloquer le dépôt sur ta carte » (tutoiement, comme le reste du catalogue), pt-BR « bloquear a caução no seu cartão » (« caução » comme `web.deposit.*` existantes). Phrases naturelles, ton calme, une idée par message, pas de jargon (« pré-autorisation », « rail » n'apparaissent pas), aucune donnée [C2] (déclencheur, âge, signal de risque) dans les textes. | +| 2 | INFO | Clé retirée des quatre textes du prototype (`apps/web/app/proto/copy/*.ts`) et devenue officielle : `createCopy.t` délègue les clés hors prototype à `i18n.t` (`copy/index.ts:67`), donc `checkout.tsx:139` (`t('web.deposit.unavailable', { count })`) continue de rendre le même texte ; le typage et le test « une vue = une langue » passent en CI (qualité et e2e verts). Aucune casse. | +| 3 | MINEUR | `web.deposit.unavailableNone` n'est utilisé nulle part (ni écran, ni sélecteur) et rien ne dit quand l'employer : `decideDepositGate` rend `maxBookableDays` = 0 (aucune durée possible) ou `null` (`PARAM_MISSING`), cas où `web.deposit.unavailable` afficherait « vous pouvez réserver jusqu'à 0 jour(s) ». À l'écran S05 (US-701) : 0 ou `null` ⇒ `unavailableNone`, au moins 1 ⇒ `unavailable` ; l'inscrire dans la passation d'US-701 et ajouter un petit sélecteur testé. Pour `PARAM_MISSING` (montant LUXE non fixé), « pour cette voiture » est exact et ne laisse pas croire à une durée plus courte possible. | +| 4 | MINEUR | Le message de refus ne propose pas de sortie (autre voiture, autres dates, aide) ; le texte de 10b UX-24 original non plus. À prévoir avec l'action de S05 (lien « changer les dates » ou « voir d'autres voitures ») ; sans objet pour cette partie serveur. | +| 5 | INFO | Accessibilité : le prototype rend le refus dans une bannière `tone="danger"` à `live="assertive"` (`checkout.tsx:137-141`), annoncée avant le paiement ; rien à changer. Avant le checkout, la mention de caution d'un LUXE reste à écrire (T70 c, US-701) : hors périmètre, non annoncée comme faite. | + +Aucun défaut majeur ni bloquant. + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-225/ux-2026-11-18b.md b/docs/team/reviews/US-225/ux-2026-11-18b.md new file mode 100644 index 000000000..dd4beddcf --- /dev/null +++ b/docs/team/reviews/US-225/ux-2026-11-18b.md @@ -0,0 +1,17 @@ +# Revue ux — US-225 « caution : rails de la pré-autorisation, ré-autorisation, débit puis remboursement, refus (partie serveur, FAKE) » (PR n° 236), seconde passe — 2026-11-18 + +Relecteur : revue-ux / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 46ca6a54..0b7a8eb76c1460be5b7d8a381147840521a85a08 + +Contexte : tête 0b7a8eb7 de `story/US-225-caution` (CI verte) ; les revues de première passe (tête 94177336) sont périmées. Relu : `git diff cc016c91..0b7a8eb7` (correction 29f4796b, libellés 6abd5455, fusion de `main` #239 US-224f en 0b7a8eb7) et `git diff origin/main...0b7a8eb7`. Tests non réexécutés ici (CI de la tête). + +| # | Gravité | Constat | +| --- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | La correction ne touche aucun texte visible ni écran : hors fusion de `main` (textes d'US-224f, v81), seul le numéro du catalogue passe à **v82**. Les clés `web.deposit.unavailable` et `web.deposit.unavailableNone` sont toujours présentes en es, en, fr et pt-BR avec le ton, le tutoiement et le vocabulaire (« caución », « caução ») de la première passe ; les textes d'US-224f de `main` sont conservés dans les quatre catalogues (aucune clé perdue à la fusion). | +| 2 | INFO | Libellés de test reformulés sans « #236 » (pris pour une couleur par le contrôle des styles) : sans effet sur l'interface ni sur le contenu des catalogues. Le message de refus reste affiché dans la bannière `tone="danger"` à `live="assertive"` du prototype, annoncée avant le paiement. | +| 3 | MINEUR | Toujours ouverts, sans écran dans cette story : `unavailableNone` non utilisé (0 ou `null` jour possible ⇒ `unavailableNone`, au moins 1 ⇒ `unavailable`, à inscrire pour US-701) et aucune sortie proposée dans le message de refus (changer les dates, voir d'autres voitures). | +| 4 | INFO | Après un repli (caution libérée en entier, frais prélevés par MIT), le voyageur devra être informé (« ta caution est libérée ; X frais sont débités ») : texte à livrer en quatre langues avec US-702, rien à changer ici. | + +Aucun défaut majeur ni bloquant. + +Verdict : APPROUVÉ diff --git a/packages/db/README.md b/packages/db/README.md index 369bfa166..3cac6f8c8 100644 --- a/packages/db/README.md +++ b/packages/db/README.md @@ -1029,3 +1029,11 @@ Migration `0141_payment_refund_multi_tender`. Aucune fixture nouvelle. - **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`). + +## Paramètres de la caution « comme Turo » (US-225 ; 08 BR-PAY-06 ; ADR-108, ADR-164) + +Migration générée `0142_config_deposit_rail_params` (groupe `deposit_always_required` + clés nommées de `POST_SEED_PARAMS`), fixture `9943_test_us225_deposit_rail_fixtures.sql` (`test_fixture.us225_param_version`, clés fermées, transaction annulée, EXECUTE `app_api`). + +- **Valeurs PROPOSÉES**, identiques au PA et au PY, `fail_mode` BLOCK, portée pays : `deposit_always_required` faux, `deposit_trigger_classes` `["LUXE"]` (à confirmer par le fondateur), `deposit_young_driver_age` 30, `deposit_young_driver_classes` `[]` (DEC-FONDATEUR-21), `deposit_on_risk_flag` vrai, `risk_control_deployed` faux, `deposit_reauth_lead_h` 24, `deposit_fee_notice_h` 48. `deposit_amount`, `deposit_charge_cap` et `provider_max_hold_h` restent sans valeur (absent : caution exigée refusée, rail « débit puis remboursement » interdit, aucune pré-autorisation). Aucun interrupteur touché ; aucun droit nouveau. +- **Lecture** : `PgDepositRailConfigReader` (module PAY) sous `app_api` ou `app_worker` : `core.config_param_value`, `core.config_go_live('funds_holding_enabled', pays)`, `core.payment_psp_capability`. +- **Preuves** : `test/l0/l0-us225-deposit-rails.test.ts` (PA USD, PY PYG ; `app_api`, `app_worker`, `app_anon`) ; `apps/api/src/modules/pay/testing/deposit-rail-config.int.test.ts` (décision du checkout sur la configuration réelle, sous `app_api`). diff --git a/packages/db/country-data-allowlist.json b/packages/db/country-data-allowlist.json index 32b15e189..2ec8588eb 100644 --- a/packages/db/country-data-allowlist.json +++ b/packages/db/country-data-allowlist.json @@ -88,6 +88,10 @@ { "path": "packages/db/migrations/0134_config_vehicle_value_class_params.sql", "justification": "Graine complémentaire du paramètre vehicle_default_value_class (08 BR-ACC-05 : classes STANDARD / PREMIUM / LUXE ; BOARD N-83 : classe d'un véhicule que ni la variante du catalogue ni une règle de marque ou de modèle ne classe, attribuée à la publication), valeurs PROPOSÉES PA / PY (STANDARD, comme Turo), générée par apps/api/src/modules/cfg/internal/seed-sql.ts (renderParamSeedSql) depuis les données CFG ; le test seed-sql.test.ts échoue si le fichier diffère du rendu. 0009 est immuable (ADR-044, ADR-075). US-113, ADR-159." + }, + { + "path": "packages/db/migrations/0142_config_deposit_rail_params.sql", + "justification": "Graine complémentaire des paramètres des déclencheurs et des rails de la caution (08 BR-PAY-06 « Caution conditionnelle », « Mécanisme » ; 17 §7.2 ; ADR-108 : aucune caution par défaut, deposit_trigger_classes {LUXE}, deposit_young_driver_classes vide par DEC-FONDATEUR-21, risk_control_deployed faux), valeurs PROPOSÉES PA / PY, générée par apps/api/src/modules/cfg/internal/seed-sql.ts (renderParamSeedSql) depuis les données CFG ; le test seed-sql.test.ts échoue si le fichier diffère du rendu. 0009 est immuable (ADR-044, ADR-075). US-225, ADR-164." } ] } diff --git a/packages/db/migrations/0142_config_deposit_rail_params.sql b/packages/db/migrations/0142_config_deposit_rail_params.sql new file mode 100644 index 000000000..c959c55fb --- /dev/null +++ b/packages/db/migrations/0142_config_deposit_rail_params.sql @@ -0,0 +1,49 @@ +-- 0142 — graine complémentaire : paramètres « deposit_always_required* » (US-225 ; 17 §7.2). +-- FICHIER GÉNÉRÉ depuis apps/api/src/modules/cfg/data/params.json par seed-sql.ts +-- (renderParamSeedSql) : ne pas l’éditer à la main (test seed-sql.test.ts). Appliquée sous +-- `migrator`. 0009 est immuable (ADR-044) : elle reste rendue sans ces paramètres (ADR-075). +-- Valeurs PROPOSÉES ; valid_from posé par la garde (platform.now()). +-- +-- Retour arrière (base sans dépendance) : DELETE des valeurs puis des définitions dont la clé +-- commence par « deposit_always_required » ou vaut deposit_fee_notice_h, deposit_on_risk_flag, deposit_reauth_lead_h, deposit_trigger_classes, deposit_young_driver_age, deposit_young_driver_classes, risk_control_deployed ; +-- jamais en production : nouvelle migration à la place. +INSERT INTO core.config_param_definition (key, type, unit, allowed_scopes, currency_bound, fail_mode, optional, go_live_switch, not_applicable_in, allowed_values, source_ref, status) VALUES + ('deposit_always_required', 'BOOL', NULL, ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 (déclencheur COUNTRY : caution imposée à tout trip du pays) ; 17 §7.2 ; ADR-108 ; absent ou illisible : déclencheur vrai, caution exigée (fail-closed)', 'PROPOSÉ comme Turo (ADR-108) : aucune caution par défaut'), + ('deposit_fee_notice_h', 'DURATION', 'h', ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 « Libération à heure fixe » : un frais annexe n’est capturé sur la caution que s’il a été notifié au voyageur au moins 48 h avant la décision (délai BR-REIMB-03) ; sinon débit MIT séparé', 'PROPOSÉ (08 BR-PAY-06, BR-REIMB-03)'), + ('deposit_on_risk_flag', 'BOOL', NULL, ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 (déclencheur RISK : trip signalé par le contrôle de risque, BR-VERIF-09, ADM-029) ; 17 §7.2 ; absent : déclencheur vrai (fail-closed)', 'PROPOSÉ comme Turo (vrai) ; sans effet tant que risk_control_deployed est faux'), + ('deposit_reauth_lead_h', 'DURATION', 'h', ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 « Mécanisme » rail (a) : ré-autorisation planifiée à auth_expiry − 24 h', 'PROPOSÉ (08 BR-PAY-06 ; la capacité SUPPORTS_REAUTH reste à valider avec le PSP)'), + ('deposit_trigger_classes', 'JSON', 'value_class_set', ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 (déclencheur CLASS : classe de valeur du véhicule, ADR-159) ; 17 §7.2 ; ADR-108 ; absent : toutes les classes déclenchent (fail-closed)', 'PROPOSÉ comme Turo ({LUXE}, équivalent Super Deluxe) ; à confirmer par le fondateur avant la mise en ligne'), + ('deposit_young_driver_age', 'INT', 'years', ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 (déclencheur AGE, seuil strict, plus jeune conducteur approuvé) ; 17 §7.2 ; ADR-108 ; absent : tout âge déclenche (fail-closed)', 'PROPOSÉ comme Turo (30 ans) ; sans effet tant que deposit_young_driver_classes est vide'), + ('deposit_young_driver_classes', 'JSON', 'value_class_set', ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 (déclencheur AGE : classes du catalogue concernées) ; 17 §7.2 ; absent : toutes les classes (fail-closed)', 'décidé (DEC-FONDATEUR-21, 2026-11-12) : ensemble vide, aucune caution liée à l’âge au PA et au PY'), + ('risk_control_deployed', 'BOOL', NULL, ARRAY['COUNTRY']::text[], false, 'BLOCK', false, false, '{}'::text[], NULL, '08 BR-PAY-06 (« contrôle non déployé ≠ en panne », risk_control_deployed) ; ADR-108 point 3 bis ; faux : RISK non évalué (risk_evaluated = false) ; absent : contrôle tenu pour déployé, une panne rend RISK vrai (fail-closed)', 'PROPOSÉ (faux tant que la caution sur signal de risque n’est pas branchée au contrôle de risque de US-209 ; changé seulement par l’administration avec journal)'); + +INSERT INTO core.config_param_value (key, country_code, scope_type, scope_id, network, value, change_reason) VALUES + ('deposit_always_required', 'PA', 'COUNTRY', NULL, NULL, 'false'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_always_required', 'PY', 'COUNTRY', NULL, NULL, 'false'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_fee_notice_h', 'PA', 'COUNTRY', NULL, NULL, '48'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_fee_notice_h', 'PY', 'COUNTRY', NULL, NULL, '48'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_on_risk_flag', 'PA', 'COUNTRY', NULL, NULL, 'true'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_on_risk_flag', 'PY', 'COUNTRY', NULL, NULL, 'true'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_reauth_lead_h', 'PA', 'COUNTRY', NULL, NULL, '24'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_reauth_lead_h', 'PY', 'COUNTRY', NULL, NULL, '24'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_trigger_classes', 'PA', 'COUNTRY', NULL, NULL, '["LUXE"]'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_trigger_classes', 'PY', 'COUNTRY', NULL, NULL, '["LUXE"]'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_young_driver_age', 'PA', 'COUNTRY', NULL, NULL, '30'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_young_driver_age', 'PY', 'COUNTRY', NULL, NULL, '30'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_young_driver_classes', 'PA', 'COUNTRY', NULL, NULL, '[]'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('deposit_young_driver_classes', 'PY', 'COUNTRY', NULL, NULL, '[]'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('risk_control_deployed', 'PA', 'COUNTRY', NULL, NULL, 'false'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'), + ('risk_control_deployed', 'PY', 'COUNTRY', NULL, NULL, 'false'::jsonb, 'graine US-225 : défauts PROPOSÉS (08 BR-PAY-06 ; 17 §7.2 ; ADR-108 ; ADR-164)'); + +-- Fail-closed : chaque paramètre du groupe a une valeur dans chaque pays déclaré. +DO $check$ +BEGIN + IF EXISTS (SELECT 1 FROM core.config_param_definition AS d + CROSS JOIN core.config_country AS c + WHERE (d.key LIKE 'deposit\_always\_required%' OR d.key = ANY (ARRAY['deposit_fee_notice_h', 'deposit_on_risk_flag', 'deposit_reauth_lead_h', 'deposit_trigger_classes', 'deposit_young_driver_age', 'deposit_young_driver_classes', 'risk_control_deployed']::text[])) + AND NOT EXISTS (SELECT 1 FROM core.config_param_value AS v + WHERE v.key = d.key AND v.country_code = c.code)) THEN + RAISE EXCEPTION 'graine : paramètre deposit_always_required* sans valeur pour un pays' USING ERRCODE = 'check_violation'; + END IF; +END +$check$; diff --git a/packages/db/test-migrations/9943_test_us225_deposit_rail_fixtures.sql b/packages/db/test-migrations/9943_test_us225_deposit_rail_fixtures.sql new file mode 100644 index 000000000..15c1d5d47 --- /dev/null +++ b/packages/db/test-migrations/9943_test_us225_deposit_rail_fixtures.sql @@ -0,0 +1,35 @@ +-- 9943 — fixtures des preuves des rails de la caution (US-225, migration 0142 ; ADR-164). +-- TESTS SEULEMENT. +-- +-- JAMAIS appliquée hors tests : seul le harnais ajoute test-migrations/, et seulement à la base +-- jetable principale `rueda_test_*` (le schéma test_fixture est créé par 9001). +-- +-- Nouvelle version d'un paramètre de la caution, valable à platform.now(), écrite dans la +-- transaction de l'appelant (app_api), qui l'ANNULE ensuite (comme us124_param_version). Clés +-- fermées : paramètres de déclencheur et de rail que lit PgDepositRailConfigReader, valeurs de +-- test de 08 (T57–T59, T69–T73). Jamais un interrupteur de mise en service : funds_holding_enabled +-- ne s'ouvre que par la procédure à deux personnes (test/support/golive.ts). Les attendus du test +-- viennent de 08 et des oracles de docs/specs/tools/, jamais de ces fixtures. +-- +-- Retour arrière : DROP FUNCTION test_fixture.us225_param_version(text, text, jsonb). + +CREATE FUNCTION test_fixture.us225_param_version(p_key text, p_country text, p_value jsonb) + RETURNS void + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +BEGIN + IF p_key NOT IN ('deposit_always_required', 'deposit_trigger_classes', 'deposit_young_driver_age', + 'deposit_young_driver_classes', 'deposit_on_risk_flag', 'risk_control_deployed', + 'deposit_amount', 'deposit_charge_cap', 'provider_max_hold_h', + 'deposit_reauth_lead_h') THEN + RAISE EXCEPTION 'clé hors liste : %', p_key USING ERRCODE = 'invalid_parameter_value'; + END IF; + INSERT INTO core.config_param_value (key, country_code, scope_type, value, change_reason) + VALUES (p_key, p_country, 'COUNTRY', p_value, 'test US-225 (annulé)'); +END +$fn$; + +REVOKE ALL ON FUNCTION test_fixture.us225_param_version(text, text, jsonb) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION test_fixture.us225_param_version(text, text, jsonb) TO app_api; diff --git a/packages/db/test/l0/l0-us225-deposit-rails.test.ts b/packages/db/test/l0/l0-us225-deposit-rails.test.ts new file mode 100644 index 000000000..55f3facf7 --- /dev/null +++ b/packages/db/test/l0/l0-us225-deposit-rails.test.ts @@ -0,0 +1,142 @@ +/** + * US-225 — paramètres des déclencheurs et des rails de la caution (migration 0142 ; ADR-108, + * ADR-164) sous les rôles de production `app_api` et `app_worker` (assertion L0-05 en tête de chaque + * connexion, withRole), en USD (PA) et en PYG (PY) : + * - **aucune caution par défaut** : chaque clé du groupe a sa valeur dans chaque pays, égale au + * fichier de paramètres et aux valeurs PROPOSÉES d'ADR-108 (pays faux, {LUXE}, aucune classe + * pour l'âge, contrôle de risque non déployé) ; définitions `BLOCK`, jamais un interrupteur ; + * - **aucun fonds de tiers détenu** : `funds_holding_enabled` reste fermé (`core.config_go_live`), + * `deposit_charge_cap` et `provider_max_hold_h` sans valeur (⇒ 0 : rail « débit puis + * remboursement » interdit, aucune pré-autorisation) et aucune capacité `SUPPORTS_REAUTH` + * validée dans la graine ; + * - lecture seule : `app_api` n'écrit aucun paramètre ; `app_anon` ne lit rien. + * Valeurs attendues : ADR-108 et 17 §7.2 (texte), le fichier `params.json` lu comme donnée. + */ +import { readFileSync } from 'node:fs'; +import { describe, expect, it } from 'vitest'; +import type pg from 'pg'; +import { withRole } from '../../src/testing/index.ts'; +import { COUNTRIES } from '../support/avl.ts'; + +interface ParamDoc { + params: Array<{ key: string; values: Record }>; +} +const PARAMS = JSON.parse( + readFileSync( + new URL('../../../../apps/api/src/modules/cfg/data/params.json', import.meta.url), + 'utf8', + ), +) as ParamDoc; +const seeded = (key: string, country: string): unknown => + PARAMS.params.find((p) => p.key === key)?.values[country]; + +/** Groupe de la graine 0142 et valeurs PROPOSÉES (ADR-108 point 2, 17 §7.2, DEC-FONDATEUR-21). */ +const PROPOSED: Readonly> = { + deposit_always_required: false, + deposit_trigger_classes: ['LUXE'], + deposit_young_driver_age: 30, + deposit_young_driver_classes: [], + deposit_on_risk_flag: true, + risk_control_deployed: false, + deposit_reauth_lead_h: 24, + deposit_fee_notice_h: 48, +}; +const KEYS = Object.keys(PROPOSED); + +async function current(client: pg.ClientBase, country: string): Promise> { + const { rows } = await client.query<{ key: string; value: unknown }>( + `SELECT DISTINCT ON (key) key, value + FROM core.config_param_value + WHERE country_code = $1 AND scope_type = 'COUNTRY' AND key = ANY ($2::text[]) + AND valid_from <= platform.now() AND (valid_to IS NULL OR valid_to > platform.now()) + ORDER BY key, valid_from DESC`, + [country, [...KEYS, 'deposit_charge_cap', 'provider_max_hold_h', 'deposit_amount']], + ); + return new Map(rows.map((r) => [r.key, r.value])); +} + +describe.each(COUNTRIES)('$country ($currency) — graine 0142 des rails de la caution', (c) => { + it.each(['app_api', 'app_worker'] as const)( + '%s : aucune caution par défaut, valeurs PROPOSÉES lues telles que params.json', + async (role) => { + await withRole(role, async (client) => { + const values = await current(client, c.country); + for (const key of KEYS) { + expect(values.get(key), key).toEqual(PROPOSED[key]); + expect(values.get(key), key).toEqual(seeded(key, c.country)); + } + // fail-closed : sans valeur, la caution exigée est refusée et le rail (b) interdit + expect(values.has('deposit_amount')).toBe(false); + expect(values.has('deposit_charge_cap')).toBe(false); + expect(values.has('provider_max_hold_h')).toBe(false); + }); + }, + ); + + it('app_api : funds_holding_enabled fermé ; aucune capacité SUPPORTS_REAUTH ni MAX_HOLD_HOURS validée dans la graine', async () => { + await withRole('app_api', async (client) => { + const sw = await client.query<{ open: boolean }>( + `SELECT core.config_go_live('funds_holding_enabled', $1) AS open`, + [c.country], + ); + expect(sw.rows[0]?.open).toBe(false); + const caps = await client.query<{ n: string }>( + `SELECT count(*)::text AS n FROM core.payment_psp_capability + WHERE country_code = $1 AND capability IN ('SUPPORTS_REAUTH', 'MAX_HOLD_HOURS') + AND status IN ('VALIDATED_SANDBOX', 'VALIDATED_CONTRACT')`, + [c.country], + ); + expect(caps.rows[0]?.n).toBe('0'); + }); + }); + + it('définitions : fail_mode BLOCK, portée pays, jamais un interrupteur de mise en service', async () => { + await withRole('app_worker', async (client) => { + const { rows } = await client.query<{ + key: string; + fail_mode: string; + allowed_scopes: string[]; + go_live_switch: boolean; + }>( + `SELECT key, fail_mode, allowed_scopes, go_live_switch + FROM core.config_param_definition WHERE key = ANY ($1::text[]) ORDER BY key`, + [KEYS], + ); + expect(rows.map((r) => r.key)).toEqual([...KEYS].sort()); + for (const r of rows) { + expect([r.fail_mode, r.allowed_scopes, r.go_live_switch], r.key).toEqual([ + 'BLOCK', + ['COUNTRY'], + false, + ]); + } + }); + }); + + // app_worker reçoit l'écriture de la configuration en TEST seulement (9100, gardes éprouvées) : + // seule la base de contrôle sans migrations de test le prouve pour lui (test/int/config-country) + it.each(['app_api'] as const)( + '%s : aucune écriture d’un paramètre de la caution (42501)', + async (role) => { + await withRole(role, async (client) => { + const error = await client + .query( + `INSERT INTO core.config_param_value (key, country_code, scope_type, value, change_reason) + VALUES ('deposit_always_required', $1, 'COUNTRY', 'true'::jsonb, 'test US-225')`, + [c.country], + ) + .catch((e: unknown) => e as { code?: string }); + expect((error as { code?: string }).code).toBe('42501'); + }); + }, + ); + + it('app_anon : aucune lecture des paramètres de la caution (42501)', async () => { + await withRole('app_anon', async (client) => { + const error = await client + .query(`SELECT value FROM core.config_param_value WHERE key = 'deposit_trigger_classes'`) + .catch((e: unknown) => e as { code?: string }); + expect((error as { code?: string }).code).toBe('42501'); + }); + }); +}); diff --git a/packages/fake-adapters/src/psp/fake-psp.ts b/packages/fake-adapters/src/psp/fake-psp.ts index 16208002a..a1eeaf020 100644 --- a/packages/fake-adapters/src/psp/fake-psp.ts +++ b/packages/fake-adapters/src/psp/fake-psp.ts @@ -270,7 +270,13 @@ export class FakePsp { const order = this.#order(req.reference); return this.#execute('VOID', req.merchantReference, req, () => { this.#require('SUPPORTS_VOID', order.method); - if (order.status !== 'AUTHORIZED' || order.capturedMinor > 0n || order.voided) { + // US-225 (08 E3 repli 1, BR-PAY-06, T57) : après une capture PARTIELLE, le VOID libère le + // reste de l'autorisation ; une autorisation entièrement capturée ne s'annule plus + if ( + order.status !== 'AUTHORIZED' || + order.capturedMinor >= order.amountMinor || + order.voided + ) { throw new FakePspError('INVALID_REQUEST', `annulation impossible : ${order.status}`); } return () => { diff --git a/packages/fake-adapters/test/psp/fake-psp.test.ts b/packages/fake-adapters/test/psp/fake-psp.test.ts index 35b9cead4..e7ff15117 100644 --- a/packages/fake-adapters/test/psp/fake-psp.test.ts +++ b/packages/fake-adapters/test/psp/fake-psp.test.ts @@ -385,6 +385,47 @@ describe('capacités simulées : inconnue ou non validée = non (17 §2.8)', () legs: LEGS_100, }).status, ).toBe('SUCCEEDED'); + // autorisation entièrement capturée : plus de VOID possible + expectFakeError( + () => psp.void({ merchantReference: 'void-after-full', reference: order.reference }), + 'INVALID_REQUEST', + ); + }); + + it('US-225 (08 E3 repli 1, T57) : capture partielle puis VOID du reste ; plus de capture ensuite', () => { + const { psp } = setup(); + const order = psp.createOrder({ + merchantReference: 'deposit:d1:AUTH:i1:a1', + method: 'CARD', + amountMinor: 100n, + currency: CUR, + legs: legs(0n, 0n, 0n, 100n), + capture: 'MANUAL', + }); + psp.customerPays(order.reference); + psp.capture({ + merchantReference: 'deposit:d1:CAPTURE:i1:a1', + reference: order.reference, + amountMinor: 4n, + currency: CUR, + legs: legs(4n, 0n, 0n, 0n), + }); + expect( + psp.void({ merchantReference: 'deposit:d1:VOID:i1:a1', reference: order.reference }).status, + ).toBe('SUCCEEDED'); + expectFakeError( + () => + psp.capture({ + merchantReference: 'deposit:d1:CAPTURE:i2:a1', + reference: order.reference, + amountMinor: 1n, + currency: CUR, + legs: legs(1n, 0n, 0n, 0n), + }), + 'INVALID_REQUEST', + ); + // seule la capture a déplacé des fonds : 4, sur la jambe HOST + expect(psp.movements().map((m) => [m.operation, m.amountMinor])).toEqual([['CAPTURE', 4n]]); }); it('recherche par clé du marchand sans capacité ⇒ UNSUPPORTED ; par référence du PSP : permise', () => { diff --git a/packages/i18n/src/catalogs/en.ts b/packages/i18n/src/catalogs/en.ts index b8fc37aa2..ad71ab843 100644 --- a/packages/i18n/src/catalogs/en.ts +++ b/packages/i18n/src/catalogs/en.ts @@ -103,6 +103,13 @@ export const EN_MESSAGES = { 'web.deposit.contest': 'Review and respond', 'web.deposit.debitWarning': "The deposit is charged and then refunded. We'll issue the refund on {date}; your bank may take 3 to 10 business days to show it.", + // US-225 (ADR-164) : refus de la caution avant le paiement (10b UX-24 ; 08 BR-PAY-06, T59) + 'web.deposit.unavailable': { + one: "We can't place the deposit on your card for these dates. You can book up to {count} day.", + other: + "We can't place the deposit on your card for these dates. You can book up to {count} days.", + }, + 'web.deposit.unavailableNone': "For now, we can't place the deposit on your card for this car.", 'web.catalog.title': 'Component library', 'web.catalog.intro': 'Every component in each of its states. Pick the language, theme and width to review them.', diff --git a/packages/i18n/src/catalogs/es.ts b/packages/i18n/src/catalogs/es.ts index 6a6e6a22a..78fece706 100644 --- a/packages/i18n/src/catalogs/es.ts +++ b/packages/i18n/src/catalogs/es.ts @@ -111,6 +111,14 @@ export const ES_MESSAGES = { 'web.deposit.contest': 'Revisar y responder', 'web.deposit.debitWarning': 'El depósito se cobra y luego se reembolsa. Emitiremos el reembolso el {date}; tu banco puede tardar de 3 a 10 días hábiles en mostrarlo.', + // US-225 (ADR-164) : refus de la caution avant le paiement (10b UX-24 ; 08 BR-PAY-06, T59) + 'web.deposit.unavailable': { + one: 'Para estas fechas no podemos tomar el depósito en tu tarjeta. Puedes reservar hasta {count} día.', + other: + 'Para estas fechas no podemos tomar el depósito en tu tarjeta. Puedes reservar hasta {count} días.', + }, + 'web.deposit.unavailableNone': + 'Por ahora no podemos tomar el depósito en tu tarjeta para este auto.', // Vitrine de la bibliothèque (US-032) : outil interne de revue du design, PROPOSÉ. 'web.catalog.title': 'Biblioteca de componentes', 'web.catalog.intro': diff --git a/packages/i18n/src/catalogs/fr.ts b/packages/i18n/src/catalogs/fr.ts index c9a0f0b0f..d34613eed 100644 --- a/packages/i18n/src/catalogs/fr.ts +++ b/packages/i18n/src/catalogs/fr.ts @@ -117,6 +117,14 @@ export const FR_MESSAGES = { 'web.deposit.contest': 'Vérifier et répondre', 'web.deposit.debitWarning': 'Le dépôt est débité puis remboursé. Nous émettrons le remboursement le {date} ; ta banque peut mettre de 3 à 10 jours ouvrés à l’afficher.', + // US-225 (ADR-164) : refus de la caution avant le paiement (10b UX-24 ; 08 BR-PAY-06, T59) + 'web.deposit.unavailable': { + one: 'Pour ces dates, nous ne pouvons pas bloquer le dépôt sur ta carte. Tu peux réserver jusqu’à {count} jour.', + other: + 'Pour ces dates, nous ne pouvons pas bloquer le dépôt sur ta carte. Tu peux réserver jusqu’à {count} jours.', + }, + 'web.deposit.unavailableNone': + 'Pour l’instant, nous ne pouvons pas bloquer le dépôt sur ta carte pour cette voiture.', 'web.catalog.title': 'Bibliothèque de composants', 'web.catalog.intro': 'Chaque composant dans ses états. Choisis la langue, le thème et la largeur pour les passer en revue.', diff --git a/packages/i18n/src/catalogs/index.ts b/packages/i18n/src/catalogs/index.ts index c853d9103..312b32699 100644 --- a/packages/i18n/src/catalogs/index.ts +++ b/packages/i18n/src/catalogs/index.ts @@ -252,8 +252,11 @@ export type { Catalog, Message, PluralCategory, PluralMessage, VersionedCatalog 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). + Version 82 (la 79 qui lui était réservée a été dépassée par la 81 d’US-224f) : rails de la caution (US-225, ADR-164) : `web.deposit.unavailable` (refus avant le + paiement avec la durée possible, texte de 10b UX-24) et `web.deposit.unavailableNone` (aucune + durée possible, PROPOSÉ), affichés par l'écran S05 quand il branchera la décision de la caution. */ -export const CATALOG_VERSION = 81; +export const CATALOG_VERSION = 82; /** 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 2b4e036e8..7783b88bf 100644 --- a/packages/i18n/src/catalogs/pt.ts +++ b/packages/i18n/src/catalogs/pt.ts @@ -115,6 +115,14 @@ export const PT_MESSAGES = { 'web.deposit.contest': 'Conferir e responder', 'web.deposit.debitWarning': 'A caução é cobrada e depois devolvida. Faremos o estorno em {date}; seu banco pode levar de 3 a 10 dias úteis para mostrar o valor.', + // US-225 (ADR-164) : refus de la caution avant le paiement (10b UX-24 ; 08 BR-PAY-06, T59) + 'web.deposit.unavailable': { + one: 'Para essas datas não conseguimos bloquear a caução no seu cartão. Você pode reservar até {count} dia.', + other: + 'Para essas datas não conseguimos bloquear a caução no seu cartão. Você pode reservar até {count} dias.', + }, + 'web.deposit.unavailableNone': + 'Por enquanto, não conseguimos bloquear a caução no seu cartão para este carro.', 'web.catalog.title': 'Biblioteca de componentes', 'web.catalog.intro': 'Cada componente em todos os seus estados. Escolha o idioma, o tema e a largura para revisar.',