Spécification fonctionnelle

Les quoi du produit, module par module. Pour le comment technique, voir core/api/ et les services dédiés. Pour les décisions structurantes, voir decisions/.

Module 1 — Check-in digital

Côté staff (`bell-staff.hoaiy.com/dashboard/cardex`)

Liste des guests (aujourd'hui, à venir, groupes, VIP, en séjour)
Création manuelle d'un guest (si pas de PMS ou onboarding express)
Sync automatique depuis Mews : les réservations des 60 prochains jours apparaissent
Bouton "Envoyer check-in email" → déclenche Reacher + envoi SMTP → statut invited
Bouton "Confirmer arrivée" → passe à arrived + bridge PMS + SSE unlock PWA
Bouton "Déclencher checkout" → passe à checked_out + room → cleaning + bridge PMS
Badges : VIP, canal (Booking/Expedia/...), statut check-in, groupe
Bulk actions : toggle VIP sur sélection, delete, envoi batch d'emails

Côté guest (PWA)

Email reçu : lien unique, valide 30 jours. Template avec logo hôtel, détails séjour.
Fast check-in : formulaire (prénom, nom, email verrouillé, téléphone, date de naissance, consentement marketing)
Création compte : password + signup Better Auth → lie guest.userId automatiquement
Confirmation : écran succès + preview IA concierge
Upsells : 6 produits max (cocktails, chocolats, fleurs, massages, champagne, ...), grille 2×3, quantité via pill AddButton
Paiement : Stripe Payment Element inline (carte + Apple Pay + Google Pay), frais service 1 %
Waiting page : "À très vite" tant que staff n'a pas confirmé physiquement
Unlock : SSE push dès confirmation staff → PWA home

Module 2 — Concierge IA

Côté guest

Bouton de chat accessible depuis toutes les pages PWA
Premier message → l'IA se présente, connaît le prénom + chambre + hôtel
L'IA peut :
- Répondre aux questions générales (horaires spa, menu petit-déj, WiFi)
- Exécuter des actions via tools : créer une commande room service, booker un spa, confirmer une réservation restaurant
- Escalader vers le staff si elle ne peut pas (ou si le guest demande un humain)
Streaming SSE des réponses (typing indicator natif)
Historique persistant : les conversations restent visibles pendant tout le séjour

Côté staff

Liste des chats actifs dans /dashboard/chats
Filtres : résolus/non-résolus, priorité, service
Détail chat : timeline messages, assignation staff, changement priorité, marquer résolu
Escalade vers ticket en un clic si plainte/demande spéciale
Réponse en temps réel : le guest voit ma réponse via SSE

Architecture

Audience guest_ai : défaut, IA répond
Audience guest_staff : après escalade, staff prend la main, IA silencieuse
Audience staff_internal : notes staff sur un guest (pas visible guest)

Voir Intelligence.

Module 3 — Services (room service, spa, laundry, restaurant)

Pattern commun

Guest parcourt le menu dans la PWA
Ajoute items au panier (pattern AddButton)
Checkout → Payment Element → confirmation
Dashboard staff reçoit la commande en temps réel
Staff change le statut au fil de l'exécution (preparing → delivering → delivered)
Guest voit l'état dans le drawer PWA en temps réel (SSE)

Room service

Menu petit-déjeuner / lunch / dinner / drinks (catégorisé)
Options par item (cuisson, accompagnements)
Allergens visibles (JSONB : ["gluten", "milk"])
Delivery fee + service fee 1 %
Adresse livraison = room du guest (auto)

Spa

Liste des soins avec durée + prix
Sélection date + heure + thérapeute (optionnel)
Confirmation immédiate ou requested selon dispo (staff confirme)

Laundry

Liste d'items (chemise, costume, etc.) avec prix unitaire
Special request texte libre
Collection dans la chambre, délai 24h standard

Restaurant

Booking réservation : date, heure, nombre de convives, special request
Pas de paiement pré-compte (paiement à table ou room charge via PMS)

Module 4 — Cardex staff

Le cardex Bell remplace (ou complète) celui du PMS pour la gestion guest au quotidien. Vue en grille avec 4 onglets : All / VIP / Groups / Staying.

Features

Recherche : nom, email, chambre, groupe
Filtres : statut check-in, canal, VIP, groupe
Card guest (individuel) : avatar, nom, email, chambre, dates, badges
Card groupe : contact person, nb members, dates groupe
Selection multi : toggle VIP, delete, email batch (checkbox)
Modal création : create guest manuellement
Modal édition : update guest data
Double-clic groupe → page détail avec les membres

Intégration PMS

Si l'org a Mews configuré :

Sync quotidienne 4h du matin via @elysiajs/cron → enqueue jobs BullMQ
Webhooks Mews (ServiceOrderUpdated, CustomerAdded, ...) → process immédiat
Canal détecté automatiquement (voir inferChannel() dans l'adapter)

Module 5 — Today / Staff notes

Permet au staff de laisser des notes du shift (check-list, incidents, VIP arrivant) visibles par le shift suivant.

Note = titre + contenu + service_type + priority + assigné à + due_date
Status pending → in_progress → done
Comments pour audit trail ("Jean a modifié la priorité à 'urgent'")
Filtre par status, priorité, recherche
Modal création avec service_type (restaurant / spa / housekeeping / room_service / ...)

Module 6 — Tickets (escalade)

Pour les incidents plus lourds que ce qu'un chat ou une staff_note peut résoudre.

Créé depuis un chat ("escalader vers ticket") ou manuellement
Numéro humain lisible : TKT-00042 (séquence par org)
Catégorie : plainte, demande spéciale, maintenance, housekeeping, billing, concierge
Priorité : low / medium / high / urgent
Status : open → in_progress → waiting → resolved → closed
Assignation staff, comments internes, lien vers conversation d'origine
Admin HOAIY voit les tickets escaladés cross-hôtels si category = billing

Module 7 — Rooms

Inventaire de l'hôtel
Status : available / occupied / cleaning / maintenance / reserved
Type : single / double / suite / deluxe / penthouse
Prix/nuit, capacité, amenities JSONB
Sync Mews : room.status change automatiquement sur webhook ResourceUpdated
Staff peut override manuellement (edit modal)
Stats : total, occupés, taux d'occupation, chambres maintenance

Module 8 — Analytics

Dashboards staff/manager pour piloter l'activité.

Widgets

Interactions : chats/jour, tendance 7j/4w
Conversion : % chats → bookings, funnel
Time saved : minutes économisées par l'IA (vs appels staff)
Requests : breakdown par service (donut)
Satisfaction : % réactions positives sur les réponses IA et staff
Upsells : revenus générés par les upsells pré-arrivée + in-stay
Activity : heatmap horaire (quand les guests sollicitent)

Vue admin

Admin HOAIY voit des dashboards cross-org : total propriétés, revenus cumulés, churn, usage IA.

Module 9 — Calendar

Vue calendrier mensuelle pour le manager : arrivées, départs, events hôtel (conférences, mariages), séjours en cours.

Configuration des items proposés par l'hôtel au guest :

Catégories (breakfast, lunch, dinner, drinks, room_service, spa, laundry, restaurant)
Items avec prix, description, image, option groups, allergens
Featured items mis en avant sur la home PWA
Activation/désactivation d'items (ex: plat du jour épuisé)

Module 11 — Admin : System

Scope owner/admin HOAIY uniquement.

Settings

General : nom hôtel, email, adresse, téléphone, site web, logo, fuseau, devise
AI Assistant : temperature, playground test, quotas d'utilisation
Integrations : liste PMS configurés, logs sync, webhooks, test de connexion
Users : liste staff + invite + révoquer + changer rôle
Billing : plan actif, factures Stripe, quota utilisateurs, quota guests
Privacy : cookies policy, data retention par type d'entité

Module 12 — Admin : Guests, Rooms, Organizations

Vues transverses pour admin :

Guests : liste consolidée (avec soft-deleted visibles), édition profil
Rooms : CRUD inventory, import CSV, mass update
Organizations : portfolio multi-hôtels, switch d'org active, create org

Flows clés

Voir Flows pour les diagrammes mermaid complets des parcours :

Check-in complet guest
Chat escalation vers ticket
Commande room service avec paiement
Sync Mews → bridge PMS → webhook

Ce qu'on ne fait PAS (volontairement)

Pas de channel management OTA direct (Booking, Expedia API) — on passe par le PMS qui agrège
Pas de PMS complet — on est la couche guest-facing, le PMS reste maître du rooming/yield
Pas de housekeeping dispatch avancé — room status bidirectionnel suffisant, pas de tablet housekeeper dédié
Pas de facturation hôtel complexe — on charge les upsells Bell via Stripe ou via PMS room charge, pas de factures B2C compliquées
Pas de gestion multi-langue guest au MVP — FR/EN templates emails, interface FR

Tout ça est à reconsidérer après MVP selon les demandes clients.