Flows métier

4 flows documentés en Mermaid : tout nouveau dev doit comprendre ces 4 parcours avant de toucher au code. Chacun est testé en E2E Playwright (sauf le sync PMS qui est testé en intégration).

Flow 1 — Check-in complet guest

Le flow phare. De l'email staff jusqu'à l'unlock de la PWA.

Transitions de statut

• pending (guest créé) → invited (email envoyé) → completed (digital done) → arrived (staff confirme) → checked_out (départ)

Points clés d'implémentation

1. Reacher avant envoi : si verdict invalid, blocker l'envoi et retourner une erreur UI explicite
2. BullMQ pour l'email : retries + DLQ
3. SSE pour l'unlock : pas de polling côté PWA
4. Bridge fire-and-forget : si Mews down, on continue — BullMQ retry automatique

Tests

• E2E Playwright : parcours complet depuis /dashboard/cardex jusqu'à / (PWA home)
• Intégration : cardex.service.test.ts valide chaque transition isolément

Flow 2 — Chat escalation vers ticket

Quand l'IA passe la main au staff, puis qu'un staff escalade vers un ticket.

Points clés

• Un seul modèle conversation (pas de dual système comme dans l'ancien projet), discriminé par audience (guest_ai / guest_staff / staff_internal)
• Streaming SSE pour l'IA, aussi pour les replies staff en temps réel
• Ticket garde le conversationId pour remonter l'historique

Flow 3 — Commande room service avec paiement

Points clés

• Stripe Payment Element inline (ADR-05 bis, pas décidé encore — on va documenter la décision dans un nouvel ADR)
• Webhook Stripe signé HMAC vérifié avant de faire confiance
• BullMQ pour tout ce qui est async : capture + bridge PMS + notifs
• State machine room_service_order : pending → preparing → delivering → delivered

Flow 4 — Sync Mews (daily + webhook)

Points clés

• Séparation: le cron enqueue, le worker exécute (jamais de sync lourde in-process Elysia)
• Idempotence : la sync peut tourner 10 fois de suite, elle upsert par (externalId, externalSource) — pas de dupe
• Batch guests : 1000 par appel Mews (limite API)
• Retry exponentiel : 3 tentatives avec 30s/1min/2min, DLQ ensuite
• Log de tout : chaque opération tracée dans integration_sync_log pour debug

Flow 5 — Cas d'édition staff : update room status

Points clés

• Validation state machine avant écriture DB (ADR-05)
• Bridge PMS non bloquant : si Mews down, Bell a déjà mis à jour sa propre DB, on continue
• DLQ → alerte ops : quand un bridge échoue définitivement, ops HOAIY reçoit un email

Flow 6 — Onboarding d'un nouvel hôtel (admin HOAIY)

Séquence simplifiée, plus de détails dans operations/onboarding-hotel.

Lien avec les autres pages

• Vision
• Acteurs
• Spec
• State machines
• API design