Skip to content
Draft
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
18 changes: 15 additions & 3 deletions apps/api/openapi/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -16130,7 +16130,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": [
Expand All @@ -16157,7 +16158,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"],
Expand Down Expand Up @@ -16362,6 +16363,8 @@
"hostLegMinor",
"adjustmentsMinor",
"netMinor",
"earnedMinor",
"pendingMinor",
"lines"
],
"additionalProperties": false,
Expand All @@ -16386,7 +16389,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",
Expand Down
1 change: 1 addition & 0 deletions apps/api/src/modules/avl/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 0144, 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.
Expand Down
20 changes: 18 additions & 2 deletions apps/api/src/modules/avl/internal/checkout/host-earnings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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[];
}

Expand Down Expand Up @@ -166,6 +174,8 @@ const STATEMENT_KEYS = [
'hostLegMinor',
'adjustmentsMinor',
'netMinor',
'earnedMinor',
'pendingMinor',
'lines',
];
const sameKeys = (o: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean => {
Expand Down Expand Up @@ -235,14 +245,18 @@ 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' ||
!Number.isSafeInteger(count) ||
count < 0 ||
typeof hostLegMinor !== 'string' ||
typeof adjustmentsMinor !== 'string' ||
typeof netMinor !== 'string'
typeof netMinor !== 'string' ||
typeof earnedMinor !== 'string' ||
typeof pendingMinor !== 'string'
) {
return null;
}
Expand All @@ -262,6 +276,8 @@ function statementsOf(raw: unknown, exponents: unknown): EarningsStatement[] | n
hostLegMinor,
adjustmentsMinor,
netMinor,
earnedMinor,
pendingMinor,
lines,
});
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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' }] }],
Expand Down
2 changes: 2 additions & 0 deletions apps/api/src/modules/fin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 0144, 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) :
Expand Down
1 change: 1 addition & 0 deletions apps/web/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
Loading
Loading