diff --git a/apps/api/openapi/openapi.json b/apps/api/openapi/openapi.json
index fa45f19ac..b419dab3c 100644
--- a/apps/api/openapi/openapi.json
+++ b/apps/api/openapi/openapi.json
@@ -16131,7 +16131,8 @@
"$ref": "#/components/schemas/MinorUnits"
},
"refundMinor": {
- "$ref": "#/components/schemas/MinorUnits"
+ "$ref": "#/components/schemas/MinorUnits",
+ "description": "remboursement DÛ au voyageur par la version en tête du règlement (0 sans règlement) ; ce n'est pas un remboursement émis : son état et sa date d'émission se lisent sur GET /trips/{tripId}/refunds (SM-8)"
},
"tripFee": {
"oneOf": [
@@ -16158,7 +16159,7 @@
"type": "null"
}
],
- "description": "taxe de LIGNE du devis figé (08 BR-PRICE-12) ; null sans devis figé lisible (jamais recalculée)"
+ "description": "taxe de LIGNE du devis figé (08 BR-PRICE-12), sur le trip fee facturé en entier ; null sans devis figé lisible, ou dès qu'une part du trip fee est remboursée (217b, ADR-167 : la taxe du trip fee conservé attend OQ-BR-14 ; jamais recalculée)"
},
"taxRateBps": {
"type": ["integer", "null"],
@@ -16363,6 +16364,8 @@
"hostLegMinor",
"adjustmentsMinor",
"netMinor",
+ "earnedMinor",
+ "pendingMinor",
"lines"
],
"additionalProperties": false,
@@ -16387,7 +16390,16 @@
"$ref": "#/components/schemas/SignedMinorUnits"
},
"netMinor": {
- "$ref": "#/components/schemas/SignedMinorUnits"
+ "$ref": "#/components/schemas/SignedMinorUnits",
+ "description": "Σ des lignes du mois (= earnedMinor + pendingMinor)"
+ },
+ "earnedMinor": {
+ "$ref": "#/components/schemas/SignedMinorUnits",
+ "description": "acquis : jambes HOST des versions en tête des règlements et ajustements du host_ledger (217b, ADR-167)"
+ },
+ "pendingMinor": {
+ "$ref": "#/components/schemas/MinorUnits",
+ "description": "à venir : jambes HOST capturées d'un trip encore sans règlement (à venir ou en cours ; 217b, ADR-167)"
},
"lines": {
"type": "array",
diff --git a/apps/api/src/modules/avl/README.md b/apps/api/src/modules/avl/README.md
index edb86755f..34ea95076 100644
--- a/apps/api/src/modules/avl/README.md
+++ b/apps/api/src/modules/avl/README.md
@@ -21,6 +21,7 @@ AVL ne calcule ni prix (PRC) ni règlement (STL), et n'appelle jamais le PSP lui
- US-208 : checkout en une page, partie back-end (migrations 0107, 0108, ADR-133) : devis figé avec durée de validité, commande `core.booking_cmd_checkout` (devis, annonce immédiate, boîte manuelle, conducteur titulaire, documents acceptés, pose du hold par `core.booking_cmd_place_hold`), rattachement `booking_checkout_acceptance` / `booking_checkout_terms` ; aucun paiement (US-223) ;
- US-209 (209b, migration 0119, ADR-141) : décision de l'ops sur une réservation signalée, commande `core.booking_manual_action_review_flagged` liée à `REVIEW_FLAGGED_BOOKING` (cadre d'US-101, appelée par la console) : APPROVED ⇒ `reviewed_at` et UNE prolongation `reviewed_at + LEAST(hold_ttl_minutes, hold_max_total_minutes)` (hold et occupation), puis paiement par le chemin d'US-223a ; REJECTED ⇒ `RELEASED` / `REVIEW_REJECTED`, occupation libérée ; aucun débit. Hold de revue échu jamais revu ⇒ `RELEASED` / `REVIEW_REJECTED` (déclencheur `hold_review_lapse`, quel que soit l'écrivain), élément de file d'un hold sorti sans décision clos `CANCELLED` (déclencheur `hold_review_item_close`). Branche `PAY_THEN_REVIEW` : refus d'un trip payé ⇒ `CANCELLATION_UNAVAILABLE` (US-224). Événement `booking.hold.review_decided`.
- US-217 (217a, migration 0137, ADR-161) : `GET /trips/{tripId}/receipt` (`TripReceiptController`, `SessionGuard` puis `TermsGuard`, sans cache) : reçu du trip lu par sa partie (`core.booking_trip_receipt`) : titulaire du compte d'hôte ⇒ gains du trip (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, net) ; voyageur ⇒ total payé, remboursé, trip fee et sa taxe de ligne, facture hors plateforme ; autre personne, trip inconnu ou mal formé ⇒ 404 `RECEIPT_NOT_FOUND` ; sans capture ni règlement ⇒ 409 `RECEIPT_NOT_READY` ; forme inattendue ⇒ 503 `RECEIPT_UNAVAILABLE`. `GET /host/accounts/{orgId}/earnings/{month}` (`HostEarningsController`) : relevé du mois d'un compte titulaire (`core.booking_host_earnings`) par devise ; 400 `REQUEST_INVALID`, 404 `EARNINGS_NOT_FOUND`, 503 `EARNINGS_UNAVAILABLE`. Montants en texte (signés pour les ajustements et le net), jamais recalculés ; clés exactes contrôlées ;
+- US-217 (217b, migration 0145, ADR-167) : reçu du voyageur sans taxe du trip fee dès qu'une part du trip fee est remboursée, et 409 `RECEIPT_NOT_READY` sans règlement ni capture même avec un devis (comme l'hôte) ; `refundMinor` documenté comme le remboursement **dû** au règlement (l'émis se lit sur `/trips/{tripId}/refunds`) ; relevé : `earnedMinor` (acquis) et `pendingMinor` (à venir) contrôlés comme les autres clés (forme inattendue ⇒ 503).
- US-224 (224d, migration 0130, ADR-154) : `GET /trips/{tripId}/refunds` (`TripRefundsController`, `SessionGuard` puis `TermsGuard`, sans cache) : remboursement du trip lu par sa partie (`core.booking_trip_refunds`) : voyageur ⇒ état SM-8, montant remboursé, rail, dates de planification et d'émission ; titulaire du compte d'hôte ⇒ la seule part de la jambe HOST ; toute autre personne, trip inconnu ou identifiant mal formé ⇒ 404 `REFUND_NOT_FOUND` (même réponse) ; forme inattendue ou base indisponible ⇒ 503 `REFUNDS_UNAVAILABLE`. Montants en texte, jamais recalculés ; exposant de la devise et fuseau du trip pour l'affichage ;
- US-214 (migration 0136, ADR-160) : `GET /trips` et `GET /trips/{tripId}` (`GuestTripsController`, `SessionGuard` puis `TermsGuard`, sans cache) : « Mis viajes » et détail du trip du voyageur de la SESSION (`core.booking_guest_trips`, `PgGuestTripStore`) : trips (onglets UPCOMING, IN_PROGRESS, DONE, CANCELLED) et demandes en attente de l'hôte (REQUESTED) ; auto sans plaque, hôte en prénom et initiale, adresse d'un trip à venir ou en cours seulement, total du devis figé relu (jamais recalculé) avec l'exposant de la devise, état du contrat. Trip d'une autre personne (y compris un trip hébergé par la session), inconnu ou identifiant mal formé ⇒ 404 `TRIP_NOT_FOUND` (même réponse) ; forme inattendue de la base ⇒ 503 `TRIPS_UNAVAILABLE` (fail-closed). Contrat : `avl/testing/guest-trips.contract.test.ts` ; preuve base : `l0-us214-guest-trips`.
- US-215 (215a, migration 0124, ADR-148) : annulations déclenchées par l'ops. Demande `core.booking_trip_cancellation` écrite par la commande liée `core.booking_manual_action_cancel_trip` (motif et initiateur dérivés de l'action, heure serveur) ; transition réglée `core.booking_cmd_trip_settle_cancellation` (travailleur `trip_lifecycle`, appelée par STL dans la transaction du règlement) : requalification en base (règles 1 et 2 ; preuve = pièce jointe à l'action), liaison du règlement à la demande, `settlement_id` au journal et dans `trip.status_changed`, créneau libéré, `cost_bearer`. `core.booking_cmd_trip_cancel` (US-207) reste sans appelant de production.
diff --git a/apps/api/src/modules/avl/internal/checkout/host-earnings.ts b/apps/api/src/modules/avl/internal/checkout/host-earnings.ts
index e17fe18bc..907fcab41 100644
--- a/apps/api/src/modules/avl/internal/checkout/host-earnings.ts
+++ b/apps/api/src/modules/avl/internal/checkout/host-earnings.ts
@@ -2,7 +2,8 @@
* Relevé mensuel des gains d'un compte d'hôte (US-217 partie 217a, ADR-161 ; 19 US-217 critères 2
* et 3 ; 16 PYO-013 ; 17 §3.2.13 `host_earnings_statement` / `host_earnings_line` ; 10b UX-45). Par
* devise : Σ jambes HOST des trips du mois (version en tête du règlement, sinon capture), Σ
- * ajustements du host_ledger (pénalité de l'hôte, en ligne séparée), net, et les lignes. La base
+ * ajustements du host_ledger (pénalité de l'hôte, en ligne séparée), net, acquis (règlement en
+ * tête et host_ledger) et à venir (capture sans règlement ; 217b, ADR-167, N-339), et les lignes. La base
* vérifie que la session est TITULAIRE du compte (`core.booking_host_earnings`, 0137, SECURITY
* DEFINER, EXECUTE app_api) : compte d'un autre, co-hôte, inconnu ou identifiant mal formé ⇒ 404
* `EARNINGS_NOT_FOUND`, même réponse ; mois mal formé ⇒ 400 `REQUEST_INVALID`.
@@ -80,6 +81,13 @@ export interface EarningsStatement {
readonly hostLegMinor: string;
readonly adjustmentsMinor: string;
readonly netMinor: string;
+ /**
+ * Acquis (217b, ADR-167, N-339) : jambes HOST des versions en tête des règlements et ajustements
+ * du host_ledger.
+ */
+ readonly earnedMinor: string;
+ /** À venir (217b) : jambes HOST capturées d'un trip sans règlement (à venir, en cours). */
+ readonly pendingMinor: string;
readonly lines: readonly EarningsLine[];
}
@@ -166,6 +174,8 @@ const STATEMENT_KEYS = [
'hostLegMinor',
'adjustmentsMinor',
'netMinor',
+ 'earnedMinor',
+ 'pendingMinor',
'lines',
];
const sameKeys = (o: Readonly>, keys: readonly string[]): boolean => {
@@ -235,6 +245,8 @@ function statementsOf(raw: unknown, exponents: unknown): EarningsStatement[] | n
const hostLegMinor = textOf(s['hostLegMinor'], MINOR);
const adjustmentsMinor = textOf(s['adjustmentsMinor'], SIGNED_MINOR);
const netMinor = textOf(s['netMinor'], SIGNED_MINOR);
+ const earnedMinor = textOf(s['earnedMinor'], SIGNED_MINOR);
+ const pendingMinor = textOf(s['pendingMinor'], MINOR);
if (
typeof currency !== 'string' ||
typeof count !== 'number' ||
@@ -242,7 +254,9 @@ function statementsOf(raw: unknown, exponents: unknown): EarningsStatement[] | n
count < 0 ||
typeof hostLegMinor !== 'string' ||
typeof adjustmentsMinor !== 'string' ||
- typeof netMinor !== 'string'
+ typeof netMinor !== 'string' ||
+ typeof earnedMinor !== 'string' ||
+ typeof pendingMinor !== 'string'
) {
return null;
}
@@ -262,6 +276,8 @@ function statementsOf(raw: unknown, exponents: unknown): EarningsStatement[] | n
hostLegMinor,
adjustmentsMinor,
netMinor,
+ earnedMinor,
+ pendingMinor,
lines,
});
}
diff --git a/apps/api/src/modules/avl/testing/trip-receipt.contract.test.ts b/apps/api/src/modules/avl/testing/trip-receipt.contract.test.ts
index 15fe18bba..fc91aaacf 100644
--- a/apps/api/src/modules/avl/testing/trip-receipt.contract.test.ts
+++ b/apps/api/src/modules/avl/testing/trip-receipt.contract.test.ts
@@ -333,6 +333,9 @@ describe('US-217 partie 217a — relevé mensuel des gains de l’hôte', () =>
hostLegMinor: hostLeg.toString(),
adjustmentsMinor: '-2500',
netMinor: (hostLeg - 2500n).toString(),
+ // 217b (N-339) : acquis = règlement (0) + host_ledger ; à venir = capture sans règlement
+ earnedMinor: '-2500',
+ pendingMinor: hostLeg.toString(),
lines: [
{
kind: 'EARNING',
@@ -451,6 +454,10 @@ describe('US-217 partie 217a — relevé mensuel des gains de l’hôte', () =>
for (const statements of [
[{ ...good, hostLegMinor: '-1' }],
[{ ...good, tripsCount: -1 }],
+ // 217b (N-339) : acquis et à venir exigés, à venir jamais négatif
+ [{ ...good, pendingMinor: '-1' }],
+ [{ ...good, earnedMinor: '1.5' }],
+ [Object.fromEntries(Object.entries(good).filter(([k]) => k !== 'earnedMinor'))],
[{ ...good, lines: [{ ...earning, amountMinor: '-1' }] }],
[{ ...good, lines: [{ ...earning, kind: 'COMMISSION' }] }],
[{ ...good, lines: [{ ...cxl, reason: 'HOST_CANCELLATION_PENALTY' }] }],
diff --git a/apps/api/src/modules/fin/README.md b/apps/api/src/modules/fin/README.md
index a35cc7c6a..9f4339a8e 100644
--- a/apps/api/src/modules/fin/README.md
+++ b/apps/api/src/modules/fin/README.md
@@ -27,6 +27,8 @@ Trois contrôles s'ajoutent au rapprochement nocturne, lus de `core.finance_insu
En base (migration 0137), sans table nouvelle : `host_earnings_statement` et `host_earnings_line` (17 §3.2.13) sont une **lecture calculée** des lignes immuables (version en tête du règlement, capture, devis figé, `host_ledger`), jamais un recalcul. `core.finance_earning_lines` (lignes `EARNING`, `CXL_EARNING`, `ADJUSTMENT`), `core.finance_trip_receipt_view` (vues `HOST` et `GUEST`), `core.finance_host_statement` (mois `YYYY-MM` par devise) ; les routes sont servies par AVL (`GET /trips/{tripId}/receipt`, `GET /host/accounts/{orgId}/earnings/{month}`), FIN ne dépendant pas d'IAM. Facture électronique : hors plateforme en bêta (FIN-002 MANUEL) ; entité qui facture non tranchée (ADR-013, `finance_legal_entity` vide) : le reçu n'en présente aucune.
+Partie 217b (migration 0145, ADR-167) : taxe du trip fee non rendue dès qu'une part en est remboursée, aucun reçu du voyageur sans règlement ni capture, relevé séparé en acquis (`earnedMinor`) et à venir (`pendingMinor`) ; écrans A08 et S09 · reçu dans `apps/web`.
+
## Entités
Entités de 17 §3.2.13 possédées par FIN (17 §2.2) :
diff --git a/apps/web/README.md b/apps/web/README.md
index f6cf394be..c746d7b33 100644
--- a/apps/web/README.md
+++ b/apps/web/README.md
@@ -65,6 +65,7 @@ e2e : `e2e/signup.spec.ts` (projets `mobile-360` et `mobile-390`, quatre langues
- **US-212 (constancia, centre juridique, ADR-162)** : **`/trips/{tripId}/constancia`** (voyageur ou hôte du trip, `account/trip-constancia.ts`) : usage rappelé (contrôle routier, amende après le trip), bandeau BROUILLON, résumé (plaque, période à l'heure locale avec le nom du pays, auto, hôte et conducteur en prénom et initiale, lieu de remise, total, contrat), PDF relayé par le site (`/trips/{tripId}/constancia/pdf`, session du visiteur, sans cache, empreinte en en-tête ; tout refus ⇒ 404 vide), texte es (fait foi) puis langue du lecteur (`Part` de `_contract/contract-view.tsx`). **`/host/constancia`** : recherche de l'hôte par plaque et date (action serveur, plaque dans le corps, jamais dans l'URL). **`/legal`** : centre juridique (version et date, BROUILLON, intermédiaire entre particuliers, documents publiés, documents de chaque trip, désaccords et médiation, loi applicable). Section « Otros documentos del viaje » (`_contract/trip-documents.tsx`) sur S09 · contrat et A03 · contrat. e2e : `e2e/trip-constancia.spec.ts` (projet `mobile-360`, es) ; captures `contrat-a-signer`, `contrat-signe`, `hote-contrat`, `detail-voyage` recopiées de l'artefact CI. Catalogue v78.
- **US-224 partie 224d (S10, A05, ADR-154)** : **`/trips/{tripId}/refund`** (S10 · remboursement du voyageur, `account/trip-refunds.ts`, `_refund/refund-phase.tsx`) : Kmino rembourse lui-même le montant calculé par le règlement, sur le moyen d'origine, sans attendre l'hôte ; chaque remboursement : montant (lu de l'API, jamais recalculé), état regroupé pour la personne (en préparation, émis, confirmé par le prestataire, en vérification), « Émis le {date} » dans le fuseau du trip et délai de la banque sans durée chiffrée (BR-PAY-08 : jamais une date de réception), moyen (rail) ; aucun remboursement ⇒ ce qui s'affichera ; remboursement d'un autre ⇒ même message que l'inconnu. **A05** (`/host/trips/{tripId}`) : section « Remboursement du voyageur » (absente sans remboursement) avec la seule part retirée des gains de l'hôte et l'état. e2e : `e2e/trip-refund.spec.ts` (projet `mobile-360` seulement ; remboursement posé par `GET /__e2e/refund/cancel` du double) et deux écrans de `SCREENS` (`remboursement-emis`, `hote-remboursement`). Catalogue v71. Point d'entrée du voyageur vers S10 : notification d'annulation (NTF) et détail du trip (lot 3), suites.
- **US-214 (S08, S09, ADR-160)** : **`/trips`** (S08 « Mis viajes », `account/guest-trips.ts`, `trips/guest-trip-card.tsx`) : sections non vides (demandes envoyées avec l'heure limite de l'hôte, à venir, en cours, passés, annulés), vide « Aún no tienes viajes » + recherche ; **`/trips/{tripId}`** (S09 · détail du trip) : trip, lieu de remise (adresse d'un trip à venir ou en cours seulement), hôte en prénom et initiale, total payé (lu de l'API, jamais recalculé), statut du paiement et lien vers S10 si annulé ou remboursé, documents (contrat et son état ; constancia et reçu « bientôt »), modification par le support (BR-MOD-01). Trip d'un autre ou inconnu ⇒ même message. e2e : `guest-trips.spec.ts` (360 px, es) ; écrans `mes-voyages` et `detail-voyage` dans `SCREENS`.
+- **US-217 partie 217b (S09 · reçu, A08, ADR-167)** : **`/trips/{tripId}/receipt`** (S09 · reçu du voyageur, `account/trip-receipt.ts`, lié depuis S09 dès que le paiement existe) : total payé à Kmino, trip fee facturé et sa taxe de ligne (seulement tant que rien du trip fee n'est remboursé), part remboursée et conservée, remboursement **dû** avec un lien vers S10, mention d'intermédiaire entre particuliers et hôte en prénom et initiale (US-212 critère 3), reçu sans valeur fiscale ; 409 « pas encore disponible », 404 même message pour un reçu d'autrui. **`/host/earnings?org=&month=`** (A08, `account/host-earnings.ts`, lié depuis A10) : mois du relevé (mois courant UTC par défaut, mois voisins), acquis et à régler rendus par l'API, une carte par trip (prix de base de la part, commission de Kmino, part selon le plan figé, état réglé ou à régler) et chaque pénalité sur une carte à part ; `web.a08.payoutsOff` (aucune date de versement promise) ; vide `web.a08.empty`. Montants jamais recalculés, PYG sans décimale ; HTML accessible, sans PDF (10b UX-51). e2e : `e2e/trip-receipt.spec.ts` (360 px, es) et écrans `recu-voyage`, `hote-gains` de `screens.spec.ts`.
e2e : `e2e/host-listings.spec.ts` (projets `mobile-360` et `mobile-390`, quatre langues, axe-core WCAG 2.2 A / AA sur `main` à chaque état, aucun défilement horizontal, cibles ≥ 44 px) contre `e2e/stub-api.mjs` (sessions `H0st…` : un compte d'hôte neuf par parcours ; `N0ho…` : sans compte ; photos 503 comme la production ; fiche publique fictive).
diff --git a/apps/web/account/host-earnings.test.ts b/apps/web/account/host-earnings.test.ts
new file mode 100644
index 000000000..5a8ee8a69
--- /dev/null
+++ b/apps/web/account/host-earnings.test.ts
@@ -0,0 +1,107 @@
+/**
+ * US-217 partie 217b — lecture défensive de `GET /host/accounts/{orgId}/earnings/{month}` (A08).
+ * Attendus : contrat OpenAPI de la route (ADR-161, ADR-167) et 08 TJ01 / T03 / T14 (jambe HOST
+ * 131,25 ; retenue 45,00 ; pénalité −25,00) ; jamais le code testé.
+ */
+import { describe, expect, it } from 'vitest';
+import { hostEarningsOf, monthOf, shiftMonth } from './host-earnings.ts';
+
+const ORG = '00000000-0000-4000-8000-0000000217b2';
+const TRIP_A = '00000000-0000-4000-8000-0000000217a1';
+const TRIP_B = '00000000-0000-4000-8000-0000000217a2';
+const AT = '2034-05-20T15:00:00.000Z';
+const earning = {
+ kind: 'EARNING',
+ tripId: TRIP_A,
+ tripStatus: 'BOOKED',
+ source: 'CAPTURE',
+ settlementVersion: null,
+ reason: null,
+ eventAt: AT,
+ amountMinor: '13125',
+ shareBaseMinor: '17500',
+ kminoFeeMinor: '4375',
+ hostPlanCode: 'ESTÁNDAR',
+ hostSharePct: '3/4',
+};
+const cxl = {
+ ...earning,
+ kind: 'CXL_EARNING',
+ tripId: TRIP_B,
+ tripStatus: 'CANCELLED_BY_HOST',
+ source: 'SETTLEMENT',
+ settlementVersion: 1,
+ amountMinor: '0',
+ shareBaseMinor: '0',
+ kminoFeeMinor: '0',
+};
+const penalty = {
+ ...cxl,
+ kind: 'ADJUSTMENT',
+ source: 'HOST_LEDGER',
+ reason: 'HOST_CANCELLATION_PENALTY',
+ amountMinor: '-2500',
+ shareBaseMinor: null,
+ kminoFeeMinor: null,
+ hostPlanCode: null,
+ hostSharePct: null,
+};
+const statement = {
+ currency: 'XTS',
+ currencyExponent: 2,
+ tripsCount: 2,
+ hostLegMinor: '13125',
+ adjustmentsMinor: '-2500',
+ netMinor: '10625',
+ earnedMinor: '-2500',
+ pendingMinor: '13125',
+ lines: [earning, cxl, penalty],
+};
+const body = { orgId: ORG, month: '2034-05', country: 'XA', statements: [statement] };
+const ok = (json: unknown) => ({ status: 200, json, session: null });
+
+describe('hostEarningsOf', () => {
+ it('relevé lu tel quel : acquis et à venir rendus par l’API, pénalité en ligne séparée', () => {
+ const v = hostEarningsOf(ok(body));
+ expect(v).toMatchObject({ orgId: ORG, month: '2034-05', country: 'XA' });
+ const s = v!.statements[0]!;
+ expect(s).toMatchObject({ earnedMinor: -2500n, pendingMinor: 13125n, tripsCount: 2 });
+ expect(s.lines.map((l) => [l.kind, l.amountMinor])).toEqual([
+ ['EARNING', 13125n],
+ ['CXL_EARNING', 0n],
+ ['ADJUSTMENT', -2500n],
+ ]);
+ expect(s.lines[0]).toMatchObject({ kminoFeeMinor: 4375n, shareBaseMinor: 17500n });
+ expect(hostEarningsOf(ok({ ...body, statements: [] }))?.statements).toEqual([]);
+ });
+
+ it('toute forme inattendue ⇒ null (jamais un relevé partiel ou deviné)', () => {
+ for (const bad of [
+ { ...body, orgId: 'x' },
+ { ...body, month: '2034-13' },
+ { ...body, country: 'xa' },
+ { ...body, statements: 'x' },
+ { ...body, statements: [{ ...statement, earnedMinor: undefined }] },
+ { ...body, statements: [{ ...statement, pendingMinor: '-1' }] },
+ { ...body, statements: [{ ...statement, currencyExponent: 9 }] },
+ { ...body, statements: [{ ...statement, lines: [{ ...earning, amountMinor: '-1' }] }] },
+ { ...body, statements: [{ ...statement, lines: [{ ...earning, kind: 'COMMISSION' }] }] },
+ { ...body, statements: [{ ...statement, lines: [{ ...penalty, reason: null }] }] },
+ { ...body, statements: [{ ...statement, lines: [{ ...penalty, reason: 'OTHER' }] }] },
+ { ...body, statements: [{ ...statement, lines: [{ ...penalty, source: 'CAPTURE' }] }] },
+ { ...body, statements: [{ ...statement, lines: [{ ...earning, hostSharePct: '75%' }] }] },
+ ]) {
+ expect(hostEarningsOf(ok(bad)), JSON.stringify(bad)).toBeNull();
+ }
+ expect(hostEarningsOf({ status: 404, json: {}, session: null })).toBeNull();
+ });
+
+ it('mois : navigation et mois par défaut', () => {
+ expect(shiftMonth('2034-01', -1)).toBe('2033-12');
+ expect(shiftMonth('2034-12', 1)).toBe('2035-01');
+ expect(shiftMonth('2034-05', 1)).toBe('2034-06');
+ expect(monthOf('2034-05', new Date('2036-01-01T00:00:00Z'))).toBe('2034-05');
+ expect(monthOf('2034-5', new Date('2036-01-31T23:00:00Z'))).toBe('2036-01');
+ expect(monthOf(undefined, new Date('2036-02-01T00:00:00Z'))).toBe('2036-02');
+ });
+});
diff --git a/apps/web/account/host-earnings.ts b/apps/web/account/host-earnings.ts
new file mode 100644
index 000000000..30cbf0c5e
--- /dev/null
+++ b/apps/web/account/host-earnings.ts
@@ -0,0 +1,189 @@
+/**
+ * Gains de l'hôte côté site (US-217 partie 217b, ADR-161 / ADR-167 ; 19 US-217 critères 1 et 2 ;
+ * 10b A08, UX-45 ; 16 PYO-013) : lecture DÉFENSIVE de `GET /host/accounts/{orgId}/earnings/{month}`
+ * (toute forme inattendue ⇒ `null` : l'écran dit l'erreur, jamais un relevé partiel ou deviné).
+ * Montants en unités mineures (texte de l'API, convertis en `bigint` pour l'affichage seulement),
+ * jamais recalculés ni additionnés ici : acquis (`earnedMinor`) et à venir (`pendingMinor`) sont
+ * deux sommes rendues par la base (N-339). Une pénalité de l'hôte est une ligne à part
+ * (`ADJUSTMENT`, montant négatif). Côté serveur seulement.
+ */
+import type { ApiResult } from './api-client.ts';
+
+export const EARNING_LINE_KINDS = ['EARNING', 'CXL_EARNING', 'ADJUSTMENT'] as const;
+export type EarningLineKind = (typeof EARNING_LINE_KINDS)[number];
+export const EARNING_SOURCES = ['CAPTURE', 'SETTLEMENT', 'HOST_LEDGER'] as const;
+export type EarningSource = (typeof EARNING_SOURCES)[number];
+/** Motifs du host_ledger connus de l'écran ; tout autre motif ⇒ relevé illisible. */
+export const ADJUSTMENT_REASONS = ['HOST_CANCELLATION_PENALTY'] as const;
+export type AdjustmentReason = (typeof ADJUSTMENT_REASONS)[number];
+
+export interface EarningLineView {
+ readonly kind: EarningLineKind;
+ readonly tripId: string;
+ readonly tripStatus: string;
+ readonly source: EarningSource;
+ readonly reason: AdjustmentReason | null;
+ readonly eventAt: string;
+ readonly amountMinor: bigint;
+ readonly shareBaseMinor: bigint | null;
+ readonly kminoFeeMinor: bigint | null;
+ readonly hostPlanCode: string | null;
+ readonly hostSharePct: string | null;
+}
+
+export interface EarningsStatementView {
+ readonly currency: string;
+ readonly currencyExponent: number;
+ readonly tripsCount: number;
+ readonly earnedMinor: bigint;
+ readonly pendingMinor: bigint;
+ readonly lines: readonly EarningLineView[];
+}
+
+export interface HostEarningsView {
+ readonly orgId: string;
+ readonly month: string;
+ readonly country: string;
+ readonly statements: readonly EarningsStatementView[];
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MINOR = /^(0|[1-9][0-9]{0,17})$/;
+const SIGNED = /^(0|-?[1-9][0-9]{0,17})$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const CODE = /^[A-Z][A-Z0-9_]{1,63}$/;
+const PLAN = /^[A-Z][A-Z0-9_ÁÉÍÓÚÑ]{0,31}$/u;
+const SHARE = /^[0-9]{1,9}\/[1-9][0-9]{0,8}$/;
+/** Mois du relevé « YYYY-MM ». */
+export const MONTH = /^[0-9]{4}-(0[1-9]|1[0-2])$/;
+type Obj = Readonly>;
+const isObj = (v: unknown): v is Obj => typeof v === 'object' && v !== null && !Array.isArray(v);
+const oneOf = (v: unknown, all: readonly T[]): T | null =>
+ typeof v === 'string' && (all as readonly string[]).includes(v) ? (v as T) : null;
+const amount = (v: unknown, re: RegExp): bigint | null =>
+ typeof v === 'string' && re.test(v) ? BigInt(v) : null;
+/** Montant facultatif : `null` admis ; `undefined` = anomalie. */
+const optional = (v: unknown): bigint | null | undefined =>
+ v === null ? null : (amount(v, SIGNED) ?? undefined);
+const textOrNull = (v: unknown, re: RegExp): string | null | undefined =>
+ v === null ? null : typeof v === 'string' && re.test(v) ? v : undefined;
+
+function lineOf(raw: unknown): EarningLineView | null {
+ if (!isObj(raw)) return null;
+ const kind = oneOf(raw['kind'], EARNING_LINE_KINDS);
+ const source = oneOf(raw['source'], EARNING_SOURCES);
+ const tripId = raw['tripId'];
+ const tripStatus = raw['tripStatus'];
+ const eventAt = raw['eventAt'];
+ const reason = raw['reason'] === null ? null : oneOf(raw['reason'], ADJUSTMENT_REASONS);
+ const value = amount(raw['amountMinor'], kind === 'ADJUSTMENT' ? SIGNED : MINOR);
+ const shareBaseMinor = optional(raw['shareBaseMinor']);
+ const kminoFeeMinor = optional(raw['kminoFeeMinor']);
+ const hostPlanCode = textOrNull(raw['hostPlanCode'], PLAN);
+ const hostSharePct = textOrNull(raw['hostSharePct'], SHARE);
+ if (
+ kind === null ||
+ source === null ||
+ (kind === 'ADJUSTMENT') !== (source === 'HOST_LEDGER') ||
+ (raw['reason'] !== null && reason === null) ||
+ (kind === 'ADJUSTMENT') !== (reason !== null) ||
+ typeof tripId !== 'string' ||
+ !UUID.test(tripId) ||
+ typeof tripStatus !== 'string' ||
+ !CODE.test(tripStatus) ||
+ typeof eventAt !== 'string' ||
+ !ISO.test(eventAt) ||
+ value === null ||
+ shareBaseMinor === undefined ||
+ kminoFeeMinor === undefined ||
+ hostPlanCode === undefined ||
+ hostSharePct === undefined
+ ) {
+ return null;
+ }
+ return {
+ kind,
+ tripId,
+ tripStatus,
+ source,
+ reason,
+ eventAt,
+ amountMinor: value,
+ shareBaseMinor,
+ kminoFeeMinor,
+ hostPlanCode,
+ hostSharePct,
+ };
+}
+
+/** Relevé d'une réponse 200 de `GET /host/accounts/{orgId}/earnings/{month}`, sinon `null`. */
+export function hostEarningsOf(reply: ApiResult): HostEarningsView | null {
+ if (reply.status !== 200 || !isObj(reply.json)) return null;
+ const j = reply.json;
+ const orgId = j['orgId'];
+ const month = j['month'];
+ const country = j['country'];
+ if (
+ typeof orgId !== 'string' ||
+ !UUID.test(orgId) ||
+ typeof month !== 'string' ||
+ !MONTH.test(month) ||
+ typeof country !== 'string' ||
+ !/^[A-Z]{2}$/.test(country) ||
+ !Array.isArray(j['statements'])
+ ) {
+ return null;
+ }
+ const statements: EarningsStatementView[] = [];
+ for (const s of j['statements'] as unknown[]) {
+ if (!isObj(s) || !Array.isArray(s['lines'])) return null;
+ const currency = s['currency'];
+ const exponent = s['currencyExponent'];
+ const count = s['tripsCount'];
+ const earnedMinor = amount(s['earnedMinor'], SIGNED);
+ const pendingMinor = amount(s['pendingMinor'], MINOR);
+ if (
+ typeof currency !== 'string' ||
+ !/^[A-Z]{3}$/.test(currency) ||
+ typeof exponent !== 'number' ||
+ !Number.isSafeInteger(exponent) ||
+ exponent < 0 ||
+ exponent > 4 ||
+ typeof count !== 'number' ||
+ !Number.isSafeInteger(count) ||
+ count < 0 ||
+ earnedMinor === null ||
+ pendingMinor === null
+ ) {
+ return null;
+ }
+ const lines: EarningLineView[] = [];
+ for (const l of s['lines'] as unknown[]) {
+ const line = lineOf(l);
+ if (line === null) return null;
+ lines.push(line);
+ }
+ statements.push({
+ currency,
+ currencyExponent: exponent,
+ tripsCount: count,
+ earnedMinor,
+ pendingMinor,
+ lines,
+ });
+ }
+ return { orgId, month, country, statements };
+}
+
+/** Mois voisin « YYYY-MM » (navigation du relevé ; aucune date d'argent). */
+export function shiftMonth(month: string, delta: -1 | 1): string {
+ const [y, m] = month.split('-').map(Number) as [number, number];
+ const index = y * 12 + (m - 1) + delta;
+ return `${String(Math.floor(index / 12)).padStart(4, '0')}-${String((index % 12) + 1).padStart(2, '0')}`;
+}
+
+/** Mois demandé (`?month=YYYY-MM`) s'il est bien formé, sinon le mois de `now` en UTC. */
+export function monthOf(raw: unknown, now: Date): string {
+ if (typeof raw === 'string' && MONTH.test(raw)) return raw;
+ return now.toISOString().slice(0, 7);
+}
diff --git a/apps/web/account/trip-receipt.test.ts b/apps/web/account/trip-receipt.test.ts
new file mode 100644
index 000000000..1cef67c47
--- /dev/null
+++ b/apps/web/account/trip-receipt.test.ts
@@ -0,0 +1,117 @@
+/**
+ * US-217 partie 217b — lecture défensive de `GET /trips/{id}/receipt` (vue du voyageur).
+ * Attendus : contrat OpenAPI de la route (ADR-161, ADR-167) et 08 T03 (trip fee 18,00, taxe de ligne
+ * 1,26, conservé 6,00) ; jamais le code testé.
+ */
+import { describe, expect, it } from 'vitest';
+import { guestReceiptOf, taxPercentOf } from './trip-receipt.ts';
+
+const TRIP = '00000000-0000-4000-8000-0000000217b1';
+const booked = {
+ tripId: TRIP,
+ viewerRole: 'GUEST',
+ tripStatus: 'BOOKED',
+ currency: 'XTS',
+ currencyExponent: 2,
+ timezone: 'Etc/UTC',
+ receipt: {
+ source: 'CAPTURE',
+ settlementVersion: null,
+ totalPaidMinor: '25666',
+ refundMinor: '0',
+ tripFee: {
+ chargedMinor: '1800',
+ taxMinor: '126',
+ taxRateBps: 700,
+ refundedMinor: '0',
+ retainedMinor: '1800',
+ },
+ fiscalDocument: 'OFF_PLATFORM',
+ },
+};
+const cancelled = {
+ ...booked,
+ tripStatus: 'CANCELLED_BY_GUEST',
+ receipt: {
+ ...booked.receipt,
+ source: 'SETTLEMENT',
+ settlementVersion: 1,
+ refundMinor: '18744',
+ tripFee: {
+ chargedMinor: '1800',
+ taxMinor: null,
+ taxRateBps: null,
+ refundedMinor: '1200',
+ retainedMinor: '600',
+ },
+ },
+};
+const ok = (json: unknown) => ({ status: 200, json, session: null });
+
+describe('guestReceiptOf', () => {
+ it('trip capturé : total, trip fee et sa taxe de ligne, montants en bigint', () => {
+ expect(guestReceiptOf(ok(booked))).toEqual({
+ tripId: TRIP,
+ tripStatus: 'BOOKED',
+ currency: 'XTS',
+ currencyExponent: 2,
+ timezone: 'Etc/UTC',
+ source: 'CAPTURE',
+ totalPaidMinor: 25666n,
+ refundDueMinor: 0n,
+ tripFee: {
+ chargedMinor: 1800n,
+ taxMinor: 126n,
+ taxRateBps: 700,
+ refundedMinor: 0n,
+ retainedMinor: 1800n,
+ },
+ });
+ });
+
+ it('annulé (T03) : remboursement dû, trip fee conservé sans taxe rendue (N-337)', () => {
+ const v = guestReceiptOf(ok(cancelled));
+ expect(v?.refundDueMinor).toBe(18744n);
+ expect(v?.tripFee).toEqual({
+ chargedMinor: 1800n,
+ taxMinor: null,
+ taxRateBps: null,
+ refundedMinor: 1200n,
+ retainedMinor: 600n,
+ });
+ expect(
+ guestReceiptOf(ok({ ...booked, receipt: { ...booked.receipt, tripFee: null } }))?.tripFee,
+ ).toBeNull();
+ });
+
+ it('toute autre vue ou forme inattendue ⇒ null (jamais un reçu partiel ou deviné)', () => {
+ const r = booked.receipt;
+ const fee = r.tripFee;
+ for (const bad of [
+ { ...booked, viewerRole: 'HOST' },
+ { ...booked, tripId: 'x' },
+ { ...booked, tripStatus: 'booked' },
+ { ...booked, currency: 'xts' },
+ { ...booked, currencyExponent: 7 },
+ { ...booked, timezone: 'UTC; x' },
+ { ...booked, receipt: null },
+ { ...booked, receipt: { ...r, fiscalDocument: 'INVOICE' } },
+ { ...booked, receipt: { ...r, source: 'QUOTE' } },
+ { ...booked, receipt: { ...r, totalPaidMinor: '-1' } },
+ { ...booked, receipt: { ...r, refundMinor: '1.5' } },
+ { ...booked, receipt: { ...r, hostLegMinor: '1' } },
+ { ...booked, receipt: { ...r, tripFee: { ...fee, taxMinor: 126 } } },
+ { ...booked, receipt: { ...r, tripFee: { ...fee, taxRateBps: 1.5 } } },
+ { ...booked, receipt: { ...r, tripFee: { ...fee, retainedMinor: null } } },
+ { ...booked, receipt: { ...r, tripFee: { ...fee, extra: '1' } } },
+ ]) {
+ expect(guestReceiptOf(ok(bad)), JSON.stringify(bad)).toBeNull();
+ }
+ expect(guestReceiptOf({ status: 409, json: {}, session: null })).toBeNull();
+ });
+
+ it('taux de taxe affiché en pourcentage (affichage seulement)', () => {
+ expect(taxPercentOf(700)).toBe(7);
+ expect(taxPercentOf(1050)).toBe(10.5);
+ });
+});
diff --git a/apps/web/account/trip-receipt.ts b/apps/web/account/trip-receipt.ts
new file mode 100644
index 000000000..375779809
--- /dev/null
+++ b/apps/web/account/trip-receipt.ts
@@ -0,0 +1,143 @@
+/**
+ * Reçu du voyageur côté site (US-217 partie 217b, ADR-161 / ADR-167 ; 19 US-217 critère 1, US-214
+ * critère 2 ; 10b S09 ; 16 FIN-018, FIN-002) : lecture DÉFENSIVE de `GET /trips/{id}/receipt`, vue
+ * GUEST seulement (toute autre vue, ou toute forme inattendue ⇒ `null` : l'écran dit l'erreur,
+ * jamais un reçu partiel ou deviné). Montants en unités mineures (texte de l'API, convertis en
+ * `bigint` pour l'affichage seulement), jamais recalculés :
+ * - `totalPaidMinor` : total payé à Kmino ;
+ * - `refundDueMinor` : remboursement DÛ par le règlement (clé `refundMinor` de l'API), pas un
+ * remboursement émis : l'écran renvoie à S10 pour son état et sa date d'émission (N-338) ;
+ * - trip fee : facturé, sa taxe de ligne (rendue seulement si rien du trip fee n'est remboursé,
+ * N-337), part remboursée et part conservée.
+ * Côté serveur seulement ; jamais de donnée personnelle dans une URL ni dans un journal.
+ */
+import type { ApiResult } from './api-client.ts';
+
+export interface GuestReceiptFee {
+ readonly chargedMinor: bigint;
+ readonly taxMinor: bigint | null;
+ readonly taxRateBps: number | null;
+ readonly refundedMinor: bigint;
+ readonly retainedMinor: bigint;
+}
+
+export interface GuestReceiptView {
+ readonly tripId: string;
+ readonly tripStatus: string;
+ readonly currency: string;
+ readonly currencyExponent: number;
+ readonly timezone: string;
+ /** `SETTLEMENT` : version en tête du règlement ; `CAPTURE` : aucun règlement encore. */
+ readonly source: 'CAPTURE' | 'SETTLEMENT';
+ readonly totalPaidMinor: bigint;
+ readonly refundDueMinor: bigint;
+ readonly tripFee: GuestReceiptFee | null;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MINOR = /^(0|[1-9][0-9]{0,17})$/;
+const ZONE = /^[A-Za-z_]+(\/[A-Za-z0-9_+-]+){0,2}$/;
+const CODE = /^[A-Z][A-Z0-9_]{1,63}$/;
+type Obj = Readonly>;
+const isObj = (v: unknown): v is Obj => typeof v === 'object' && v !== null && !Array.isArray(v);
+const minorOf = (v: unknown): bigint | null =>
+ typeof v === 'string' && MINOR.test(v) ? BigInt(v) : null;
+const sameKeys = (o: Obj, keys: readonly string[]): boolean => {
+ const own = Object.keys(o).sort();
+ const want = [...keys].sort();
+ return own.length === want.length && own.every((k, i) => k === want[i]);
+};
+
+const RECEIPT_KEYS = [
+ 'source',
+ 'settlementVersion',
+ 'totalPaidMinor',
+ 'refundMinor',
+ 'tripFee',
+ 'fiscalDocument',
+];
+const FEE_KEYS = ['chargedMinor', 'taxMinor', 'taxRateBps', 'refundedMinor', 'retainedMinor'];
+
+function feeOf(raw: unknown): GuestReceiptFee | null | undefined {
+ if (raw === null) return null;
+ if (!isObj(raw) || !sameKeys(raw, FEE_KEYS)) return undefined;
+ const chargedMinor = minorOf(raw['chargedMinor']);
+ const refundedMinor = minorOf(raw['refundedMinor']);
+ const retainedMinor = minorOf(raw['retainedMinor']);
+ const taxMinor = raw['taxMinor'] === null ? null : minorOf(raw['taxMinor']);
+ const bps = raw['taxRateBps'];
+ const taxRateBps =
+ bps === null
+ ? null
+ : typeof bps === 'number' && Number.isSafeInteger(bps) && bps >= 0 && bps <= 10_000
+ ? bps
+ : undefined;
+ if (
+ chargedMinor === null ||
+ refundedMinor === null ||
+ retainedMinor === null ||
+ (raw['taxMinor'] !== null && taxMinor === null) ||
+ taxRateBps === undefined
+ ) {
+ return undefined;
+ }
+ return { chargedMinor, taxMinor, taxRateBps, refundedMinor, retainedMinor };
+}
+
+/** Reçu du voyageur d'une réponse 200 de `GET /trips/{id}/receipt`, sinon `null`. */
+export function guestReceiptOf(reply: ApiResult): GuestReceiptView | null {
+ if (reply.status !== 200 || !isObj(reply.json)) return null;
+ const j = reply.json;
+ const r = j['receipt'];
+ const tripId = j['tripId'];
+ const tripStatus = j['tripStatus'];
+ const currency = j['currency'];
+ const exponent = j['currencyExponent'];
+ const timezone = j['timezone'];
+ if (
+ j['viewerRole'] !== 'GUEST' ||
+ !isObj(r) ||
+ !sameKeys(r, RECEIPT_KEYS) ||
+ r['fiscalDocument'] !== 'OFF_PLATFORM' ||
+ typeof tripId !== 'string' ||
+ !UUID.test(tripId) ||
+ typeof tripStatus !== 'string' ||
+ !CODE.test(tripStatus) ||
+ typeof currency !== 'string' ||
+ !/^[A-Z]{3}$/.test(currency) ||
+ typeof exponent !== 'number' ||
+ !Number.isSafeInteger(exponent) ||
+ exponent < 0 ||
+ exponent > 4 ||
+ typeof timezone !== 'string' ||
+ !ZONE.test(timezone)
+ ) {
+ return null;
+ }
+ const source = r['source'];
+ const totalPaidMinor = minorOf(r['totalPaidMinor']);
+ const refundDueMinor = minorOf(r['refundMinor']);
+ const tripFee = feeOf(r['tripFee']);
+ if (
+ (source !== 'CAPTURE' && source !== 'SETTLEMENT') ||
+ totalPaidMinor === null ||
+ refundDueMinor === null ||
+ tripFee === undefined
+ ) {
+ return null;
+ }
+ return {
+ tripId,
+ tripStatus,
+ currency,
+ currencyExponent: exponent,
+ timezone,
+ source,
+ totalPaidMinor,
+ refundDueMinor,
+ tripFee,
+ };
+}
+
+/** Taux de taxe en pourcentage (700 ⇒ 7 ; 1050 ⇒ 10,5) : affichage seulement. */
+export const taxPercentOf = (bps: number): number => bps / 100;
diff --git a/apps/web/app/(app)/host/earnings/loading.tsx b/apps/web/app/(app)/host/earnings/loading.tsx
new file mode 100644
index 000000000..40726025b
--- /dev/null
+++ b/apps/web/app/(app)/host/earnings/loading.tsx
@@ -0,0 +1,19 @@
+import { LoadingState, Skeleton } from '@rueda/ui';
+import { getRequestI18n } from '../../../../i18n.ts';
+import accountStyles from '../../_account/account.module.css';
+import { MAIN_ID } from '../../_shell/main-id.ts';
+
+/** A08 — état de chargement (squelettes à la forme du relevé ; annoncé poliment). */
+export default async function HostEarningsLoading() {
+ const i18n = await getRequestI18n();
+ return (
+
+ {i18n.t('web.a08.title')}
+
+
+
+
+
+
+ );
+}
diff --git a/apps/web/app/(app)/host/earnings/page.tsx b/apps/web/app/(app)/host/earnings/page.tsx
new file mode 100644
index 000000000..78bec6263
--- /dev/null
+++ b/apps/web/app/(app)/host/earnings/page.tsx
@@ -0,0 +1,272 @@
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+import { Badge, Banner, ButtonLink, EmptyState, ErrorState } from '@rueda/ui';
+import { callApi } from '../../../../account/api-client.ts';
+import { percentLabel, planName, sharePercentOf } from '../../../../account/earnings-plans.ts';
+import { hostEarningsOf, monthOf, shiftMonth } from '../../../../account/host-earnings.ts';
+import type { EarningLineView } from '../../../../account/host-earnings.ts';
+import { hostAccountsOf } from '../../../../account/host-listings.ts';
+import { clientContext } from '../../../../account/request.ts';
+import { getRequestBrand } from '../../../../brand-source.ts';
+import { getRequestI18n, getRequestLocaleTag } from '../../../../i18n.ts';
+import accountStyles from '../../_account/account.module.css';
+import { MAIN_ID } from '../../_shell/main-id.ts';
+import styles from '../host.module.css';
+
+export async function generateMetadata(): Promise {
+ const i18n = await getRequestI18n();
+ return { title: i18n.t('web.a08.title'), robots: { index: false, follow: false } };
+}
+
+const textOf = (
+ q: Readonly>,
+ key: string,
+): string | undefined => (typeof q[key] === 'string' ? q[key] : undefined);
+
+/** Nom du pays dans la langue de la vue (`Intl.DisplayNames`), sinon son code. */
+function countryName(tag: string, code: string): string {
+ try {
+ return new Intl.DisplayNames([tag], { type: 'region' }).of(code) ?? code;
+ } catch {
+ return code;
+ }
+}
+
+/** « mayo de 2034 » : libellé du mois du relevé (affichage seulement, en UTC). */
+function monthLabel(tag: string, month: string): string {
+ try {
+ return new Intl.DateTimeFormat(tag, {
+ month: 'long',
+ year: 'numeric',
+ timeZone: 'UTC',
+ }).format(new Date(`${month}-01T12:00:00.000Z`));
+ } catch {
+ return month;
+ }
+}
+
+/**
+ * A08 — gains de l'hôte (US-217 partie 217b, ADR-161 / ADR-167 ; 19 US-217 critères 1 et 2 ; 10b
+ * A08, UX-45 ; 16 PYO-013 ; 08 E7, BR-PROT-06). Relevé d'un mois lu de
+ * `GET /host/accounts/{orgId}/earnings/{month}` : par devise, **acquis** (jambes HOST des règlements
+ * et pénalités du host_ledger) et **à liquider** (trips à venir ou en cours, capturés sans
+ * règlement), deux sommes rendues par l'API (N-339) ; puis une carte par trip (base sur laquelle la
+ * part est calculée, commission de Kmino, part de l'hôte selon le plan figé) et, sur une ligne À
+ * PART, chaque pénalité de l'hôte (08 E7 règle 7). Montants jamais recalculés ni additionnés ici ;
+ * PYG sans décimale. Aucun versement n'est promis : `payouts_enabled` vaut `false` en production et
+ * aucune date de versement n'existe encore (`web.a08.payoutsOff`, 10b ; PROPOSÉ). Navigation par
+ * mois (`?month=YYYY-MM`, mois courant UTC par défaut). Un compte d'un autre hôte n'est jamais lisible
+ * (404 de l'API). Relevé annuel : lot 5 (US-541) ; PDF : HTML accessible équivalent (10b UX-51).
+ */
+export default async function HostEarningsPage({
+ searchParams,
+}: {
+ readonly searchParams: Promise>>;
+}) {
+ const [i18n, tag, query, brand] = await Promise.all([
+ getRequestI18n(),
+ getRequestLocaleTag(),
+ searchParams,
+ getRequestBrand(),
+ ]);
+ const t = i18n.t.bind(i18n);
+ const ctx = await clientContext();
+ const org = textOf(query, 'org');
+ const shell = (body: ReactNode) => (
+
+
+ {body}
+
+ );
+ const login = shell(
+ {t('web.host.login')}}
+ />,
+ );
+ if (ctx.sessionToken === null) return login;
+ const session = await callApi('GET', '/auth/session', ctx);
+ if (session.status === 401) return login;
+ const accounts = hostAccountsOf(session);
+ const month = monthOf(textOf(query, 'month'), new Date());
+ const self = (m: string, o: string) =>
+ `/host/earnings?${new URLSearchParams({ org: o, month: m }).toString()}`;
+ const error = (o: string | undefined) =>
+ shell(
+
+ {t('web.a08.retry')}
+
+ }
+ />,
+ );
+ if (accounts === null) return error(undefined);
+ if (accounts.length === 0) {
+ return shell(
+ ,
+ );
+ }
+ const account = accounts.find((a) => a.orgId === org) ?? accounts[0];
+ if (account === undefined) return error(undefined);
+ const reply = await callApi(
+ 'GET',
+ `/host/accounts/${account.orgId}/earnings/${encodeURIComponent(month)}`,
+ ctx,
+ );
+ const view = hostEarningsOf(reply);
+ if (view === null || view.month !== month) return error(account.orgId);
+
+ const label = monthLabel(tag, month);
+ const nav = (
+
+ );
+ const payoutsOff = (
+
+ {t('web.a08.payoutsOff', { country: countryName(tag, view.country) })}
+
+ );
+ const intermediary = (
+ {t('web.a08.intermediary', { brand: brand.name })}
+ );
+ if (view.statements.length === 0) {
+ return shell(
+ <>
+
+ {t('web.a08.summary', { month: label })}
+
+ {nav}
+
+ {payoutsOff}
+ {intermediary}
+ >,
+ );
+ }
+ const lineTitle = (l: EarningLineView): string =>
+ l.kind === 'ADJUSTMENT'
+ ? t('web.a08.line.HOST_CANCELLATION_PENALTY')
+ : t(l.kind === 'EARNING' ? 'web.a08.line.EARNING' : 'web.a08.line.CXL_EARNING');
+ const shareLabel = (l: EarningLineView): string => {
+ const percent = sharePercentOf(l.hostSharePct);
+ if (l.hostPlanCode === null || percent === null) return t('web.a08.line.shareNoPlan');
+ return t('web.a08.line.share', {
+ plan: planName(i18n, { planCode: l.hostPlanCode, sharePercent: percent }),
+ share: percentLabel(i18n, percent),
+ });
+ };
+ return shell(
+ <>
+
+ {t('web.a08.summary', { month: label })}
+
+ {nav}
+ {payoutsOff}
+ {view.statements.map((s) => {
+ const money = (amountMinor: bigint) =>
+ i18n.money({ amountMinor, currency: s.currency, exponent: s.currencyExponent });
+ return (
+
+
+ {t('web.a08.tripsCount', { count: String(s.tripsCount) })}
+
+
+
+ {t('web.a08.earned')}
+
+ {money(s.earnedMinor)}
+
+
+
{t('web.a08.earnedHint')}
+
+ {t('web.a08.pending')}
+ {money(s.pendingMinor)}
+
+
{t('web.a08.pendingHint')}
+
+ {t('web.a08.lines')}
+
+ {s.lines.map((l) => (
+ -
+
+ {lineTitle(l)}
+ {l.kind !== 'ADJUSTMENT' && (
+
+ {t(
+ l.source === 'CAPTURE' ? 'web.a08.line.pending' : 'web.a08.line.settled',
+ )}
+
+ )}
+
+ {l.shareBaseMinor !== null && (
+
+ {t('web.a08.line.base')}
+ {money(l.shareBaseMinor)}
+
+ )}
+ {l.kminoFeeMinor !== null && (
+
+ {t('web.a08.line.fee', { brand: brand.name })}
+ {money(l.kminoFeeMinor)}
+
+ )}
+
+
+ {l.kind === 'ADJUSTMENT' ? t('web.a08.line.penaltyHint') : shareLabel(l)}
+
+
+ {money(l.amountMinor)}
+
+
+ {l.kind !== 'ADJUSTMENT' && (
+
+ {t('web.a08.line.trip')}
+
+ )}
+
+ ))}
+
+
+ );
+ })}
+ {intermediary}
+ >,
+ );
+}
diff --git a/apps/web/app/(app)/host/page.tsx b/apps/web/app/(app)/host/page.tsx
index b63b4a17c..a1e02b23f 100644
--- a/apps/web/app/(app)/host/page.tsx
+++ b/apps/web/app/(app)/host/page.tsx
@@ -210,6 +210,16 @@ export default async function HostPage({
{t('web.host.verificationLink')}
+ {/* A08 (US-217 partie 217b) : gains par mois et par voyage */}
+
+
+ {t('web.host.earningsLink')}
+
+
{accounts.length > 1 && (