Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
afb1b6d
feat(US-227): registre de l'assureur, bordereau mensuel à double vali…
Projetapploccar Nov 18, 2026
ea702a8
Merge origin/main (US-212 #234, migration 0138) dans story/US-227-ins…
Projetapploccar Nov 18, 2026
84298d5
docs(US-227): ADR-165, passation, README, CHANGELOG, GL-42, COMME_TUR…
Projetapploccar Nov 18, 2026
da8728b
chore(US-227): schema.md conforme au job « base de données » du run 4…
Projetapploccar Nov 18, 2026
59dd687
Merge origin/main (US-224e #235, migrations 0139-0140) dans story/US-…
Projetapploccar Nov 18, 2026
15511eb
chore(US-227): schema.md conforme au job « base de données » du run 4…
Projetapploccar Nov 18, 2026
34f303f
Merge origin/main (BOARD #238) dans story/US-227-insurer-ledger ; BOA…
Projetapploccar Nov 18, 2026
f0e690d
test(US-227): trips réservés à l'heure réelle (paramètres en vigueur)…
Projetapploccar Nov 18, 2026
d7d20f2
test(US-227): horodatage de l'écriture comparé à l'horloge de la base…
Projetapploccar Nov 18, 2026
ba74738
fix(US-227): lignes du bordereau par ROWS FROM (unnest à deux tableau…
Projetapploccar Nov 18, 2026
2b5f087
Merge origin/main (US-224f #239, migration 0141) dans story/US-227-in…
Projetapploccar Nov 18, 2026
77022c7
chore(US-227): schema.md conforme au job « base de données » du run 4…
Projetapploccar Nov 18, 2026
045e733
Merge origin/main (US-225 #236, migration 0142) dans story/US-227-ins…
Projetapploccar Nov 18, 2026
504b3a5
chore(US-227): schema.md conforme au job « base de données » du run 4…
Projetapploccar Nov 18, 2026
3a479db
docs(US-227): revues code, qa, architecture, argent et sécurité (clau…
Projetapploccar Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion apps/api/src/modules/fin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
6 changes: 6 additions & 0 deletions apps/api/src/modules/fin/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
161 changes: 156 additions & 5 deletions apps/api/src/modules/fin/internal/money-reconciliation.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -33,6 +36,7 @@ import {
tripLegViolations,
} from './money-reconciliation.js';
import type {
InsurerLedgerFact,
LegBalanceAggregate,
MoneyReconciliationCheck,
SettlementAggregate,
Expand Down Expand Up @@ -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: {},
});
});
});

Expand Down Expand Up @@ -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[] = [];
Expand Down Expand Up @@ -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' });
Expand All @@ -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
Expand Down
Loading
Loading