Skip to content
Merged
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/pay/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Cible (17 §2.2, §4.5) :

- `PaymentProvider` (`internal/port.ts`, 17 §2.8) : toute méthode qui déplace des fonds reçoit des `LegAmounts` (`MONEY_MOVING_METHODS`) ; méthodes de place de marché idempotentes (`MARKETPLACE_WRITE_METHODS`).
- `WebhookVerifier` : vérification de signature par fournisseur, utilisée par `WebhookIngestService`.
- Magasins (`internal/stores.ts`) : `OperationStatusStore`, `WebhookInboxStore`, `WebhookWorkStore`, adaptateurs PostgreSQL `PgOperationRecorder`, `PgWebhookInboxStore`, `PgWebhookWorkStore`. US-224 (ADR-145) : `PgOperationRecorder.record` appelle la commande à 15 arguments ; un ordre REFUND / LEG_REALLOCATION / LEG_RELEASE d'un trip porte `settlement` (identifiant et version en tête du règlement), sinon la base le refuse ; un webhook de ces ordres sans montant ne les prouve pas (`UNPROVEN`). US-224b (ADR-147) : `PgRefundPlanner` planifie un remboursement de règlement (`plan` : instance SM-8, avance de Kmino attendue si la part HOST est déjà versée, ordre PENDING) et autorise son envoi (`submit` : `SUBMITTED`, `DUPLICATE`, `SUPERSEDED` ou `BLOCKED` avec son motif, tant qu'une avance n'a pas de décision FINANCE à deux personnes) ; l'appel au PSP ne suit que `SUBMITTED`. US-224c (ADR-150) : `PgRefundOrders` (`due` : file de l'ordonnanceur ; `orderForSend` : ordre stocké relu sous les verrous du trip et de l'ordre, gardés pendant l'appel au PSP, refus `NOT_SUBMITTED`, `FINAL`, `SUPERSEDED_UNSENT`, `NO_TARGET` ; `markAlerted` ; `applyLegMovement`) ; `PaymentConnectorRegistry` et `PRODUCTION_PAYMENT_CONNECTORS` (aucun connecteur avant le lot C) ; `REFUND_INSTANCE_STATUSES` (types resserrés de `PgRefundPlanner`, N-227).
- Magasins (`internal/stores.ts`) : `OperationStatusStore`, `WebhookInboxStore`, `WebhookWorkStore`, adaptateurs PostgreSQL `PgOperationRecorder`, `PgWebhookInboxStore`, `PgWebhookWorkStore`. US-224 (ADR-145) : `PgOperationRecorder.record` appelle la commande à 15 arguments ; un ordre REFUND / LEG_REALLOCATION / LEG_RELEASE d'un trip porte `settlement` (identifiant et version en tête du règlement), sinon la base le refuse ; un webhook de ces ordres sans montant ne les prouve pas (`UNPROVEN`). US-224b (ADR-147) : `PgRefundPlanner` planifie un remboursement de règlement (`plan` : instance SM-8, avance de Kmino attendue si la part HOST est déjà versée, ordre PENDING) et autorise son envoi (`submit` : `SUBMITTED`, `DUPLICATE`, `SUPERSEDED` ou `BLOCKED` avec son motif, tant qu'une avance n'a pas de décision FINANCE à deux personnes) ; l'appel au PSP ne suit que `SUBMITTED`. US-224c (ADR-150) : `PgRefundOrders` (`due` : file de l'ordonnanceur ; `orderForSend` : ordre stocké relu sous les verrous du trip et de l'ordre, gardés pendant l'appel au PSP, refus `NOT_SUBMITTED`, `FINAL`, `SUPERSEDED_UNSENT`, `NO_TARGET` ; `markAlerted` ; `applyLegMovement`) ; `PaymentConnectorRegistry` et `PRODUCTION_PAYMENT_CONNECTORS` (aucun connecteur avant le lot C) ; `REFUND_INSTANCE_STATUSES` (types resserrés de `PgRefundPlanner`, N-227). US-224f (ADR-166) : `PgRefundOrders.awaitChoice` (instance `FAILED` après un rejet confirmé ⇒ `PENDING_CUSTOMER_CHOICE`, `attempt_no` + 1 ; `DUPLICATE`, `SUPERSEDED`) ; la base refuse un rail natif sur un moyen autre qu'une carte et tout remboursement d'un moyen au-delà de ce qu'il a payé.
- FAKE : `FakePsp` de `@rueda/fake-adapters/psp`, traduit vers le port par `testing/fake-payment-provider.ts` ; `testing/` n'est exporté par aucun index et reste hors de la compilation de production.

API publique (`index.ts`, liste complète dans le fichier) : `PayModule`, `PayWebhookModule`, `postgresPayAdapters`, `PRODUCTION_PROVIDERS` ; types et constantes du port ; jambes (`LEGS`, `assertMovingLegs`, `legSum`…) ; erreurs (`PaymentError`, `PAYMENT_ERROR_CODES`) ; capacités (`CapabilitySet`, `CAPABILITIES`) ; idempotence (`settlementOperationKey`, `holdAttemptKey`…) ; `MoneyCommandSender` ; webhooks (`WebhookIngestService`, `WebhookProcessor`) ; PAN (`containsPan`, `maskPan`) ; démarrage (`assertPaymentStartup`, `checkPaymentStartup`).
Expand Down
16 changes: 16 additions & 0 deletions apps/api/src/modules/pay/internal/pg-stores.ts
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,22 @@ export class PgRefundOrders {
return rows[0]?.changed === true;
}

/**
* US-224f (ADR-166, 08 SM-8) : instance `FAILED` après un rejet confirmé ⇒ `PENDING_CUSTOMER_CHOICE`
* (`attempt_no` + 1) ; déjà en attente ⇒ `DUPLICATE` ; remplacée ⇒ `SUPERSEDED`.
*/
async awaitChoice(instanceId: string): Promise<'AWAITING_CHOICE' | 'DUPLICATE' | 'SUPERSEDED'> {
const { rows } = await this.#tx.query<{ outcome: string }>(
'SELECT core.payment_cmd_refund_await_choice($1) AS outcome',
[instanceId],
);
const outcome = rows[0]?.outcome;
if (outcome !== 'AWAITING_CHOICE' && outcome !== 'DUPLICATE' && outcome !== 'SUPERSEDED') {
throw new Error('PAY : attente du choix du rail sans issue connue');
}
return outcome;
}

/** Opération d'une instance (report après confirmation). */
async operationOf(instanceId: string): Promise<string> {
const { rows } = await this.#tx.query<{ operation_id: string }>(
Expand Down
2 changes: 2 additions & 0 deletions apps/api/src/modules/stl/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,3 +120,5 @@ Les tests L0 et d'intégration demandent PostgreSQL : guide `docs/ops/INSTALL.md
La pénalité de l'hôte qui annule (`host_penalty_minor` du règlement, 08 E7 règle 7) est écrite au `host_ledger` (`core.settlement_host_ledger_entry`, migration 0129) par la base elle-même, dans la transaction de `TripCancellationProcessor` : la liaison du règlement à la demande (`core.booking_cmd_trip_settle_cancellation`) déclenche `core.settlement_cmd_post_host_penalty`. Aucun code de l'API n'écrit ni ne lit le `host_ledger` ; FINANCE et ADMIN du pays lisent le solde par hôte et par devise (`core.settlement_host_ledger_balance_v`). Aucune retenue sur un versement (GL-33, suite US-709 / US-314).

**Créance de la règle 3 bis (US-224e, ADR-163).** Quand une avance de Kmino sur une jambe `HOST` déjà versée devient effective (`OPEN`, au report du remboursement par `core.settlement_cmd_apply_leg_movement`, `RefundScheduler`), la base écrit dans la même instruction la créance de l'hôte (`RELEASED_LEG_ADVANCE`, montant de l'avance stockée, 08 TJ18b / TJ18d) par le déclencheur `platform_advance_receivable_posted`. Aucun code de l'API n'y participe ; aucun recouvrement (`NETTING`, SM-6b) avant US-709.

**Remboursement réparti sur les moyens d'origine (US-224f, ADR-166).** Le processeur des annulations lit tous les encaissements réussis du loyer du trip (`tendersOf` : capture, débit MIT, recouvrement, devise du trip, ordre des captures, montant déjà engagé sur chacun) et `ordersByTender` (pur) en tire un ordre par moyen : 08 E2 décide le montant de chaque moyen (`refundsByTender` de `@rueda/money`), la règle 10 ses jambes ; la réaffectation est rattachée au premier moyen de la cascade ; clé `…:REFUND:{moyen}:i1:a1`. Bêta (fail-closed) : seule la carte est remboursée (`NATIVE_PARTIAL`) ; un moyen non natif ou un crédit qui doit rembourser quelque chose ⇒ `REFUND_RAIL_UNAVAILABLE`, rien n'est écrit, la demande est garée avec une alerte. L'ordonnanceur (`RefundScheduler`) fait passer une instance en échec confirmé à `PENDING_CUSTOMER_CHOICE` (`attempt_no` + 1, `PgRefundOrders.awaitChoice`) dans la transaction qui pose l'alerte `FIN_REFUND_FAILED` ; aucun autre rail n'est ouvert en bêta.
5 changes: 5 additions & 0 deletions apps/api/src/modules/stl/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,19 @@ export {
TripCancellationProcessor,
cancellationEvent,
cancellationParams,
ordersByTender,
planCancellation,
registerTripCancellations,
tenderKindOf,
} from './internal/trip-cancellation.js';
export type {
BetaRefundRail,
CancellationFacts,
CancellationOrder,
CancellationOutcome,
CancellationPlan,
CaptureTender,
TenderOrder,
} from './internal/trip-cancellation.js';
// Ordonnanceur des remboursements planifiés (US-224c, ADR-150)
export {
Expand Down
33 changes: 33 additions & 0 deletions apps/api/src/modules/stl/internal/refund-scheduler.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,7 @@ function answers(over: Partial<Record<string, unknown[] | Error>> = {}): Answer
if (sql.includes('payment_cmd_refund_order_for_send')) return [orderRow('TJ02b')];
if (sql.includes('payment_cmd_apply_operation_status')) return [{ outcome: 'APPLIED' }];
if (sql.includes('payment_cmd_refund_mark_alerted')) return [{ changed: true }];
if (sql.includes('payment_cmd_refund_await_choice')) return [{ outcome: 'AWAITING_CHOICE' }];
if (sql.includes('FROM core.payment_refund_instance')) return [{ operation_id: OPERATION }];
if (sql.includes('settlement_cmd_apply_leg_movement')) return [{ outcome: 'APPLIED' }];
return new Error(`requête inattendue : ${sql}`);
Expand Down Expand Up @@ -360,8 +361,40 @@ describe('ordonnanceur — états et refus', () => {
step: 'ATTENTION',
alert: { code: 'FIN_REFUND_FAILED', key: 'FAILED', errorCode: 'REFUND_FAILED' },
});
// US-224f : marque et attente du choix d'un autre rail dans LA MÊME transaction, après l'alerte
expect(db.calls.slice(-2).map((c) => [c.sql.match(/core\.(\w+)/)?.[1], c.params])).toEqual([
['payment_cmd_refund_mark_alerted', [INSTANCE, 'FAILED']],
['payment_cmd_refund_await_choice', [INSTANCE]],
]);
await s.process(due({ status: 'FAILED', operationStatus: 'FAILED', finAlert: 'FAILED' }));
expect(alerts.sent.map((a) => a.code)).toEqual(['FIN_REFUND_FAILED']);
expect(db.called('payment_cmd_refund_await_choice')).toHaveLength(1);
});

