Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion apps/api/src/modules/fin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ 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. Depuis US-227, quatorze contrôles (section suivante).
`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 ; depuis US-221b, 0149, ADR-170 : tout trip dont la disposition `CONVERSION` porte une capture prouvée est examiné et « encaissé » compte cette capture, si bien qu'une capture convertie jamais portée ressort en `TRIP_CAPTURE_LEGS`). 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)

Expand Down
5 changes: 5 additions & 0 deletions changelog.d/US-221-report-capture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
lot: L2
module: Règlement et finance

- Corrigé : le paiement d'un voyage réservé par le checkout est désormais porté, au moment même de la réservation, sur la part de l'hôte, de l'assureur, de la taxe et de Kmino, chacune à son montant exact, et la part de l'assureur entre dans son registre ; une confirmation rejouée ne le porte jamais deux fois (US-221)
- Corrigé : le contrôle de nuit de l'argent voit tout voyage réservé dont le paiement est prouvé, même s'il n'a pas été porté sur ses parts, et le signale alors comme un écart (US-221)
32 changes: 32 additions & 0 deletions docs/adr/ADR-170-report-de-la-capture-convertie.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# ADR-170 — Report de la capture d'un checkout sur les soldes par jambe du trip réservé, à la conversion

- **Statut** : PROPOSÉ (US-221 partie 221b, agent argent / back-end, 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.5 étape 4 (la conversion d'une `CAPTURE` porte la capture sur les soldes), §2.3 (commande `settlement_cmd_apply_conversion_capture`, politiques de conversion de `cmd_money_owner`) et §2.9.
- **Corrige** : défauts D1 et D2 de la passation US-221 (PR #245, ex-#243).
- **Complète** : ADR-139 (paiement par jambes, preuve par webhook), ADR-161 (faits de l'invariant par jambe), ADR-165 (écriture `COLLECTION` du registre de l'assureur).
- **Sources** : 08 E7 règles 1, 2 et 10 (jambes explicites, jamais un prorata ; soldes par trip et jambe), vecteurs TJ01 (USD), TJ08a (PYG) ; 17 v6 §2.5 étape 4, §2.9 (« soldes modifiés seulement par les commandes `settlement.cmd_*`, dans la transaction qui reçoit la preuve »), §4.3 point 8.

## Contexte

`core.booking_convert_payment` (0126) crée le trip `BOOKED` d'un hold payé et prouvé, sans rattacher l'opération de capture au trip (`payment_operation.trip_id` reste `NULL`). `core.settlement_cmd_apply_leg_movement` (0123), seul report sur les soldes, refuse une opération sans trip (`leg_movement_unsupported`) et n'est appelé en production que pour un remboursement. Résultat pour tout trip réservé par le vrai checkout : `trip_leg_balance` vide, aucune écriture `COLLECTION` au registre de l'assureur, aucune source de capture pour le reçu de l'hôte, et un remboursement ultérieur impossible à reporter (D1). Comme `core.finance_trip_leg_facts` (0137) ne retenait que les trips ayant un solde ou un règlement, le rapprochement de nuit ne voyait pas ces encaissements (D2).

## Décision

1. **Report dans la transaction de la conversion** : après la création du trip, de la disposition `CONVERSION` et du hold `CONVERTED`, la conversion d'une `CAPTURE` appelle `core.settlement_cmd_apply_conversion_capture(opération)`. Un refus annule toute la conversion (aucun trip sans ses soldes) ; la tâche `booking_conversion` compte l'erreur et réessaie. Une `AUTH` (fixtures) n'encaisse rien : aucun report.
2. **Commande dédiée** (`cmd_money_owner`, `SECURITY DEFINER`, `EXECUTE` `app_worker`, travailleurs `booking_conversion`, `disposition_sweeper`, `payment_intent_sweeper`) plutôt qu'un élargissement de `settlement_cmd_apply_leg_movement` (travailleur `payment_command`) : le périmètre est fermé à la capture d'un hold converti. Sous le verrou du trip : disposition `CONVERSION` exigée, `DUPLICATE` si un mouvement existe déjà, opération `CAPTURE` de loyer `SUCCEEDED` **prouvée**, même devise et même pays que le trip, quatre jambes ≥ 0 de Σ = montant, garde de détention de fonds de 0123 (`funds_holding_enabled`, fail-closed). Puis rattachement de l'opération et de ses jambes au trip, quatre soldes créés à zéro, `captured_minor` de chaque jambe = **sa** jambe de l'opération (montant explicite, égal au devis figé contrôlé à l'étape 2 de la conversion), mouvement `CAPTURE` (le déclencheur de 0143 écrit la `COLLECTION` de la jambe `INSURER`). Contrôle final : opération et jambes rattachées, chaque solde = sa jambe, sinon refus (une ligne filtrée par la RLS ne passe jamais en silence).
3. **Droits au plus juste, miroir exact** : `cmd_money_owner` lit la disposition (quatre colonnes) et reçoit `UPDATE (trip_id)` de l'opération et des jambes. Politiques ajoutées, réservées aux trois travailleurs de conversion : rattachement d'une `CAPTURE` prouvée sans trip au trip de **sa** disposition `CONVERSION` ; mouvement `CAPTURE` de l'opération de la disposition du trip ; solde créé à zéro puis `captured_minor` = jambe de cette opération, tout autre cumul nul. Déclencheurs (tous rôles, sur un changement de `trip_id`) : `trip_id` d'une opération ou d'une jambe ne passe que de `NULL` au trip de la conversion, sans autre changement (`operation_trip_attach_invalid` ⇒ `INVARIANT_VIOLATION`).
4. **Rejeu idempotent** : une conversion rejouée (`REPLAY`) d'une `CAPTURE` appelle la même commande, qui rend `DUPLICATE` ; elle rattrape une conversion antérieure à 0149 jamais portée. `settlement_cmd_apply_leg_movement` rejoué sur la capture rend `DUPLICATE` (mouvement unique par opération).
5. **Rapprochement (D2)** : un trip est tenu dès que sa disposition `CONVERSION` porte une `CAPTURE` **prouvée** (`SUCCEEDED`, preuve rattachée). « Encaissé » = Σ des encaissements portés et de cette capture : une capture convertie jamais portée ressort en `TRIP_CAPTURE_LEGS` (Σ capturé ≠ Σ encaissé) et en `STATEMENT_HOST_LEG` (aucune ligne de relevé). Un encaissement non prouvé n'est pas un encaissement (ADR-139). Les encaissements rattachés directement au trip (`MIT_CHARGE`, `DEBT_COLLECTION`, capture d'un trip) restent jugés une fois portés : leur report après la preuve appartient à la boîte d'envoi monétaire (`payment_command`, non déclarée avant le lot C), et les compter avant créerait un écart de nuit à chaque preuve en attente de report (essai de la CI : scènes de `concurrence-webhook.int.test.ts`, run 44397196230).

## Alternatives écartées

- **Élargir `settlement_cmd_apply_leg_movement` aux travailleurs de conversion** : ouvrirait remboursements, réaffectations et versements à des travailleurs qui n'en ont pas l'usage ; la commande dédiée ne sait que porter une capture convertie.
- **Report différé par la boîte d'envoi monétaire** (`payment_command`) : un trip `BOOKED` existerait sans soldes entre deux tâches, et le consommateur `payment_command` n'est pas déclaré avant le lot C ; 17 §2.9 demande le report dans la transaction qui reçoit la preuve.
- **Changer le nom du travailleur dans la transaction** pour réutiliser la commande existante : usurpation du contexte de session, refusée.
- **Garder la conversion et lever une alerte** si le report échoue : laisserait un trip réservé sans soldes ; fail-closed retenu (aucun trip sans ses soldes), l'opération reste due et visible par le rapprochement (D2).

## Limites et conséquences (suites)

- Encaissement rattaché directement au trip, prouvé mais non porté (MIT, recouvrement) : à faire entrer dans les faits avec le report à la preuve de la boîte d'envoi monétaire (lot C), avec un délai de grâce PROPOSÉ.
- Aucune reprise des conversions antérieures à 0149 par migration (aucune donnée de production en bêta) : rattrapage au rejeu de la conversion, et le rapprochement les signale (D2).
- Le parcours doré d'US-221 (PR #245) : son test `it.fails` « D2 (défaut) » passe désormais (à retirer à sa fusion) ; « D1 (défaut) » appelle `settlement_cmd_apply_leg_movement` sur la capture et attend `APPLIED` : il obtient `DUPLICATE` (capture déjà portée à la conversion) et doit être réécrit sur les soldes, comme la preuve L0 de cette story.
- Annulation du trip converti par le vrai chemin (`TripCancellationProcessor` sans `tripOf`), contrat et constancia du trip réservé : suites de la passation US-221 (trous 1 et 2), débloquées.
Loading
Loading