diff --git a/apps/api/src/modules/fin/README.md b/apps/api/src/modules/fin/README.md index e7593dd5..a35cc7c6 100644 --- a/apps/api/src/modules/fin/README.md +++ b/apps/api/src/modules/fin/README.md @@ -17,7 +17,11 @@ FIN ne calcule ni le règlement ni les jambes (STL), et ne déplace pas de fonds ## Rapprochement de l'argent (US-047, ADR-087) -`internal/money-reconciliation.ts` : tâche périodique du travailleur `reconciliation` (24 h, PROPOSÉ ; déclarée dans `apps/api/src/worker-tasks.ts`). En lecture seule, sur toute la base, elle relit les versions de règlement (`core.settlement_settlement`, `core.settlement_settlement_leg`) et les soldes par jambe (`core.settlement_trip_leg_balance`) : politiques `worker_money_read` de 0027 et 0036. Onze contrôles (codes PROPOSÉS) : `SETTLEMENT_LEGS_INCOMPLETE`, `SETTLEMENT_LEG_NEGATIVE`, `SETTLEMENT_LEGS_SUM`, `SETTLEMENT_HOST_LEG`, `SETTLEMENT_REFUND_BALANCE`, `SETTLEMENT_VARIATIONS_REFUND`, `SETTLEMENT_VERSION_CHAIN`, `LEG_BALANCE_OVERDRAWN` et, depuis US-217a (ADR-161), `TRIP_CAPTURE_LEGS` (Σ capturé = Σ des encaissements portés = Σ de leurs jambes), `TRIP_SETTLED_TOTAL` (total payé de la version en tête = encaissé), `STATEMENT_HOST_LEG` (jambe HOST du relevé de l'hôte = jambe HOST attendue, lue d'une autre source), sur les faits par trip de `core.finance_trip_leg_facts()` (0137 ; requête `tripLegFactsSql`, source `TRIP_LEG_FACTS_SOURCE`, montants et pays seulement). Leurs règles et leurs sources (08 E1, E4, E7 ; 17 §2.9, §3.2.8) sont dans l'en-tête du fichier. Le rapport ne contient que des comptes par contrôle et par pays. Tout écart lève une alerte P1 `FIN_MONEY_RECONCILIATION` par pays (runbook `docs/ops/MONITORING.md`). Un contexte autre que ce travailleur lève `MoneyReconciliationContractError` (jamais de zéros trompeurs). Les requêtes d'agrégat (`settlementAggregatesSql`, `legBalanceAggregatesSql`) lisent leurs tables en CTE (`SETTLEMENT_SOURCE`, `SETTLEMENT_LEG_SOURCE`, `LEG_BALANCE_SOURCE`) : le test d'intégration y ajoute une ligne en écart pour prouver la détection sur PostgreSQL réel, et la tâche n'utilise que les tables. +`internal/money-reconciliation.ts` : tâche périodique du travailleur `reconciliation` (24 h, PROPOSÉ ; déclarée dans `apps/api/src/worker-tasks.ts`). En lecture seule, sur toute la base, elle relit les versions de règlement (`core.settlement_settlement`, `core.settlement_settlement_leg`) et les soldes par jambe (`core.settlement_trip_leg_balance`) : politiques `worker_money_read` de 0027 et 0036. Onze contrôles (codes PROPOSÉS) : `SETTLEMENT_LEGS_INCOMPLETE`, `SETTLEMENT_LEG_NEGATIVE`, `SETTLEMENT_LEGS_SUM`, `SETTLEMENT_HOST_LEG`, `SETTLEMENT_REFUND_BALANCE`, `SETTLEMENT_VARIATIONS_REFUND`, `SETTLEMENT_VERSION_CHAIN`, `LEG_BALANCE_OVERDRAWN` et, depuis US-217a (ADR-161), `TRIP_CAPTURE_LEGS` (Σ capturé = Σ des encaissements portés = Σ de leurs jambes), `TRIP_SETTLED_TOTAL` (total payé de la version en tête = encaissé), `STATEMENT_HOST_LEG` (jambe HOST du relevé de l'hôte = jambe HOST attendue, lue d'une autre source), sur les faits par trip de `core.finance_trip_leg_facts()` (0137 ; requête `tripLegFactsSql`, source `TRIP_LEG_FACTS_SOURCE`, montants et pays seulement). Leurs règles et leurs sources (08 E1, E4, E7 ; 17 §2.9, §3.2.8) sont dans l'en-tête du fichier. Le rapport ne contient que des comptes par contrôle et par pays. Tout écart lève une alerte P1 `FIN_MONEY_RECONCILIATION` par pays (runbook `docs/ops/MONITORING.md`). Un contexte autre que ce travailleur lève `MoneyReconciliationContractError` (jamais de zéros trompeurs). Les requêtes d'agrégat (`settlementAggregatesSql`, `legBalanceAggregatesSql`) lisent leurs tables en CTE (`SETTLEMENT_SOURCE`, `SETTLEMENT_LEG_SOURCE`, `LEG_BALANCE_SOURCE`) : le test d'intégration y ajoute une ligne en écart pour prouver la détection sur PostgreSQL réel, et la tâche n'utilise que les tables. Depuis US-227, quatorze contrôles (section suivante). + +## Jambe de l'assureur au rapprochement (US-227, ADR-165) + +Trois contrôles s'ajoutent au rapprochement nocturne, lus de `core.finance_insurer_ledger_facts()` (0143, travailleur `reconciliation`) : `INSURER_LEDGER_COLLECTION` (écritures d'encaissement du registre = jambes `INSURER` des encaissements portés), `INSURER_LEDGER_SETTLEMENT` (écritures de règlement = variations `INSURER` stockées), `INSURER_BORDEREAU_OVERBILLED` (porté par un bordereau émis ≤ prime due), à l'unité mineure, par pays. Une écriture sans contrat d'assureur est comptée (`examined.insurerUnattributed`), pas un écart. ## Reçu des gains, reçu du trip fee, relevé mensuel (US-217 partie 217a, ADR-161) diff --git a/apps/api/src/modules/fin/index.ts b/apps/api/src/modules/fin/index.ts index 6238bf43..7e523581 100644 --- a/apps/api/src/modules/fin/index.ts +++ b/apps/api/src/modules/fin/index.ts @@ -35,8 +35,14 @@ export { TRIP_LEG_FACTS_SOURCE, tripLegFactsSql, tripLegViolations, + // US-227 (ADR-165) : faits de la jambe assureur, lus de core.finance_insurer_ledger_facts() + INSURER_LEDGER_FACTS_SOURCE, + insurerLedgerFactsSql, + insurerLedgerViolations, + parseInsurerLedgerFactRow, } from './internal/money-reconciliation.js'; export type { + InsurerLedgerFact, MoneyReconciliationCheck, MoneyReconciliationReport, TripLegFact, diff --git a/apps/api/src/modules/fin/internal/money-reconciliation.test.ts b/apps/api/src/modules/fin/internal/money-reconciliation.test.ts index 5a716e68..8441d882 100644 --- a/apps/api/src/modules/fin/internal/money-reconciliation.test.ts +++ b/apps/api/src/modules/fin/internal/money-reconciliation.test.ts @@ -14,12 +14,15 @@ import { assertSafeAlert } from '../../bus/index.js'; import { alertOnViolations, evaluateMoneyReconciliation, + INSURER_LEDGER_FACTS_SQL, + insurerLedgerViolations, LEG_BALANCE_AGGREGATES_SQL, legBalanceOverdrawn, MONEY_RECONCILIATION_CHECKS, MONEY_RECONCILIATION_PERIOD_SECONDS, MONEY_RECONCILIATION_WORKER, MoneyReconciliationContractError, + parseInsurerLedgerFactRow, parseLegBalanceRow, parseSettlementRow, parseTripLegFactRow, @@ -33,6 +36,7 @@ import { tripLegViolations, } from './money-reconciliation.js'; import type { + InsurerLedgerFact, LegBalanceAggregate, MoneyReconciliationCheck, SettlementAggregate, @@ -113,13 +117,21 @@ describe('US-047 — rapprochement de l’argent : agrégats cohérents', () => expect(legBalanceOverdrawn(balanceOf(c))).toBe(false); }); - it('rapport vide : onze contrôles à 0, rien examiné', () => { + it('rapport vide : quatorze contrôles à 0, rien examiné', () => { const r = evaluateMoneyReconciliation([], []); expect(Object.keys(r.checks)).toEqual([...MONEY_RECONCILIATION_CHECKS]); - expect(MONEY_RECONCILIATION_CHECKS).toHaveLength(11); + // US-227 : trois contrôles de la jambe assureur s'ajoutent aux onze d'US-047 et d'US-217a + expect(MONEY_RECONCILIATION_CHECKS).toHaveLength(14); expect(r.violations).toBe(0n); - // US-217a : les faits par trip sont un troisième ensemble examiné (vide ici) - expect(r.examined).toEqual({ settlements: {}, legBalances: {}, trips: {} }); + // US-217a : les faits par trip sont un troisième ensemble examiné ; US-227 : la jambe + // assureur un quatrième, et les écritures sans contrat sont comptées à part (vides ici) + expect(r.examined).toEqual({ + settlements: {}, + legBalances: {}, + trips: {}, + insurerTrips: {}, + insurerUnattributed: {}, + }); }); }); @@ -419,6 +431,139 @@ describe('US-217a — invariant par jambe : chaque contrôle détecte son écart }); }); +/** + * Jambe assureur d'un trip (US-227) tirée des vecteurs : capture TJ01 / TJ08a (jambe INSURER de + * l'encaissement porté), variation TJ02b / TJ08b de la version 1 ; prime due = capture + variation. + */ +function insurerFactOf(c: (typeof CASES)[number]): InsurerLedgerFact { + const collected = legVector(golden, c.capture).legsMinor.INSURER; + const varied = legVector(golden, c.variation).legsMinor.INSURER; + return { + country: c.country, + collectedEntries: collected, + collectedLegs: collected, + settledEntries: varied, + settledVariations: varied, + billed: 0n, + due: collected + varied, + unattributed: false, + }; +} + +/** Trip terminé sans règlement, porté en entier par un bordereau émis. */ +function billedFactOf(c: (typeof CASES)[number]): InsurerLedgerFact { + const collected = legVector(golden, c.capture).legsMinor.INSURER; + return { + ...insurerFactOf(c), + settledEntries: 0n, + settledVariations: 0n, + billed: collected, + due: collected, + }; +} + +const INSURER_CORRUPTIONS: readonly [ + string, + (f: InsurerLedgerFact) => InsurerLedgerFact, + readonly MoneyReconciliationCheck[], +][] = [ + [ + 'écriture d’encaissement ≠ jambe INSURER portée (une unité mineure)', + (f) => ({ ...f, collectedEntries: f.collectedEntries + 1n }), + ['INSURER_LEDGER_COLLECTION'], + ], + [ + 'variation INSURER stockée sans son écriture de règlement (une unité mineure)', + (f) => ({ ...f, settledVariations: f.settledVariations - 1n }), + ['INSURER_LEDGER_SETTLEMENT'], + ], + [ + 'bordereau émis au-delà de la prime due (une unité mineure)', + (f) => ({ ...f, billed: f.due + 1n }), + ['INSURER_BORDEREAU_OVERBILLED'], + ], +]; + +describe('US-227 — jambe assureur : le registre est le miroir des jambes INSURER stockées (chaque pays configuré)', () => { + it.each(CASES)( + '$country : trip annulé (TJ02b / TJ08b) et trip porté par un bordereau ⇒ aucun écart', + (c) => { + expect(insurerFactOf(c).due).toBe(0n); + expect(insurerLedgerViolations(insurerFactOf(c))).toEqual([]); + expect(insurerLedgerViolations(billedFactOf(c))).toEqual([]); + const r = evaluateMoneyReconciliation([], [], [], [insurerFactOf(c), billedFactOf(c)]); + expect(r.violations).toBe(0n); + expect(r.examined.insurerTrips).toEqual({ [c.country]: 2 }); + expect(r.examined.insurerUnattributed).toEqual({}); + }, + ); + + for (const c of CASES) { + it.each(INSURER_CORRUPTIONS)(`${c.country} : %s`, (_label, corrupt, expected) => { + const bad = corrupt(billedFactOf(c)); + expect(insurerLedgerViolations(bad)).toEqual(expected); + const r = evaluateMoneyReconciliation([], [], [], [billedFactOf(c), bad]); + for (const check of expected) { + expect(r.checks[check]).toEqual({ total: 1n, byCountry: { [c.country]: 1n } }); + } + expect(r.violations).toBe(BigInt(expected.length)); + }); + } + + it.each(CASES)( + '$country : aucun bordereau émis et prime due négative (capture hors registre) ⇒ aucun écart', + (c) => { + const base = insurerFactOf(c); + const f = { ...base, collectedEntries: 0n, collectedLegs: 0n, due: base.settledEntries }; + expect(f.due < 0n).toBe(true); + expect(insurerLedgerViolations(f)).toEqual([]); + }, + ); + + it.each(CASES)('$country : écriture sans contrat d’assureur ⇒ comptée, pas un écart', (c) => { + const r = evaluateMoneyReconciliation( + [], + [], + [], + [{ ...insurerFactOf(c), unattributed: true }], + ); + expect(r.violations).toBe(0n); + expect(r.examined.insurerUnattributed).toEqual({ [c.country]: 1 }); + }); + + it('lecture fail-closed : montant illisible, booléen ou pays invalide ⇒ erreur de contrat', () => { + const row = { + country: FIRST.country, + collected_entries: '2550', + collected_legs: '2550', + settled_entries: '-2550', + settled_variations: '-2550', + billed: '0', + due: '0', + unattributed: false, + }; + expect(parseInsurerLedgerFactRow(row)).toEqual({ + country: FIRST.country, + collectedEntries: 2550n, + collectedLegs: 2550n, + settledEntries: -2550n, + settledVariations: -2550n, + billed: 0n, + due: 0n, + unattributed: false, + }); + for (const bad of [ + { ...row, collected_entries: 2550 }, + { ...row, due: '1.5' }, + { ...row, unattributed: 'false' }, + { ...row, country: FIRST.country.toLowerCase() }, + { ...row, billed: null }, + ]) { + expect(() => parseInsurerLedgerFactRow(bad)).toThrow(MoneyReconciliationContractError); + } + }); +}); + /** Transaction programmée : contexte, puis lignes de règlement et de solde. */ class ScriptedSql implements SqlClient { readonly texts: string[] = []; @@ -540,6 +685,7 @@ describe('US-047 — tâche du travailleur reconciliation', () => { SETTLEMENT_AGGREGATES_SQL, LEG_BALANCE_AGGREGATES_SQL, TRIP_LEG_FACTS_SQL, + INSURER_LEDGER_FACTS_SQL, ]); expect(lines).toHaveLength(1); expect(JSON.parse(lines[0] ?? '{}')).toMatchObject({ level: 'error', violations: '1' }); @@ -554,7 +700,12 @@ describe('US-047 — tâche du travailleur reconciliation', () => { }); it('les requêtes ne lisent ni horloge ni identifiant rendu (lecture seule)', () => { - for (const q of [SETTLEMENT_AGGREGATES_SQL, LEG_BALANCE_AGGREGATES_SQL, TRIP_LEG_FACTS_SQL]) { + for (const q of [ + SETTLEMENT_AGGREGATES_SQL, + LEG_BALANCE_AGGREGATES_SQL, + TRIP_LEG_FACTS_SQL, + INSURER_LEDGER_FACTS_SQL, + ]) { expect(q).not.toMatch(/\b(now|current_timestamp|clock_timestamp)\b/i); expect(q).not.toMatch(/\b(INSERT|UPDATE|DELETE|TRUNCATE)\b/); // seules colonnes rendues : pays, versions, drapeaux et montants diff --git a/apps/api/src/modules/fin/internal/money-reconciliation.ts b/apps/api/src/modules/fin/internal/money-reconciliation.ts index b5063c30..f486b39c 100644 --- a/apps/api/src/modules/fin/internal/money-reconciliation.ts +++ b/apps/api/src/modules/fin/internal/money-reconciliation.ts @@ -17,6 +17,9 @@ * | `TRIP_CAPTURE_LEGS` | trip encaissé : Σ capturé des soldes = Σ des encaissements portés = Σ de leurs jambes | 19 US-217 critère 3 ; 08 E7 règles 1, 8 | * | `TRIP_SETTLED_TOTAL` | trip encaissé et réglé : total payé de la version en tête = Σ des encaissements portés | 19 US-217 critère 3 ; 17 §3.2.8 | * | `STATEMENT_HOST_LEG` | jambe HOST du relevé = jambe HOST attendue (en-tête de la version en tête, sinon jambes HOST des encaissements, sinon solde capturé) | 19 US-217 critère 3 ; 08 E7 | + * | `INSURER_LEDGER_COLLECTION` | par trip : Σ écritures d'encaissement du registre de l'assureur = Σ jambes INSURER des encaissements portés, à l'unité mineure | 19 US-227 ; 08 E7 règle 1 ; 17 §2.9 | + * | `INSURER_LEDGER_SETTLEMENT` | par trip : Σ écritures de règlement du registre = Σ variations INSURER des versions stockées | 19 US-227 ; 08 E7 règle 3, E4 | + * | `INSURER_BORDEREAU_OVERBILLED` | par trip : Σ porté par des bordereaux émis ≤ prime due (Σ écritures) | 19 US-227 ; 08 E7 règle 3 bis | * * La base refuse déjà la plupart de ces écarts (contraintes et trigger différé * `settlement_balanced`, 0027) : ce contrôle est le filet indépendant que demande 19 §1.8, au même @@ -29,7 +32,10 @@ * les opérations de paiement et le relevé de l'hôte ne lui sont pas lisibles autrement) ; la * requête n'en garde que des montants et un pays, le rapport que des comptes. Les deux premiers ne * portent que sur un trip dont un encaissement est porté (un solde posé sans opération n'a rien à - * comparer). + * comparer). Les trois contrôles de la jambe assureur (US-227, ADR-165) lisent + * `core.finance_insurer_ledger_facts()` (0143, même garde) ; une écriture sans contrat d'assureur + * (aucun contrat en vigueur à la réservation) n'est pas un écart mais est COMPTÉE + * (`examined.insurerUnattributed`) : elle n'entre dans aucun bordereau (GL-42). * * Fail-closed : un contexte autre que le travailleur `reconciliation` (la RLS ne montrerait rien et * le contrôle rendrait des zéros trompeurs), un compte illisible ou un montant hors du format @@ -56,6 +62,9 @@ export const MONEY_RECONCILIATION_CHECKS = [ 'TRIP_CAPTURE_LEGS', 'TRIP_SETTLED_TOTAL', 'STATEMENT_HOST_LEG', + 'INSURER_LEDGER_COLLECTION', + 'INSURER_LEDGER_SETTLEMENT', + 'INSURER_BORDEREAU_OVERBILLED', ] as const; export type MoneyReconciliationCheck = (typeof MONEY_RECONCILIATION_CHECKS)[number]; @@ -114,6 +123,25 @@ export interface TripLegFact { readonly statementHost: bigint | null; } +/** Faits de la jambe assureur d'un trip (`core.finance_insurer_ledger_facts()`, 0143). */ +export interface InsurerLedgerFact { + readonly country: string; + /** Σ écritures d'encaissement du registre de l'assureur. */ + readonly collectedEntries: bigint; + /** Σ jambes INSURER des encaissements portés (CAPTURE, MIT_CHARGE, DEBT_COLLECTION). */ + readonly collectedLegs: bigint; + /** Σ écritures de règlement du registre. */ + readonly settledEntries: bigint; + /** Σ variations INSURER des versions de règlement stockées. */ + readonly settledVariations: bigint; + /** Σ porté par des bordereaux émis (rédigés par la commande). */ + readonly billed: bigint; + /** Prime due : Σ des écritures du trip. */ + readonly due: bigint; + /** Une écriture au moins sans contrat d'assureur. */ + readonly unattributed: boolean; +} + export interface CheckCount { readonly total: bigint; /** Violations par pays (seuls les pays en écart). */ @@ -128,6 +156,10 @@ export interface MoneyReconciliationReport { readonly settlements: Readonly>; readonly legBalances: Readonly>; readonly trips: Readonly>; + /** Trips dont la jambe assureur est examinée (US-227). */ + readonly insurerTrips: Readonly>; + /** Trips dont une écriture du registre n'a pas de contrat d'assureur (comptés, pas un écart). */ + readonly insurerUnattributed: Readonly>; }; } @@ -161,6 +193,11 @@ export const TRIP_LEG_FACTS_SOURCE = `SELECT country_code, captured_minor, colle head_total_paid_minor, expected_host_minor, statement_host_minor FROM core.finance_trip_leg_facts()`; +/** Faits de la jambe assureur (US-227, 0143) : montants et pays seulement. */ +export const INSURER_LEDGER_FACTS_SOURCE = `SELECT country_code, collected_entries_minor, collected_legs_minor, + settled_entries_minor, settled_variations_minor, billed_minor, due_minor, unattributed + FROM core.finance_insurer_ledger_facts()`; + /** * Une ligne par version de règlement : en-tête, version remplacée et agrégats des jambes. Montants * en texte (bigint exact, jamais un nombre JavaScript). Aucune donnée personnelle, aucun identifiant @@ -231,10 +268,26 @@ SELECT f.country_code AS country, FROM f`; } +/** Une ligne par trip dont la jambe assureur est tenue (US-227). */ +export function insurerLedgerFactsSql(facts: string = INSURER_LEDGER_FACTS_SOURCE): string { + return ` +WITH f AS (${facts}) +SELECT f.country_code AS country, + f.collected_entries_minor::text AS collected_entries, + f.collected_legs_minor::text AS collected_legs, + f.settled_entries_minor::text AS settled_entries, + f.settled_variations_minor::text AS settled_variations, + f.billed_minor::text AS billed, + f.due_minor::text AS due, + f.unattributed + FROM f`; +} + /** Requêtes de la tâche de production (sources réelles seulement). */ export const SETTLEMENT_AGGREGATES_SQL = settlementAggregatesSql(); export const LEG_BALANCE_AGGREGATES_SQL = legBalanceAggregatesSql(); export const TRIP_LEG_FACTS_SQL = tripLegFactsSql(); +export const INSURER_LEDGER_FACTS_SQL = insurerLedgerFactsSql(); const MINOR = /^-?[0-9]{1,19}$/; const COUNTRY = /^[A-Z]{2}$/; @@ -321,6 +374,34 @@ export function parseTripLegFactRow(row: Record): TripLegFact { }; } +/** Lit une ligne de `INSURER_LEDGER_FACTS_SQL` ; fail-closed. */ +export function parseInsurerLedgerFactRow(row: Record): InsurerLedgerFact { + return { + country: country(row.country), + collectedEntries: minor(row.collected_entries, 'collected_entries'), + collectedLegs: minor(row.collected_legs, 'collected_legs'), + settledEntries: minor(row.settled_entries, 'settled_entries'), + settledVariations: minor(row.settled_variations, 'settled_variations'), + billed: minor(row.billed, 'billed'), + due: minor(row.due, 'due'), + unattributed: bool(row.unattributed, 'unattributed'), + }; +} + +/** + * Contrôles en écart de la jambe assureur d'un trip (fonction pure, US-227) : le registre est le + * miroir exact des jambes INSURER stockées, à l'unité mineure ; aucun bordereau émis ne porte plus + * que la prime due. + */ +export function insurerLedgerViolations(f: InsurerLedgerFact): MoneyReconciliationCheck[] { + const out: MoneyReconciliationCheck[] = []; + if (f.collectedEntries !== f.collectedLegs) out.push('INSURER_LEDGER_COLLECTION'); + if (f.settledEntries !== f.settledVariations) out.push('INSURER_LEDGER_SETTLEMENT'); + // un trip sans bordereau émis n'est jamais « surfacturé » (prime due nulle ou négative admise) + if (f.billed > 0n && f.billed > f.due) out.push('INSURER_BORDEREAU_OVERBILLED'); + return out; +} + /** * Contrôles en écart d'un trip (fonction pure, US-217a) : Σ jambes de chaque trip = montant * encaissé, à l'unité mineure près ; jambe HOST du relevé = jambe HOST attendue. Une jambe HOST @@ -387,6 +468,7 @@ export function evaluateMoneyReconciliation( settlements: readonly SettlementAggregate[], legBalances: readonly LegBalanceAggregate[], tripFacts: readonly TripLegFact[] = [], + insurerFacts: readonly InsurerLedgerFact[] = [], ): MoneyReconciliationReport { const totals = new Map>( MONEY_RECONCILIATION_CHECKS.map((c) => [c, new Map()]), @@ -399,6 +481,8 @@ export function evaluateMoneyReconciliation( const examinedSettlements: Record = {}; const examinedBalances: Record = {}; const examinedTrips: Record = {}; + const examinedInsurer: Record = {}; + const unattributed: Record = {}; for (const s of settlements) { examinedSettlements[s.country] = (examinedSettlements[s.country] ?? 0) + 1; for (const check of settlementViolations(s)) hit(check, s.country); @@ -411,6 +495,11 @@ export function evaluateMoneyReconciliation( examinedTrips[f.country] = (examinedTrips[f.country] ?? 0) + 1; for (const check of tripLegViolations(f)) hit(check, f.country); } + for (const f of insurerFacts) { + examinedInsurer[f.country] = (examinedInsurer[f.country] ?? 0) + 1; + if (f.unattributed) unattributed[f.country] = (unattributed[f.country] ?? 0) + 1; + for (const check of insurerLedgerViolations(f)) hit(check, f.country); + } let violations = 0n; const checks = Object.fromEntries( MONEY_RECONCILIATION_CHECKS.map((c) => { @@ -429,6 +518,8 @@ export function evaluateMoneyReconciliation( settlements: examinedSettlements, legBalances: examinedBalances, trips: examinedTrips, + insurerTrips: examinedInsurer, + insurerUnattributed: unattributed, }, }; } @@ -450,10 +541,12 @@ export async function runMoneyReconciliation(tx: SqlClient): Promise>(SETTLEMENT_AGGREGATES_SQL); const balances = await tx.query>(LEG_BALANCE_AGGREGATES_SQL); const trips = await tx.query>(TRIP_LEG_FACTS_SQL); + const insurer = await tx.query>(INSURER_LEDGER_FACTS_SQL); return evaluateMoneyReconciliation( settlements.rows.map(parseSettlementRow), balances.rows.map(parseLegBalanceRow), trips.rows.map(parseTripLegFactRow), + insurer.rows.map(parseInsurerLedgerFactRow), ); } diff --git a/apps/api/src/modules/stl/README.md b/apps/api/src/modules/stl/README.md index c04c148a..86088bcd 100644 --- a/apps/api/src/modules/stl/README.md +++ b/apps/api/src/modules/stl/README.md @@ -13,30 +13,31 @@ STL ne déplace aucun fonds lui-même. Il planifie des commandes que PAY exécut - Le module Nest de ce dossier est un **squelette** : `internal/` contient `settlement-review.ts` (US-224) et `trip-cancellation.ts` (US-215) ; `index.ts` exporte `StlModule`, `settleOrFinReview` et le règlement des annulations (`TripCancellationProcessor`, `registerTripCancellations`, `planCancellation`). - Le **moteur pur** vit dans `packages/money` (US-017 : moteur des annulations ; US-018 : règlement persistable, versions, jambes). Voir [`packages/money/README.md`](../../../../../packages/money/README.md), sections « Moteur de règlement » et « Règlements persistés ». - La **persistance** vit en base (US-018, US-062, US-061). Voir [`packages/db/README.md`](../../../../../packages/db/README.md), sections « Règlements et jambes », « Rôle P2P_HOST, tables d'argent et minimisation » et « Port de place de marché ». -- Restent à venir : le grand livre en partie double (US-530), le service qui ordonne les remboursements et alerte FIN sur un envoi retenu (US-224 partie 224c, US-215 ; l'instance et l'avance sont en base depuis 224b, ADR-147), le recouvrement des avances (US-709), l'assureur et les bordereaux (US-227), le moteur complet (US-518). +- Restent à venir : le grand livre en partie double (US-530), le service qui ordonne les remboursements et alerte FIN sur un envoi retenu (US-224 partie 224c, US-215 ; l'instance et l'avance sont en base depuis 224b, ADR-147), le recouvrement des avances (US-709), l'ordre de reversement à l'assureur (lot C ; registre et bordereaux : US-227, ADR-165), le moteur complet (US-518). ## Entités Bêta (17 §10 point 3) : schéma unique `core`, tables préfixées `settlement_`. -| Entité (17 §3.2.8) | État | -| ------------------------------------------ | --------------------------------------------------------------- | -| `settlement` | table `core.settlement_settlement` (migration 0027) | -| `settlement_line` | table `core.settlement_settlement_line` (migration 0027) | -| `settlement_leg` | table `core.settlement_settlement_leg` (migration 0027) | -| `trip_leg_balance` | table `core.settlement_trip_leg_balance` (migration 0027) | -| `finance_approval` (listée en 17 §3.2.9) | table `core.settlement_finance_approval` (migration 0036) | -| `platform_advance` | table `core.settlement_platform_advance` (migration 0036) | -| `insurer_ledger_state` | table `core.settlement_insurer_ledger_state` (migration 0036) | -| `insurer_bordereau` | table `core.settlement_insurer_bordereau` (migration 0036) | -| `insurer_bordereau_line` | table `core.settlement_insurer_bordereau_line` (migration 0036) | -| `ledger_account` | cible 17, pas encore créée | -| `journal_entry` | cible 17, pas encore créée | -| `journal_line` | cible 17, pas encore créée | -| `account_balance` | cible 17, pas encore créée | -| `host_ledger_state` | cible 17, pas encore créée | -| `host_ledger[hôte][devise]` (17 §2.9) | table `core.settlement_host_ledger_entry` (migration 0129) | -| `insurer`, `insurer_contract` (17 §3.2.13) | cible 17, pas encore créées (US-227) | +| Entité (17 §3.2.8) | État | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ | +| `settlement` | table `core.settlement_settlement` (migration 0027) | +| `settlement_line` | table `core.settlement_settlement_line` (migration 0027) | +| `settlement_leg` | table `core.settlement_settlement_leg` (migration 0027) | +| `trip_leg_balance` | table `core.settlement_trip_leg_balance` (migration 0027) | +| `finance_approval` (listée en 17 §3.2.9) | table `core.settlement_finance_approval` (migration 0036) | +| `platform_advance` | table `core.settlement_platform_advance` (migration 0036) | +| `insurer_ledger_state` | table `core.settlement_insurer_ledger_state` (migration 0036) | +| `insurer_bordereau` | table `core.settlement_insurer_bordereau` (migration 0036) | +| `insurer_bordereau_line` | table `core.settlement_insurer_bordereau_line` (migration 0036) | +| `ledger_account` | cible 17, pas encore créée | +| `journal_entry` | cible 17, pas encore créée | +| `journal_line` | cible 17, pas encore créée | +| `account_balance` | cible 17, pas encore créée | +| `host_ledger_state` | cible 17, pas encore créée | +| `host_ledger[hôte][devise]` (17 §2.9) | table `core.settlement_host_ledger_entry` (migration 0129) | +| `insurer`, `insurer_contract` (17 §3.2.13) | tables `core.settlement_insurer`, `core.settlement_insurer_contract` (0081 ; colonnes et clés de 0143) | +| `insurer_ledger` (17 §2.9) | table `core.settlement_insurer_ledger_entry` (migration 0143) | Tables présentes en base mais absentes des listes d'entités de 17 : @@ -122,3 +123,7 @@ La pénalité de l'hôte qui annule (`host_penalty_minor` du règlement, 08 E7 r **Créance de la règle 3 bis (US-224e, ADR-163).** Quand une avance de Kmino sur une jambe `HOST` déjà versée devient effective (`OPEN`, au report du remboursement par `core.settlement_cmd_apply_leg_movement`, `RefundScheduler`), la base écrit dans la même instruction la créance de l'hôte (`RELEASED_LEG_ADVANCE`, montant de l'avance stockée, 08 TJ18b / TJ18d) par le déclencheur `platform_advance_receivable_posted`. Aucun code de l'API n'y participe ; aucun recouvrement (`NETTING`, SM-6b) avant US-709. **Remboursement réparti sur les moyens d'origine (US-224f, ADR-166).** Le processeur des annulations lit tous les encaissements réussis du loyer du trip (`tendersOf` : capture, débit MIT, recouvrement, devise du trip, ordre des captures, montant déjà engagé sur chacun) et `ordersByTender` (pur) en tire un ordre par moyen : 08 E2 décide le montant de chaque moyen (`refundsByTender` de `@rueda/money`), la règle 10 ses jambes ; la réaffectation est rattachée au premier moyen de la cascade ; clé `…:REFUND:{moyen}:i1:a1`. Bêta (fail-closed) : seule la carte est remboursée (`NATIVE_PARTIAL`) ; un moyen non natif ou un crédit qui doit rembourser quelque chose ⇒ `REFUND_RAIL_UNAVAILABLE`, rien n'est écrit, la demande est garée avec une alerte. L'ordonnanceur (`RefundScheduler`) fait passer une instance en échec confirmé à `PENDING_CUSTOMER_CHOICE` (`attempt_no` + 1, `PgRefundOrders.awaitChoice`) dans la transaction qui pose l'alerte `FIN_REFUND_FAILED` ; aucun autre rail n'est ouvert en bêta. + +## Registre et bordereau de l'assureur (US-227, ADR-165) + +La jambe `INSURER` est écrite au registre de l'assureur (`core.settlement_insurer_ledger_entry`, migration 0143) par la base elle-même, dans la transaction de sa source : chaque encaissement porté sur les soldes (`COLLECTION`, jambe de l'opération) et chaque version de règlement (`SETTLEMENT_VARIATION`, variation stockée ; une version n+1 n'écrit que sa variation depuis la version n). Une variation sur un trip déjà porté par un bordereau émis est refusée (`insurer_leg_on_bordereau`) : l'annulation de l'ops est garée `FIN_REVIEW`. La tâche `bordereau` (`internal/insurer-bordereau.ts`, 24 h, `registerInsurerBordereaux` dans `worker-tasks.ts`) appelle `core.settlement_cmd_draft_insurer_bordereaux(NULL)` : bordereau DRAFT du mois clos par contrat, projection `insurer_ledger_state`. L'émission reste `ISSUE_BORDEREAU` à deux personnes FINANCE (console d'US-101), gardée par `insurer_bordereau_issue_check`. Aucun paiement à l'assureur (lot C, GL-42). Preuves : `insurer-bordereau.test.ts`, `packages/db/test/l0/l0-us227-insurer-ledger.test.ts`. diff --git a/apps/api/src/modules/stl/index.ts b/apps/api/src/modules/stl/index.ts index 0b296376..b07c29ea 100644 --- a/apps/api/src/modules/stl/index.ts +++ b/apps/api/src/modules/stl/index.ts @@ -25,6 +25,12 @@ export type { CaptureTender, TenderOrder, } from './internal/trip-cancellation.js'; +// Bordereau mensuel de l'assureur (US-227, ADR-165) +export { + INSURER_BORDEREAU_PERIOD_SECONDS, + INSURER_BORDEREAU_WORKER, + registerInsurerBordereaux, +} from './internal/insurer-bordereau.js'; // Ordonnanceur des remboursements planifiés (US-224c, ADR-150) export { REFUND_SCHEDULER_BATCH, diff --git a/apps/api/src/modules/stl/internal/insurer-bordereau.test.ts b/apps/api/src/modules/stl/internal/insurer-bordereau.test.ts new file mode 100644 index 00000000..7ae045a1 --- /dev/null +++ b/apps/api/src/modules/stl/internal/insurer-bordereau.test.ts @@ -0,0 +1,77 @@ +/** + * US-227 (ADR-165) — tâche périodique du bordereau de l'assureur, sans base : déclaration (file + * `bordereau`, 24 h), une passe appelle la seule commande de la base et ne journalise que des comptes ; + * une issue inconnue est une erreur de contrat (fail-closed). La preuve sur PostgreSQL réel, sous + * les rôles de production, est `packages/db/test/l0/l0-us227-insurer-ledger.test.ts`. + */ +import { describe, expect, it } from 'vitest'; +import { BusRegistry } from '../../bus/index.js'; +import type { SqlClient, SqlResult } from '../../bus/index.js'; +import { + DRAFT_INSURER_BORDEREAUX_SQL, + draftCounts, + INSURER_BORDEREAU_PERIOD_SECONDS, + INSURER_BORDEREAU_WORKER, + InsurerBordereauContractError, + registerInsurerBordereaux, +} from './insurer-bordereau.js'; + +class ScriptedSql implements SqlClient { + readonly texts: string[] = []; + constructor(private readonly rows: Record[]) {} + query(text: string): Promise> { + this.texts.push(text); + return Promise.resolve({ rows: this.rows as R[], rowCount: this.rows.length }); + } +} + +describe('US-227 — tâche du bordereau de l’assureur', () => { + it('déclarée au registre (file bordereau, 24 h) ; une passe appelle la commande et journalise des comptes', async () => { + const registry = new BusRegistry(); + const lines: string[] = []; + registerInsurerBordereaux(registry, (l) => lines.push(l)); + expect(registry.queueNames()).toEqual([INSURER_BORDEREAU_WORKER]); + expect(INSURER_BORDEREAU_WORKER).toBe('bordereau'); + const task = registry.periodicTasks().find((t) => t.name === INSURER_BORDEREAU_WORKER); + expect(task?.spec.periodSeconds).toBe(INSURER_BORDEREAU_PERIOD_SECONDS); + expect(INSURER_BORDEREAU_PERIOD_SECONDS).toBe(86_400); + const handler = registry.handlerOf(INSURER_BORDEREAU_WORKER); + if (handler?.kind !== 'timer') throw new Error('minuterie attendue'); + const sql = new ScriptedSql([ + { outcome: 'DRAFTED', country: 'AA' }, + { outcome: 'EMPTY', country: 'AA' }, + { outcome: 'PERIOD_OPEN', country: 'BB' }, + ]); + await handler.handle({}, sql); + expect(sql.texts).toEqual([DRAFT_INSURER_BORDEREAUX_SQL]); + expect(JSON.parse(lines[0] ?? '{}')).toEqual({ + level: 'info', + worker: 'bordereau', + drafted: 1, + exists: 0, + empty: 1, + period_open: 1, + }); + // aucun identifiant ni montant au journal + expect(lines[0]).not.toMatch(/[0-9a-f]{8}-[0-9a-f]{4}-/i); + }); + + it('la requête ne lit aucune horloge et n’écrit rien elle-même (la base décide le mois)', () => { + expect(DRAFT_INSURER_BORDEREAUX_SQL).not.toMatch( + /\b(now|current_timestamp|clock_timestamp)\b/i, + ); + expect(DRAFT_INSURER_BORDEREAUX_SQL).toMatch(/settlement_cmd_draft_insurer_bordereaux\(NULL\)/); + }); + + it('issue inconnue ⇒ erreur de contrat (fail-closed)', () => { + expect(draftCounts([{ outcome: 'EXISTS' }])).toEqual({ + DRAFTED: 0, + EXISTS: 1, + EMPTY: 0, + PERIOD_OPEN: 0, + }); + for (const bad of [{ outcome: 'ISSUED' }, { outcome: null }, { outcome: 1 }]) { + expect(() => draftCounts([bad])).toThrow(InsurerBordereauContractError); + } + }); +}); diff --git a/apps/api/src/modules/stl/internal/insurer-bordereau.ts b/apps/api/src/modules/stl/internal/insurer-bordereau.ts new file mode 100644 index 00000000..797ad91a --- /dev/null +++ b/apps/api/src/modules/stl/internal/insurer-bordereau.ts @@ -0,0 +1,70 @@ +/** + * Bordereau mensuel de l'assureur partenaire (US-227, ADR-165 ; 08 E7 règles 6 et 7 ; 17 §2.9 + * `insurer_ledger`) : tâche périodique du travailleur `bordereau`. Chaque passage appelle + * `core.settlement_cmd_draft_insurer_bordereaux(NULL)` (0143) : pour le mois clos de chaque pays, + * un bordereau DRAFT par contrat d'assureur (lignes = prime due des trips terminés, jamais une + * ligne gelée par un chargeback ouvert), puis la projection `insurer_ledger_state`. La base décide + * tout (mois, éligibilité, montants lus du registre) ; ce module ne calcule aucun montant. + * + * L'émission reste une décision FINANCE à deux personnes (`ISSUE_BORDEREAU` par + * `cmd_request_finance_action` puis `cmd_approve_finance_action`, console d'US-101). Aucun + * paiement : aucun ordre `releaseLeg` ni reversement à l'assureur avant le lot C (PSP FAKE, aucun + * fonds de tiers détenu). Le journal ne porte que des comptes par issue (aucun identifiant, 17 §6.3). + */ +import type { BusRegistry } from '../../bus/index.js'; + +/** Travailleur du bordereau (liste des politiques `cmd_money_ins` de 0036 et 0143). */ +export const INSURER_BORDEREAU_WORKER = 'bordereau'; + +/** Une passe par 24 h (PROPOSÉ, ADR-165) : la rédaction est idempotente par (contrat, mois). */ +export const INSURER_BORDEREAU_PERIOD_SECONDS = 86_400; + +/** Mois précédent de chaque pays (NULL), dans le fuseau du pays. */ +export const DRAFT_INSURER_BORDEREAUX_SQL = + 'SELECT outcome, country FROM core.settlement_cmd_draft_insurer_bordereaux(NULL)'; + +const OUTCOMES = ['DRAFTED', 'EXISTS', 'EMPTY', 'PERIOD_OPEN'] as const; +type DraftOutcome = (typeof OUTCOMES)[number]; + +/** Erreur de contrat : issue inconnue rendue par la commande (fail-closed). */ +export class InsurerBordereauContractError extends Error { + override readonly name = 'InsurerBordereauContractError'; +} + +/** Comptes par issue d'une passe (fonction pure). */ +export function draftCounts( + rows: readonly { readonly outcome: unknown }[], +): Record { + const counts: Record = { DRAFTED: 0, EXISTS: 0, EMPTY: 0, PERIOD_OPEN: 0 }; + for (const r of rows) { + if (typeof r.outcome !== 'string' || !(OUTCOMES as readonly string[]).includes(r.outcome)) { + throw new InsurerBordereauContractError('issue de rédaction inconnue'); + } + counts[r.outcome as DraftOutcome]++; + } + return counts; +} + +/** Déclare la tâche périodique `bordereau`. */ +export function registerInsurerBordereaux( + registry: BusRegistry, + log: (line: string) => void, + periodSeconds: number = INSURER_BORDEREAU_PERIOD_SECONDS, +): void { + registry.registerPeriodic(INSURER_BORDEREAU_WORKER, periodSeconds, async (_payload, tx) => { + const { rows } = await tx.query<{ outcome: unknown; country: unknown }>( + DRAFT_INSURER_BORDEREAUX_SQL, + ); + const c = draftCounts(rows); + log( + JSON.stringify({ + level: 'info', + worker: INSURER_BORDEREAU_WORKER, + drafted: c.DRAFTED, + exists: c.EXISTS, + empty: c.EMPTY, + period_open: c.PERIOD_OPEN, + }), + ); + }); +} diff --git a/apps/api/src/modules/stl/internal/trip-cancellation.test.ts b/apps/api/src/modules/stl/internal/trip-cancellation.test.ts index 496ec86e..494a8b74 100644 --- a/apps/api/src/modules/stl/internal/trip-cancellation.test.ts +++ b/apps/api/src/modules/stl/internal/trip-cancellation.test.ts @@ -305,6 +305,11 @@ describe('classement des refus', () => { outcome: 'FIN_REVIEW', code: 'OPERATION_SETTLEMENT_FIN_REVIEW', }); + // US-227 (ADR-165) : jambe INSURER déjà portée par un bordereau émis ⇒ revue FIN + expect(classify({ code: '55000', constraint: 'insurer_leg_on_bordereau' })).toEqual({ + outcome: 'FIN_REVIEW', + code: 'INSURER_LEG_ON_BORDEREAU', + }); expect(classify({ code: '55000', constraint: 'trip_transition_forbidden' })).toEqual({ outcome: 'FAILED', code: 'TRIP_TRANSITION_FORBIDDEN', diff --git a/apps/api/src/modules/stl/internal/trip-cancellation.ts b/apps/api/src/modules/stl/internal/trip-cancellation.ts index 65b27eb9..cc374889 100644 --- a/apps/api/src/modules/stl/internal/trip-cancellation.ts +++ b/apps/api/src/modules/stl/internal/trip-cancellation.ts @@ -712,13 +712,17 @@ export function classifyOrUnexpected(error: unknown): CancellationOutcome { } } -/** Contraintes de la base qui renvoient à la décision FINANCE d'US-224b (08 E7 règle 5). */ +/** + * Contraintes de la base qui renvoient à la décision FINANCE d'US-224b (08 E7 règle 5) ; US-227 + * (ADR-165) : jambe INSURER déjà portée par un bordereau émis (08 E7 règle 3 bis, ADR-147). + */ const FIN_CONSTRAINTS = new Set([ 'operation_settlement_fin_review', 'refund_exceeds_collected', // US-224f (08 E2) : jamais plus que le payé d'un moyen 'refund_exceeds_tender', 'advance_decision_required', + 'insurer_leg_on_bordereau', ]); /** Interblocage, sérialisation : reprise au passage suivant. */ const RETRY_STATES = new Set(['40P01', '40001']); diff --git a/apps/api/src/worker-tasks.test.ts b/apps/api/src/worker-tasks.test.ts index e0d6dd6a..b8508e1e 100644 --- a/apps/api/src/worker-tasks.test.ts +++ b/apps/api/src/worker-tasks.test.ts @@ -85,6 +85,8 @@ describe('tâches du travailleur (US-003)', () => { 'booking_contract', 'booking_conversion', 'booking_oracle', + // US-227 (ADR-165) : bordereau mensuel de l'assureur (rédaction seulement) + 'bordereau', 'disposition_sweeper', 'hold_expiry', 'iam_otp_pruner', @@ -109,6 +111,7 @@ describe('tâches du travailleur (US-003)', () => { ).toEqual([ ['booking_conversion', 10, 5], ['booking_oracle', 86_400, 5], + ['bordereau', 86_400, 5], ['disposition_sweeper', 60, 5], ['hold_expiry', 60, 5], ['iam_otp_pruner', 3_600, 5], diff --git a/apps/api/src/worker-tasks.ts b/apps/api/src/worker-tasks.ts index e830e9f4..8bb671e7 100644 --- a/apps/api/src/worker-tasks.ts +++ b/apps/api/src/worker-tasks.ts @@ -11,6 +11,7 @@ * | `disposition_sweeper` | `disposition_sweeper_period_s` (min. pays) | `core.booking_disposition_candidates` puis, une opération par transaction, `core.booking_disposition_repair` (0041, C17) | * | `booking_oracle` | 24 h (ADR-068) | `core.booking_production_oracle_alert` (0045, C12) | * | `reconciliation` | 24 h (ADR-087) | contrôles de rapprochement de l'argent, lecture seule (FIN, US-047) ; alerte `FIN_MONEY_RECONCILIATION` | + * | `bordereau` | 24 h (US-227, ADR-165) | `core.settlement_cmd_draft_insurer_bordereaux` (0143) : bordereaux DRAFT du mois clos par contrat d'assureur et projection `insurer_ledger_state` ; émission par FINANCE à deux personnes, aucun paiement | * | `risk_pruner` | 1 h | `core.risk_cmd_prune` (0047, US-052) | * | `ntf_dispatcher`, `ntf_sender` | événements, minuterie | NTF (US-021) ; plafond SMS du pays (`ntfSmsBudget`, US-052) ; parties des réservations lues par `core.booking_notification_parties` (0133, adaptateur `postgresNotificationParties` d'AVL, US-213) | * | `ops_monitor` | 60 s (ADR-080) | `core.ops_monitor_metrics` (0051) ; alertes sur le port `AlertChannel` (US-004) | @@ -63,7 +64,11 @@ import { } from './modules/ntf/index.js'; import { resolveCancellationParams } from './modules/prc/index.js'; import { ntfSmsBudget } from './modules/risk/index.js'; -import { registerRefundScheduler, registerTripCancellations } from './modules/stl/index.js'; +import { + registerInsurerBordereaux, + registerRefundScheduler, + registerTripCancellations, +} from './modules/stl/index.js'; export const HOLD_EXPIRY_WORKER = 'hold_expiry'; /** Webhooks PSP reçus : rattachement et statut (17 §4.4 points 5 à 8 ; US-019, US-223). */ @@ -304,6 +309,9 @@ export function registerWorkerTasks(registry: BusRegistry, deps: WorkerTaskDeps) const alerts = deps.alerts ?? new LogAlertChannel(deps.log); registerOpsMonitor(registry, alerts, deps.log); registerMoneyReconciliation(registry, alerts, deps.log); + // Bordereau de l'assureur (US-227, ADR-165) : rédaction du mois clos, émission par FINANCE à + // deux personnes ; aucun paiement à l'assureur avant le lot C + registerInsurerBordereaux(registry, deps.log); // Annulations demandées par l'ops (US-215, ADR-148) : règlement, transition et remboursements // dans une transaction par demande ; refus garés (FIN_REVIEW, FAILED) et alertés registerTripCancellations(registry, deps.transactions, alerts, deps.log); diff --git a/apps/api/test/int/reconciliation.int.test.ts b/apps/api/test/int/reconciliation.int.test.ts index 6dc92c47..cbb7f918 100644 --- a/apps/api/test/int/reconciliation.int.test.ts +++ b/apps/api/test/int/reconciliation.int.test.ts @@ -260,6 +260,9 @@ describe('US-047 — parcours doré de règlement puis rapprochement, dans chaqu expect(report.examined.legBalances[c.country]).toBe(after.balances); // US-217a : les deux trips du parcours sont examinés par l'invariant par jambe (relevé) expect(report.examined.trips[c.country] ?? 0).toBeGreaterThanOrEqual(2); + // US-227 : la jambe INSURER des règlements du parcours est portée au registre de + // l'assureur (variation de chaque version) et rapprochée sans écart + expect(report.examined.insurerTrips[c.country] ?? 0).toBeGreaterThanOrEqual(1); expect(after.totalPaid - before.totalPaid).toBe( a.trip.totalPaidMinor + 2n * b.trip.totalPaidMinor, ); diff --git a/changelog.d/US-227-insurer-ledger.md b/changelog.d/US-227-insurer-ledger.md new file mode 100644 index 00000000..ea2d9d8b --- /dev/null +++ b/changelog.d/US-227-insurer-ledger.md @@ -0,0 +1,7 @@ +lot: L2 +module: Règlement et finance + +- Ajouté : registre de la prime due à l'assureur partenaire, trip par trip : chaque paiement encaissé et chaque règlement y portent la part de l'assureur telle qu'enregistrée, dans la même opération, jamais recalculée (US-227) +- Ajouté : bordereau mensuel de l'assureur préparé chaque jour pour le mois clos (voyages terminés seulement, jamais une ligne gelée par une contestation de paiement) et émis seulement par deux personnes FINANCE distinctes ; aucun paiement à l'assureur pendant la bêta (US-227) +- Ajouté : le contrôle de nuit de l'argent vérifie que le registre de l'assureur retrouve exactement la part de l'assureur des paiements et des règlements, et qu'aucun bordereau ne porte plus que la prime due (US-227) +- Sécurité : registre immuable, écrit par la seule base ; lecture par FINANCE et ADMIN du pays ; un remboursement qui toucherait une prime déjà portée par un bordereau émis est arrêté pour revue FINANCE (US-227) diff --git a/docs/adr/ADR-165-registre-et-bordereau-de-l-assureur.md b/docs/adr/ADR-165-registre-et-bordereau-de-l-assureur.md new file mode 100644 index 00000000..f5f1d81b --- /dev/null +++ b/docs/adr/ADR-165-registre-et-bordereau-de-l-assureur.md @@ -0,0 +1,41 @@ +# ADR-165 — Registre de l'assureur (`insurer_ledger`), bordereau mensuel à double validation et rapprochement + +- **Statut** : PROPOSÉ (US-227, agent back-end / argent, claude-opus-5-5, 2026-11-18). Revues exigées : code, architecture, sécurité, argent, QA (`docs/team/review-requirements.json`) ; argent, RLS / rôles, `SECURITY DEFINER` et concurrence sur un autre modèle que l'auteur. À reporter dans 17 §2.9 (`insurer_ledger` : table d'écritures à côté de `insurer_ledger_state`), §3.2.8 (`insurer_ledger_entry`, `insurer_bordereau.period_month`), §3.2.13 (`bordereau_period`, `chargeback_clause`), §2.3 (lecture `fin_read`) et 16 A.8 (codes). +- **Complète** : ADR-064 (tables d'argent sans écrivain : bordereaux et position de l'assureur), ADR-111 (contrat de l'assureur sans colonnes d'argent, clés étrangères laissées à US-227), ADR-147 (jambe `INSURER` déjà portée par un bordereau : pas d'avance, refus fail-closed), ADR-153 (modèle du `host_ledger`). +- **Sources** : 19 US-227 ; 16 PRT-003 ; 08 E4 (variation n → n+1), E7 règles 1, 3, 3 bis, 6 et 7, vecteurs TJ01, TJ02b (USD), TJ08a, TJ08b (PYG), TJ14a, TJ14b ; 17 v6 §2.3 (RLS-21 à RLS-24), §2.9, §3.2.8, §3.2.13, §7.2 (`insurer_settlement_at` mensuel, PROPOSÉ). + +## Contexte + +Les tables `insurer_ledger_state`, `insurer_bordereau` et `insurer_bordereau_line` (0036, US-062) et la double validation `ISSUE_BORDEREAU` (0036, 0097, 0123) existaient sans écrivain métier : aucune trace de la prime due à l'assureur trip par trip, aucun bordereau rédigé, aucun contrôle. La jambe `INSURER` est stockée à deux endroits : dans chaque encaissement porté (`payment_operation_leg`, montant explicite, 08 E7 règle 1) et dans chaque version de règlement (`settlement_leg.variation_minor`, règle 3). Aucun paiement n'est possible avant le lot C (PSP `FAKE`, aucun fonds de tiers détenu, `insurer_contract_active` = `false`). + +## Décision + +1. **Registre `core.settlement_insurer_ledger_entry`** : une écriture signée par ligne, `bigint` en unités mineures de la devise du trip, motif fermé : `COLLECTION` (jambe `INSURER` d'un encaissement porté `CAPTURE`, `MIT_CHARGE`, `DEBT_COLLECTION`, toujours positive) ou `SETTLEMENT_VARIATION` (variation signée de la jambe `INSURER` d'une version de règlement). Rattachée au trip, au compte d'hôte, à sa source (opération portée par clé étrangère vers `settlement_leg_movement` ; règlement **et sa version** par la clé composite `settlement_ledger_scope_unique` de 0129) et au contrat de l'assureur. Idempotente par opération et par règlement. Immuable (`settlement_immutable`). +2. **Jamais un montant calculé** : la politique d'insertion de `cmd_money_owner` n'admet une écriture que si sa source existe **au montant exact** (jambe `INSURER` de l'opération portée, ou `variation_minor` de la jambe `INSURER` de la version) : ni recalcul, ni prorata, ni montant reçu. +3. **Même transaction que la source, par construction** : déclencheurs `insurer_ledger_collection_posted` (AFTER INSERT sur `settlement_leg_movement`) et `insurer_ledger_variation_posted` (AFTER INSERT sur `settlement_settlement_leg`, jambe `INSURER`, variation non nulle), fonctions `SECURITY DEFINER` de `cmd_money_owner` sans aucun EXECUTE (comme ADR-153). Aucun chemin d'encaissement ni de règlement ne peut omettre l'écriture ; un échec annule la source. +4. **Version n+1 = contre-passation par la variation** : la base d'une version n+1 est la jambe signée de la version n (0027) ; sa variation est donc exactement « annuler n, appliquer n+1 ». Une écriture par version, jamais de réécriture de la version n ; Σ écritures du trip = jambe `INSURER` retenue de la version en tête. +5. **Contrat de l'assureur figé à la réservation** : le contrat du pays en vigueur à la création du trip (au plus un, exclusion GiST de 0081). Aucun contrat ⇒ écriture gardée **sans** contrat (aucun montant perdu), jamais facturée, comptée par le rapprochement (`examined.insurerUnattributed`) ; GL-42 l'exclut avant la mise en service. +6. **Jambe déjà portée par un bordereau émis** (08 E7 règle 3 bis) : toute variation `INSURER` d'un trip dont une ligne appartient à un bordereau non `DRAFT` est **refusée** (`insurer_leg_on_bordereau`) ; le règlement entier est annulé et l'annulation demandée par l'ops est garée `FIN_REVIEW` (`TripCancellationProcessor`). Pas d'avance de Kmino ni de créance sur l'assureur en bêta (ADR-147). +7. **Bordereau mensuel** (`bordereau_period` = `MONTHLY`, défaut PROPOSÉ de 17 §7.2) : commande `core.settlement_cmd_draft_insurer_bordereaux(text)` du travailleur `bordereau` (tâche STL de 24 h). Pour le mois clos dans le fuseau du pays : un bordereau `DRAFT` par contrat et par mois (`period_month`, index unique, verrou consultatif par contrat), une ligne par trip **terminé** (fin prévue ≤ fin du mois, état hors cours et hors litige) dont la prime due (Σ écritures) est positive, dont la jambe `INSURER` n'est **pas gelée** (chargeback ouvert, règle 7) et qui n'est pas déjà portée ; total = Σ lignes. Puis projection `insurer_ledger_state` : à payer (prime due non portée par un bordereau émis, non gelée), gelée, créance (porté au-delà de la prime due). +8. **Émission à deux personnes** : inchangée (`ISSUE_BORDEREAU`, FINANCE A demande, FINANCE B approuve, garde ADR-122 / ADR-124, auto-approbation refusée même dans une seconde session). Garde `insurer_bordereau_issue_check` (DRAFT → ISSUED, SECURITY INVOKER sous la commande d'approbation) : au moins une ligne et Σ lignes = total (`insurer_bordereau_incoherent`), aucune ligne gelée depuis la rédaction (`insurer_bordereau_line_frozen`), chaque ligne = prime due actuelle (`insurer_bordereau_stale`). Les lignes ne s'ajoutent qu'à un bordereau `DRAFT` (politique resserrée). +9. **Chargeback** (règle 7, TJ14a / TJ14b) : aucun motif ne réduit la prime due hors règlement ; un trip gelé n'entre dans aucun bordereau et bloque l'émission du bordereau qui le porte. +10. **Rapprochement nocturne** (FIN, `reconciliation`) : `core.finance_insurer_ledger_facts()` par trip, trois contrôles : `INSURER_LEDGER_COLLECTION` (Σ écritures d'encaissement = Σ jambes `INSURER` des encaissements portés), `INSURER_LEDGER_SETTLEMENT` (Σ écritures de règlement = Σ variations `INSURER` stockées), `INSURER_BORDEREAU_OVERBILLED` (porté par bordereau émis ≤ prime due), à l'unité mineure. +11. **Clés étrangères** vers `settlement_insurer` / `settlement_insurer_contract` (`insurer_ledger_state`, `insurer_bordereau`, `platform_advance`) ; contrat : `bordereau_period` (`MONTHLY`) et `chargeback_clause` (`PREMIUM_NEVER_REDUCED`), formes fermées, défauts PROPOSÉS. +12. **Aucun paiement** : aucun ordre `releaseLeg` ni reversement (19 US-227 critère 4), `psp_release_ref` jamais posé ; aucun interrupteur lu ni modifié. + +## Alternatives écartées + +- **Écrire à l'exécution du remboursement** (mouvement `REFUND`) plutôt qu'au règlement : la prime due change à la décision (version du règlement), pas au versement ; deux sources pour une même baisse auraient compté deux fois. Le rapprochement compare les deux à part. +- **Contre-passation explicite de la version n** (écriture inverse puis écriture pleine de n+1) : demande de recalculer « n+1 depuis la capture », un montant dérivé ; la variation stockée l'exprime déjà. +- **Rattacher l'assureur au bordereau seulement** : la position par assureur (`insurer_ledger_state`) ne serait pas calculable entre deux bordereaux. +- **Garde d'émission dans la commande d'approbation** (fonction de 270 lignes recopiée) : un déclencheur ciblé garde la commande existante intacte et couvre tout futur chemin. +- **Refuser l'écriture sans contrat** : rendrait toute capture avec protection impossible tant qu'aucun contrat n'est saisi (aucune commande de saisie, N-190) ; la garder sans contrat ne perd rien et ne paie rien. + +## Limites et conséquences (suites) + +- Ordre de reversement à l'assureur (`releaseLeg` variante A, ordre de versement variante B), une seule fois à `insurer_settlement_at` : lot C (critère 4 d'US-227, GL-42). +- Écrivain du gel par chargeback (`frozen_minor` alimenté, ouverture et issue du litige) : story des chargebacks (US-709 / lot 3). +- Sortie d'un bordereau `DRAFT` périmé ou gelé (annulation, nouvelle rédaction) : aucune transition `VOID` ; la garde refuse l'émission, FINANCE attend le dégel. Suite US-227b. +- Commande de saisie du contrat de l'assureur, contrôle franchise ≤ RC, page des mentions : N-190. +- Console FINANCE du bordereau (lignes, total, période) avant la décision : aujourd'hui la file des approbations d'US-101 ; écran dédié en suite (textes es / en / fr / pt-BR). +- Rapprochement avec le relevé de l'assureur (17 §2.9) : à son premier relevé réel (lot C). diff --git a/docs/architecture/schema.md b/docs/architecture/schema.md index ba7762c0..7912f9fc 100644 --- a/docs/architecture/schema.md +++ b/docs/architecture/schema.md @@ -7,7 +7,7 @@ Lu dans le catalogue (`pg_catalog`) d'une base jetable du banc, après les seule ## Synthèse -- 143 migrations ; 127 tables ; 3 vues ; 714 politiques RLS ; 285 fonctions `SECURITY DEFINER` ; 249 autres fonctions. +- 144 migrations ; 128 tables ; 3 vues ; 720 politiques RLS ; 289 fonctions `SECURITY DEFINER` ; 251 autres fonctions. - Tables sans RLS `ENABLE` + `FORCE` : aucune. - Rôles applicatifs avec `SUPERUSER` ou `BYPASSRLS` : aucun. @@ -158,6 +158,7 @@ Lu dans le catalogue (`pg_catalog`) d'une base jetable du banc, après les seule | `0140_booking_defaulted_host_trips_cancel` | AVL / SUP : hôte défaillant, annulation de ses trips à venir par l'ops, voyageurs remboursés | | `0141_payment_refund_multi_tender` | PAY : remboursement réparti sur les moyens d'origine (TJ16c / TJ16d) et reprise après un | | `0142_config_deposit_rail_params` | graine complémentaire : paramètres « deposit_always_required* » (US-225 ; 17 §7.2). | +| `0143_settlement_insurer_ledger` | STL / FIN : jambe de l'assureur — registre `insurer_ledger`, bordereau mensuel à double | ## Rôles @@ -5368,6 +5369,7 @@ Politiques RLS : - `catalog_cmd_read` (SELECT, PERMISSIVE, catalog_cmd_owner) USING `true` - `cmd_hold_contract_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `true` +- `cmd_money_sel` (SELECT, PERMISSIVE, cmd_money_owner) USING `true` - `migrator_all` (ALL, PERMISSIVE, migrator) USING `true` WITH CHECK `true` ### `core.settlement_insurer_bordereau` @@ -5394,15 +5396,19 @@ Politiques RLS : | `created_at` | `timestamp with time zone` | oui | `platform.now()` | | `updated_at` | `timestamp with time zone` | oui | `platform.now()` | | `row_version` | `integer` | oui | `0` | +| `period_month` | `text` | non | — | Contraintes : +- `insurer_bordereau_contract_fk` : `FOREIGN KEY (insurer_contract_id, insurer_id, country_code) REFERENCES core.settlement_insurer_contract(id, insurer_id, country_code)` - `insurer_bordereau_country_format` : `CHECK (country_code ~ '^[A-Z]{2}$'::text)` - `insurer_bordereau_currency_format` : `CHECK (currency ~ '^[A-Z]{3}$'::text)` - `insurer_bordereau_id_country_unique` : `UNIQUE (id, country_code)` +- `insurer_bordereau_insurer_fk` : `FOREIGN KEY (insurer_id, country_code) REFERENCES core.settlement_insurer(id, country_code)` - `insurer_bordereau_issue_pair` : `CHECK ((issued_by IS NULL) = (second_validated_by IS NULL) AND (issued_by IS NULL) = (approval_id IS NULL) AND (issued_by IS NULL) = (issued_at IS NULL) AND (issued_by IS NULL OR issued_by <> second_validated_by))` - `insurer_bordereau_issued_shape` : `CHECK ((status = 'DRAFT'::text) = (issued_by IS NULL))` - `insurer_bordereau_paid_shape` : `CHECK ((status = 'PAID'::text) = (paid_at IS NOT NULL))` +- `insurer_bordereau_period_month_format` : `CHECK (period_month IS NULL OR period_month ~ '^[0-9]{4}-(0[1-9]\|1[0-2])$'::text)` - `insurer_bordereau_period_nonempty` : `CHECK (NOT isempty(period))` - `insurer_bordereau_status_valid` : `CHECK (status = ANY (ARRAY['DRAFT'::text, 'ISSUED'::text, 'PAID'::text, 'DISPUTED'::text]))` - `insurer_bordereau_total_nonneg` : `CHECK (total_minor >= 0)` @@ -5411,9 +5417,13 @@ Contraintes : - `settlement_insurer_bordereau_pkey` : `PRIMARY KEY (id)` - `settlement_insurer_bordereau_second_validated_by_fkey` : `FOREIGN KEY (second_validated_by) REFERENCES core.iam_user_account(id)` +Index : + +- `insurer_bordereau_contract_month` : `CREATE UNIQUE INDEX insurer_bordereau_contract_month ON core.settlement_insurer_bordereau USING btree (insurer_contract_id, period_month) WHERE (period_month IS NOT NULL)` + Politiques RLS : -- `cmd_money_ins` (INSERT, PERMISSIVE, cmd_money_owner) WITH CHECK `((app.actor_kind() = 'WORKER'::text) AND (app.worker_name() = 'bordereau'::text) AND (status = 'DRAFT'::text))` +- `cmd_money_ins` (INSERT, PERMISSIVE, cmd_money_owner) WITH CHECK `((app.actor_kind() = 'WORKER'::text) AND (app.worker_name() = 'bordereau'::text) AND (status = 'DRAFT'::text) AND (period_month IS NOT NULL))` - `cmd_money_sel` (SELECT, PERMISSIVE, cmd_money_owner) USING `true` - `cmd_money_upd` (UPDATE, PERMISSIVE, cmd_money_owner) USING `((app.actor_kind() = 'STAFF'::text) AND (country_code = ANY (app.country_scope())) AND (status = 'DRAFT'::text))` WITH CHECK `((app.actor_kind() = 'STAFF'::text) AND (country_code = ANY (app.country_scope())) AND (status = 'ISSUED'::text))` - `fin_read` (SELECT, PERMISSIVE, app_api) USING `((app.actor_kind() = 'STAFF'::text) AND (country_code = ANY (app.country_scope())) AND (app.has_staff_role('FINANCE'::text, country_code) OR app.has_staff_role('ADMIN'::text, country_code)))` @@ -5424,6 +5434,7 @@ Politiques RLS : Déclencheurs : - `bordereau_transition_guard` : `CREATE TRIGGER bordereau_transition_guard BEFORE UPDATE ON core.settlement_insurer_bordereau FOR EACH ROW EXECUTE FUNCTION core.settlement_insurer_bordereau_guard()` +- `insurer_bordereau_issue_check` : `CREATE TRIGGER insurer_bordereau_issue_check BEFORE UPDATE OF status ON core.settlement_insurer_bordereau FOR EACH ROW WHEN (old.status = 'DRAFT'::text AND new.status = 'ISSUED'::text) EXECUTE FUNCTION core.settlement_insurer_bordereau_issue_check()` - `money_no_delete` : `CREATE TRIGGER money_no_delete BEFORE DELETE ON core.settlement_insurer_bordereau FOR EACH ROW EXECUTE FUNCTION core.settlement_no_delete()` - `money_no_truncate` : `CREATE TRIGGER money_no_truncate BEFORE TRUNCATE ON core.settlement_insurer_bordereau FOR EACH STATEMENT EXECUTE FUNCTION core.settlement_no_delete()` - `touch_row` : `CREATE TRIGGER touch_row BEFORE UPDATE ON core.settlement_insurer_bordereau FOR EACH ROW EXECUTE FUNCTION platform.touch_row()` @@ -5452,7 +5463,7 @@ Contraintes : Politiques RLS : -- `cmd_money_ins` (INSERT, PERMISSIVE, cmd_money_owner) WITH CHECK `((app.actor_kind() = 'WORKER'::text) AND (app.worker_name() = 'bordereau'::text))` +- `cmd_money_ins` (INSERT, PERMISSIVE, cmd_money_owner) WITH CHECK `((app.actor_kind() = 'WORKER'::text) AND (app.worker_name() = 'bordereau'::text) AND (EXISTS ( SELECT 1 FROM core.settlement_insurer_bordereau b WHERE ((b.id = settlement_insurer_bordereau_line.bordereau_id) AND (b.country_code = settlement_insurer_bordereau_line.country_code) AND (b.status = 'DRAFT'::text)))))` - `cmd_money_sel` (SELECT, PERMISSIVE, cmd_money_owner) USING `true` - `fin_read` (SELECT, PERMISSIVE, app_api) USING `((app.actor_kind() = 'STAFF'::text) AND (country_code = ANY (app.country_scope())) AND (app.has_staff_role('FINANCE'::text, country_code) OR app.has_staff_role('ADMIN'::text, country_code)))` - `migrator_all` (ALL, PERMISSIVE, migrator) USING `true` WITH CHECK `true` @@ -5486,10 +5497,14 @@ Déclencheurs : | `rc_amount_minor` | `bigint` | non | — | | `deductibles` | `jsonb` | non | — | | `exclusions` | `jsonb` | non | — | +| `bordereau_period` | `text` | oui | `'MONTHLY'::text` | +| `chargeback_clause` | `text` | oui | `'PREMIUM_NEVER_REDUCED'::text` | Contraintes : +- `settlement_insurer_contract_bordereau_period_valid` : `CHECK (bordereau_period = 'MONTHLY'::text)` - `settlement_insurer_contract_broker_fk` : `FOREIGN KEY (broker_id, country_code) REFERENCES core.settlement_insurer(id, country_code)` +- `settlement_insurer_contract_chargeback_clause_valid` : `CHECK (chargeback_clause = 'PREMIUM_NEVER_REDUCED'::text)` - `settlement_insurer_contract_country_format` : `CHECK (country_code ~ '^[A-Z]{2}$'::text)` - `settlement_insurer_contract_currency_format` : `CHECK (currency IS NULL OR currency ~ '^[A-Z]{3}$'::text)` - `settlement_insurer_contract_deductibles_shape` : `CHECK (deductibles IS NULL OR jsonb_typeof(deductibles) = 'object'::text AND deductibles ?& ARRAY['BASICA'::text, 'ESTANDAR'::text, 'TOTAL'::text] AND (deductibles - ARRAY['BASICA'::text, 'ESTANDAR'::text, 'TOTAL'::text]) = '{}'::jsonb AND jsonb_typeof(deductibles -> 'BASICA'::text) = 'string'::text AND jsonb_typeof(deductibles -> 'ESTANDAR'::text) = 'string'::text AND jsonb_typeof(deductibles -> 'TOTAL'::text) = 'string'::text AND (deductibles ->> 'BASICA'::text) ~ '^(0\|[1-9][0-9]{0,13})$'::text AND (deductibles ->> 'ESTANDAR'::text) ~ '^(0\|[1-9][0-9]{0,13})$'::text AND (deductibles ->> 'TOTAL'::text) ~ '^(0\|[1-9][0-9]{0,13})$'::text)` @@ -5501,6 +5516,7 @@ Contraintes : - `settlement_insurer_contract_period` : `CHECK (valid_to IS NULL OR valid_to > valid_from)` - `settlement_insurer_contract_pkey` : `PRIMARY KEY (id)` - `settlement_insurer_contract_rc_positive` : `CHECK (rc_amount_minor IS NULL OR rc_amount_minor > 0 AND rc_amount_minor <= '100000000000000'::bigint)` +- `settlement_insurer_contract_scope_unique` : `UNIQUE (id, insurer_id, country_code)` - `settlement_insurer_contract_signed` : `CHECK (signed_at <= valid_from)` - `settlement_insurer_contract_terms_complete` : `CHECK ((currency IS NULL) = (rc_amount_minor IS NULL) AND (currency IS NULL) = (deductibles IS NULL) AND (currency IS NULL) = (exclusions IS NULL))` - `settlement_insurer_contract_version_positive` : `CHECK (version >= 1)` @@ -5510,12 +5526,70 @@ Politiques RLS : - `catalog_cmd_read` (SELECT, PERMISSIVE, catalog_cmd_owner) USING `true` - `cmd_hold_contract_read` (SELECT, PERMISSIVE, cmd_hold_owner) USING `true` +- `cmd_money_sel` (SELECT, PERMISSIVE, cmd_money_owner) USING `true` - `migrator_all` (ALL, PERMISSIVE, migrator) USING `true` WITH CHECK `true` Déclencheurs : - `settlement_insurer_contract_terms_guard` : `CREATE TRIGGER settlement_insurer_contract_terms_guard BEFORE INSERT OR DELETE OR UPDATE ON core.settlement_insurer_contract FOR EACH ROW EXECUTE FUNCTION core.settlement_insurer_contract_terms_guard()` +### `core.settlement_insurer_ledger_entry` + +- RLS : ENABLE + FORCE ; propriétaire `migrator` +- Droits : cmd_money_owner: SELECT ; migrator: DELETE, INSERT, REFERENCES, SELECT, TRIGGER, TRUNCATE, UPDATE + +| Colonne | Type | NOT NULL | Défaut | +| ------- | ---- | -------- | ------ | +| `id` | `uuid` | oui | — | +| `trip_id` | `uuid` | oui | — | +| `segment_no` | `integer` | oui | — | +| `org_id` | `uuid` | oui | — | +| `country_code` | `text` | oui | — | +| `currency` | `text` | oui | — | +| `insurer_id` | `uuid` | non | — | +| `insurer_contract_id` | `uuid` | non | — | +| `reason` | `text` | oui | — | +| `operation_id` | `uuid` | non | — | +| `settlement_id` | `uuid` | non | — | +| `settlement_version` | `integer` | non | — | +| `amount_minor` | `bigint` | oui | — | +| `created_at` | `timestamp with time zone` | oui | `platform.now()` | + +Contraintes : + +- `insurer_ledger_entry_amount_nonzero` : `CHECK (amount_minor <> 0)` +- `insurer_ledger_entry_attribution` : `CHECK ((insurer_id IS NULL) = (insurer_contract_id IS NULL))` +- `insurer_ledger_entry_contract_fk` : `FOREIGN KEY (insurer_contract_id, insurer_id, country_code) REFERENCES core.settlement_insurer_contract(id, insurer_id, country_code)` +- `insurer_ledger_entry_country_format` : `CHECK (country_code ~ '^[A-Z]{2}$'::text)` +- `insurer_ledger_entry_currency_format` : `CHECK (currency ~ '^[A-Z]{3}$'::text)` +- `insurer_ledger_entry_operation_fk` : `FOREIGN KEY (operation_id) REFERENCES core.settlement_leg_movement(operation_id)` +- `insurer_ledger_entry_operation_unique` : `UNIQUE (operation_id)` +- `insurer_ledger_entry_reason_valid` : `CHECK (reason = ANY (ARRAY['COLLECTION'::text, 'SETTLEMENT_VARIATION'::text]))` +- `insurer_ledger_entry_segment_beta` : `CHECK (segment_no = 1)` +- `insurer_ledger_entry_settlement_fk` : `FOREIGN KEY (settlement_id, trip_id, segment_no, settlement_version, org_id, country_code, currency) REFERENCES core.settlement_settlement(id, trip_id, segment_no, version, org_id, country_code, currency)` +- `insurer_ledger_entry_settlement_unique` : `UNIQUE (settlement_id)` +- `insurer_ledger_entry_source_shape` : `CHECK (reason = 'COLLECTION'::text AND operation_id IS NOT NULL AND settlement_id IS NULL AND settlement_version IS NULL AND amount_minor > 0 OR reason = 'SETTLEMENT_VARIATION'::text AND operation_id IS NULL AND settlement_id IS NOT NULL AND settlement_version IS NOT NULL)` +- `insurer_ledger_entry_trip_fk` : `FOREIGN KEY (trip_id, country_code) REFERENCES core.booking_trip(id, country_code)` +- `insurer_ledger_entry_version_positive` : `CHECK (settlement_version >= 1)` +- `settlement_insurer_ledger_entry_pkey` : `PRIMARY KEY (id)` + +Index : + +- `insurer_ledger_entry_contract_idx` : `CREATE INDEX insurer_ledger_entry_contract_idx ON core.settlement_insurer_ledger_entry USING btree (insurer_contract_id, country_code, currency) WHERE (insurer_contract_id IS NOT NULL)` +- `insurer_ledger_entry_trip_idx` : `CREATE INDEX insurer_ledger_entry_trip_idx ON core.settlement_insurer_ledger_entry USING btree (trip_id)` + +Politiques RLS : + +- `cmd_money_ins` (INSERT, PERMISSIVE, cmd_money_owner) WITH CHECK `(((reason = 'COLLECTION'::text) AND (EXISTS ( SELECT 1 FROM (core.settlement_leg_movement m JOIN core.payment_payment_operation_leg g ON (((g.operation_id = m.operation_id) AND (g.leg = 'INSURER'::text)))) WHERE ((m.operation_id = settlement_insurer_ledger_entry.operation_id) AND (m.trip_id = settlement_insurer_ledger_entry.trip_id) AND (m.segment_no = settlement_insurer_ledger_entry.segment_no) AND (m.kind = ANY (ARRAY['CAPTURE'::text, 'MIT_CHARGE'::text, 'DEBT_COLLECTION'::text])) AND (g.amount_minor = settlement_insurer_ledger_entry.amount_minor))))) OR ((reason = 'SETTLEMENT_VARIATION'::text) AND (EXISTS ( SELECT 1 FROM core.settlement_settlement_leg l WHERE ((l.settlement_id = settlement_insurer_ledger_entry.settlement_id) AND (l.leg = 'INSURER'::text) AND (l.trip_id = settlement_insurer_ledger_entry.trip_id) AND (l.segment_no = settlement_insurer_ledger_entry.segment_no) AND (l.variation_minor = settlement_insurer_ledger_entry.amount_minor))))))` +- `cmd_money_sel` (SELECT, PERMISSIVE, cmd_money_owner) USING `true` +- `fin_read` (SELECT, PERMISSIVE, app_api) USING `((app.actor_kind() = 'STAFF'::text) AND (country_code = ANY (app.country_scope())) AND (app.has_staff_role('FINANCE'::text, country_code) OR app.has_staff_role('ADMIN'::text, country_code)))` +- `migrator_all` (ALL, PERMISSIVE, migrator) USING `true` WITH CHECK `true` + +Déclencheurs : + +- `settlement_immutable` : `CREATE TRIGGER settlement_immutable BEFORE DELETE OR UPDATE ON core.settlement_insurer_ledger_entry FOR EACH ROW EXECUTE FUNCTION core.settlement_guard_immutable()` +- `settlement_immutable_truncate` : `CREATE TRIGGER settlement_immutable_truncate BEFORE TRUNCATE ON core.settlement_insurer_ledger_entry FOR EACH STATEMENT EXECUTE FUNCTION core.settlement_guard_immutable()` + ### `core.settlement_insurer_ledger_state` - RLS : ENABLE + FORCE ; propriétaire `migrator` @@ -5539,6 +5613,7 @@ Contraintes : - `insurer_ledger_amounts_nonneg` : `CHECK (payable_minor >= 0 AND frozen_minor >= 0 AND receivable_minor >= 0)` - `insurer_ledger_country_format` : `CHECK (country_code ~ '^[A-Z]{2}$'::text)` - `insurer_ledger_currency_format` : `CHECK (currency ~ '^[A-Z]{3}$'::text)` +- `insurer_ledger_insurer_fk` : `FOREIGN KEY (insurer_id, country_code) REFERENCES core.settlement_insurer(id, country_code)` - `settlement_insurer_ledger_state_pkey` : `PRIMARY KEY (insurer_id, country_code, currency)` Politiques RLS : @@ -5591,6 +5666,7 @@ Politiques RLS : Déclencheurs : +- `insurer_ledger_collection_posted` : `CREATE TRIGGER insurer_ledger_collection_posted AFTER INSERT ON core.settlement_leg_movement FOR EACH ROW WHEN (new.kind = ANY (ARRAY['CAPTURE'::text, 'MIT_CHARGE'::text, 'DEBT_COLLECTION'::text])) EXECUTE FUNCTION core.settlement_post_insurer_collection()` - `settlement_immutable` : `CREATE TRIGGER settlement_immutable BEFORE DELETE OR UPDATE ON core.settlement_leg_movement FOR EACH ROW EXECUTE FUNCTION core.settlement_guard_immutable()` - `settlement_immutable_truncate` : `CREATE TRIGGER settlement_immutable_truncate BEFORE TRUNCATE ON core.settlement_leg_movement FOR EACH STATEMENT EXECUTE FUNCTION core.settlement_guard_immutable()` @@ -5633,6 +5709,7 @@ Contraintes : - `platform_advance_currency_format` : `CHECK (currency ~ '^[A-Z]{3}$'::text)` - `platform_advance_decision_pair` : `CHECK ((decided_by IS NULL) = (decision_second_by IS NULL) AND (decided_by IS NULL) = (decision_approval_id IS NULL) AND (decided_by IS NULL OR decided_by <> decision_second_by))` - `platform_advance_funded_from_valid` : `CHECK (funded_from = ANY (ARRAY['TRIP_PLATFORM_LEG'::text, 'COUNTRY_PLATFORM_BALANCE'::text]))` +- `platform_advance_insurer_fk` : `FOREIGN KEY (insurer_id, country_code) REFERENCES core.settlement_insurer(id, country_code)` - `platform_advance_no_receivable` : `CHECK ((cause <> ALL (ARRAY['CREDIT_BEYOND_PLATFORM'::text, 'CHARGEBACK_LOSS'::text])) OR receivable_minor = 0)` - `platform_advance_org_country_fk` : `FOREIGN KEY (org_id, country_code) REFERENCES core.iam_organization(id, country_code)` - `platform_advance_recovered_shape` : `CHECK (status <> 'RECOVERED'::text OR recovered_minor = receivable_minor)` @@ -5809,6 +5886,7 @@ Politiques RLS : Déclencheurs : +- `insurer_ledger_variation_posted` : `CREATE TRIGGER insurer_ledger_variation_posted AFTER INSERT ON core.settlement_settlement_leg FOR EACH ROW WHEN (new.leg = 'INSURER'::text AND new.variation_minor <> 0) EXECUTE FUNCTION core.settlement_post_insurer_variation()` - `settlement_immutable` : `CREATE TRIGGER settlement_immutable BEFORE DELETE OR UPDATE ON core.settlement_settlement_leg FOR EACH ROW EXECUTE FUNCTION core.settlement_guard_immutable()` - `settlement_immutable_truncate` : `CREATE TRIGGER settlement_immutable_truncate BEFORE TRUNCATE ON core.settlement_settlement_leg FOR EACH STATEMENT EXECUTE FUNCTION core.settlement_guard_immutable()` @@ -6472,6 +6550,7 @@ Chacune a un propriétaire `NOLOGIN` dédié (ADR-053) et un `search_path` figé | `core.ctr_staff_cmd_publish_document(p_token_hash bytea, p_request_id uuid, p_kind text, p_country text, p_is_major boolean, p_valid_from timestamp with time zone, p_legal_review_ref text, p_bodies jsonb)` | `TABLE(outcome text, version integer)` | `iam_staff_owner` | search_path=pg_catalog, pg_temp | app_api: EXECUTE ; iam_staff_owner: EXECUTE | | `core.finance_earning_lines(p_org uuid)` | `TABLE(line_kind text, trip_id uuid, country_code text, currency text, period_month text, event_at timestamp with time zone, trip_status text, source text, settlement_version integer, reason text, amount_minor bigint, share_base_minor bigint, host_plan_code text, host_share_pct text)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | | `core.finance_host_statement(p_org uuid, p_month text)` | `jsonb` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_hold_owner: EXECUTE ; cmd_money_owner: EXECUTE | +| `core.finance_insurer_ledger_facts()` | `TABLE(country_code text, currency text, collected_entries_minor bigint, collected_legs_minor bigint, settled_entries_minor bigint, settled_variations_minor bigint, billed_minor bigint, due_minor bigint, unattributed boolean)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.finance_trip_leg_facts()` | `TABLE(trip_id uuid, country_code text, currency text, captured_minor bigint, collected_minor bigint, collected_legs_minor bigint, head_total_paid_minor bigint, expected_host_minor bigint, statement_host_minor bigint)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.finance_trip_receipt_view(p_trip_id uuid, p_viewer text)` | `jsonb` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_hold_owner: EXECUTE ; cmd_money_owner: EXECUTE | | `core.iam_auth_lookup(p_email text)` | `TABLE(user_id uuid, password_hash text, status text)` | `iam_auth_owner` | search_path=pg_catalog, pg_temp | app_api: EXECUTE ; iam_auth_owner: EXECUTE | @@ -6582,12 +6661,15 @@ Chacune a un propriétaire `NOLOGIN` dédié (ADR-053) et un `search_path` figé | `core.settlement_cancellation_of(p_settlement_id uuid)` | `TABLE(id uuid, trip_id uuid, segment_no integer, version integer, supersedes_id uuid, kind text, requested_reason text, reason text, origin text, target_state text, inputs jsonb, superseded boolean)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_hold_owner: EXECUTE ; cmd_money_owner: EXECUTE | | `core.settlement_cmd_apply_leg_movement(p_operation_id uuid)` | `text` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.settlement_cmd_approve_finance_action(p_token_hash bytea, p_approval_id uuid)` | `TABLE(outcome text, approval_id uuid)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_api: EXECUTE ; cmd_money_owner: EXECUTE | +| `core.settlement_cmd_draft_insurer_bordereaux(p_month text)` | `TABLE(outcome text, country text, bordereau uuid, lines integer, total bigint)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.settlement_cmd_post_advance_receivable(p_advance_id uuid)` | `uuid` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | | `core.settlement_cmd_post_host_penalty(p_settlement_id uuid)` | `uuid` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | | `core.settlement_cmd_record(p_settlement_id uuid, p_trip_id uuid, p_segment_no integer, p_version integer, p_supersedes_id uuid, p_trip_row_version integer, p_record jsonb)` | `uuid` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_worker: EXECUTE ; cmd_money_owner: EXECUTE | | `core.settlement_cmd_request_finance_action(p_token_hash bytea, p_request_id uuid, p_action text, p_subject_id uuid, p_reason text)` | `TABLE(outcome text, approval_id uuid)` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | app_api: EXECUTE ; cmd_money_owner: EXECUTE | | `core.settlement_post_advance_receivable()` | `trigger` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | | `core.settlement_post_cancellation_penalty()` | `trigger` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | +| `core.settlement_post_insurer_collection()` | `trigger` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | +| `core.settlement_post_insurer_variation()` | `trigger` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE | | `core.settlement_staff_cancellation_summary(p_settlement_id uuid)` | `jsonb` | `cmd_money_owner` | search_path=pg_catalog, pg_temp | cmd_money_owner: EXECUTE ; iam_staff_owner: EXECUTE | | `core.support_close_review_item(p_item_id uuid, p_status text, p_decision text, p_actor uuid)` | `TABLE(outcome text, item_id uuid)` | `iam_staff_owner` | search_path=pg_catalog, pg_temp | cmd_hold_owner: EXECUTE ; iam_staff_owner: EXECUTE ; kyc_cmd_owner: EXECUTE | | `core.support_enqueue_review(p_queue text, p_subject_type text, p_subject_id uuid, p_country text, p_actor uuid)` | `TABLE(outcome text, item_id uuid)` | `iam_staff_owner` | search_path=pg_catalog, pg_temp | catalog_cmd_owner: EXECUTE ; cmd_hold_owner: EXECUTE ; iam_staff_owner: EXECUTE ; kyc_cmd_owner: EXECUTE | @@ -6825,6 +6907,8 @@ Chacune a un propriétaire `NOLOGIN` dédié (ADR-053) et un `search_path` figé | `core.settlement_finance_approval_guard()` | `trigger` | `migrator` | migrator: EXECUTE | | `core.settlement_guard_immutable()` | `trigger` | `migrator` | migrator: EXECUTE | | `core.settlement_insurer_bordereau_guard()` | `trigger` | `migrator` | migrator: EXECUTE | +| `core.settlement_insurer_bordereau_issue_check()` | `trigger` | `migrator` | migrator: EXECUTE | +| `core.settlement_insurer_contract_of_trip(p_trip_id uuid)` | `TABLE(insurer_id uuid, contract_id uuid)` | `cmd_money_owner` | cmd_money_owner: EXECUTE | | `core.settlement_insurer_contract_terms_guard()` | `trigger` | `migrator` | migrator: EXECUTE | | `core.settlement_insurer_vehicle_coverage(p_country text, p_timezone text, p_year integer, p_value_class text, p_plate_category text)` | `TABLE(outcome text, reasons text[], contract_id uuid)` | `migrator` | catalog_cmd_owner: EXECUTE ; migrator: EXECUTE | | `core.settlement_no_delete()` | `trigger` | `migrator` | migrator: EXECUTE | diff --git a/docs/ops/GO_LIVE_CHECKLIST.md b/docs/ops/GO_LIVE_CHECKLIST.md index 43bfa6e7..dd50af15 100644 --- a/docs/ops/GO_LIVE_CHECKLIST.md +++ b/docs/ops/GO_LIVE_CHECKLIST.md @@ -65,6 +65,7 @@ | GL-36 | **Confirmation et notifications de réservation complètes avec le canal réel** (US-213, ADR-157). **Existe** (bêta, aucun canal réel : `ntf_sender` fail-closed) : destinataires lus en base (`core.booking_notification_parties`, 0133) ; confirmation du voyageur (adresse exacte et contrat dans la réservation, permis physique, conseils de sécurité, jamais le téléphone de l’hôte) et de l’hôte (aucune donnée du voyageur) ; demande reçue, refusée, expirée, non confirmée après acceptation ; S06 confirmé (10b S07). **Manque avant l’ouverture d’un pays** : les **numéros du support et de l’assistance de l’assureur** dans la confirmation (19 US-213 critère 2 ; données du fondateur et du contrat de l’assureur, `POUR_LE_FONDATEUR.md` §2.13) ; le **lien** vers le contrat (S09) et le **PDF joint** (origine web publique du travailleur, pièces jointes du port `MessagingChannel`, canal e-mail réel du lot C ; N-243) ; la **constancia** (US-212) ; les co-hôtes prévenus (seul le titulaire l’est) ; le lien de la notification d’annulation vers S10 (224d) | message de confirmation reçu en préproduction par le voyageur et par l’hôte, en es et dans une autre langue, avec les deux numéros, le lien du contrat et la constancia ; envoi en moins d’une minute après `BOOKED` (16 M5) ; rejeu de l’événement sans doublon ; preuves `l0-us213-notification-parties`, `ntf.int.test.ts` | fondateur (numéros), US-212, lot C, NTF | | | GL-37 | **Détail du trip du voyageur complet : constancia et reçu téléchargeables** (US-214, ADR-160 ; 19 US-214 critère 2, 16 BKG-027). **Existe** (bêta, sur `FAKE`) : S08 « Mis viajes » et S09 détail du trip (lieu de remise, hôte en prénom et initiale, total payé, contrat avec son état et son lien, lien vers le remboursement) ; constancia et reçu annoncés « bientôt ». **À faire avant l'ouverture d'un pays** : constancia bilingue téléchargeable depuis S09 (US-212, LEG-026) ; reçu du voyageur (US-217, FIN-002 : facture hors plateforme en bêta) ; point d'entrée vers S08 dans la navigation du site et depuis S06 confirmé ; numéros d'aide et urgence (SUP-004, S17) | essai en préproduction : réservation → S08 → S09 dans les quatre langues, en USD et en PYG sans décimale ; contrat, constancia et reçu téléchargés ; trip d'un autre ⇒ introuvable ; preuves `l0-us214-guest-trips`, `guest-trips.spec.ts` | US-212, US-217, US-214 (suites) | | GL-38 | **Reçu des gains de l'hôte et facture du trip fee avant l'ouverture d'un pays** (US-217 partie 217a, ADR-161). **Existe** (bêta, sur `FAKE`) : reçu des gains par trip et relevé mensuel de l'hôte titulaire (jambe HOST de la version en tête du règlement ou de la capture, plan et part figés, frais retenus par Kmino, pénalité du `host_ledger` en ligne séparée), reçu du paiement et du trip fee du voyageur (taxe de ligne du devis figé), lus de l'état stocké ; invariant par jambe dans le rapprochement de nuit (`TRIP_CAPTURE_LEGS`, `TRIP_SETTLED_TOTAL`, `STATEMENT_HOST_LEG`, alerte P1). **Manque avant l'ouverture d'un pays** : entité qui facture le trip fee et ses mentions légales par pays (ADR-013, OQ-MK-06 ; `finance_legal_entity` vide, la production refuse de démarrer) ; facture électronique PAC / SIFEN réelle (US-604, lot C ; hors plateforme jusque-là, FIN-002 MANUEL) ; avis comptable sur la taxe du trip fee retenu après une annulation (OQ-BR-14) ; écrans A08 et S09 (Bêta L3) ; relevé annuel (FIN-018, lot 5). | +| GL-42 | **Prime de l'assureur versée par bordereau, une seule fois** (US-227, ADR-165) : **existe** : registre de la prime due par trip dans la transaction du paiement et du règlement, bordereau mensuel rédigé par la base et émis par deux personnes FINANCE, rapprochement nocturne. **Manque avant `insurer_contract_active[pays]` = `true`** : contrat de l'assureur saisi (commande de saisie, N-190) avec sa périodicité et sa clause de chargeback ; aucune écriture du registre sans contrat dans le pays (`examined.insurerUnattributed` = 0) ; ordre de reversement à l'assureur émis une seule fois à `insurer_settlement_at` (`releaseLeg` en variante A, ordre de versement en variante B si `funds_holding_enabled`) ; gel par chargeback écrit par la story des chargebacks ; sortie d'un bordereau DRAFT périmé ou gelé ; écran FINANCE du bordereau ; second approbateur FINANCE désigné | essai en préproduction : paiement avec protection, règlement, bordereau du mois, demande et approbation par deux personnes, reversement unique à l'assureur, rapprochement sans écart ; preuves `l0-us227-insurer-ledger`, `money-reconciliation.test.ts` | fondateur (contrat d'assureur), lot C, US-709, US-101 | | | 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`) | diff --git a/docs/team/COMME_TURO.md b/docs/team/COMME_TURO.md index f7806140..58a79329 100644 --- a/docs/team/COMME_TURO.md +++ b/docs/team/COMME_TURO.md @@ -216,3 +216,4 @@ Règles : | 2026-11-18 | US-212 | Comment se règle un désaccord entre l'hôte et le voyageur ? | les parties échangent d'abord par la messagerie ; à défaut, le support examine le cas avec les deux parties et tranche (médiation) ; les recours légaux restent ouverts | aide publique de Turo (litiges entre hôte et voyageur) ; 16 LEG-015 | messagerie, support avec le numéro du trip et médiation, puis protection du consommateur ou tribunaux du lieu du trip ; aucune clause « definitiva e inapelable » ni arbitrage obligatoire (OQ-BR-24) | PROPOSÉ | | 2026-11-18 | US-225 | Si la durée du trip dépasse la validité d'une pré-autorisation, que fait-on de la caution ? | la caution n'existe que pour certains trips ; elle est affichée au checkout avant la réservation, puis rendue automatiquement après le trip ; les frais constatés ensuite sont débités sur la carte enregistrée | 08 BR-PAY-06 (pages d'aide de Turo sur les cautions, relues pour ADR-108) ; 10b UX-24 | aucune caution sans déclencheur : un trip sans caution n'est jamais refusé pour sa durée ; avec caution, ré-autorisation si le PSP la valide, sinon « débit puis remboursement » seulement si la détention de fonds est ouverte, sinon refus **avant le paiement** avec le nombre de jours possibles ; jamais de fonds bloqués faute de rail (ADR-164) | PROPOSÉ | | 2026-11-18 | US-225 | À la libération, comment prend-on les frais annexes sur la caution ? | la caution est rendue automatiquement ; les frais après le trip passent par la carte enregistrée | 08 BR-PAY-06 « Libération à heure fixe », E3 ; T57, T58 | frais prouvés, non contestés et notifiés au moins 48 h avant la décision capturés sur la caution (dans sa limite) puis le reste libéré ; sans capture partielle : caution entièrement libérée puis débit séparé ; « débit puis remboursement » : remboursement total puis débit séparé des frais (aucune retenue sur des fonds détenus) (ADR-164) | PROPOSÉ | +| 2026-11-18 | US-227 | Comment la prime de l'assureur est-elle suivie et payée ? | l'assureur partenaire couvre chaque location ; sa part des frais de protection lui revient selon le contrat, réglée périodiquement par Turo | 08 E7 règles 6 et 7 ; pages publiques de Turo sur les plans de protection et l'assureur partenaire | prime due tenue trip par trip à partir de la part assureur enregistrée ; bordereau mensuel (défaut, contrat à signer) émis par deux personnes FINANCE ; une contestation de paiement gèle la ligne sans réduire la prime ; aucun paiement avant le lot C ; ADR-165 | PROPOSÉ | diff --git a/docs/team/POUR_LE_FONDATEUR.md b/docs/team/POUR_LE_FONDATEUR.md index a0deec3f..3904af65 100644 --- a/docs/team/POUR_LE_FONDATEUR.md +++ b/docs/team/POUR_LE_FONDATEUR.md @@ -57,6 +57,9 @@ Pour chaque point : ce qu'on sait, puis **ma suggestion** (comme Turo, avec le m → **Ce qu'on propose** (PROPOSÉ, comme Turo, le moins de limitations possible) : une classe **« standard » par défaut** pour une voiture inconnue, ou un classement automatique par marque (Porsche, Land Rover, Mercedes, Lexus… en premium ou luxe), selon ce que le contrat de l'assureur accepte. C'est fait côté code (N-83, ADR-159, PROPOSÉ) : à la publication, une voiture sans classe prend la classe de son modèle s'il est connu, sinon celle de sa marque ou de son modèle s'il est cher (Porsche, Ferrari, Range Rover, Land Cruiser… en luxe ; Mercedes, BMW, Audi, Lexus, Land Rover, Volvo… en premium), sinon **standard**. Aucune voiture chère n'est rangée en standard. Rien n'est publié en production sans contrat d'assureur (interrupteurs à false). → **Ce qu'on attend de toi** : demander à l'assureur, dans le même contrat que §2.3 bis, (1) comment il classe une voiture absente de son catalogue, (2) le **minimum de responsabilité civile** par événement (`insurer_rc_minimum` ; valeurs de test PA 100 000 USD, PY 750 000 000 ₲, voir §4.1 quinquies), (3) sa **grille** par niveau de protection. +**2.3 septies Bordereau de l'assureur (US-227, 2026-11-18, GL-42).** Le code tient, voyage par voyage, la part des protections qui revient à l'assureur, prépare chaque mois un **bordereau** (liste des voyages terminés et total dû) et ne l'émet que si **deux personnes FINANCE différentes** le valident. Aucun paiement n'est fait à l'assureur pendant la bêta. Défauts PROPOSÉS : bordereau **mensuel** ; une contestation de paiement (chargeback) **gèle** la ligne sans jamais réduire la prime due ; une prime déjà facturée ne peut plus être remboursée sans revue FINANCE. +→ **Ce qu'on attend de toi** : dans le contrat de l'assureur (§2.3 bis), faire préciser la **périodicité** du bordereau, le **délai de paiement** et la **clause de chargeback** (comme Turo : la prime reste due). Il faudra aussi le second approbateur FINANCE de §2.7. + **2.4 Fournisseur de vérification d'identité.** Veriff, Sumsub, Shufti, Didit, MetaMap annoncent le Panama et le Paraguay. → **Suggestion** : le moins cher de ceux qui confirment **par écrit** le permis de conduire panaméen et paraguayen **et** les permis et passeports étrangers (touristes). Parcours minimal comme Turo : permis plus selfie, pas de justificatif de domicile. diff --git a/docs/team/handoffs/US-227.md b/docs/team/handoffs/US-227.md new file mode 100644 index 00000000..1f74321c --- /dev/null +++ b/docs/team/handoffs/US-227.md @@ -0,0 +1,35 @@ +# Passation US-227 — jambe de l'assureur : `insurer_ledger`, bordereau à double validation, rapprochement + +Agent de story (back-end / argent), claude-opus-5-5. Branche `story/US-227-insurer-ledger` (partie d'`origin/main` après #231, puis fusion de #234), worktree `../wt/US-227`. Décision : **ADR-165** (PROPOSÉ). PR en brouillon. + +## Périmètre + +Fait : registre de la prime due par trip (critère 1), bordereau mensuel rédigé par la base et émis par deux personnes FINANCE (critère 2, commandes existantes d'US-062 / US-101), lectures fermées hors FINANCE / ADMIN (critère 3), refus d'une variation sur une jambe déjà portée par un bordereau émis (08 E7 règle 3 bis, ADR-147), gel par chargeback qui exclut la ligne et bloque l'émission (règle 7), contrôles du rapprochement nocturne, clés étrangères vers l'assureur et le contrat (reports d'US-062 et d'US-108). **Pas fait** (critère 4) : ordre de reversement à l'assureur (`releaseLeg` / versement) à `insurer_settlement_at` : lot C (aucun PSP réel, aucun fonds de tiers détenu). Aucun interrupteur lu ni modifié ; aucun texte visible (aucun catalogue). + +## Numéros + +Migration **0143** (`0143_settlement_insurer_ledger.sql` ; 0138 prise par US-212 #234, 0139-0140 par US-224e #235, 0141 par US-224f #239, 0142 par US-225 #236 : **renuméroter à chaque fusion de main** qui prend 0143 : fichier, en-tête, `schema.md`, README db / STL / FIN, ADR-165, commentaires des tests et du code qui citent 0143). **ADR-165**, ligne **GL-42**, fixture **9947**. + +## Fait + +- **Migration 0143** : table `core.settlement_insurer_ledger_entry` (miroir exact de la source imposé par la politique d'insertion) ; déclencheurs `insurer_ledger_collection_posted` et `insurer_ledger_variation_posted` (SECURITY DEFINER, cmd_money_owner, aucun EXECUTE) ; `core.settlement_cmd_draft_insurer_bordereaux(text)` (travailleur `bordereau`, EXECUTE app_worker) ; garde `insurer_bordereau_issue_check` ; `core.finance_insurer_ledger_facts()` (travailleur `reconciliation`) ; colonnes `period_month` (bordereau), `bordereau_period` et `chargeback_clause` (contrat) ; politiques d'insertion du bordereau et des lignes resserrées ; clés étrangères. +- **API** : tâche `bordereau` (STL, `internal/insurer-bordereau.ts`, 24 h) ; trois contrôles FIN (`INSURER_LEDGER_COLLECTION`, `INSURER_LEDGER_SETTLEMENT`, `INSURER_BORDEREAU_OVERBILLED`) ; `insurer_leg_on_bordereau` garé `FIN_REVIEW` par `TripCancellationProcessor`. +- **Preuves** : `packages/db/test/l0/l0-us227-insurer-ledger.test.ts` (rôles de production, PA USD / PY PYG, groupe isolé : capture TJ01 / TJ08a ⇒ +prime, règlement T03 / T27 ⇒ variation TJ02b / TJ08b, transaction annulée ⇒ rien, rejeu ⇒ une écriture ; immuabilité, RLS-21 ; bordereau du mois clos, idempotence, mois ouvert, autre travailleur ; FINANCE A demande, A seconde session ⇒ `SELF_APPROVAL`, B ⇒ `ISSUED`, lignes rattachées au trip ; position projetée ; refus règle 3 bis ; lectures RLS-22 / 23 / 24 ; gardes d'émission gelée et périmée) ; tests unitaires FIN, STL, `worker-tasks`. +- **Docs** : ADR-165, README db / STL / FIN, `changelog.d/US-227-insurer-ledger.md`, GL-42, `COMME_TURO.md`, `POUR_LE_FONDATEUR.md` §2.3 septies, BOARD, matrice, inventaire, liste blanche `SECURITY DEFINER`, `schema.md` (recopié du job « base de données »). + +## Tests existants modifiés (pour la revue sécurité) + +- `l0-rls-columns.test.ts` : `period_month` ajoutée aux colonnes lisibles par app_api du bordereau (FINANCE / ADMIN ; nouvelle colonne accordée). +- `l0-rls-actors.test.ts` (RLS-12) : la nouvelle table porte `org_id`, elle est ajoutée à la liste (politique `fin_read`). +- `l0-us043-authorization-matrix.test.ts` : peuplement du monde par `us227_insert_entry` (aucune assertion changée). +- `stl-schema.test.ts` : nouvelle table dans la liste des tables STL. +- Fixture 9700 : `us062_insert_bordereau` et `us062_insert_insurer_ledger` **remplacées dans 9947** (même signature, mêmes lignes) pour créer un assureur et un contrat réels (clés étrangères) ; aucun attendu ne porte sur ces identifiants. +- `money-reconciliation.test.ts`, `worker-tasks.test.ts`, `trip-cancellation.test.ts`, `reconciliation.int.test.ts` : ajouts (14 contrôles, file `bordereau`, classement `FIN_REVIEW`, jambe assureur examinée). + +## Décisions PROPOSÉ + +Bordereau mensuel ; contrat figé à la réservation (création du trip) ; écriture sans contrat gardée mais jamais facturée (comptée au rapprochement) ; ligne seulement pour un trip terminé, non gelé, prime > 0 ; variation sur bordereau émis refusée (pas de créance sur l'assureur en bêta) ; position `insurer_ledger_state` projetée à chaque passe du travailleur. + +## Suites + +Reversement à l'assureur (lot C, GL-42) ; écrivain du gel par chargeback (US-709 / lot 3) ; sortie d'un bordereau DRAFT périmé ou gelé (transition `VOID`, US-227b) ; commande de saisie du contrat (N-190) ; écran FINANCE du bordereau (quatre langues) ; rapprochement avec le relevé de l'assureur (lot C). diff --git a/docs/team/reviews/US-227/architecture-2026-11-18.md b/docs/team/reviews/US-227/architecture-2026-11-18.md new file mode 100644 index 00000000..935a468e --- /dev/null +++ b/docs/team/reviews/US-227/architecture-2026-11-18.md @@ -0,0 +1,19 @@ +# Revue architecture — US-227 « jambe de l'assureur : insurer_ledger, bordereau à double validation, rapprochement » (PR n° 237) — 2026-11-18 + +Relecteur : revue-architecture / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 5f6427e7..504b3a52 + +Contexte : ADR-165 relu contre ADR-064, 111, 145, 147, 153, 19 US-227, 17 v6 (§2.3, §2.9, §3.2.8, §3.2.13, §7.2) et 08 E7 ; modules STL, FIN, DB ; numérotation, schéma, catalogue, documents du fondateur. Aucune base exécutée ici. + +| # | Gravité | Constat | +| --- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | **Numérotation et documents** : 0143 est contiguë avec `main` (dernière : 0142, US-225) ; ADR-165 libre (163, 164, 166 présentes) ; GL-42 était réservé ; fixture 9947 ; `docs/architecture/schema.md` recopié du job « base de données » (504b3a52, seul changement depuis le run rouge de 045e7333). Catalogue inchangé : aucun texte visible, donc rien en es / en / fr / pt-BR ; la réservation de version 80 par US-227 reste un trou numérique sans effet. | +| 2 | INFO | **Cohérence avec le modèle `host_ledger` (ADR-153)** : table d'écritures immuable, miroir imposé par la politique d'insertion, écrite dans la transaction de sa source par déclencheur `SECURITY DEFINER` de `cmd_money_owner` sans EXECUTE, lecture FINANCE / ADMIN du pays. Même famille, mêmes patrons, rien de nouveau à apprendre. Frontières de modules respectées : STL porte la tâche, FIN le rapprochement, l'émission reste aux commandes d'US-062 / US-101 ; imports par `index.ts`. | +| 3 | INFO | **Décisions PROPOSÉ** (bordereau mensuel, contrat figé à la création du trip, écriture sans contrat gardée et jamais facturée, refus d'une variation sur bordereau émis, position projetée) : défauts fail-closed de 17 §7.2 et d'ADR-147, aucun interrupteur lu ni écrit, aucun paiement ni fonds de tiers (critère 4 renvoyé au lot C, GL-42). Le refus d'une variation sur bordereau émis s'écarte de la lettre de 08 règle 3 bis (avance et imputation sur le bordereau suivant) : écart assumé par ADR-147, qu'ADR-165 cite ; à porter dans 17 §2.9 avec les reports annoncés. | +| 4 | MINEUR | **Trou de conception : prime encaissée après l'émission** (un encaissement INSURER sur un trip déjà ligné ne reçoit ni refus ni bordereau complémentaire ; voir revue argent n° 6) et **bordereau DRAFT périmé sans sortie** (aucune transition VOID : la garde refuse l'émission, les trips restent liés à un DRAFT inutilisable). Les deux se rejoignent : à traiter ensemble dans US-227b (transition `VOID` et ligne complémentaire, ou refus symétrique à l'encaissement), à inscrire aux « Limites » d'ADR-165 qui ne cite aujourd'hui que le second. | +| 5 | MINEUR | **Éligibilité d'un trip au bordereau** : état hors cours et hors litige, sans exiger le règlement de la version en tête (revue argent n° 8) ; l'ADR dit « terminé » sans lister les états retenus. À préciser (liste fermée, ou condition « règlement présent ») avant que l'écran FINANCE n'expose la notion. | +| 6 | MINEUR | **Rattachement du contrat à chaque écriture** plutôt qu'au trip : un contrat saisi après le premier encaissement (N-190) sépare les écritures d'un même trip entre « sans contrat » et « contrat » (revue argent n° 9). Une colonne de contrat figée au trip (17 §3.2.13) ou un contrôle « une écriture sans contrat sur trip à contrat » règlerait la question ; sans effet tant que `insurer_contract_active` = `false`. | +| 7 | INFO | **Retour arrière et expand / contract** : colonnes avec défaut, contraintes, table, fonctions, déclencheurs, politiques ajoutés ; deux politiques resserrées (ALTER POLICY) avec leur état antérieur noté ; rien retiré. Contrat posé et lu seulement par `cmd_money_owner` (`bordereau_period`, `chargeback_clause`, classe C0 à l'inventaire), aucune fuite vers `app_api`. | +| 8 | INFO | **Suites inscrites** : reversement lot C (GL-42), écrivain du gel (US-709), VOID d'un DRAFT (US-227b), saisie du contrat (N-190), écran FINANCE en quatre langues, relevé de l'assureur (lot C) ; `POUR_LE_FONDATEUR.md` et `COMME_TURO.md` mis à jour. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-227/argent-2026-11-18.md b/docs/team/reviews/US-227/argent-2026-11-18.md new file mode 100644 index 00000000..6861a8f8 --- /dev/null +++ b/docs/team/reviews/US-227/argent-2026-11-18.md @@ -0,0 +1,22 @@ +# Revue argent — US-227 « jambe de l'assureur : insurer_ledger, bordereau à double validation, rapprochement » (PR n° 237) — 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 : 5f6427e7..504b3a52 + +Contexte : migration 0143, déclencheurs, commande de rédaction, garde d'émission, faits du rapprochement, tests L0 / unitaires et fixtures relus en entier ; attendus rapprochés de 08 (E7 règles 1, 3, 3 bis, 6, 7 ; TJ01, TJ02b, TJ08a, TJ08b, TJ14b) et de `docs/specs/tools/golden_vectors.json` (lu avec `python -I -X utf8` : INSURER 2 550 / −2 550 USD, 105 000 / −105 000 PYG, soit 21,00 + 4,50 et 0,7 × 150 000). CI du run 44361351100 verte à la tête ; aucune base démarrée ici. + +| # | Gravité | Constat | +| --- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | **Somme du registre = jambes INSURER, à l'unité mineure.** COLLECTION = jambe INSURER de l'opération portée (0143:537-552) ; SETTLEMENT_VARIATION = `variation_minor` stocké (0143:582-592, jamais recalculé). La base de la v1 est l'état capturé et celle de n+1 la jambe de n (0027:17-18, 181) : Σ écritures = jambe retenue de la version en tête. Cas chiffrés relus : trip annulé USD +2 550 −2 550 = 0, PYG +105 000 −105 000 = 0 ; trip terminé : prime due 2 550 (USD) et 105 000 (PYG), une ligne de ce montant, total = Σ lignes. | +| 2 | INFO | **Politique d'insertion** (0143:206-225) : l'écriture n'est admise qu'au montant exact de la source (`g.amount_minor =` ou `l.variation_minor =`), pour les motifs et types d'opération attendus ; aucun montant reçu, aucun prorata ; ni UPDATE ni DELETE (déclencheur `settlement_immutable` et droits par colonnes). La forme `insurer_ledger_entry_source_shape` borne le signe (COLLECTION > 0, montant ≠ 0). | +| 3 | INFO | **Règle 3 bis** : 08 prévoit l'avance de Kmino sur `PLATFORM` et l'imputation sur le bordereau suivant ; la PR refuse la variation (`insurer_leg_on_bordereau`, 0143:574-581) et gare l'annulation en `FIN_REVIEW` (`trip-cancellation.ts`, FIN_CONSTRAINTS). Écart à la lettre de 08, mais conforme à ADR-147 (ligne 35 : pas d'avance, refus fail-closed) et à l'esprit fail-closed : aucun fonds avancé, aucune créance inventée, le remboursement du voyageur attend la décision FINANCE. Décision PROPOSÉ à garder visible pour le fondateur. | +| 4 | INFO | **Bordereau mensuel** (0143:333-389) : une ligne par trip hors cours et hors litige, prime due > 0, jambe non gelée, non déjà portée ; total = Σ lignes ; un bordereau par (contrat, mois) sous verrou consultatif et index unique ; mois ouvert ⇒ `PERIOD_OPEN`. Mois précédent calculé dans le fuseau du pays (31 mars − 1 mois = 28 février : le mois ne saute jamais). Un trip tardif rejoint le bordereau du mois suivant. Écriture sans contrat : gardée, jamais facturée, comptée (`insurerUnattributed`). Aucun paiement, aucun `releaseLeg`, aucun interrupteur lu ni écrit, aucun fonds de tiers. | +| 5 | INFO | **Trois contrôles FIN** (`money-reconciliation.ts`, `finance_insurer_ledger_facts`) : COLLECTION et SETTLEMENT à l'unité mineure, OVERBILLED (porté émis > prime due). Chaque corruption d'une unité est testée dans chaque pays configuré, attendus tirés des vecteurs (`legVector`), non du code testé. | +| 6 | MINEUR | **Prime encaissée après l'émission, jamais facturée et non détectée.** Le déclencheur d'encaissement (0143:526-555) n'a pas la garde de la règle 3 bis : un `DEBT_COLLECTION` ou `MIT_CHARGE` portant une jambe INSURER sur un trip déjà ligné par un bordereau émis ajoute une écriture positive ; la commande exclut ensuite tout trip déjà ligné (0143:369-370) et OVERBILLED ne regarde que porté > dû. Exemple : TJ01 (2 550) émis, puis 1 000 encaissés : dû 3 550, porté 2 550, 1 000 « à payer » dans `insurer_ledger_state` sans bordereau. Bordereau encore DRAFT : l'émission est refusée (`insurer_bordereau_stale`) et, sans transition VOID (suite US-227b), le bordereau et tous ses trips restent bloqués. Atteignable seulement avec une capture partielle reportée (08 règle 4, TJ17) ; PSP `FAKE`, `insurer_contract_active` = `false`. À inscrire aux suites de l'ADR-165 : ligne complémentaire ou refus symétrique, et contrôle « dû − porté > 0 sur trip ligné ». | +| 7 | MINEUR | **Course entre la garde d'émission et une variation.** La garde (0143:623-665) lit le registre sans verrou ; la variation (0143:574-581) lit l'état du bordereau sans verrou : deux transactions simultanées voient chacune l'ancien état, le bordereau est émis à 2 550 alors que le registre passe à 0. Fenêtre de quelques millisecondes ; OVERBILLED le détecterait la nuit. Un `FOR SHARE` sur la ligne du bordereau dans le déclencheur de variation (ou un verrou consultatif par trip) la fermerait. | +| 8 | MINEUR | **Éligibilité « terminé » large.** La liste d'exclusion (0143:367-368) laisse passer `RETURNED`, `POST_TRIP`, `TERMINATED_EARLY`, `VEHICLE_LOST` sans exiger de règlement : une prime encaissée peut être ligne d'un bordereau avant la version finale (remboursement de jours non utilisés, TJ02b). La garde d'émission rattrape un règlement arrivé avant l'émission ; après, la règle 3 bis le refuse (FIN_REVIEW). Fail-closed, sans perte ; l'exigence « règlement de la version en tête présent » est à inscrire aux suites. | +| 9 | MINEUR | **Rattachement du contrat à l'écriture.** `settlement_insurer_contract_of_trip` (0143:256-271) est évalué à chaque écriture : si le contrat n'est saisi (N-190) qu'après un premier encaissement, les collectes restent sans contrat et les variations suivantes en portent un ; Σ par contrat serait fausse (négative, donc non facturée). Sans effet avant la mise en service (aucun hôte activable sans contrat, GL-42) ; `insurerUnattributed` le rend visible. | +| 10 | MINEUR | **Aucun test d'une version n+1** : la propriété « n+1 n'écrit que sa variation depuis n » (ADR-165 point 4) n'est prouvée qu'indirectement (base de 0027) ; l'unique règlement exercé est la v1 d'annulation. Un L0 v1 puis v2 (USD et PYG) fermerait la preuve. Le registre n'est pas non plus comparé directement à `kept_minor` de la version en tête (seulement miroir des encaissements et des variations). | +| 11 | INFO | `insurer_ledger_state.payable_minor` compte aussi la prime des trips non terminés (test : « à payer » = trip terminé + trip BOOKED) : c'est la prime due non portée, non le montant exigible ; à nommer ainsi dans l'écran FINANCE à venir. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-227/code-2026-11-18.md b/docs/team/reviews/US-227/code-2026-11-18.md new file mode 100644 index 00000000..4dab96ef --- /dev/null +++ b/docs/team/reviews/US-227/code-2026-11-18.md @@ -0,0 +1,19 @@ +# Revue code — US-227 « jambe de l'assureur : insurer_ledger, bordereau à double validation, rapprochement » (PR n° 237) — 2026-11-18 + +Relecteur : revue-code / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 5f6427e7..504b3a52 + +Contexte : diff complet lu (migration 0143, tâche STL `insurer-bordereau.ts`, `money-reconciliation.ts`, `worker-tasks.ts`, `trip-cancellation.ts`, fixtures, tests, documents). CI verte au run 44361351100 (tentative 1). Aucune base démarrée ici. + +| # | Gravité | Constat | +| --- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | **Structure SQL propre** : tout est qualifié, `search_path` figé, `#variable_conflict use_column` là où des colonnes de sortie portent le nom des colonnes lues (0143:451), verrou consultatif par contrat avant lecture, rédaction idempotente (EXISTS), `ROWS FROM (unnest, unnest)` pour apparier trips et montants ; pas de SQL dynamique. Le retour arrière en en-tête est complet (objets, politiques, colonnes, droits). | +| 2 | INFO | **API** : `insurer-bordereau.ts` ne calcule aucun montant (la base décide) et ne journalise que des comptes par issue ; issue inconnue ⇒ erreur de contrat fail-closed (`draftCounts`) ; tâche déclarée par `registerPeriodic` 24 h, ajoutée à `worker-tasks.ts` et à son test (liste des files, périodes). Import des modules par `index.ts` seulement. Les trois contrôles FIN suivent le patron de US-217a (SQL de faits, analyse fail-closed des montants texte, fonction pure `insurerLedgerViolations`, comptes par pays). | +| 3 | INFO | **Tests** : les attendus viennent des vecteurs (`legVector(golden, …)` : TJ01 / TJ02b en USD, TJ08a / TJ08b en PYG), jamais du code testé ; une preuve de chaque refus par code de contrainte (`insurer_leg_on_bordereau`, `insurer_bordereau_stale`, `insurer_bordereau_line_frozen`, `insurer_ledger_command_forbidden`, `settlement_immutable`). Le classement `FIN_REVIEW` du nouveau code est testé (`trip-cancellation.test.ts`). | +| 4 | MINEUR | **Commentaire d'en-tête de `l0-us227-insurer-ledger.test.ts` périmé** : il décrit une « année tirée entre 1950 et 1999 » et un contrat « sur cette année seulement », alors que le code fixe `YEAR = 2089` avec des trips réservés à l'heure réelle et un contrat en vigueur depuis une heure pour dix ans (`us227_contract`). Le code est juste (le contrat est évalué à la création du trip), le texte trompe le prochain lecteur. | +| 5 | MINEUR | **Mois de la commande et période** : `period` du bordereau vaut le mois clos alors que les lignes peuvent venir de mois antérieurs (trip tardif, travailleur arrêté plus d'un mois) ; `period_month` porte donc le mois de rédaction, non celui des trips. Sans effet sur les montants ; à documenter dans le README STL quand l'écran FINANCE affichera la période. | +| 6 | MINEUR | **Projection de la position à chaque passe** : la requête de `insurer_ledger_state` recalcule sur toutes les écritures du pays chaque jour (agrégat par trip, deux `LATERAL`). Correct et idempotent, mais en O(écritures) ; à surveiller quand le volume du registre croîtra (index sur `(country_code, currency)` à envisager). | +| 7 | INFO | **Fixtures** : `us062_insert_bordereau` / `us062_insert_insurer_ledger` remplacées par `CREATE OR REPLACE` à signature et à corps équivalents (sauf identifiants désormais réels), commentées et dotées d'un retour arrière ; fonctions de test avec `search_path` figé, EXECUTE limité à `app_worker` / `app_api`. `numbering.test.ts` : 0143 suit 0142 de `main`. | +| 8 | INFO | Suites déclarées et honnêtes (reversement lot C, écrivain du gel, VOID d'un DRAFT, saisie du contrat N-190, écran FINANCE, relevé de l'assureur) ; les deux manques repérés par la revue argent (prime encaissée après l'émission, règlement de la version en tête exigé avant la ligne) sont à y ajouter. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-227/qa-2026-11-18.md b/docs/team/reviews/US-227/qa-2026-11-18.md new file mode 100644 index 00000000..7f4f5428 --- /dev/null +++ b/docs/team/reviews/US-227/qa-2026-11-18.md @@ -0,0 +1,19 @@ +# Revue qa — US-227 « jambe de l'assureur : insurer_ledger, bordereau à double validation, rapprochement » (PR n° 237) — 2026-11-18 + +Relecteur : revue-qa / claude-sonnet-5-5 (famille A, modèle autre que l'auteur claude-opus-5-5) +Entrées : 5f6427e7..504b3a52 + +Contexte : critères 1 à 4 d'US-227 (19) rapprochés des preuves ; `l0-us227-insurer-ledger.test.ts`, tests unitaires FIN / STL / worker-tasks, test d'intégration de rapprochement relus ; historique des runs lu par `gh`. Aucune base exécutée ici ; CI du run 44361351100 verte, tentative 1, tous les jobs. + +| # | Gravité | Constat | +| --- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | **Critère 1** : capture postée ⇒ +prime (TJ01 2 550 USD, TJ08a 105 000 PYG) ; règlement ⇒ variation INSURER stockée (TJ02b −2 550, TJ08b −105 000) ; somme du trip annulé = 0 ; écriture née et morte avec la transaction qui la porte (transaction annulée ⇒ aucune écriture) ; rejeu du report ⇒ une seule écriture ; horodatage borné par `platform.now()`. **Critère 2** : FINANCE A demande, A approuve en seconde session élevée ⇒ `SELF_APPROVAL`, B ⇒ `ISSUED`, lignes rattachées au trip. **Critère 3** : voyageur, hôte, OPS_AGENT, FINANCE d'un autre pays ⇒ 0 ligne sur les quatre tables ; FINANCE du pays lit. **Critère 4** : hors périmètre déclaré (lot C), aucun test attendu ; aucun ordre de reversement n'existe. | +| 2 | INFO | **Conditions L0-05** : toutes les preuves passent par `withRole('app_worker' / 'app_api')`, jamais migrator ; le travailleur est posé par le contexte de session (`bordereau`, `reconciliation`, `settlement`), les écritures directes d'un rôle applicatif refusées (`42501`). Deux pays (PA en USD, PY en PYG sans décimale) par `describe.each(COUNTRIES)`, attendus par devise tirés des vecteurs. Groupe isolé dans `vitest.l0.config.ts`, contrat de test replacé en `afterAll`. | +| 3 | INFO | **Rapprochement** : chaque corruption d'une unité mineure sur chacun des trois contrôles est jouée dans chaque pays configuré ; cas « aucun écart » (annulé, porté), prime négative hors registre, écriture sans contrat comptée, lecture fail-closed des lignes (montant numérique, décimal, booléen texte, pays minuscule, null). `reconciliation.int.test.ts` vérifie que la jambe INSURER du parcours doré est examinée. | +| 4 | INFO | **CI** : le run 44357324556 (045e7333) était rouge sur trois jobs (base de données, qualité, guide d'installation), tous pour la même cause : `schema.md` non recopié du job (inventaire des données, `test:unit`) ; entre ce SHA et la tête, seul `docs/architecture/schema.md` change (504b3a52), et le run 44361351100 est vert en tentative 1, sans relance. Je n'ai pas trouvé dans les runs listés d'échec du job « restauration chronométrée » (port occupé) : il est vert à la tête ; si un échec isolé a existé sur un autre SHA, c'est une instabilité hors du diff (aucun fichier de la restauration n'est touché) à inscrire au BOARD plutôt qu'à relancer. | +| 5 | MINEUR | **Garde d'émission `insurer_bordereau_incoherent` non éprouvée** (Σ lignes ≠ total, ou aucune ligne) : seules `line_frozen` et `stale` le sont en L0. La rédaction par la commande garantit Σ = total ; la garde est le filet si une ligne était ajoutée à la main sur un DRAFT (politique resserrée), non prouvée. | +| 6 | MINEUR | **Chemins non rejoués en L0** : version n+1 d'un règlement (variation seule de n+1), issue `EMPTY`, écriture sans contrat (jamais facturée), bordereau d'un second mois qui reprend un trip tardif, FINANCE d'un autre pays qui tente `ISSUE_BORDEREAU`. Les propriétés sont soutenues par des contraintes de 0027 ou par le code lu, mais aucune assertion ne les verrouille (USD et PYG). | +| 7 | MINEUR | **Gel (règle 7, TJ14b) joué par une fixture** (`marketplace_freeze_leg`) faute d'écrivain applicatif du gel (US-709 / lot 3, déclaré) : la preuve porte sur l'exclusion de la rédaction et sur la garde d'émission, pas sur le dégel « libéré en entier » de TJ14b. À compléter quand l'écrivain existe. | +| 8 | INFO | Aucun texte visible : le catalogue ne bouge pas (aucun test es / en / fr / pt-BR à ajouter). `rehearsal.sh` attend la file `bordereau` et son test unitaire (`worker-tasks.test.ts`) la liste avec sa période de 86 400 s. | + +Verdict : APPROUVÉ diff --git a/docs/team/reviews/US-227/securite-2026-11-18.md b/docs/team/reviews/US-227/securite-2026-11-18.md new file mode 100644 index 00000000..5c71068a --- /dev/null +++ b/docs/team/reviews/US-227/securite-2026-11-18.md @@ -0,0 +1,19 @@ +# Revue sécurité — US-227 « jambe de l'assureur : insurer_ledger, bordereau à double validation, rapprochement » (PR n° 237) — 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 : 5f6427e7..504b3a52 + +Contexte : migration 0143, allowlist `SECURITY DEFINER`, matrice d'autorisations, inventaire, fixtures 9700 / 9947, tests de sécurité modifiés (diff un par un), `rehearsal.sh`. CI verte au run 44361351100 (jobs base de données, revues, gitleaks). Chemins protégés `.github/`, `scripts/ci/`, `scripts/team/`, `review-requirements.json`, `.gitleaksignore` : non touchés (seul `scripts/deploy/rehearsal.sh` l'est). Aucune base exécutée ici. + +| # | Gravité | Constat | +| --- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | INFO | **Table `core.settlement_insurer_ledger_entry`** (0143:126-225) : `ENABLE` + `FORCE`, `migrator_all`, `REVOKE ALL FROM PUBLIC`, lecture `app_api` par colonnes et politique `fin_read` (STAFF, pays, FINANCE ou ADMIN ; SUPERADMIN, OPS, SUPPORT et staff sans session : aucune ligne), `app_worker` et `app_anon` sans droit. Immuable (UPDATE, DELETE, TRUNCATE). Aucun identifiant du personnel. Matrice et inventaire (`ORG`, C1) à jour ; RLS-22 à 24 éprouvées sous rôles de production dans les deux pays. | +| 2 | INFO | **`SECURITY DEFINER`** : quatre fonctions de la famille `cmd_money` (deux commandes, deux déclencheurs), `SET search_path = pg_catalog, pg_temp`, objets qualifiés, aucun SQL dynamique, `REVOKE ALL FROM PUBLIC`. Propriétaire `cmd_money_owner` (déclencheurs : ALTER OWNER avec `GRANT CREATE` ouvert puis retiré, 0143:613-616 ; commandes créées sous `SET LOCAL ROLE`) ; EXECUTE : rédaction et faits `app_worker` seulement, déclencheurs aucun ; l'allowlist (4 entrées) correspond. La commande et les faits vérifient le travailleur (`bordereau`, `reconciliation`) ; l'aide `contract_of_trip` n'a aucun EXECUTE. La garde d'émission est `SECURITY INVOKER` (sous la commande d'approbation), sans privilège propre. | +| 3 | INFO | **Émission à deux personnes inchangée** (commandes d'US-062 / US-101) ; la garde `insurer_bordereau_issue_check` s'y ajoute (incohérence, ligne gelée, prime périmée) sans la contourner ; politiques d'insertion resserrées (bordereau `DRAFT` avec `period_month`, lignes seulement sur un bordereau `DRAFT`, travailleur `bordereau`). Épreuves : auto-approbation refusée même en seconde session élevée (`SELF_APPROVAL`), FINANCE B approuve, gardes gelée et périmée. Un bordereau sans `period_month` n'est posable que par la fixture sous migrator (la garde l'ignore, 0143:632-634) : aucun chemin applicatif. | +| 4 | INFO | **Tests de sécurité modifiés, un par un** : `l0-rls-columns` (+ `period_month`, nouvelle colonne accordée à FINANCE / ADMIN, assertion identique) ; `l0-rls-actors` RLS-12 (+ la table, qui porte `org_id`, avec `fin_read`) ; `stl-schema` (+ la table, mêmes attentes RLS, propriétaire, immuabilité) ; `l0-us043` (peuplement du monde par `us227_insert_entry`, aucune assertion changée, ce qui éprouve la table sur des lignes réelles) ; `vitest.l0.config.ts` (fichier isolé). Aucune attente retirée ni assouplie. | +| 5 | INFO | **Fixture 9700 remplacée dans 9947** (`CREATE OR REPLACE`, signatures égales, `SECURITY DEFINER` + `search_path` figé, droits conservés) : `us062_insert_bordereau` et `us062_insert_insurer_ledger` posent les mêmes lignes, avec un assureur et un contrat réels (clés étrangères de 0143) ; les identifiants aléatoires d'avant ne sont assertés nulle part (appelants repérés par recherche : l0-us062, l0-us043, l0-us101, pg-console-stores, route-matrix). Les preuves d'US-062 / US-101 / US-043 gardent leur sens et passent à la tête (CI verte). Fixtures sous `test-migrations/` seulement, jamais en production. Contrat de test posé dans le fichier isolé, replacé en 1801 en `afterAll` (exclusion GiST de 0081) : aucune fuite vers d'autres fichiers. | +| 6 | INFO | **Autres points de la fiche** : horloge `platform.now()` seule (aucun `now()` ni `current_timestamp`) ; aucun interrupteur lu ni écrit (`insurer_contract_active` cité en commentaire seulement) ; aucune donnée personnelle en journal (la tâche ne journalise que des comptes par issue) ; file `bordereau` ajoutée à la liste attendue de `rehearsal.sh` (ordre alphabétique, rien d'autre) ; codes d'erreur mappés (`errors.ts`, `FIN_REVIEW`) ; clés étrangères vers l'assureur et le contrat avec portée (id, assureur, pays). | +| 7 | MINEUR | **Concurrence** : la garde d'émission et le déclencheur de variation lisent sans verrou l'état l'un de l'autre (0143:574-581, 623-665) ; à l'instant exact d'un règlement et d'une émission, un bordereau peut être émis sur une prime déjà annulée (fenêtre de quelques millisecondes, détectable la nuit par OVERBILLED). Verrou partagé sur la ligne du bordereau côté variation recommandé. Les rédacteurs, eux, sont sérialisés par contrat (verrou consultatif) et par l'index unique (contrat, mois). | +| 8 | MINEUR | **Politique d'insertion de COLLECTION** (0143:208-217) : elle n'épingle ni la devise, ni le compte d'hôte, ni le pays au trip de l'opération (seule la clé étrangère (trip, pays) joue) ; le seul écrivain est le déclencheur, qui lit ces valeurs du trip, donc sans exploit aujourd'hui. À durcir par `EXISTS` sur `booking_trip` si un autre écrivain apparaît (la variation, elle, est épinglée par la clé composite de 0129). | + +Verdict : APPROUVÉ diff --git a/packages/db/README.md b/packages/db/README.md index 3cac6f8c..cdd502cf 100644 --- a/packages/db/README.md +++ b/packages/db/README.md @@ -1037,3 +1037,15 @@ Migration générée `0142_config_deposit_rail_params` (groupe `deposit_always_r - **Valeurs PROPOSÉES**, identiques au PA et au PY, `fail_mode` BLOCK, portée pays : `deposit_always_required` faux, `deposit_trigger_classes` `["LUXE"]` (à confirmer par le fondateur), `deposit_young_driver_age` 30, `deposit_young_driver_classes` `[]` (DEC-FONDATEUR-21), `deposit_on_risk_flag` vrai, `risk_control_deployed` faux, `deposit_reauth_lead_h` 24, `deposit_fee_notice_h` 48. `deposit_amount`, `deposit_charge_cap` et `provider_max_hold_h` restent sans valeur (absent : caution exigée refusée, rail « débit puis remboursement » interdit, aucune pré-autorisation). Aucun interrupteur touché ; aucun droit nouveau. - **Lecture** : `PgDepositRailConfigReader` (module PAY) sous `app_api` ou `app_worker` : `core.config_param_value`, `core.config_go_live('funds_holding_enabled', pays)`, `core.payment_psp_capability`. - **Preuves** : `test/l0/l0-us225-deposit-rails.test.ts` (PA USD, PY PYG ; `app_api`, `app_worker`, `app_anon`) ; `apps/api/src/modules/pay/testing/deposit-rail-config.int.test.ts` (décision du checkout sur la configuration réelle, sous `app_api`). + +## Registre et bordereau de l'assureur (US-227 ; 08 E7 règles 3, 3 bis, 6, 7 ; 17 §2.9 ; ADR-165) + +Migration `0143_settlement_insurer_ledger`. Fixture `9947_test_us227_insurer_ledger_fixtures.sql` (contrat de test sur une période, lecture des écritures, écriture posée dans le monde de la matrice, essais d'immuabilité ; assureur et contrat « de structure » des fixtures de 9700, dont `us062_insert_bordereau` et `us062_insert_insurer_ledger` sont remplacées à signature égale pour les clés étrangères de 0143). + +- **Table** `core.settlement_insurer_ledger_entry` (classe C1, sujet ORG) : écriture signée en unités mineures de la devise du trip, motif `COLLECTION` (jambe `INSURER` d'un encaissement porté, clé vers `settlement_leg_movement`) ou `SETTLEMENT_VARIATION` (variation stockée d'une version, clé composite `settlement_ledger_scope_unique`), contrat de l'assureur en vigueur à la réservation (NULL si aucun) ; unique par opération et par règlement ; immuable. La politique d'insertion de `cmd_money_owner` exige la source au montant exact. +- **Écriture** : déclencheurs `insurer_ledger_collection_posted` (`settlement_leg_movement`) et `insurer_ledger_variation_posted` (`settlement_settlement_leg`), fonctions SECURITY DEFINER de cmd_money_owner sans EXECUTE ; refus `insurer_leg_on_bordereau` si le trip est porté par un bordereau émis. +- **Bordereau** : `core.settlement_cmd_draft_insurer_bordereaux(text)` (cmd_money_owner, EXECUTE app_worker, travailleur `bordereau`) ; colonne `period_month`, index unique (contrat, mois) ; lignes seulement sur un bordereau DRAFT ; garde `insurer_bordereau_issue_check` (incohérent, gelé, périmé) à l'émission par `cmd_approve_finance_action`. +- **Contrat** : `bordereau_period` (`MONTHLY`), `chargeback_clause` (`PREMIUM_NEVER_REDUCED`) ; clés étrangères vers l'assureur et le contrat sur `insurer_ledger_state`, `insurer_bordereau`, `platform_advance`. +- **Rapprochement** : `core.finance_insurer_ledger_facts()` (cmd_money_owner, EXECUTE app_worker, travailleur `reconciliation`). +- **Codes** : `insurer_ledger_command_forbidden` ⇒ `FORBIDDEN` ; `insurer_leg_on_bordereau`, `insurer_bordereau_incoherent`, `insurer_bordereau_stale`, `insurer_bordereau_line_frozen` ⇒ `INVARIANT_VIOLATION`. +- **Preuves** : `test/l0/l0-us227-insurer-ledger.test.ts` (TJ01, TJ02b, TJ08a, TJ08b ; T03, T27 ; PA USD, PY PYG ; groupe isolé) ; matrice d'autorisations peuplée (`l0-us043-authorization-matrix`). diff --git a/packages/db/authorization-matrix.json b/packages/db/authorization-matrix.json index 8fb72ebb..368ad948 100644 --- a/packages/db/authorization-matrix.json +++ b/packages/db/authorization-matrix.json @@ -2265,6 +2265,7 @@ "issued_at", "paid_at", "period", + "period_month", "status", "total_minor", "updated_at" @@ -2282,6 +2283,7 @@ "issued_at", "paid_at", "period", + "period_month", "psp_release_ref", "row_version", "status", @@ -2493,6 +2495,50 @@ "staff_sans_session": "aucune" } }, + "core.settlement_insurer_ledger_entry": { + "type": "table", + "droits": { + "app_api": { + "SELECT": [ + "amount_minor", + "country_code", + "created_at", + "currency", + "id", + "insurer_contract_id", + "insurer_id", + "operation_id", + "org_id", + "reason", + "segment_no", + "settlement_id", + "settlement_version", + "trip_id" + ] + }, + "app_worker": {}, + "app_anon": {} + }, + "politiques": { + "app_api": ["fin_read:SELECT"], + "app_worker": [], + "app_anon": [] + }, + "lecture": { + "sans_contexte": "aucune", + "voyageur": "aucune", + "hote": "aucune", + "cohote": "aucune", + "hote_org_forgee": "aucune", + "SUPPORT_AGENT": "aucune", + "OPS_AGENT": "aucune", + "FINANCE": "country_code = :pays", + "ADMIN": "country_code = :pays", + "ADMIN_portee_elargie": "country_code = :pays", + "SUPERADMIN": "aucune", + "staff_sans_session": "aucune" + } + }, "core.settlement_platform_advance": { "type": "table", "droits": { diff --git a/packages/db/migrations/0143_settlement_insurer_ledger.sql b/packages/db/migrations/0143_settlement_insurer_ledger.sql new file mode 100644 index 00000000..aeaeec64 --- /dev/null +++ b/packages/db/migrations/0143_settlement_insurer_ledger.sql @@ -0,0 +1,675 @@ +-- 0143 — STL / FIN : jambe de l'assureur — registre `insurer_ledger`, bordereau mensuel à double +-- validation FINANCE et rapprochement. +-- US-227 (agent back-end / argent) ; 19 US-227 (critères 1 à 3 ; critère 4 : aucun ordre de +-- reversement en bêta, suite lot C) ; 16 PRT-003 ; 08 E4 (versions, variation n → n+1), E7 règles +-- 1, 3, 3 bis, 6 et 7, BR-PROT-01 ; vecteurs TJ01, TJ02b (USD), TJ08a, TJ08b (PYG), TJ14a, TJ14b ; +-- 17 v6 §2.3 (RLS-21 à RLS-24, `cmd_money_owner`), §2.9 (`insurer_ledger`, bordereaux), §3.2.8, +-- §3.2.13 ; ADR-064, ADR-111, ADR-147 (jambe déjà portée par un bordereau : refus fail-closed), +-- ADR-153 (modèle du `host_ledger`), ADR-165 (cette migration). Appliquée sous `migrator`, en une +-- transaction. +-- +-- Cette migration : +-- 1. contrat de l'assureur : colonnes `bordereau_period` (MONTHLY, défaut PROPOSÉ de 17 §7.2) et +-- `chargeback_clause` (PREMIUM_NEVER_REDUCED, 08 E7 règle 7), contrainte de portée +-- (id, assureur, pays) ; clés étrangères vers `settlement_insurer` et `settlement_insurer_contract` +-- des tables `insurer_ledger_state`, `insurer_bordereau` et `platform_advance` (reports d'US-062 +-- et d'US-108) ; +-- 2. bordereau : colonne `period_month` (mois `YYYY-MM` du pays) posée par la commande de rédaction, +-- un bordereau par (contrat, mois) ; politiques d'insertion resserrées (bordereau rédigé par la +-- commande, lignes seulement sur un bordereau DRAFT) ; +-- 3. table `core.settlement_insurer_ledger_entry` : une écriture signée par ligne, `bigint` en +-- unités mineures de la devise du trip, rattachée au trip, au compte d'hôte, au contrat de +-- l'assureur en vigueur à la réservation (NULL si aucun : jamais facturée), et à sa source : +-- l'encaissement porté (`COLLECTION` : jambe INSURER de l'opération, motif positif) ou la +-- version du règlement (`SETTLEMENT_VARIATION` : variation signée de la jambe INSURER stockée, +-- E7 règle 3). Jamais recalculée, jamais un prorata : la politique d'insertion exige la ligne +-- source au montant exact. Idempotente par (opération) et par (règlement). Immuable. Une +-- version n+1 n'écrit que sa variation depuis la version n (sa base est la jambe de la +-- version n, 0027) : c'est la contre-passation de la version remplacée, sans réécrire la +-- version n ; +-- 4. écritures DANS LA MÊME TRANSACTION que leur source : déclencheurs AFTER INSERT sur +-- `settlement_leg_movement` (encaissements) et sur `settlement_settlement_leg` (jambe INSURER, +-- variation non nulle) ; une variation sur un trip dont la jambe INSURER est déjà portée par un +-- bordereau émis est REFUSÉE (`insurer_leg_on_bordereau`, 08 E7 règle 3 bis, ADR-147 : pas +-- d'avance sur une jambe assureur libérée en bêta, revue FIN) ; +-- 5. commande `core.settlement_cmd_draft_insurer_bordereaux(text)` (travailleur `bordereau`) : +-- pour le mois clos du pays, un bordereau DRAFT par contrat, une ligne par trip terminé dont la +-- prime due (Σ des écritures) est positive, non gelée (chargeback ouvert, 08 E7 règle 7) et pas +-- encore portée ; puis projection `insurer_ledger_state` (à payer, gelé, créance) ; +-- 6. garde d'émission `insurer_bordereau_issue_check` (DRAFT → ISSUED, dans la commande +-- d'approbation FINANCE existante de 0123) : Σ lignes = total, chaque ligne = prime due +-- actuelle du trip, aucune ligne gelée ; sinon refus ; +-- 7. faits du rapprochement `core.finance_insurer_ledger_facts()` (travailleur `reconciliation`). +-- +-- Aucun paiement à l'assureur : aucun ordre `releaseLeg` ni reversement (PSP FAKE, aucun fonds de +-- tiers détenu ; 19 US-227 critère 4 : suite du lot C). `insurer_contract_active` n'est pas lu ni +-- modifié. Aucun texte visible. +-- +-- Codes (packages/db/src/errors.ts) : +-- insurer_ledger_command_forbidden (42501) → FORBIDDEN ; +-- insurer_leg_on_bordereau (55000) → INVARIANT_VIOLATION (revue FIN du règlement) ; +-- insurer_bordereau_incoherent (23000) → INVARIANT_VIOLATION ; +-- insurer_bordereau_stale (55000) → INVARIANT_VIOLATION ; +-- insurer_bordereau_line_frozen (55000) → INVARIANT_VIOLATION ; +-- settlement_immutable (23000) → IMMUTABLE_RECORD (0027). +-- +-- Expand / contract : colonnes (avec défaut), contraintes, table, fonctions, déclencheurs, droits +-- et politiques AJOUTÉS ; deux politiques d'insertion de cmd_money_owner resserrées (ALTER POLICY) ; +-- rien n'est retiré. +-- +-- Retour arrière : +-- DROP TRIGGER insurer_bordereau_issue_check ON core.settlement_insurer_bordereau; +-- DROP TRIGGER insurer_ledger_variation_posted ON core.settlement_settlement_leg; +-- DROP TRIGGER insurer_ledger_collection_posted ON core.settlement_leg_movement; +-- DROP FUNCTION core.finance_insurer_ledger_facts(), +-- core.settlement_cmd_draft_insurer_bordereaux(text), +-- core.settlement_insurer_bordereau_issue_check(), +-- core.settlement_post_insurer_variation(), core.settlement_post_insurer_collection(), +-- core.settlement_insurer_contract_of_trip(uuid); +-- DROP TABLE core.settlement_insurer_ledger_entry; +-- ALTER POLICY cmd_money_ins ON core.settlement_insurer_bordereau WITH CHECK (<0036>); +-- ALTER POLICY cmd_money_ins ON core.settlement_insurer_bordereau_line WITH CHECK (<0036>); +-- ALTER TABLE core.settlement_insurer_bordereau DROP COLUMN period_month, +-- DROP CONSTRAINT insurer_bordereau_insurer_fk, DROP CONSTRAINT insurer_bordereau_contract_fk; +-- ALTER TABLE core.settlement_insurer_ledger_state DROP CONSTRAINT insurer_ledger_insurer_fk; +-- ALTER TABLE core.settlement_platform_advance DROP CONSTRAINT platform_advance_insurer_fk; +-- ALTER TABLE core.settlement_insurer_contract DROP COLUMN bordereau_period, +-- DROP COLUMN chargeback_clause, DROP CONSTRAINT settlement_insurer_contract_scope_unique; +-- (droits de cmd_money_owner de la section 5 : REVOKE). + +-- 1. Contrat de l'assureur et clés étrangères ---------------------------------------------------- + +ALTER TABLE core.settlement_insurer_contract + ADD COLUMN bordereau_period text NOT NULL DEFAULT 'MONTHLY' + CONSTRAINT settlement_insurer_contract_bordereau_period_valid + CHECK (bordereau_period IN ('MONTHLY')), + ADD COLUMN chargeback_clause text NOT NULL DEFAULT 'PREMIUM_NEVER_REDUCED' + CONSTRAINT settlement_insurer_contract_chargeback_clause_valid + CHECK (chargeback_clause IN ('PREMIUM_NEVER_REDUCED')), + ADD CONSTRAINT settlement_insurer_contract_scope_unique UNIQUE (id, insurer_id, country_code); +COMMENT ON COLUMN core.settlement_insurer_contract.bordereau_period IS + 'Périodicité du bordereau (insurer_settlement_at, 08 E7 règle 6) : MONTHLY, défaut PROPOSÉ ; ' + 'fixée par le contrat signé (décision du fondateur). US-227 (ADR-165).'; +COMMENT ON COLUMN core.settlement_insurer_contract.chargeback_clause IS + 'Clause de chargeback : PREMIUM_NEVER_REDUCED (08 E7 règle 7 : la prime due n''est jamais ' + 'réduite par un chargeback perdu sans décision écrite). US-227 (ADR-165).'; + +ALTER TABLE core.settlement_insurer_ledger_state + ADD CONSTRAINT insurer_ledger_insurer_fk FOREIGN KEY (insurer_id, country_code) + REFERENCES core.settlement_insurer (id, country_code); +ALTER TABLE core.settlement_platform_advance + ADD CONSTRAINT platform_advance_insurer_fk FOREIGN KEY (insurer_id, country_code) + REFERENCES core.settlement_insurer (id, country_code); + +-- 2. Bordereau : mois de la commande, unicité, clés étrangères ------------------------------------- + +ALTER TABLE core.settlement_insurer_bordereau + ADD COLUMN period_month text + CONSTRAINT insurer_bordereau_period_month_format + CHECK (period_month IS NULL OR period_month ~ '^[0-9]{4}-(0[1-9]|1[0-2])$'), + ADD CONSTRAINT insurer_bordereau_insurer_fk FOREIGN KEY (insurer_id, country_code) + REFERENCES core.settlement_insurer (id, country_code), + ADD CONSTRAINT insurer_bordereau_contract_fk FOREIGN KEY (insurer_contract_id, insurer_id, country_code) + REFERENCES core.settlement_insurer_contract (id, insurer_id, country_code); +COMMENT ON COLUMN core.settlement_insurer_bordereau.period_month IS + 'Mois YYYY-MM du pays couvert (période [début, fin) dans le fuseau du pays) ; posé par ' + 'settlement_cmd_draft_insurer_bordereaux, seul rédacteur. US-227 (ADR-165).'; +-- un bordereau par contrat et par mois (rédaction idempotente) +CREATE UNIQUE INDEX insurer_bordereau_contract_month ON core.settlement_insurer_bordereau + (insurer_contract_id, period_month) WHERE (period_month IS NOT NULL); + +-- lecture : FINANCE / ADMIN du pays (fin_read de 0036) et travailleurs de la liste blanche +GRANT SELECT (period_month) ON core.settlement_insurer_bordereau TO app_api, app_worker; + +-- 3. Registre de l'assureur ---------------------------------------------------------------------- + +CREATE TABLE core.settlement_insurer_ledger_entry ( + id uuid PRIMARY KEY, + trip_id uuid NOT NULL, + segment_no integer NOT NULL + CONSTRAINT insurer_ledger_entry_segment_beta CHECK (segment_no = 1), -- bêta : voir settlement + org_id uuid NOT NULL, -- compte d'hôte du trip (portée) + country_code text NOT NULL + CONSTRAINT insurer_ledger_entry_country_format CHECK (country_code ~ '^[A-Z]{2}$'), + currency text NOT NULL -- devise du trip + CONSTRAINT insurer_ledger_entry_currency_format CHECK (currency ~ '^[A-Z]{3}$'), + -- contrat en vigueur à la réservation du trip (17 §3.2.13 : valeurs figées à la réservation) ; + -- NULL si aucun : l'écriture est gardée (aucun montant perdu) mais n'entre dans aucun bordereau + insurer_id uuid, + insurer_contract_id uuid, + reason text NOT NULL + CONSTRAINT insurer_ledger_entry_reason_valid CHECK (reason IN ('COLLECTION', 'SETTLEMENT_VARIATION')), + operation_id uuid, -- COLLECTION : encaissement porté + settlement_id uuid, -- SETTLEMENT_VARIATION : version + settlement_version integer + CONSTRAINT insurer_ledger_entry_version_positive CHECK (settlement_version >= 1), + -- signé, du point de vue de l'assureur : > 0 prime due en plus, < 0 prime due en moins + amount_minor bigint NOT NULL + CONSTRAINT insurer_ledger_entry_amount_nonzero CHECK (amount_minor <> 0), + created_at timestamptz NOT NULL DEFAULT platform.now(), + CONSTRAINT insurer_ledger_entry_attribution CHECK ((insurer_id IS NULL) = (insurer_contract_id IS NULL)), + CONSTRAINT insurer_ledger_entry_source_shape CHECK ( + (reason = 'COLLECTION' AND operation_id IS NOT NULL AND settlement_id IS NULL + AND settlement_version IS NULL AND amount_minor > 0) + OR (reason = 'SETTLEMENT_VARIATION' AND operation_id IS NULL AND settlement_id IS NOT NULL + AND settlement_version IS NOT NULL)), + CONSTRAINT insurer_ledger_entry_operation_unique UNIQUE (operation_id), + CONSTRAINT insurer_ledger_entry_settlement_unique UNIQUE (settlement_id), + CONSTRAINT insurer_ledger_entry_trip_fk FOREIGN KEY (trip_id, country_code) + REFERENCES core.booking_trip (id, country_code), + CONSTRAINT insurer_ledger_entry_operation_fk FOREIGN KEY (operation_id) + REFERENCES core.settlement_leg_movement (operation_id), + CONSTRAINT insurer_ledger_entry_settlement_fk + FOREIGN KEY (settlement_id, trip_id, segment_no, settlement_version, org_id, country_code, currency) + REFERENCES core.settlement_settlement (id, trip_id, segment_no, version, org_id, country_code, currency), + CONSTRAINT insurer_ledger_entry_contract_fk FOREIGN KEY (insurer_contract_id, insurer_id, country_code) + REFERENCES core.settlement_insurer_contract (id, insurer_id, country_code) +); +CREATE INDEX insurer_ledger_entry_trip_idx ON core.settlement_insurer_ledger_entry (trip_id); +CREATE INDEX insurer_ledger_entry_contract_idx ON core.settlement_insurer_ledger_entry + (insurer_contract_id, country_code, currency) WHERE (insurer_contract_id IS NOT NULL); + +COMMENT ON TABLE core.settlement_insurer_ledger_entry IS + 'insurer_ledger (08 E7 ; 17 §2.9) : prime due à l''assureur, écritures signées par trip, lues ' + 'de la jambe INSURER stockée (encaissement porté, variation de chaque version du règlement), ' + 'dans la transaction de leur source ; immuable. US-227 (ADR-165).'; + +CREATE TRIGGER settlement_immutable BEFORE UPDATE OR DELETE ON core.settlement_insurer_ledger_entry + FOR EACH ROW EXECUTE FUNCTION core.settlement_guard_immutable(); +CREATE TRIGGER settlement_immutable_truncate BEFORE TRUNCATE ON core.settlement_insurer_ledger_entry + FOR EACH STATEMENT EXECUTE FUNCTION core.settlement_guard_immutable(); + +-- RLS : ENABLE + FORCE, socle migrator_all, lecture FINANCE / ADMIN du pays (comme host_ledger) +ALTER TABLE core.settlement_insurer_ledger_entry ENABLE ROW LEVEL SECURITY; +ALTER TABLE core.settlement_insurer_ledger_entry FORCE ROW LEVEL SECURITY; +CREATE POLICY migrator_all ON core.settlement_insurer_ledger_entry TO migrator + USING (true) WITH CHECK (true); +REVOKE ALL ON core.settlement_insurer_ledger_entry FROM PUBLIC; +-- aucun identifiant du personnel dans la table : toutes les colonnes, FINANCE et ADMIN du pays +GRANT SELECT (id, trip_id, segment_no, org_id, country_code, currency, insurer_id, + insurer_contract_id, reason, operation_id, settlement_id, settlement_version, + amount_minor, created_at) + ON core.settlement_insurer_ledger_entry TO app_api; +CREATE POLICY fin_read ON core.settlement_insurer_ledger_entry FOR SELECT TO app_api + USING (app.actor_kind() = 'STAFF' AND country_code = ANY (app.country_scope()) + AND (app.has_staff_role('FINANCE', country_code) OR app.has_staff_role('ADMIN', country_code))); + +-- propriétaire des commandes d'argent : lecture ; insertion par colonnes, une écriture n'existe +-- qu'en MIROIR EXACT de sa source (jamais un montant reçu) ; ni UPDATE ni DELETE +GRANT SELECT ON core.settlement_insurer_ledger_entry TO cmd_money_owner; +GRANT INSERT (id, trip_id, segment_no, org_id, country_code, currency, insurer_id, + insurer_contract_id, reason, operation_id, settlement_id, settlement_version, + amount_minor) + ON core.settlement_insurer_ledger_entry TO cmd_money_owner; +CREATE POLICY cmd_money_sel ON core.settlement_insurer_ledger_entry FOR SELECT TO cmd_money_owner + USING (true); +CREATE POLICY cmd_money_ins ON core.settlement_insurer_ledger_entry FOR INSERT TO cmd_money_owner + WITH CHECK ( + (settlement_insurer_ledger_entry.reason = 'COLLECTION' AND EXISTS ( + SELECT 1 + FROM core.settlement_leg_movement AS m + JOIN core.payment_payment_operation_leg AS g + ON g.operation_id = m.operation_id AND g.leg = 'INSURER' + WHERE m.operation_id = settlement_insurer_ledger_entry.operation_id + AND m.trip_id = settlement_insurer_ledger_entry.trip_id + AND m.segment_no = settlement_insurer_ledger_entry.segment_no + AND m.kind IN ('CAPTURE', 'MIT_CHARGE', 'DEBT_COLLECTION') + AND g.amount_minor = settlement_insurer_ledger_entry.amount_minor)) + OR (settlement_insurer_ledger_entry.reason = 'SETTLEMENT_VARIATION' AND EXISTS ( + SELECT 1 + FROM core.settlement_settlement_leg AS l + WHERE l.settlement_id = settlement_insurer_ledger_entry.settlement_id + AND l.leg = 'INSURER' + AND l.trip_id = settlement_insurer_ledger_entry.trip_id + AND l.segment_no = settlement_insurer_ledger_entry.segment_no + AND l.variation_minor = settlement_insurer_ledger_entry.amount_minor))); + +-- 4. Politiques d'insertion du bordereau resserrées (0036) ---------------------------------------- +GRANT INSERT (period_month) ON core.settlement_insurer_bordereau TO cmd_money_owner; +ALTER POLICY cmd_money_ins ON core.settlement_insurer_bordereau + WITH CHECK (app.actor_kind() = 'WORKER' AND app.worker_name() = 'bordereau' AND status = 'DRAFT' + AND period_month IS NOT NULL); +ALTER POLICY cmd_money_ins ON core.settlement_insurer_bordereau_line + WITH CHECK (app.actor_kind() = 'WORKER' AND app.worker_name() = 'bordereau' + AND EXISTS (SELECT 1 FROM core.settlement_insurer_bordereau AS b + WHERE b.id = settlement_insurer_bordereau_line.bordereau_id + AND b.country_code = settlement_insurer_bordereau_line.country_code + AND b.status = 'DRAFT')); + +-- 5. Lectures de cmd_money_owner nécessaires (sous migrator, propriétaire des tables) ------------- +GRANT SELECT (created_at) ON core.booking_trip TO cmd_money_owner; +GRANT SELECT (time_zone) ON core.config_country TO cmd_money_owner; +GRANT SELECT (id, country_code, status) ON core.settlement_insurer TO cmd_money_owner; +CREATE POLICY cmd_money_sel ON core.settlement_insurer FOR SELECT TO cmd_money_owner USING (true); +GRANT SELECT (id, insurer_id, country_code, valid_from, valid_to, bordereau_period) + ON core.settlement_insurer_contract TO cmd_money_owner; +CREATE POLICY cmd_money_sel ON core.settlement_insurer_contract FOR SELECT TO cmd_money_owner + USING (true); + +-- 6. Fonctions de la famille cmd_money ----------------------------------------------------------- +GRANT CREATE ON SCHEMA core TO cmd_money_owner; +SET LOCAL ROLE cmd_money_owner; + +-- Contrat de l'assureur du trip : celui du pays en vigueur à la réservation (création du trip) ; +-- au plus un (exclusion GiST de 0081). Aide interne SECURITY INVOKER : appelée par les fonctions +-- de son propriétaire seulement (aucun EXECUTE). +CREATE FUNCTION core.settlement_insurer_contract_of_trip(p_trip_id uuid) + RETURNS TABLE (insurer_id uuid, contract_id uuid) + LANGUAGE sql + STABLE + SET search_path = pg_catalog, pg_temp +AS $fn$ + SELECT c.insurer_id, c.id + FROM core.booking_trip AS t + JOIN core.settlement_insurer_contract AS c + ON c.country_code = t.country_code + AND c.valid_from <= t.created_at + AND (c.valid_to IS NULL OR c.valid_to > t.created_at) + WHERE t.id = p_trip_id + ORDER BY c.valid_from DESC + LIMIT 1 +$fn$; +COMMENT ON FUNCTION core.settlement_insurer_contract_of_trip(uuid) IS + 'Contrat de l''assureur en vigueur à la réservation du trip (pays du trip) ; aucune ligne si ' + 'aucun. Aide interne de cmd_money_owner. US-227 (ADR-165).'; +REVOKE ALL ON FUNCTION core.settlement_insurer_contract_of_trip(uuid) FROM PUBLIC; + +-- Bordereaux du mois clos de chaque pays (17 §2.9 ; 08 E7 règles 6 et 7), travailleur `bordereau`. +-- p_month NULL : mois précédent dans le fuseau du pays ; sinon `YYYY-MM`, refusé s'il n'est pas +-- clos (PERIOD_OPEN). Par contrat : un bordereau DRAFT par mois (EXISTS si déjà rédigé), une ligne +-- par trip terminé (fin prévue ≤ fin du mois, état hors cours et hors litige) dont la prime due +-- Σ écritures > 0, jambe INSURER non gelée et pas encore portée ; total = Σ lignes. Puis projection +-- `insurer_ledger_state` du pays : à payer (prime due non portée, non gelée), gelée (chargeback +-- ouvert), créance (portée au-delà de la prime due). Aucun ordre de paiement. +CREATE FUNCTION core.settlement_cmd_draft_insurer_bordereaux(p_month text) + RETURNS TABLE (outcome text, country text, bordereau uuid, lines integer, total bigint) + LANGUAGE plpgsql + VOLATILE + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_now timestamptz := platform.now(); + c record; + k record; + v_month text; + v_first date; + v_lower timestamptz; + v_upper timestamptz; + v_next timestamptz; + v_id uuid; + v_trips uuid[]; + v_amounts bigint[]; + v_total bigint; + v_count integer; +BEGIN + IF app.actor_kind() IS DISTINCT FROM 'WORKER' + OR app.worker_name() IS DISTINCT FROM 'bordereau' THEN + RAISE EXCEPTION 'insurer_ledger: commande réservée au travailleur bordereau' + USING ERRCODE = 'insufficient_privilege', CONSTRAINT = 'insurer_ledger_command_forbidden'; + END IF; + IF p_month IS NOT NULL AND p_month !~ '^[0-9]{4}-(0[1-9]|1[0-2])$' THEN + RAISE EXCEPTION 'insurer_ledger: mois invalide (YYYY-MM attendu)' + USING ERRCODE = 'invalid_parameter_value'; + END IF; + FOR c IN + SELECT y.code::text AS code, y.currency::text AS currency, y.time_zone + FROM core.config_country AS y + ORDER BY y.code + LOOP + v_month := COALESCE(p_month, + pg_catalog.to_char((v_now AT TIME ZONE c.time_zone) - interval '1 month', + 'YYYY-MM')); + v_first := pg_catalog.to_date(v_month || '-01', 'YYYY-MM-DD'); + v_lower := v_first::timestamp AT TIME ZONE c.time_zone; + v_upper := (v_first + interval '1 month') AT TIME ZONE c.time_zone; + -- prochaine émission : fin du mois en cours dans le fuseau du pays + v_next := (pg_catalog.date_trunc('month', v_now AT TIME ZONE c.time_zone) + interval '1 month') + AT TIME ZONE c.time_zone; + + IF v_upper > v_now THEN + RETURN QUERY SELECT 'PERIOD_OPEN'::text, c.code, NULL::uuid, 0, 0::bigint; + ELSE + FOR k IN + SELECT DISTINCT e.insurer_contract_id AS contract_id, e.insurer_id + FROM core.settlement_insurer_ledger_entry AS e + WHERE e.country_code = c.code AND e.currency = c.currency + AND e.insurer_contract_id IS NOT NULL + ORDER BY 1 + LOOP + -- un rédacteur à la fois par contrat ; l'index unique (contrat, mois) en défense + PERFORM pg_catalog.pg_advisory_xact_lock( + pg_catalog.hashtext('rueda.insurer_bordereau:' || k.contract_id::text)); + SELECT b.id INTO v_id + FROM core.settlement_insurer_bordereau AS b + WHERE b.insurer_contract_id = k.contract_id AND b.period_month = v_month; + IF v_id IS NOT NULL THEN + RETURN QUERY + SELECT 'EXISTS'::text, c.code, v_id, + (SELECT pg_catalog.count(*)::integer + FROM core.settlement_insurer_bordereau_line AS l WHERE l.bordereau_id = v_id), + (SELECT b.total_minor FROM core.settlement_insurer_bordereau AS b WHERE b.id = v_id); + CONTINUE; + END IF; + SELECT pg_catalog.array_agg(d.trip_id ORDER BY d.trip_id), + pg_catalog.array_agg(d.due ORDER BY d.trip_id), + COALESCE(pg_catalog.sum(d.due), 0)::bigint, + pg_catalog.count(*)::integer + INTO v_trips, v_amounts, v_total, v_count + FROM (SELECT e.trip_id, pg_catalog.sum(e.amount_minor)::bigint AS due + FROM core.settlement_insurer_ledger_entry AS e + WHERE e.insurer_contract_id = k.contract_id AND e.country_code = c.code + AND e.currency = c.currency AND e.segment_no = 1 + GROUP BY e.trip_id) AS d + JOIN core.booking_trip AS t ON t.id = d.trip_id + WHERE d.due > 0 + AND t.scheduled_end <= v_upper + AND t.status NOT IN ('BOOKED', 'CHECKIN_OPEN', 'START_WINDOW_EXPIRED', 'IN_PROGRESS', + 'OVERDUE', 'UNRETURNED', 'IN_DISPUTE') + AND NOT EXISTS (SELECT 1 FROM core.settlement_insurer_bordereau_line AS l + WHERE l.trip_id = d.trip_id AND l.segment_no = 1) + AND NOT EXISTS (SELECT 1 FROM core.settlement_trip_leg_balance AS lb + WHERE lb.trip_id = d.trip_id AND lb.segment_no = 1 + AND lb.leg = 'INSURER' AND lb.frozen); + IF v_count = 0 THEN + RETURN QUERY SELECT 'EMPTY'::text, c.code, NULL::uuid, 0, 0::bigint; + CONTINUE; + END IF; + v_id := pg_catalog.gen_random_uuid(); + INSERT INTO core.settlement_insurer_bordereau + (id, insurer_id, insurer_contract_id, country_code, currency, period, total_minor, + period_month) + VALUES (v_id, k.insurer_id, k.contract_id, c.code, c.currency, + pg_catalog.tstzrange(v_lower, v_upper, '[)'), v_total, v_month); + INSERT INTO core.settlement_insurer_bordereau_line + (bordereau_id, country_code, trip_id, segment_no, amount_minor) + SELECT v_id, c.code, u.trip_id, 1, u.amount + FROM ROWS FROM (pg_catalog.unnest(v_trips), pg_catalog.unnest(v_amounts)) + AS u(trip_id, amount); + RETURN QUERY SELECT 'DRAFTED'::text, c.code, v_id, v_count, v_total; + END LOOP; + END IF; + + -- projection de la position de chaque assureur du pays (17 §2.9 insurer_ledger) + INSERT INTO core.settlement_insurer_ledger_state AS s + (insurer_id, country_code, currency, payable_minor, frozen_minor, receivable_minor, + next_bordereau_at) + SELECT p.insurer_id, c.code, c.currency, p.payable, p.frozen, p.receivable, v_next + FROM (SELECT x.insurer_id, + COALESCE(pg_catalog.sum(x.open) FILTER (WHERE x.open > 0 AND NOT x.frozen), 0)::bigint + AS payable, + COALESCE(pg_catalog.sum(x.open) FILTER (WHERE x.open > 0 AND x.frozen), 0)::bigint + AS frozen, + COALESCE(pg_catalog.sum(-x.open) FILTER (WHERE x.open < 0), 0)::bigint + AS receivable + FROM (SELECT d.insurer_id, d.due - COALESCE(bl.billed, 0) AS open, + COALESCE(fz.frozen, false) AS frozen + FROM (SELECT e.insurer_id, e.trip_id, pg_catalog.sum(e.amount_minor) AS due + FROM core.settlement_insurer_ledger_entry AS e + WHERE e.country_code = c.code AND e.currency = c.currency + AND e.insurer_id IS NOT NULL AND e.segment_no = 1 + GROUP BY e.insurer_id, e.trip_id) AS d + LEFT JOIN LATERAL ( + SELECT pg_catalog.sum(l.amount_minor) AS billed + FROM core.settlement_insurer_bordereau_line AS l + JOIN core.settlement_insurer_bordereau AS b ON b.id = l.bordereau_id + WHERE l.trip_id = d.trip_id AND l.segment_no = 1 + AND b.status <> 'DRAFT' AND b.insurer_id = d.insurer_id) AS bl ON true + LEFT JOIN LATERAL ( + SELECT pg_catalog.bool_or(lb.frozen) AS frozen + FROM core.settlement_trip_leg_balance AS lb + WHERE lb.trip_id = d.trip_id AND lb.segment_no = 1 + AND lb.leg = 'INSURER') AS fz ON true) AS x + GROUP BY x.insurer_id) AS p + ON CONFLICT ON CONSTRAINT settlement_insurer_ledger_state_pkey DO UPDATE + SET payable_minor = EXCLUDED.payable_minor, frozen_minor = EXCLUDED.frozen_minor, + receivable_minor = EXCLUDED.receivable_minor, + next_bordereau_at = EXCLUDED.next_bordereau_at; + END LOOP; +END +$fn$; +COMMENT ON FUNCTION core.settlement_cmd_draft_insurer_bordereaux(text) IS + 'Bordereaux DRAFT du mois clos par contrat d''assureur et projection insurer_ledger_state ; ' + 'travailleur bordereau seulement (EXECUTE app_worker) ; aucun paiement. US-227 (ADR-165).'; +REVOKE ALL ON FUNCTION core.settlement_cmd_draft_insurer_bordereaux(text) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION core.settlement_cmd_draft_insurer_bordereaux(text) TO app_worker; + +-- Faits du rapprochement de la jambe assureur, par trip (identifiant technique non rendu par le +-- rapport : comptes par pays, FIN, money-reconciliation.ts) : Σ écritures d'encaissement et Σ +-- jambes INSURER des encaissements portés ; Σ écritures de règlement et Σ variations INSURER des +-- versions ; Σ porté par des bordereaux émis de la commande ; prime due ; écriture sans contrat. +CREATE FUNCTION core.finance_insurer_ledger_facts() + RETURNS TABLE (country_code text, currency text, collected_entries_minor bigint, + collected_legs_minor bigint, settled_entries_minor bigint, + settled_variations_minor bigint, billed_minor bigint, due_minor bigint, + unattributed boolean) + LANGUAGE plpgsql + STABLE + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +#variable_conflict use_column +BEGIN + IF app.actor_kind() IS DISTINCT FROM 'WORKER' + OR app.worker_name() IS DISTINCT FROM 'reconciliation' THEN + RAISE EXCEPTION 'finance: insurer ledger facts are read by the reconciliation worker only' + USING ERRCODE = 'insufficient_privilege'; + END IF; + RETURN QUERY + WITH col AS ( + SELECT m.trip_id, pg_catalog.sum(g.amount_minor)::bigint AS legs + FROM core.settlement_leg_movement AS m + JOIN core.payment_payment_operation_leg AS g + ON g.operation_id = m.operation_id AND g.leg = 'INSURER' + WHERE m.segment_no = 1 AND m.kind IN ('CAPTURE', 'MIT_CHARGE', 'DEBT_COLLECTION') + GROUP BY m.trip_id + ), + vari AS ( + SELECT l.trip_id, pg_catalog.sum(l.variation_minor)::bigint AS variations + FROM core.settlement_settlement_leg AS l + WHERE l.segment_no = 1 AND l.leg = 'INSURER' + GROUP BY l.trip_id + ), + ent AS ( + SELECT e.trip_id, + pg_catalog.sum(e.amount_minor) FILTER (WHERE e.reason = 'COLLECTION')::bigint AS col, + pg_catalog.sum(e.amount_minor) FILTER (WHERE e.reason = 'SETTLEMENT_VARIATION')::bigint + AS var, + pg_catalog.sum(e.amount_minor)::bigint AS due, + pg_catalog.bool_or(e.insurer_contract_id IS NULL) AS unattributed + FROM core.settlement_insurer_ledger_entry AS e + WHERE e.segment_no = 1 + GROUP BY e.trip_id + ), + bil AS ( + -- bordereaux rédigés par la commande (period_month posé), émis ou au-delà + SELECT l.trip_id, pg_catalog.sum(l.amount_minor)::bigint AS billed + FROM core.settlement_insurer_bordereau_line AS l + JOIN core.settlement_insurer_bordereau AS b ON b.id = l.bordereau_id + WHERE l.segment_no = 1 AND b.status <> 'DRAFT' AND b.period_month IS NOT NULL + GROUP BY l.trip_id + ), + ids AS ( + SELECT col.trip_id AS id FROM col + UNION SELECT vari.trip_id FROM vari + UNION SELECT ent.trip_id FROM ent + UNION SELECT bil.trip_id FROM bil + ) + SELECT t.country_code, t.currency, + COALESCE(ent.col, 0)::bigint, COALESCE(col.legs, 0)::bigint, + COALESCE(ent.var, 0)::bigint, COALESCE(vari.variations, 0)::bigint, + COALESCE(bil.billed, 0)::bigint, COALESCE(ent.due, 0)::bigint, + COALESCE(ent.unattributed, false) + FROM ids + JOIN core.booking_trip AS t ON t.id = ids.id + LEFT JOIN col ON col.trip_id = ids.id + LEFT JOIN vari ON vari.trip_id = ids.id + LEFT JOIN ent ON ent.trip_id = ids.id + LEFT JOIN bil ON bil.trip_id = ids.id; +END +$fn$; +COMMENT ON FUNCTION core.finance_insurer_ledger_facts() IS + 'Faits du rapprochement de la jambe assureur par trip : écritures du registre et jambes INSURER ' + 'stockées (encaissements portés, variations des versions), porté par bordereau émis, prime due. ' + 'Travailleur reconciliation seulement (EXECUTE app_worker). US-227 (ADR-165).'; +REVOKE ALL ON FUNCTION core.finance_insurer_ledger_facts() FROM PUBLIC; +GRANT EXECUTE ON FUNCTION core.finance_insurer_ledger_facts() TO app_worker; + +RESET ROLE; +REVOKE CREATE ON SCHEMA core FROM cmd_money_owner; + +-- 7. Déclencheurs d'écriture (créés par migrator, propriétaire des tables, puis transférés à +-- cmd_money_owner, comme 0129 section 5) -------------------------------------------------------- + +-- Encaissement porté (CAPTURE, MIT_CHARGE, DEBT_COLLECTION) : jambe INSURER de l'opération, lue +-- de `payment_operation_leg` (montant explicite, 08 E7 règle 1) ; 0 ⇒ rien. Rejeu : rien (UNIQUE). +CREATE FUNCTION core.settlement_post_insurer_collection() + RETURNS trigger + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_amount bigint; + t record; + k record; +BEGIN + SELECT g.amount_minor INTO v_amount + FROM core.payment_payment_operation_leg AS g + WHERE g.operation_id = NEW.operation_id AND g.leg = 'INSURER'; + IF v_amount IS NULL OR v_amount = 0 THEN + RETURN NULL; + END IF; + SELECT x.org_id, x.country_code, x.currency INTO t + FROM core.booking_trip AS x WHERE x.id = NEW.trip_id; + SELECT y.insurer_id, y.contract_id INTO k + FROM core.settlement_insurer_contract_of_trip(NEW.trip_id) AS y; + INSERT INTO core.settlement_insurer_ledger_entry + (id, trip_id, segment_no, org_id, country_code, currency, insurer_id, insurer_contract_id, + reason, operation_id, amount_minor) + VALUES (pg_catalog.gen_random_uuid(), NEW.trip_id, NEW.segment_no, t.org_id, t.country_code, + t.currency, k.insurer_id, k.contract_id, 'COLLECTION', NEW.operation_id, v_amount) + ON CONFLICT ON CONSTRAINT insurer_ledger_entry_operation_unique DO NOTHING; + RETURN NULL; +END +$fn$; +COMMENT ON FUNCTION core.settlement_post_insurer_collection() IS + 'Déclencheur insurer_ledger_collection_posted : la jambe INSURER d''un encaissement porté sur les ' + 'soldes est écrite au registre de l''assureur, dans la même transaction. US-227 (ADR-165).'; +REVOKE ALL ON FUNCTION core.settlement_post_insurer_collection() FROM PUBLIC; + +-- Version de règlement : variation signée de la jambe INSURER stockée (08 E7 règle 3 ; version +-- n+1 : variation depuis la version n). Jambe déjà portée par un bordereau émis ⇒ refus (règle +-- 3 bis, ADR-147) : le règlement entier est annulé et part en revue FIN. +CREATE FUNCTION core.settlement_post_insurer_variation() + RETURNS trigger + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + s record; + k record; +BEGIN + IF EXISTS (SELECT 1 + FROM core.settlement_insurer_bordereau_line AS l + JOIN core.settlement_insurer_bordereau AS b ON b.id = l.bordereau_id + WHERE l.trip_id = NEW.trip_id AND l.segment_no = NEW.segment_no + AND b.status <> 'DRAFT') THEN + RAISE EXCEPTION 'insurer_ledger: jambe INSURER déjà portée par un bordereau émis (08 E7 règle 3 bis)' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'insurer_leg_on_bordereau'; + END IF; + SELECT x.version, x.org_id, x.country_code, x.currency INTO s + FROM core.settlement_settlement AS x WHERE x.id = NEW.settlement_id; + SELECT y.insurer_id, y.contract_id INTO k + FROM core.settlement_insurer_contract_of_trip(NEW.trip_id) AS y; + INSERT INTO core.settlement_insurer_ledger_entry + (id, trip_id, segment_no, org_id, country_code, currency, insurer_id, insurer_contract_id, + reason, settlement_id, settlement_version, amount_minor) + VALUES (pg_catalog.gen_random_uuid(), NEW.trip_id, NEW.segment_no, s.org_id, s.country_code, + s.currency, k.insurer_id, k.contract_id, 'SETTLEMENT_VARIATION', NEW.settlement_id, + s.version, NEW.variation_minor) + ON CONFLICT ON CONSTRAINT insurer_ledger_entry_settlement_unique DO NOTHING; + RETURN NULL; +END +$fn$; +COMMENT ON FUNCTION core.settlement_post_insurer_variation() IS + 'Déclencheur insurer_ledger_variation_posted : la variation de la jambe INSURER d''une version de ' + 'règlement est écrite au registre de l''assureur, dans la même transaction ; refus si la jambe ' + 'est déjà portée par un bordereau émis. US-227 (ADR-165).'; +REVOKE ALL ON FUNCTION core.settlement_post_insurer_variation() FROM PUBLIC; + +CREATE TRIGGER insurer_ledger_collection_posted + AFTER INSERT ON core.settlement_leg_movement + FOR EACH ROW + WHEN (NEW.kind IN ('CAPTURE', 'MIT_CHARGE', 'DEBT_COLLECTION')) + EXECUTE FUNCTION core.settlement_post_insurer_collection(); +CREATE TRIGGER insurer_ledger_variation_posted + AFTER INSERT ON core.settlement_settlement_leg + FOR EACH ROW + WHEN (NEW.leg = 'INSURER' AND NEW.variation_minor <> 0) + EXECUTE FUNCTION core.settlement_post_insurer_variation(); + +GRANT CREATE ON SCHEMA core TO cmd_money_owner; +ALTER FUNCTION core.settlement_post_insurer_collection() OWNER TO cmd_money_owner; +ALTER FUNCTION core.settlement_post_insurer_variation() OWNER TO cmd_money_owner; +REVOKE CREATE ON SCHEMA core FROM cmd_money_owner; + +-- 8. Garde d'émission (SECURITY INVOKER : exécutée sous cmd_money_owner par la commande +-- d'approbation FINANCE de 0123, seule à écrire ISSUED) ------------------------------------------ +-- Un bordereau rédigé par la commande (period_month posé) n'est émis que s'il porte au moins une +-- ligne, Σ lignes = total, chaque ligne = prime due actuelle du trip (Σ écritures du contrat ; une +-- variation postérieure à la rédaction ⇒ bordereau périmé) et aucune jambe INSURER gelée. +CREATE FUNCTION core.settlement_insurer_bordereau_issue_check() + RETURNS trigger + LANGUAGE plpgsql + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_count integer; + v_sum bigint; +BEGIN + IF NEW.period_month IS NULL THEN + RETURN NEW; + END IF; + SELECT pg_catalog.count(*)::integer, COALESCE(pg_catalog.sum(l.amount_minor), 0)::bigint + INTO v_count, v_sum + FROM core.settlement_insurer_bordereau_line AS l + WHERE l.bordereau_id = NEW.id; + IF v_count = 0 OR v_sum <> NEW.total_minor THEN + RAISE EXCEPTION 'insurer_bordereau: lignes absentes ou Σ lignes ≠ total' + USING ERRCODE = 'integrity_constraint_violation', CONSTRAINT = 'insurer_bordereau_incoherent'; + END IF; + IF EXISTS (SELECT 1 + FROM core.settlement_insurer_bordereau_line AS l + JOIN core.settlement_trip_leg_balance AS lb + ON lb.trip_id = l.trip_id AND lb.segment_no = l.segment_no AND lb.leg = 'INSURER' + WHERE l.bordereau_id = NEW.id AND lb.frozen) THEN + RAISE EXCEPTION 'insurer_bordereau: une ligne porte une jambe INSURER gelée (08 E7 règle 7)' + USING ERRCODE = 'object_not_in_prerequisite_state', + CONSTRAINT = 'insurer_bordereau_line_frozen'; + END IF; + IF EXISTS (SELECT 1 + FROM core.settlement_insurer_bordereau_line AS l + WHERE l.bordereau_id = NEW.id + AND l.amount_minor IS DISTINCT FROM ( + SELECT pg_catalog.sum(e.amount_minor)::bigint + FROM core.settlement_insurer_ledger_entry AS e + WHERE e.trip_id = l.trip_id AND e.segment_no = l.segment_no + AND e.insurer_contract_id = NEW.insurer_contract_id)) THEN + RAISE EXCEPTION 'insurer_bordereau: prime due changée depuis la rédaction' + USING ERRCODE = 'object_not_in_prerequisite_state', CONSTRAINT = 'insurer_bordereau_stale'; + END IF; + RETURN NEW; +END +$fn$; +COMMENT ON FUNCTION core.settlement_insurer_bordereau_issue_check() IS + 'Garde insurer_bordereau_issue_check (DRAFT → ISSUED) : lignes = total, lignes = prime due ' + 'actuelle, aucune ligne gelée, pour un bordereau rédigé par la commande. US-227 (ADR-165).'; +REVOKE ALL ON FUNCTION core.settlement_insurer_bordereau_issue_check() FROM PUBLIC; + +CREATE TRIGGER insurer_bordereau_issue_check + BEFORE UPDATE OF status ON core.settlement_insurer_bordereau + FOR EACH ROW + WHEN (OLD.status = 'DRAFT' AND NEW.status = 'ISSUED') + EXECUTE FUNCTION core.settlement_insurer_bordereau_issue_check(); diff --git a/packages/db/personal-data-inventory.json b/packages/db/personal-data-inventory.json index 898c5d18..ab322f8c 100644 --- a/packages/db/personal-data-inventory.json +++ b/packages/db/personal-data-inventory.json @@ -1992,7 +1992,9 @@ "currency": "C0", "rc_amount_minor": "C0", "deductibles": "C0", - "exclusions": "C0" + "exclusions": "C0", + "bordereau_period": "C0", + "chargeback_clause": "C0" } }, "core.settlement_insurer_bordereau": { @@ -2005,6 +2007,7 @@ "country_code": "C1", "currency": "C1", "period": "C1", + "period_month": "C1", "total_minor": "C1", "status": "C1", "issued_by": "C1", @@ -2081,6 +2084,32 @@ "advance_id": "C1" } }, + "core.settlement_insurer_ledger_entry": { + "lifecycle": "A", + "subjects": [ + { + "column": "org_id", + "type": "ORG" + } + ], + "export": "controller", + "columns": { + "id": "C1", + "trip_id": "C1", + "segment_no": "C1", + "org_id": "C1", + "country_code": "C1", + "currency": "C1", + "insurer_id": "C1", + "insurer_contract_id": "C1", + "reason": "C1", + "operation_id": "C1", + "settlement_id": "C1", + "settlement_version": "C1", + "amount_minor": "C1", + "created_at": "C1" + } + }, "core.settlement_platform_advance": { "lifecycle": "A", "subjects": [ diff --git a/packages/db/security-definer-allowlist.json b/packages/db/security-definer-allowlist.json index b831d914..2597363b 100644 --- a/packages/db/security-definer-allowlist.json +++ b/packages/db/security-definer-allowlist.json @@ -2008,6 +2008,34 @@ "owner": "cmd_money_owner", "execute": ["app_worker"], "story": "US-224" + }, + { + "signature": "core.settlement_cmd_draft_insurer_bordereaux(text)", + "family": "cmd_money", + "owner": "cmd_money_owner", + "execute": ["app_worker"], + "story": "US-227" + }, + { + "signature": "core.finance_insurer_ledger_facts()", + "family": "cmd_money", + "owner": "cmd_money_owner", + "execute": ["app_worker"], + "story": "US-227" + }, + { + "signature": "core.settlement_post_insurer_collection()", + "family": "cmd_money", + "owner": "cmd_money_owner", + "execute": [], + "story": "US-227" + }, + { + "signature": "core.settlement_post_insurer_variation()", + "family": "cmd_money", + "owner": "cmd_money_owner", + "execute": [], + "story": "US-227" } ] } diff --git a/packages/db/src/errors.ts b/packages/db/src/errors.ts index f8def9ae..bba44c08 100644 --- a/packages/db/src/errors.ts +++ b/packages/db/src/errors.ts @@ -395,6 +395,12 @@ export const CONSTRAINT_CODES: Readonly diff --git a/packages/db/test-migrations/9947_test_us227_insurer_ledger_fixtures.sql b/packages/db/test-migrations/9947_test_us227_insurer_ledger_fixtures.sql new file mode 100644 index 00000000..4c935ed5 --- /dev/null +++ b/packages/db/test-migrations/9947_test_us227_insurer_ledger_fixtures.sql @@ -0,0 +1,209 @@ +-- 9947 — Fixtures de TEST d'US-227 (0143, ADR-165) : registre de l'assureur et bordereaux. Jamais en +-- production (test-migrations/ seulement). SECURITY DEFINER sous migrator (politiques migrator_all) ; +-- l'appelant reste sous un rôle de production (L0-05). +-- +-- - us062_fixture_insurer : assureur et contrat « de structure » du pays, en vigueur un seul jour +-- de 1800 (aucune réservation ne tombe dans sa période : aucune écriture ne lui est rattachée), +-- créés une fois par pays sous verrou consultatif ; donne aux lignes de structure des fixtures +-- de 9700 (US-062) les clés étrangères vers `settlement_insurer` / `settlement_insurer_contract` +-- qu'ajoute 0143 ; +-- - us062_insert_bordereau / us062_insert_insurer_ledger : REMPLACENT les corps de 9700 (mêmes +-- signatures, mêmes droits, mêmes lignes posées) ; seuls changent les identifiants d'assureur +-- et de contrat, désormais réels (clés étrangères de 0143). Aucun attendu des tests appelants +-- ne porte sur ces identifiants ; +-- - us227_contract : assureur ACTIVE et contrat du pays (par défaut : en vigueur depuis une +-- heure, pour dix ans) ; us227_retire_contract le replace ensuite hors du temps des autres +-- fichiers (le fichier de preuves est isolé : aucun autre contrat n'est posé pendant ce temps) ; +-- - us227_entries : écritures du registre d'un trip (lecture des preuves sous app_worker) ; +-- - us227_insert_entry : écriture posée dans le monde de la matrice d'autorisations +-- (l0-us043-authorization-matrix) sur le règlement en tête du trip, pour éprouver chaque +-- cellule de lecture sur des lignes réelles (montant : donnée de test, jamais un attendu ; sans +-- effet si le règlement a déjà son écriture) ; +-- - us227_try_update / us227_try_delete : immuabilité sous le propriétaire de la table. +-- +-- Retour arrière : DROP FUNCTION test_fixture.us062_fixture_insurer(text), +-- test_fixture.us227_contract(text, timestamptz, timestamptz), test_fixture.us227_entries(uuid), +-- test_fixture.us227_insert_entry(uuid), test_fixture.us227_try_update(uuid), +-- test_fixture.us227_try_delete(uuid), test_fixture.us227_retire_contract(uuid) ; corps de 9700 rétablis pour us062_insert_bordereau et +-- us062_insert_insurer_ledger. + +CREATE FUNCTION test_fixture.us062_fixture_insurer(p_country text) + RETURNS TABLE (insurer_id uuid, contract_id uuid) + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_from timestamptz := '1800-01-01T00:00:00Z'; + v_insurer uuid; + v_id uuid; +BEGIN + PERFORM pg_catalog.pg_advisory_xact_lock(pg_catalog.hashtext('rueda.us062_fixture_insurer:' || p_country)); + SELECT c.insurer_id, c.id INTO v_insurer, v_id + FROM core.settlement_insurer_contract AS c + WHERE c.country_code = p_country AND c.valid_from = v_from; + IF v_id IS NULL THEN + v_insurer := pg_catalog.gen_random_uuid(); + v_id := pg_catalog.gen_random_uuid(); + INSERT INTO core.settlement_insurer (id, country_code, name, kind, status) + VALUES (v_insurer, p_country, 'Assureur de structure (fixture)', 'INSURER', 'ACTIVE'); + INSERT INTO core.settlement_insurer_contract (id, insurer_id, country_code, version, + vehicle_eligibility, signed_at, valid_from, + valid_to) + VALUES (v_id, v_insurer, p_country, 1800, + pg_catalog.jsonb_build_object('maxVehicleAgeYears', 30, + 'valueClasses', pg_catalog.jsonb_build_array('STANDARD'), + 'usages', pg_catalog.jsonb_build_array('PARTICULAR')), + v_from, v_from, v_from + interval '1 day'); + END IF; + RETURN QUERY SELECT v_insurer, v_id; +END +$fn$; + +CREATE OR REPLACE FUNCTION test_fixture.us062_insert_bordereau(p_id uuid, p_country text, + p_currency text, p_total bigint) + RETURNS void + LANGUAGE sql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ + INSERT INTO core.settlement_insurer_bordereau + (id, insurer_id, insurer_contract_id, country_code, currency, period, total_minor) + SELECT p_id, f.insurer_id, f.contract_id, p_country, p_currency, + tstzrange('2031-01-01T00:00:00Z', '2031-02-01T00:00:00Z', '[)'), p_total + FROM test_fixture.us062_fixture_insurer(p_country) AS f +$fn$; + +CREATE OR REPLACE FUNCTION test_fixture.us062_insert_insurer_ledger(p_insurer_id uuid, + p_country text, + p_currency text, + p_payable bigint) + RETURNS void + LANGUAGE sql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ + INSERT INTO core.settlement_insurer (id, country_code, name, kind, status) + VALUES (p_insurer_id, p_country, 'Assureur de structure (fixture)', 'INSURER', 'ACTIVE') + ON CONFLICT DO NOTHING; + INSERT INTO core.settlement_insurer_ledger_state (insurer_id, country_code, currency, payable_minor) + VALUES (p_insurer_id, p_country, p_currency, p_payable); +$fn$; + +CREATE FUNCTION test_fixture.us227_contract(p_country text, p_from timestamptz, p_to timestamptz) + RETURNS TABLE (insurer_id uuid, contract_id uuid) + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + v_insurer uuid := pg_catalog.gen_random_uuid(); + v_id uuid := pg_catalog.gen_random_uuid(); + v_from timestamptz := COALESCE(p_from, platform.now() - interval '1 hour'); + v_to timestamptz := COALESCE(p_to, platform.now() + interval '10 years'); +BEGIN + INSERT INTO core.settlement_insurer (id, country_code, name, kind, license_ref, status) + VALUES (v_insurer, p_country, 'Aseguradora de prueba', 'INSURER', 'SSRP-TEST-227', 'ACTIVE'); + -- version unique par pays et par date de début (aucune course avec le « max + 1 » des autres + -- fixtures, qui ne créent que des contrats en vigueur depuis la veille) + INSERT INTO core.settlement_insurer_contract (id, insurer_id, country_code, version, + vehicle_eligibility, signed_at, valid_from, + valid_to) + VALUES (v_id, v_insurer, p_country, + 1000000 + (pg_catalog.date_part('epoch', v_from)::bigint % 1000000000)::integer, + pg_catalog.jsonb_build_object('maxVehicleAgeYears', 30, + 'valueClasses', pg_catalog.jsonb_build_array('STANDARD'), + 'usages', pg_catalog.jsonb_build_array('PARTICULAR')), + v_from, v_from, v_to); + RETURN QUERY SELECT v_insurer, v_id; +END +$fn$; + +-- Contrat de test replacé hors du temps des autres fichiers à la fin des preuves : une seconde +-- de 1801 propre au contrat (aucun recouvrement, exclusion GiST de 0081) ; conditions inchangées +-- (garde de 0115) ; écritures et bordereaux gardent son identifiant. +CREATE FUNCTION test_fixture.us227_retire_contract(p_contract uuid) + RETURNS void + LANGUAGE sql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ + UPDATE core.settlement_insurer_contract AS c + SET signed_at = x.at, valid_from = x.at, valid_to = x.at + interval '1 second' + FROM (SELECT '1801-01-01T00:00:00Z'::timestamptz + + pg_catalog.make_interval(secs => pg_catalog.abs(pg_catalog.hashtext(p_contract::text))::double precision) + AS at) AS x + WHERE c.id = p_contract +$fn$; + +CREATE FUNCTION test_fixture.us227_entries(p_trip_id uuid) + RETURNS TABLE (id uuid, reason text, amount_minor text, currency text, country_code text, + insurer_id uuid, insurer_contract_id uuid, operation_id uuid, + settlement_id uuid, settlement_version integer, created_at timestamptz) + LANGUAGE sql + STABLE + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ + SELECT e.id, e.reason, e.amount_minor::text, e.currency, e.country_code, e.insurer_id, + e.insurer_contract_id, e.operation_id, e.settlement_id, e.settlement_version, e.created_at + FROM core.settlement_insurer_ledger_entry AS e + WHERE e.trip_id = p_trip_id + ORDER BY e.created_at, e.reason, e.id +$fn$; + +CREATE FUNCTION test_fixture.us227_insert_entry(p_trip_id uuid) + RETURNS void + LANGUAGE plpgsql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ +DECLARE + s record; +BEGIN + SELECT x.id, x.trip_id, x.segment_no, x.version, x.org_id, x.country_code, x.currency INTO s + FROM core.settlement_settlement AS x + WHERE x.trip_id = p_trip_id + ORDER BY x.version DESC + LIMIT 1; + IF s.id IS NULL THEN + RAISE EXCEPTION 'us227_insert_entry: règlement absent'; + END IF; + INSERT INTO core.settlement_insurer_ledger_entry + (id, trip_id, segment_no, org_id, country_code, currency, reason, settlement_id, + settlement_version, amount_minor) + VALUES (pg_catalog.gen_random_uuid(), s.trip_id, s.segment_no, s.org_id, s.country_code, + s.currency, 'SETTLEMENT_VARIATION', s.id, s.version, -1) + ON CONFLICT ON CONSTRAINT insurer_ledger_entry_settlement_unique DO NOTHING; +END +$fn$; + +CREATE FUNCTION test_fixture.us227_try_update(p_id uuid) + RETURNS void + LANGUAGE sql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ + UPDATE core.settlement_insurer_ledger_entry SET amount_minor = amount_minor - 1 WHERE id = p_id +$fn$; + +CREATE FUNCTION test_fixture.us227_try_delete(p_id uuid) + RETURNS void + LANGUAGE sql + SECURITY DEFINER + SET search_path = pg_catalog, pg_temp +AS $fn$ + DELETE FROM core.settlement_insurer_ledger_entry WHERE id = p_id +$fn$; + +REVOKE ALL ON FUNCTION + test_fixture.us062_fixture_insurer(text), + test_fixture.us227_contract(text, timestamptz, timestamptz), test_fixture.us227_entries(uuid), + test_fixture.us227_insert_entry(uuid), test_fixture.us227_try_update(uuid), + test_fixture.us227_try_delete(uuid), test_fixture.us227_retire_contract(uuid) + FROM PUBLIC; +GRANT EXECUTE ON FUNCTION + test_fixture.us227_contract(text, timestamptz, timestamptz), test_fixture.us227_entries(uuid), + test_fixture.us227_insert_entry(uuid), test_fixture.us227_try_update(uuid), + test_fixture.us227_try_delete(uuid), test_fixture.us227_retire_contract(uuid) + TO app_worker, app_api; diff --git a/packages/db/test/int/stl-schema.test.ts b/packages/db/test/int/stl-schema.test.ts index 5ec98595..702d0078 100644 --- a/packages/db/test/int/stl-schema.test.ts +++ b/packages/db/test/int/stl-schema.test.ts @@ -32,6 +32,11 @@ const US108_TABLES = ['settlement_insurer', 'settlement_insurer_contract'] as co * commande de cmd_money_owner ; prouvés par l0-us709a-host-ledger.test.ts et la matrice d'US-043. */ const US709_TABLES = ['settlement_host_ledger_entry'] as const; +/** + * Registre de l'assureur d'US-227 (0143, ADR-165) : lecture FINANCE / ADMIN, écriture par les seuls + * déclencheurs de cmd_money_owner (miroir de la source) ; prouvé par l0-us227-insurer-ledger.test.ts. + */ +const US227_TABLES = ['settlement_insurer_ledger_entry'] as const; /** Tables en ajout seul : un règlement n'est jamais modifié (08 E4). */ const APPEND_ONLY = STL_TABLES.filter((t) => t !== 'settlement_trip_leg_balance'); @@ -54,7 +59,7 @@ describe('schéma STL (US-018, 0027)', () => { ORDER BY 1`, ); expect(rows.map((r) => r.t)).toEqual( - [...STL_TABLES, ...US062_TABLES, ...US108_TABLES, ...US709_TABLES].sort(), + [...STL_TABLES, ...US062_TABLES, ...US108_TABLES, ...US709_TABLES, ...US227_TABLES].sort(), ); for (const r of rows) { expect(r, r.t).toMatchObject({ rls: true, force: true, owner: 'migrator', m: true }); diff --git a/packages/db/test/l0/l0-rls-actors.test.ts b/packages/db/test/l0/l0-rls-actors.test.ts index baa3e7ea..512c3a60 100644 --- a/packages/db/test/l0/l0-rls-actors.test.ts +++ b/packages/db/test/l0/l0-rls-actors.test.ts @@ -711,6 +711,8 @@ describe('RLS-5, RLS-12, RLS-18', () => { 'settlement_settlement', // US-709a (0129, ADR-153) : host_ledger, lecture FINANCE / ADMIN du pays (fin_read) 'settlement_host_ledger_entry', + // US-227 (0143, ADR-165) : registre de l'assureur, lecture FINANCE / ADMIN du pays (fin_read) + 'settlement_insurer_ledger_entry', 'settlement_platform_advance', // US-062 : créance du titulaire, FINANCE / ADMIN 'settlement_settlement_leg', 'settlement_trip_leg_balance', diff --git a/packages/db/test/l0/l0-rls-columns.test.ts b/packages/db/test/l0/l0-rls-columns.test.ts index 1f759158..12eac2ea 100644 --- a/packages/db/test/l0/l0-rls-columns.test.ts +++ b/packages/db/test/l0/l0-rls-columns.test.ts @@ -279,6 +279,8 @@ const API_COLUMNS: Record = { 'country_code', 'currency', 'period', + // US-227 (0143, ADR-165) : mois du bordereau rédigé par la commande (FINANCE / ADMIN du pays) + 'period_month', 'total_minor', 'status', 'issued_at', diff --git a/packages/db/test/l0/l0-us043-authorization-matrix.test.ts b/packages/db/test/l0/l0-us043-authorization-matrix.test.ts index fb83a7f8..456bb6ff 100644 --- a/packages/db/test/l0/l0-us043-authorization-matrix.test.ts +++ b/packages/db/test/l0/l0-us043-authorization-matrix.test.ts @@ -821,6 +821,16 @@ beforeAll(async () => { } } }); + // US-227 (0143, ADR-165) : une écriture du registre de l'assureur sur le règlement en tête des + // trips a1, a2 et b1 (sans effet si le règlement a déjà la sienne), pour éprouver chaque cellule + // de la table sur des lignes réelles, par pays + await withTestTransaction(client, { commit: true }, async (tx) => { + for (const x of world.countries) { + for (const trip of [x.trips.a1.id, x.trips.a2.id, x.trips.b1.id]) { + await tx.query('SELECT test_fixture.us227_insert_entry($1)', [trip]); + } + } + }); }); }, 240_000); diff --git a/packages/db/test/l0/l0-us227-insurer-ledger.test.ts b/packages/db/test/l0/l0-us227-insurer-ledger.test.ts new file mode 100644 index 00000000..b1103138 --- /dev/null +++ b/packages/db/test/l0/l0-us227-insurer-ledger.test.ts @@ -0,0 +1,657 @@ +/** + * US-227 (migration 0143, ADR-165) — jambe de l'assureur : registre `insurer_ledger` alimenté dans la + * transaction de sa source (encaissement porté, version de règlement), bordereau mensuel rédigé par + * le travailleur `bordereau` et émis par DEUX personnes FINANCE distinctes, gardes d'émission (ligne + * gelée, prime changée), refus d'une variation sur une jambe déjà portée par un bordereau émis, RLS + * (RLS-21 à RLS-24), en USD (PA) et en PYG sans décimale (PY). + * + * Sous les rôles de PRODUCTION (`withRole` : assertion L0-05 en tête) : app_worker prépare et VALIDE + * les trips par les vraies commandes (capture signée et portée sur les soldes, règlement v1 du + * travailleur `settlement`) dans une période d'horloge virtuelle passée et propre à l'exécution + * (année tirée entre 1950 et 1999, contrat de l'assureur de test sur cette année seulement : aucun + * recouvrement avec les contrats « en vigueur depuis la veille » des autres fixtures) ; app_api porte + * les décisions FINANCE (sessions élevées, fixture 9650). Fichier isolé (`vitest.l0.config.ts`) : + * compte PSP FAKE ACTIVE du pays partagé (fixture 9800). + * + * Attendus : vecteurs de l'export des oracles (`@rueda/money/golden-vectors`), jamais le code testé : + * capture TJ01 (INSURER 25,50 USD) / TJ08a (INSURER 105 000 PYG) ; règlement T03 / T27, variations + * TJ02b / TJ08b (INSURER −25,50 / −105 000) ; 19 US-227 critères 1 à 3 ; 08 E7 règles 3, 3 bis, 6, 7. + */ +import { legVector } from '@rueda/money/golden-vectors'; +import type pg from 'pg'; +import { afterAll, describe, expect, it } from 'vitest'; +import { setSessionContext } from '../../src/index.ts'; +import { withRole, withTestTransaction } from '../../src/testing/index.ts'; +import { COUNTRIES } from '../support/avl.ts'; +import type { CountryCase } from '../support/avl.ts'; +import { applySignedStatus, caught, payTx, recordOperation, uuid } from '../support/pay.ts'; +import type { Legs } from '../support/pay.ts'; +import { staff, staffSessionHash } from '../support/rls.ts'; +import { golden, recordAsSettlementWorker, recordOfVector } from '../support/settlement.ts'; + +type Tx = pg.ClientBase; +const LEGS = ['HOST', 'INSURER', 'TAX_THIRD_PARTY', 'PLATFORM'] as const; +const REASON = 'Bordereau mensuel de l’assureur, contrôle de test'; +const REQUEST = 'SELECT * FROM core.settlement_cmd_request_finance_action($1, $2, $3, $4, $5)'; +const APPROVE = 'SELECT * FROM core.settlement_cmd_approve_finance_action($1, $2)'; +const DRAFT = `SELECT outcome, country, bordereau, lines, total::text AS total + FROM core.settlement_cmd_draft_insurer_bordereaux($1)`; + +/** Vecteurs par devise (jamais par pays). */ +const REF: Readonly> = { + USD: { capture: 'TJ01', cancelled: 'T03', variation: 'TJ02b' }, + PYG: { capture: 'TJ08a', cancelled: 'T27', variation: 'TJ08b' }, +}; + +/** + * Trips RÉSERVÉS à l'heure réelle (paramètres du pays en vigueur depuis la migration ; contrat de + * test en vigueur à cet instant), mais PRÉVUS en 2089 : les bordereaux portent sur des mois de 2089, + * clos sous une horloge virtuelle (aucun autre trip de la base n'y tombe). + */ +const YEAR = 2089; +const at = (month: number, day: number): string => + `${YEAR}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}T15:00:00.000Z`; +const monthOf = (month: number): string => `${YEAR}-${String(month).padStart(2, '0')}`; + +interface Entry { + readonly id: string; + readonly reason: string; + readonly amount_minor: string; + readonly currency: string; + readonly country_code: string; + readonly insurer_id: string | null; + readonly insurer_contract_id: string | null; + readonly operation_id: string | null; + readonly settlement_id: string | null; + readonly settlement_version: number | null; + readonly created_at: Date; +} + +interface Captured { + readonly trip: string; + readonly guest: string; + readonly operation: string; +} + +async function asWorker(tx: Tx, workerName: string): Promise { + await setSessionContext(tx, { kind: 'WORKER', workerName }); +} + +/** Trip capturé (jambes du vecteur) par la vraie commande, preuve signée et report sur les soldes. */ +async function capturedTrip( + tx: Tx, + c: CountryCase, + org: string, + capture: Legs, + month: number, +): Promise { + const trip = uuid(); + const guest = uuid(); + await asWorker(tx, 'payment_command'); + await tx.query(`SELECT test_fixture.rls_insert_trip($1, $2, $3, $4, $5, $6, $7, $8, $9)`, [ + trip, + guest, + org, + uuid(), + c.country, + c.currency, + c.timezone, + at(month, 10), + at(month, 13), + ]); + const account = ( + await tx.query<{ id: string }>('SELECT test_fixture.us024_psp_account($1) AS id', [c.country]) + ).rows[0]!.id; + const { operation_id: op } = await recordOperation(tx, { + tripId: trip, + accountId: account, + kind: 'CAPTURE', + amountMinor: LEGS.reduce((s, k) => s + capture[k], 0n), + currency: c.currency, + idemPlain: `trip:${trip}:CAPTURE:${uuid()}`, + legs: capture, + }); + expect(await applySignedStatus(tx, op, 'SUCCEEDED')).toBe('APPLIED'); + const moved = await tx.query<{ r: string }>( + 'SELECT core.settlement_cmd_apply_leg_movement($1) AS r', + [op], + ); + expect(moved.rows[0]?.r).toBe('APPLIED'); + return { trip, guest, operation: op }; +} + +async function entriesOf(tx: Tx, trip: string): Promise { + const { rows } = await tx.query('SELECT * FROM test_fixture.us227_entries($1)', [trip]); + return rows; +} + +interface DraftRow { + readonly outcome: string; + readonly country: string; + readonly bordereau: string | null; + readonly lines: number; + readonly total: string; +} + +/** Une passe du travailleur `bordereau` sur un mois clos (VALIDÉE). */ +async function draft(worker: Tx, month: string, closedAt: string): Promise { + return withTestTransaction(worker, { virtualNow: closedAt, commit: true }, async (tx) => { + await asWorker(tx, 'bordereau'); + return (await tx.query(DRAFT, [month])).rows; + }); +} + +interface Outcome { + readonly outcome: string; + readonly approval_id: string | null; +} + +/** Commande FINANCE sous le contexte STAFF de l'API (session élevée), VALIDÉE. */ +async function finance( + api: Tx, + actor: string, + token: Buffer, + country: string, + sql: string, + params: readonly unknown[], +): Promise { + return withTestTransaction(api, { commit: true }, async (tx) => { + await setSessionContext(tx, { + kind: 'STAFF', + actorId: actor, + countryScope: [country], + sessionTokenHash: token.toString('hex'), + }); + const { rows } = await tx.query(sql, [token, ...params]); + return rows[0] ?? { outcome: '', approval_id: null }; + }); +} + +const hashOf = (actor: string): Buffer => Buffer.from(staffSessionHash(actor) ?? '', 'hex'); + +describe.each(COUNTRIES)( + 'US-227 — registre et bordereau de l’assureur — $country ($currency)', + (c) => { + const r = REF[c.currency]; + if (r === undefined) throw new Error(`aucun vecteur en ${c.currency}`); + const capture = { ...legVector(golden, r.capture).legsMinor } as Legs; + const premium = capture.INSURER; + const variation = legVector(golden, r.variation).legsMinor.INSURER; + const other = COUNTRIES.find((x) => x.country !== c.country)!; + + // le contrat de test (en vigueur à l'heure réelle) est replacé hors du temps des autres fichiers + // (exclusion d'une version en vigueur par pays) ; écritures et bordereaux gardent son identifiant + afterAll(async () => { + if (w.contract === '') return; + await withRole('app_worker', (worker) => + withTestTransaction(worker, { commit: true }, async (tx) => { + await tx.query('SELECT test_fixture.us227_retire_contract($1)', [w.contract]); + }), + ); + }); + + // monde du pays, construit par les premiers essais puis relu par les suivants (ordre du fichier) + const w = { + insurer: '', + contract: '', + org: uuid(), + /** annulé par le voyageur (T03 / T27) : prime due 0 */ + cancelled: null as Captured | null, + /** terminé : une ligne du bordereau de mars */ + completed: null as Captured | null, + /** terminé, jambe INSURER gelée (chargeback ouvert) : exclu */ + frozen: null as Captured | null, + /** encore BOOKED : exclu */ + booked: null as Captured | null, + march: '', + financeA: '', + financeB: '', + financeOther: '', + ops: '', + financeASecond: Buffer.alloc(0), + }; + + it('oracle : la capture porte la prime du vecteur, le règlement la rend en entier', async () => { + await withRole('app_worker', () => Promise.resolve()); + expect(legVector(golden, r.capture).currency).toBe(c.currency); + expect(premium > 0n).toBe(true); + expect(variation).toBe(-premium); + }); + + it('critère 1 : capture postée ⇒ +prime au registre ; règlement ⇒ variation INSURER stockée (−prime) ; même transaction que la source, contrat en vigueur à la réservation, rejeu sans double écriture', async () => { + await withRole('app_worker', async (worker) => { + await withTestTransaction(worker, { commit: true }, async (tx) => { + const k = await tx.query<{ insurer_id: string; contract_id: string }>( + 'SELECT * FROM test_fixture.us227_contract($1, NULL, NULL)', + [c.country], + ); + w.insurer = k.rows[0]!.insurer_id; + w.contract = k.rows[0]!.contract_id; + }); + + // transaction ANNULÉE : l'écriture naît et meurt avec la capture qui la porte + let ghost = ''; + await payTx(worker, {}, async (tx) => { + const g = await capturedTrip(tx, c, w.org, capture, 3); + ghost = g.trip; + const e = await entriesOf(tx, g.trip); + expect(e.map((x) => [x.reason, BigInt(x.amount_minor)])).toEqual([ + ['COLLECTION', premium], + ]); + }); + await withTestTransaction(worker, {}, async (tx) => { + expect(await entriesOf(tx, ghost)).toEqual([]); + }); + + await payTx(worker, { commit: true }, async (tx) => { + w.cancelled = await capturedTrip(tx, c, w.org, capture, 3); + const settlement = await recordAsSettlementWorker( + tx, + { tripId: w.cancelled.trip, version: 1 }, + recordOfVector(r.cancelled), + ); + w.completed = await capturedTrip(tx, c, w.org, capture, 3); + w.frozen = await capturedTrip(tx, c, w.org, capture, 3); + w.booked = await capturedTrip(tx, c, w.org, capture, 3); + for (const t of [w.completed, w.frozen]) { + await tx.query(`SELECT test_fixture.us049_set_trip_status($1, 'COMPLETED')`, [t.trip]); + } + await tx.query(`SELECT test_fixture.marketplace_freeze_leg($1, 'INSURER')`, [ + w.frozen.trip, + ]); + + const e = await entriesOf(tx, w.cancelled.trip); + expect(e).toHaveLength(2); + const [col, set] = [ + e.find((x) => x.reason === 'COLLECTION'), + e.find((x) => x.reason === 'SETTLEMENT_VARIATION'), + ]; + expect(col).toMatchObject({ + currency: c.currency, + country_code: c.country, + insurer_id: w.insurer, + insurer_contract_id: w.contract, + operation_id: w.cancelled.operation, + settlement_id: null, + }); + expect(BigInt(col!.amount_minor)).toBe(premium); + // jambe INSURER STOCKÉE de la version 1 (jamais recalculée) : TJ02b / TJ08b + expect(set).toMatchObject({ + settlement_id: settlement, + settlement_version: 1, + operation_id: null, + insurer_contract_id: w.contract, + }); + expect(BigInt(set!.amount_minor)).toBe(variation); + // horodatage = horloge de la base (platform.now() à l'écriture, avant cette lecture) + const now = await tx.query<{ n: Date }>('SELECT platform.now() AS n'); + const nowMs = now.rows[0]!.n.getTime(); + expect(col!.created_at.getTime()).toBeLessThanOrEqual(nowMs); + expect(col!.created_at.getTime()).toBeGreaterThan(nowMs - 120_000); + expect(e.reduce((s, x) => s + BigInt(x.amount_minor), 0n)).toBe(0n); + + // rejeu du report de la capture : aucune seconde écriture + await asWorker(tx, 'payment_command'); + const again = await tx.query<{ r: string }>( + 'SELECT core.settlement_cmd_apply_leg_movement($1) AS r', + [w.completed.operation], + ); + expect(again.rows[0]?.r).not.toBe('APPLIED'); + expect(await entriesOf(tx, w.completed.trip)).toHaveLength(1); + }); + }); + }); + + it('critère 1 (TJ14) : aucun motif ne réduit la prime due hors règlement ; écritures immuables ; aucun rôle applicatif n’écrit le registre ni le bordereau (RLS-21)', async () => { + await withRole('app_worker', async (worker) => { + await withTestTransaction(worker, {}, async (tx) => { + const [e] = await entriesOf(tx, w.completed!.trip); + const upd = await caught(tx, () => + tx.query('SELECT test_fixture.us227_try_update($1)', [e!.id]), + ); + expect(upd?.constraint).toBe('settlement_immutable'); + const del = await caught(tx, () => + tx.query('SELECT test_fixture.us227_try_delete($1)', [e!.id]), + ); + expect(del?.constraint).toBe('settlement_immutable'); + for (const worker_name of ['settlement', 'bordereau', 'reconciliation']) { + await asWorker(tx, worker_name); + const ins = await caught(tx, () => + tx.query( + `INSERT INTO core.settlement_insurer_ledger_entry + (id, trip_id, segment_no, org_id, country_code, currency, reason, operation_id, + amount_minor) + VALUES ($1, $2, 1, $3, $4, $5, 'COLLECTION', $6, 1)`, + [uuid(), w.completed!.trip, w.org, c.country, c.currency, w.completed!.operation], + ), + ); + expect(ins?.code, worker_name).toBe('42501'); + } + }); + }); + await withRole('app_api', async (api) => { + await withTestTransaction(api, {}, async (tx) => { + for (const sql of [ + `INSERT INTO core.settlement_insurer_ledger_entry (id, trip_id, segment_no, org_id, + country_code, currency, reason, operation_id, amount_minor) + VALUES ('${uuid()}', '${w.completed!.trip}', 1, '${w.org}', '${c.country}', + '${c.currency}', 'COLLECTION', '${w.completed!.operation}', 1)`, + `UPDATE core.settlement_insurer_bordereau SET status = 'ISSUED'`, + `DELETE FROM core.settlement_insurer_ledger_entry`, + `UPDATE core.settlement_insurer_ledger_state SET payable_minor = 0`, + ]) { + const err = await caught(tx, () => tx.query(sql)); + expect(err?.code, sql).toBe('42501'); + } + }); + }); + }); + + it('bordereau du mois clos : une ligne par trip terminé dont la prime est due, non gelée ; total = Σ lignes ; rédaction idempotente ; position de l’assureur projetée', async () => { + await withRole('app_worker', async (worker) => { + const rows = await draft(worker, monthOf(3), at(4, 2)); + const mine = rows.filter((x) => x.country === c.country && x.outcome === 'DRAFTED'); + expect(mine).toHaveLength(1); + expect(mine[0]).toMatchObject({ lines: 1, total: premium.toString() }); + w.march = mine[0]!.bordereau!; + + await withTestTransaction(worker, {}, async (tx) => { + await asWorker(tx, 'bordereau'); + const b = await tx.query<{ + status: string; + insurer_id: string; + insurer_contract_id: string; + currency: string; + period_month: string; + total: string; + lower_ok: boolean; + upper_ok: boolean; + }>( + `SELECT status, insurer_id, insurer_contract_id, currency, period_month, + total_minor::text AS total, + lower(period) = ($2::date)::timestamp AT TIME ZONE $4 AS lower_ok, + upper(period) = ($3::date)::timestamp AT TIME ZONE $4 AS upper_ok + FROM core.settlement_insurer_bordereau WHERE id = $1`, + [w.march, `${monthOf(3)}-01`, `${monthOf(4)}-01`, c.timezone], + ); + expect(b.rows[0]).toEqual({ + status: 'DRAFT', + insurer_id: w.insurer, + insurer_contract_id: w.contract, + currency: c.currency, + period_month: monthOf(3), + total: premium.toString(), + lower_ok: true, + upper_ok: true, + }); + const lines = await tx.query<{ trip_id: string; amount: string; country_code: string }>( + `SELECT trip_id, amount_minor::text AS amount, country_code + FROM core.settlement_insurer_bordereau_line WHERE bordereau_id = $1`, + [w.march], + ); + expect(lines.rows).toEqual([ + { trip_id: w.completed!.trip, amount: premium.toString(), country_code: c.country }, + ]); + // position : à payer = trip terminé (ligne DRAFT, pas encore émise) + trip BOOKED ; + // gelé = trip au chargeback ouvert ; aucune créance + const s = await tx.query<{ payable: string; frozen: string; receivable: string }>( + `SELECT payable_minor::text AS payable, frozen_minor::text AS frozen, + receivable_minor::text AS receivable + FROM core.settlement_insurer_ledger_state + WHERE insurer_id = $1 AND country_code = $2 AND currency = $3`, + [w.insurer, c.country, c.currency], + ); + expect(s.rows[0]).toEqual({ + payable: (2n * premium).toString(), + frozen: premium.toString(), + receivable: '0', + }); + }); + + // seconde passe : le même bordereau, aucune ligne de plus + const again = await draft(worker, monthOf(3), at(4, 2)); + expect(again.filter((x) => x.country === c.country && x.bordereau === w.march)).toEqual([ + { + outcome: 'EXISTS', + country: c.country, + bordereau: w.march, + lines: 1, + total: premium.toString(), + }, + ]); + // mois non clos : rien + await withTestTransaction(worker, { virtualNow: at(3, 20) }, async (tx) => { + await asWorker(tx, 'bordereau'); + const open = await tx.query(DRAFT, [monthOf(3)]); + expect(open.rows.filter((x) => x.country === c.country)).toEqual([ + { outcome: 'PERIOD_OPEN', country: c.country, bordereau: null, lines: 0, total: '0' }, + ]); + }); + // autre travailleur : refus + await withTestTransaction(worker, {}, async (tx) => { + await asWorker(tx, 'settlement'); + const err = await caught(tx, () => tx.query(DRAFT, [monthOf(3)])); + expect(err?.constraint).toBe('insurer_ledger_command_forbidden'); + }); + }); + }); + + it('critère 2 (RLS-24) : FINANCE A demande ISSUE_BORDEREAU puis l’approuve elle-même, même dans une seconde session ⇒ refus ; FINANCE B approuve ⇒ ISSUED, chaque ligne rattachée à un trip', async () => { + await withRole('app_api', async (api) => { + await withTestTransaction(api, { commit: true }, async (tx) => { + w.financeA = await staff(tx, 'FINANCE', [c.country]); + w.financeB = await staff(tx, 'FINANCE', [c.country]); + w.financeOther = await staff(tx, 'FINANCE', [other.country]); + w.ops = await staff(tx, 'OPS_AGENT', [c.country]); + w.financeASecond = Buffer.from(uuid().replace(/-/g, '').repeat(2), 'hex'); + await tx.query('SELECT test_fixture.iam_open_elevated_session($1, $2)', [ + w.financeA, + w.financeASecond, + ]); + }); + const req = await finance(api, w.financeA, hashOf(w.financeA), c.country, REQUEST, [ + uuid(), + 'ISSUE_BORDEREAU', + w.march, + REASON, + ]); + expect(req.outcome).toBe('REQUESTED'); + const self = await finance(api, w.financeA, w.financeASecond, c.country, APPROVE, [ + req.approval_id, + ]); + expect(self.outcome).toBe('SELF_APPROVAL'); + const ok = await finance(api, w.financeB, hashOf(w.financeB), c.country, APPROVE, [ + req.approval_id, + ]); + expect(ok.outcome).toBe('APPROVED'); + + await withTestTransaction(api, {}, async (tx) => { + const row = await tx.query<{ + status: string; + issued_by: string; + second_validated_by: string; + }>( + 'SELECT status, issued_by, second_validated_by FROM test_fixture.us062_bordereau_row($1)', + [w.march], + ); + expect(row.rows[0]).toEqual({ + status: 'ISSUED', + issued_by: w.financeA, + second_validated_by: w.financeB, + }); + await setSessionContext(tx, { + kind: 'STAFF', + actorId: w.financeB, + countryScope: [c.country], + sessionTokenHash: hashOf(w.financeB).toString('hex'), + }); + const lines = await tx.query<{ trip_id: string }>( + 'SELECT trip_id FROM core.settlement_insurer_bordereau_line WHERE bordereau_id = $1', + [w.march], + ); + expect(lines.rows).toEqual([{ trip_id: w.completed!.trip }]); + const entries = await tx.query<{ n: number }>( + `SELECT count(*)::int AS n FROM core.settlement_insurer_ledger_entry + WHERE trip_id = ANY ($1::uuid[])`, + [[w.cancelled!.trip, w.completed!.trip]], + ); + expect(entries.rows[0]?.n).toBe(3); + }); + }); + + // position projetée par la passe suivante : la ligne émise n'est plus à payer + await withRole('app_worker', async (worker) => { + await draft(worker, monthOf(3), at(4, 2)); + await withTestTransaction(worker, {}, async (tx) => { + await asWorker(tx, 'bordereau'); + const s = await tx.query<{ payable: string; frozen: string; receivable: string }>( + `SELECT payable_minor::text AS payable, frozen_minor::text AS frozen, + receivable_minor::text AS receivable + FROM core.settlement_insurer_ledger_state + WHERE insurer_id = $1 AND country_code = $2 AND currency = $3`, + [w.insurer, c.country, c.currency], + ); + expect(s.rows[0]).toEqual({ + payable: premium.toString(), + frozen: premium.toString(), + receivable: '0', + }); + }); + }); + }); + + it('critère 1 (règle 3 bis) : une variation INSURER sur un trip déjà porté par un bordereau émis est refusée ; rien n’est écrit', async () => { + await withRole('app_worker', async (worker) => { + await withTestTransaction(worker, {}, async (tx) => { + const err = await caught(tx, () => + recordAsSettlementWorker( + tx, + { tripId: w.completed!.trip, version: 1, tripRowVersion: 1 }, + recordOfVector(r.cancelled), + ), + ); + expect(err?.constraint).toBe('insurer_leg_on_bordereau'); + expect(await entriesOf(tx, w.completed!.trip)).toHaveLength(1); + }); + }); + }); + + it('critère 3 (RLS-22, RLS-23, RLS-24) : voyageur, hôte, OPS_AGENT sans dossier et FINANCE d’un autre pays ne lisent rien ; FINANCE du pays lit registre, bordereau et position', async () => { + await withRole('app_api', async (api) => { + await withTestTransaction(api, {}, async (tx) => { + const read = async (): Promise => { + const out: number[] = []; + for (const t of [ + 'settlement_insurer_ledger_entry', + 'settlement_insurer_bordereau', + 'settlement_insurer_bordereau_line', + 'settlement_insurer_ledger_state', + ]) { + const { rows } = await tx.query<{ n: number }>( + `SELECT count(*)::int AS n FROM core.${t} WHERE country_code = $1`, + [c.country], + ); + out.push(rows[0]?.n ?? -1); + } + return out; + }; + await setSessionContext(tx, { kind: 'GUEST', actorId: w.completed!.guest }); + expect(await read()).toEqual([0, 0, 0, 0]); + await setSessionContext(tx, { kind: 'HOST', actorId: uuid(), orgId: w.org }); + expect(await read()).toEqual([0, 0, 0, 0]); + for (const [actor, scope] of [ + [w.ops, c.country], + [w.financeOther, other.country], + ] as const) { + await setSessionContext(tx, { + kind: 'STAFF', + actorId: actor, + countryScope: [scope, c.country], + sessionTokenHash: hashOf(actor).toString('hex'), + }); + expect(await read()).toEqual([0, 0, 0, 0]); + } + await setSessionContext(tx, { + kind: 'STAFF', + actorId: w.financeA, + countryScope: [c.country], + sessionTokenHash: hashOf(w.financeA).toString('hex'), + }); + const seen = await read(); + expect(seen.every((n) => n > 0)).toBe(true); + }); + }); + }); + + it('gardes d’émission : une ligne dont la jambe INSURER est gelée après la rédaction (chargeback ouvert, règle 7) bloque l’émission ; une prime changée depuis la rédaction aussi', async () => { + let may = ''; + let july = ''; + let mayTrip = ''; + await withRole('app_worker', async (worker) => { + await payTx(worker, { commit: true }, async (tx) => { + const t = await capturedTrip(tx, c, w.org, capture, 5); + await tx.query(`SELECT test_fixture.us049_set_trip_status($1, 'COMPLETED')`, [t.trip]); + mayTrip = t.trip; + }); + may = (await draft(worker, monthOf(5), at(6, 2))).find( + (x) => x.country === c.country && x.outcome === 'DRAFTED', + )!.bordereau!; + await payTx(worker, { commit: true }, async (tx) => { + await asWorker(tx, 'payment_command'); + await tx.query(`SELECT test_fixture.marketplace_freeze_leg($1, 'INSURER')`, [mayTrip]); + }); + + let julyTrip = ''; + await payTx(worker, { commit: true }, async (tx) => { + const t = await capturedTrip(tx, c, w.org, capture, 7); + await tx.query(`SELECT test_fixture.us049_set_trip_status($1, 'COMPLETED')`, [t.trip]); + julyTrip = t.trip; + }); + const rows = await draft(worker, monthOf(7), at(8, 2)); + const j = rows.find((x) => x.country === c.country && x.outcome === 'DRAFTED')!; + expect(j).toMatchObject({ lines: 1, total: premium.toString() }); + july = j.bordereau!; + // règlement APRÈS la rédaction (bordereau encore DRAFT : la variation est admise) + await payTx(worker, { commit: true }, async (tx) => { + await recordAsSettlementWorker( + tx, + { tripId: julyTrip, version: 1, tripRowVersion: 1 }, + recordOfVector(r.cancelled), + ); + }); + }); + + await withRole('app_api', async (api) => { + for (const [subject, constraint] of [ + [may, 'insurer_bordereau_line_frozen'], + [july, 'insurer_bordereau_stale'], + ] as const) { + const req = await finance(api, w.financeA, hashOf(w.financeA), c.country, REQUEST, [ + uuid(), + 'ISSUE_BORDEREAU', + subject, + REASON, + ]); + expect(req.outcome).toBe('REQUESTED'); + await withTestTransaction(api, {}, async (tx) => { + await setSessionContext(tx, { + kind: 'STAFF', + actorId: w.financeB, + countryScope: [c.country], + sessionTokenHash: hashOf(w.financeB).toString('hex'), + }); + const err = await caught(tx, () => + tx.query(APPROVE, [hashOf(w.financeB), req.approval_id]), + ); + expect(err?.constraint, subject).toBe(constraint); + const row = await tx.query<{ status: string }>( + 'SELECT status FROM test_fixture.us062_bordereau_row($1)', + [subject], + ); + expect(row.rows[0]?.status).toBe('DRAFT'); + }); + } + }); + }); + }, +); diff --git a/packages/db/vitest.l0.config.ts b/packages/db/vitest.l0.config.ts index 613b449c..ce86d8e8 100644 --- a/packages/db/vitest.l0.config.ts +++ b/packages/db/vitest.l0.config.ts @@ -53,6 +53,9 @@ const ISOLATED = [ // compte PSP ACTIVE du pays partagé (fixture 9800) 'test/l0/l0-us224e-host-receivable.test.ts', 'test/l0/l0-us224e-defaulted-host.test.ts', + // US-227 : trips, contrat d'assureur de test (période passée), bordereaux et décisions FINANCE + // VALIDÉS (deux rôles), compte PSP ACTIVE du pays partagé (fixture 9800) + 'test/l0/l0-us227-insurer-ledger.test.ts', ]; const C11 = ['test/l0/l0-c11-fuzz.test.ts']; // US-049 : les attaques de la red team (test/redteam//) tournent seules, après tous les autres diff --git a/scripts/deploy/rehearsal.sh b/scripts/deploy/rehearsal.sh index cd354a43..7b75d554 100644 --- a/scripts/deploy/rehearsal.sh +++ b/scripts/deploy/rehearsal.sh @@ -76,7 +76,7 @@ say 'API saine ; route de webhook FAKE absente (404)' worker_logs="$(local_compose logs --no-color worker)" grep -q '"event":"worker.started"' <<<"$worker_logs" || fail 'travailleur : démarrage non journalisé' -grep -q '"queues":\["booking_contract","booking_conversion","booking_oracle","disposition_sweeper","hold_expiry","iam_otp_pruner","iam_otp_sender","kyc_score_pruner","ntf_dispatcher","ntf_sender","ops_monitor","privacy_request","reconciliation","refund_scheduler","review_sla_watch","risk_pruner","security_incident_watch","trip_lifecycle","webhook_ingest"\]' <<<"$worker_logs" || { +grep -q '"queues":\["booking_contract","booking_conversion","booking_oracle","bordereau","disposition_sweeper","hold_expiry","iam_otp_pruner","iam_otp_sender","kyc_score_pruner","ntf_dispatcher","ntf_sender","ops_monitor","privacy_request","reconciliation","refund_scheduler","review_sla_watch","risk_pruner","security_incident_watch","trip_lifecycle","webhook_ingest"\]' <<<"$worker_logs" || { # diagnostic : la ligne de démarrage (version et noms des files seulement, aucun secret) grep -F '"event":"worker.started"' <<<"$worker_logs" | tail -n 3 >&2 || true fail 'travailleur : files attendues absentes'