it('US-224f : seule l’alerte d’un échec confirmé ouvre le choix du rail ; issue inconnue de la base ⇒ alerte rejouée au passage suivant', async () => {
const blocked = new FakeDb(
answers({
payment_cmd_submit_refund: [{ outcome: 'BLOCKED', blocked_reason: 'ADVANCE_CAP_UNSET' }],
}),
);
const s1 = new RefundScheduler({
transactions: transactionsOf(blocked),
alerts: new Alerts(),
connectors: registryOf(new StubConnector(HONEST, () => new Error('jamais appelé'))),
});
expect((await s1.process(due())).step).toBe('BLOCKED');
expect(blocked.called('payment_cmd_refund_await_choice')).toEqual([]);

const odd = new FakeDb(answers({ payment_cmd_refund_await_choice: [{ outcome: 'X' }] }));
const lines: string[] = [];
const s2 = new RefundScheduler({
transactions: transactionsOf(odd),
alerts: new Alerts(),
connectors: registryOf(undefined),
log: (l) => lines.push(l),
});
await s2.process(due({ status: 'FAILED', operationStatus: 'FAILED' }));
expect(lines.some((l) => l.includes('alert_deferred'))).toBe(true);
});

it('issue inconnue : UNKNOWN appliqué, repris plus tard ; ordre en vol relu d’abord (aucun renvoi) puis SENT', async () => {
Expand Down
23 changes: 17 additions & 6 deletions apps/api/src/modules/stl/internal/refund-scheduler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,10 @@
* l'instance suit le statut de l'ordre (déclencheur de 0127 : `SENT`, `CONFIRMED`, `FAILED`) ;
* 3. `CONFIRMED` prouvé : report sur les soldes des jambes (`core.settlement_cmd_apply_leg_movement`,
* l'avance de Kmino décidée devient `OPEN`) ;
* 4. `FAILED` : alerte FIN `FIN_REFUND_FAILED` (une fois). Nouvelle tentative et choix du rail :
* suite (SM-8 `PENDING_CUSTOMER_CHOICE`).
* 4. `FAILED` : alerte FIN `FIN_REFUND_FAILED` (une fois) ; dans la transaction qui la marque, le
* rejet confirmé ouvre le choix d'un autre rail par le voyageur (SM-8 `PENDING_CUSTOMER_CHOICE`,
* `attempt_no` + 1, `core.payment_cmd_refund_await_choice`, US-224f, ADR-166) ; aucun autre rail
* n'est ouvert en bêta, rien n'est converti en crédit.
*
* Une instance ne bloque jamais les suivantes (`process` ne lève pas). Chaque état n'est signalé
* qu'une fois (`fin_alert`, posé APRÈS l'envoi de l'alerte : une alerte perdue est rejouée). Les
Expand Down Expand Up @@ -89,6 +91,9 @@ export interface RefundSchedulerDeps {
readonly log?: (line: string) => void;
}

/** Clé d'alerte d'une instance `FAILED` (rejet confirmé du PSP). */
const FAILED_ALERT_KEY = 'FAILED';

const attention = (code: RefundAlertCode, key: string, errorCode: string): RefundOutcome => ({
step: 'ATTENTION',
alert: { code, key, errorCode },
Expand Down Expand Up @@ -126,9 +131,15 @@ export class RefundScheduler {
counts: { refunds: 1 },
labels: { country: due.country, error_code: alert.errorCode },
});
await this.#deps.transactions.run(PAYMENT_COMMAND_WORKER, (db) =>
new PgRefundOrders(db).markAlerted(due.instanceId, alert.key),
);
await this.#deps.transactions.run(PAYMENT_COMMAND_WORKER, async (db) => {
const orders = new PgRefundOrders(db);
await orders.markAlerted(due.instanceId, alert.key);
// US-224f (08 SM-8, E4) : rejet confirmé signalé ⇒ attente du choix d'un autre rail ; une
// marque sans la transition (ou l'inverse) n'est jamais validée
if (due.status === 'FAILED' && alert.key === FAILED_ALERT_KEY) {
await orders.awaitChoice(due.instanceId);
}
});
} catch (error) {
// alerte ou marque impossible : rejouée au passage suivant (jamais perdue en silence)
this.#log({ level: 'warn', event: 'alert_deferred', error_class: errorClass(error) });
Expand Down Expand Up @@ -190,7 +201,7 @@ export class RefundScheduler {
return { step: outcome === 'APPLIED' ? 'REPORTED' : 'DUPLICATE' };
}
case 'FAILED':
return attention('FIN_REFUND_FAILED', 'FAILED', 'REFUND_FAILED');
return attention('FIN_REFUND_FAILED', FAILED_ALERT_KEY, 'REFUND_FAILED');
default:
return { step: 'DUPLICATE' };
}
Expand Down
Loading
Loading