# Patch Spec Frontend ESTAIR — Selling GDS Amadeus > **Document** : Patch à intégrer dans `ESTAIR_FRONTEND_SPEC_COMPLET.md` > **Périmètre** : Modules PNR, Presales (vue contextuelle), États de Vente, Accounts (rappel) > **Version** : 1.1 — 10/05/2026 > **Auteur** : Nicephore / ESTAIR Connect > > **Changelog v1.1** : > - Statuts PNR alignés sur les valeurs métier existantes (En attente, À émettre, En cours, Émission partielle, Émis) > - Mise à jour temps réel via **WebSocket** (et non polling) > - Permissions des CTAs (Void, Refund, Execute) **gérées dynamiquement** via Admin CHAPS et metadata, non figées dans le frontend --- ## Sommaire 1. [Module PNR](#1-module-pnr) - 1.1 [Vue Liste](#11-vue-liste) - 1.2 [Vue Détail](#12-vue-détail) - 1.3 [Vue contextuelle Presales (dans détail PNR)](#13-vue-contextuelle-presales) - 1.4 [Triggers automatiques](#14-triggers-automatiques) 2. [Module États de Vente](#2-module-états-de-vente) 3. [Module Accounts (rappel)](#3-module-accounts-rappel) 4. [Composants transverses](#4-composants-transverses) - 4.1 [Pop-up de confirmation Execute](#41-pop-up-de-confirmation-execute) - 4.2 [Visualisation Conditions tarifaires (fare_basis)](#42-visualisation-conditions-tarifaires) 5. [Logique métier et règles transverses](#5-logique-métier-et-règles-transverses) --- ## 1. Module PNR ### 1.1 Vue Liste #### Bouton "Nouveau" **Position** : barre d'actions en haut de la liste PNR (CTA primaire). **Comportement** : - Ouvre une modal **"Charger un PNR"** - Champ unique : numéro PNR (record locator, 6 caractères alphanumériques) - Validation côté front : - Longueur exacte : 6 caractères - Pattern : `^[A-Z0-9]{6}$` - Conversion automatique en majuscules à la saisie - Boutons : `Annuler` / `Charger` **Action sur "Charger"** : 1. Appel API : `POST /api/pnrs/load` avec body `{ pnr: "ABC123" }` 2. Backend déclenche un message vers Messager → Octopus → Amadeus pour un Load PNR (graphique) 3. Le PNR est créé immédiatement côté ESTAIR avec : - `account_uuid` = agence demandeuse (de l'utilisateur connecté) - `status` = `En attente` - Aucun contenu visible (segments, passagers, presales = vides) 4. Affichage d'un toast : `PNR ABC123 en cours de chargement…` 5. La modal se ferme et la liste se rafraîchit **À la réception du fichier AIR Amadeus** (asynchrone) : - Le PNR est mis à jour avec les données réelles - L'`account_uuid` est **réécrit** selon l'office ID retourné par Amadeus (voir [§5 - Logique métier](#5-logique-métier-et-règles-transverses)) - Le `status` passe à `À émettre` - Notification temps réel envoyée via WebSocket à l'utilisateur (et au panneau de la liste si ouvert) #### Statuts PNR — référentiel complet Les statuts métier d'un PNR sont définis dans CHAPS et synchronisés via metadata. Les 5 statuts du référentiel actuel : | Statut | Sens | Couleur badge | Lignes grisées | |--------|------|---------------|----------------| | `En attente` | PNR créé via Load PNR, en attente du fichier AIR Amadeus. Contenu vide. | Orange | Oui | | `À émettre` | PNR chargé avec données, presales en place, **aucun** presale émis | Bleu | Non | | `En cours` | Exécution en cours (Execute lancé, attente retours Amadeus) | Bleu clair (animé) | Non | | `Émission partielle` | Certains presales émis, d'autres en échec ou pending | Jaune | Non | | `Émis` | Tous les presales émis (au moins un état de vente créé) | Vert | Non | **Affichage colonne `Status` dans la liste** : - Badge `VChip` avec couleur correspondante - Label en français tel que défini ci-dessus **Cas spécifique `En attente`** : - Lignes grisées (opacité 60%) - Aucune action contextuelle disponible (pas de menu kebab, pas de CTA) - Le clic sur la ligne ouvre la vue détail mais affiche un état vide avec message : > *Ce PNR est en cours de chargement. Les informations seront disponibles dès la réception du fichier AIR Amadeus.* #### Mise à jour temps réel — WebSocket **Mécanisme** : abonnement WebSocket par utilisateur (canal authentifié via Keycloak token). **Canaux** : - Canal privé utilisateur : `private-user.{user_id}` — événements globaux (notifications) - Canal privé agence : `private-account.{account_uuid}` — événements PNR de l'agence (changements de statut, nouveaux PNR chargés) **Événements écoutés** : | Événement | Payload | Action UI | |-----------|---------|-----------| | `pnr.status.updated` | `{ pnr_id, old_status, new_status }` | Mise à jour du badge sans rechargement complet de la liste | | `pnr.air.received` | `{ pnr_id, account_uuid }` | Mise à jour du PNR dans la liste (statut + contenu) ; toast si l'utilisateur est sur la liste ou le détail de ce PNR | | `pnr.account.reassigned` | `{ pnr_id, old_account_uuid, new_account_uuid }` | Si le PNR a été réaffecté à une autre agence, retrait silencieux de la liste de l'utilisateur d'origine | | `presale.fare_basis.created` | `{ presale_id, pnr_id }` | Mise à jour de l'indicateur fare_basis (⏳ → ✓) sans rechargement | | `edv.created` | `{ edv_id, pnr_id }` | Rafraîchissement de l'onglet États de Vente du détail PNR si ouvert | | `pnr.execute.completed` | `{ pnr_id, success, items_results }` | Mise à jour du statut PNR + toasts par presale | **Implémentation côté Nuxt 3** : - Plugin `~/plugins/websocket.client.ts` (suffixe `.client.ts` obligatoire pour éviter SSR crash, cohérent avec le pattern Keycloak) - Connexion établie après authentification réussie (Keycloak token disponible) - Reconnexion automatique en cas de perte de connexion - Nettoyage des abonnements à la déconnexion **Fallback** : en cas d'indisponibilité WebSocket (firewall, réseau), polling automatique 60s comme solution de secours, **uniquement** pour les PNR en `En attente` ou `En cours` visibles à l'écran. --- ### 1.2 Vue Détail #### Structure générale La vue détail PNR utilise le pattern **Vuexy detail panel with grow tabs** déjà défini dans la spec principale. Elle comprend : - **En-tête** : numéro PNR, statut, agence, date de création, dernière mise à jour - **Onglets (grow tabs)** : - Vue d'ensemble (segments, passagers, contacts) - Presales (vue contextuelle) ← cible de cette section - États de vente - Documents - Historique - **Zone d'actions principales** (en haut à droite) : CTA `Execute` + autres actions (selon contexte) #### CTA "Execute" (mode global) **Position** : zone d'actions principales du détail PNR (CTA primaire). **Visibilité** : - Visible uniquement si `pnr.status` ∈ `{ "À émettre", "Émission partielle" }` - Caché si `pnr.status` ∈ `{ "En attente", "En cours", "Émis" }` - En `Émission partielle`, le bouton n'agit que sur les presales encore non émis (filtrage automatique côté backend) **Permissions** : - Récupérées dynamiquement via les **metadata CTA** (configurées dans Admin CHAPS, voir [§5.5](#55-permissions-via-cta-metadata)) - Vérification finale côté backend à chaque appel **Comportement au clic** : 1. Récupération de **tous les presales** liés au PNR avec statut exécutable 2. Construction de la syntaxe cryptique Amadeus pour chaque presale (côté backend) 3. Ouverture de la **pop-up de confirmation Execute** (voir [§4.1](#41-pop-up-de-confirmation-execute)) qui affiche la commande complète 4. Sur confirmation, exécution séquentielle des commandes via Messager 5. Toast de retour : succès / erreur par presale #### Mode sélectif L'exécution sélective s'effectue depuis la **vue contextuelle Presales** dans l'onglet Presales du détail PNR (voir [§1.3](#13-vue-contextuelle-presales)). **Pas d'exécution sélective depuis cette zone d'actions principales.** --- ### 1.3 Vue contextuelle Presales **Localisation** : onglet `Presales` de la vue détail PNR. #### Structure Liste tabulaire des presales du PNR uniquement, avec : - Checkboxes par ligne (sélection multiple) - Colonnes : type (TST/EMD), passager, route, montant, statut, fare_basis présent (oui/non), actions ligne - Pagination intégrée si > 25 lignes #### Sélection multiple **Comportement** : - Checkbox dans l'en-tête : sélectionne/désélectionne toute la page - Checkbox par ligne : sélection individuelle - **Barre d'actions contextuelle** (sticky en haut de la liste) : - Apparaît dès qu'**au moins un presale est sélectionné** - Affiche le compteur : `3 presale(s) sélectionné(s)` - Boutons : `Exécuter la sélection` / `Désélectionner tout` - Disparaît quand la sélection retombe à 0 **Règle métier critique** : la sélection est limitée au PNR courant. Aucune sélection cross-PNR possible (par construction de la vue). #### Bouton "Exécuter la sélection" **Comportement** : 1. Vérification côté front : au moins un presale sélectionné 2. **Vérification dépendance EMD ↔ TST** : - Si un EMD sélectionné dépend d'un TST non sélectionné → afficher un avertissement bloquant : > *L'EMD #X dépend du TST #Y qui doit être exécuté en même temps. Voulez-vous l'ajouter à la sélection ?* - Boutons : `Ajouter le TST` (force l'inclusion) / `Annuler` 3. Construction de la commande cryptique Amadeus pour la sélection 4. Ouverture de la pop-up de confirmation Execute (voir [§4.1](#41-pop-up-de-confirmation-execute)) 5. Sur confirmation, exécution via Messager #### Indicateur fare_basis Colonne `Conditions tarifaires` dans la liste presales : - Icône verte ✓ si `fare_basis` existe sur ce presale - Icône grise ⏳ si `fare_basis` absent (Read PNR pas encore exécuté ou en cours) - Clic sur la cellule → ouvre la modal **Conditions tarifaires** (voir [§4.2](#42-visualisation-conditions-tarifaires)) --- ### 1.4 Triggers automatiques Ces actions sont déclenchées **côté backend** via Laravel Observers. Le frontend n'intervient pas dans le déclenchement, mais doit refléter visuellement les changements de statut. | Événement | Trigger backend | Reflet UI | |-----------|-----------------|-----------| | PNR créé via Load PNR | Aucun (attente fichier AIR) | Statut `En attente`, lignes grisées | | PNR mis à jour via fichier AIR | Réécriture `account_uuid` selon office ID | Statut → `À émettre`, données visibles, événement WS `pnr.air.received` | | PNR mis à jour via fichier AIR + presales sans fare_basis | Dispatch `ReadPnrJob` (graphique) | Indicateur ⏳ sur les presales concernés | | Read PNR retourne | Création `fare_basis` liés aux presales | Indicateur ✓ + accessibilité de la modal Conditions, événement WS `presale.fare_basis.created` | | Execute lancé | Modification statut PNR | Statut → `En cours`, animation badge | | Execute terminé (tous OK) | Création EDV + clone fare_basis | Statut → `Émis`, événement WS `pnr.execute.completed` | | Execute terminé (partiel) | Création partielle EDV | Statut → `Émission partielle` | | EDV créé avec presale ayant fare_basis | Clone des fare_basis du presale vers l'EDV | Indicateur ✓ sur l'EDV | | EDV créé avec presale sans fare_basis | Dispatch `ReadPnrJob` puis double association (presale + EDV) | Indicateur ⏳ puis ✓ | **Notification utilisateur** : - À l'arrivée d'un Read PNR retour, toast discret en bas à droite : *Conditions tarifaires mises à jour pour le PNR ABC123* - Pas de notification pour la réécriture de `account_uuid` (transparent pour l'utilisateur) --- ## 2. Module États de Vente ### 2.1 Vue Liste **Pas d'évolution** par rapport à la spec existante, **sauf** : - **Aucune action groupée** : retirer la barre d'actions contextuelle si elle existait - **Aucune checkbox de sélection multiple** sur les lignes - **Aucun bouton d'édition ou exécution en masse** > Toute action sur un EDV nécessite obligatoirement de naviguer vers la vue détail. ### 2.2 Vue Détail #### Zone d'actions principales **Logique d'affichage du CTA principal** : ```pseudocode si edv.date_emission == aujourd'hui (timezone agence) : afficher CTA "Void" (rouge) sinon : afficher CTA "Refund" (orange) ``` **Règle exclusive** : un seul CTA visible à la fois. Pas de menu déroulant ni de choix. #### CTA "Void" **Conditions d'affichage** : - `edv.date_emission == aujourd'hui` (date d'émission est la date courante en timezone agence) - `edv.status` permet le void (pas déjà voidé, pas déjà remboursé) **Permissions** : - Récupérées dynamiquement via les **metadata CTA** (Admin CHAPS, voir [§5.5](#55-permissions-via-cta-metadata)) - Le frontend ne connaît pas les rôles autorisés : il reçoit du backend la liste des CTAs disponibles pour l'EDV courant et l'utilisateur connecté **Comportement au clic** : 1. Ouverture de la pop-up de confirmation Execute (voir [§4.1](#41-pop-up-de-confirmation-execute)) 2. Affichage : - Intitulé : `Annulation du jour (Void)` - Détails de l'EDV (passager, billet/EMD, montant) - Mode de paiement : EasyPay (readonly, voir [§5](#5-logique-métier-et-règles-transverses)) - Commande cryptique Amadeus générée (avec syntaxe code IATA 172 conforme) 3. Sur confirmation, exécution via Messager 4. Toast de retour + rafraîchissement de la vue détail (statut EDV passe à `voided`) #### CTA "Refund" **Conditions d'affichage** : - `edv.date_emission != aujourd'hui` - `edv.status` permet le refund **Permissions** : - Récupérées dynamiquement via les **metadata CTA** (Admin CHAPS, voir [§5.5](#55-permissions-via-cta-metadata)) **Comportement au clic** : 1. Ouverture de la pop-up de confirmation Execute (voir [§4.1](#41-pop-up-de-confirmation-execute)) 2. Affichage spécifique Refund : - Intitulé : `Remboursement (Refund)` - Détails de l'EDV - **Détail des taxes refundables vs non-refundables** (voir bloc dédié ci-dessous) - Mode de paiement : EasyPay (readonly) - Commande cryptique Amadeus générée 3. Sur confirmation, exécution via Messager 4. Toast de retour + rafraîchissement de la vue détail ##### Bloc "Détail des taxes" dans la pop-up Refund Affichage tabulaire : | Code | Libellé | Montant | Refundable | |------|---------|---------|------------| | YQ | Carrier surcharge | 25.00 EUR | ✓ Oui | | YR | Carrier surcharge | 15.00 EUR | ✗ Non | | FR | Tax FR | 12.50 EUR | ✗ Non | | QX | Tax QX | 8.00 EUR | ✓ Oui | **⚠ Important — Logique YQ/YR** : la refundability des taxes YQ et YR n'est **pas** une règle blanket non-refundable. Elle dépend des **fare rules** retournées par le Read PNR (catégorie `refundable_taxes` dans `fare_basis.rule_categories`). Le frontend affiche **fidèlement** les valeurs `refundable: true|false` retournées par le backend, sans appliquer de logique métier propre. Un tooltip d'aide informe l'utilisateur : > *La refundabilité des taxes YQ/YR dépend des conditions tarifaires du billet (fare rules). Consultez le détail des conditions tarifaires pour plus d'informations.* Avec un lien `Voir conditions tarifaires` qui ouvre la modal correspondante (voir [§4.2](#42-visualisation-conditions-tarifaires)). **Total remboursé** affiché en bas du bloc : - `Total à rembourser : XX.XX EUR` (somme des montants refundables) - `Non remboursable : YY.YY EUR` (somme des montants non-refundables) --- ## 3. Module Accounts (rappel) > Cette section est un rappel des triggers automatiques liés aux comptes. La spec UI complète des Accounts reste celle du document principal. ### Trigger : Verify Office ID **Déclenchement** : - À la création d'un compte - À la mise à jour d'un compte si `verified_office_id` est vide **Action** : appel automatique vers Amadeus via Messager → Octopus pour vérifier l'office ID. Le résultat met à jour `account.verified_office_id`. **Reflet UI** dans la vue détail Account : - Champ `Office ID vérifié` : - Si `verified_office_id` rempli : badge vert ✓ + valeur affichée - Si `verified_office_id` vide et trigger en cours : badge orange ⏳ `Vérification en cours…` - Si `verified_office_id` vide et trigger échoué : badge rouge ✗ `Vérification échouée` + bouton `Relancer` **Bouton "Relancer la vérification"** : - Visible uniquement si statut = échec - Permissions : récupérées dynamiquement via les **metadata CTA** (Admin CHAPS, voir [§5.5](#55-permissions-via-cta-metadata)) - Au clic : redéclenche le trigger côté backend --- ## 4. Composants transverses ### 4.1 Pop-up de confirmation Execute **Composant réutilisable** : `` Utilisé pour **toutes** les actions GDS Amadeus déclenchées depuis le front : - Execute PNR global - Execute Presales sélectionnés - Void EDV - Refund EDV #### Structure ``` ┌─────────────────────────────────────────────────┐ │ [INTITULÉ DE L'ACTION] ✕ │ ├─────────────────────────────────────────────────┤ │ │ │ Description claire de ce qui va être exécuté │ │ (ex: "Émission de 2 TST et 1 EMD pour le PNR │ │ ABC123") │ │ │ │ ┌─ Détails ─────────────────────────────────┐ │ │ │ • Passager 1 : DUPONT JEAN — TST 3 │ │ │ │ • Passager 2 : DUPONT MARIE — TST 4 │ │ │ │ • EMD 5 lié au TST 3 │ │ │ └───────────────────────────────────────────┘ │ │ │ │ ┌─ Mode de paiement ────────────────────────┐ │ │ │ EasyPay [readonly]│ │ │ │ ⓘ Modification disponible en V2 │ │ │ └───────────────────────────────────────────┘ │ │ │ │ ┌─ Commande Amadeus générée ────────────────┐ │ │ │ TTP/T1 │ │ │ │ TTP/T2 │ │ │ │ EMDI/M5 │ │ │ │ │ │ │ │ [📋 Copier] │ │ │ └───────────────────────────────────────────┘ │ │ │ │ [Annuler] [Confirmer] │ └─────────────────────────────────────────────────┘ ``` #### Props du composant ```typescript interface ExecuteConfirmDialogProps { open: boolean; title: string; // Intitulé clair de l'action description: string; // Description courte items: ExecuteItem[]; // Liste des éléments à exécuter amadeusCommand: string; // Commande cryptique générée (multi-lignes possible) paymentMode: 'easypay' | 'cb'; // V1 : toujours 'easypay' paymentModeReadonly: boolean; // V1 : toujours true onConfirm: () => Promise; onCancel: () => void; loading?: boolean; } interface ExecuteItem { type: 'tst' | 'emd' | 'void' | 'refund'; label: string; // ex: "Passager 1 : DUPONT JEAN — TST 3" metadata?: Record; // Contexte additionnel } ``` #### Comportement - **Bouton `Confirmer`** : - Désactivé pendant l'exécution (loader) - Au succès : ferme la modal, toast vert - À l'échec : reste ouverte, affiche le message d'erreur - **Bouton `Annuler`** : ferme la modal sans action - **Bouton `Copier`** sur la commande : copie dans le presse-papier (utile pour debug ou exécution manuelle de secours) #### Mode de paiement EasyPay (V1) - Champ affiché en `readonly` avec valeur `EasyPay` - Helper text : *Modification du mode de paiement disponible dans une version future* - Pas de sélecteur, pas de modification possible - **V2 (roadmap)** : transformation en `