Acteurs

4 acteurs humains (guest, staff réceptionniste, manager, admin HOAIY) + 3 acteurs systèmes (IA concierge, PMS, Stripe). Chacun a un périmètre clair d'actions et de visibilité.

Vue d'ensemble

Acteurs humains

1. Guest

C'est qui : un invité de l'hôtel, français ou étranger, qui a fait une réservation via le canal X (Booking, Expedia, direct, etc.) et qui reçoit un email de pré-check-in la veille de son arrivée.

Son parcours type :

1. Reçoit l'email Bell (depuis noreply@hoaiy.com, de la part de l'hôtel)
2. Clique le lien → arrive sur la PWA avec pré-remplissage des données
3. Remplit formulaire (identité, paiement, optionnellement upsells)
4. Reçoit confirmation "À très vite"
5. Arrive à l'hôtel — staff confirme son arrivée physique → PWA débloquée
6. Pendant le séjour : commande room service, spa, laundry, chat avec concierge IA
7. Checkout → PWA verrouillée à nouveau

Ce qu'il voit : sa propre expérience uniquement. Aucune visibilité sur les autres guests de l'hôtel ou sur le staff.

Role DB : member.role = 'guest'.

2. Staff (réceptionniste, serveur, housekeeping)

C'est qui : l'employé de l'hôtel qui traite les guests au quotidien. Peut être multi-casquette dans les petits hôtels (réceptionniste + bar).

Son quotidien :

1. Se connecte au dashboard bell-staff.hoaiy.com
2. Consulte le cardex du jour (arrivées, séjours en cours, départs)
3. Envoie les emails de check-in aux prochaines arrivées
4. Confirme l'arrivée physique des guests
5. Traite les chats entrants (guest demande quelque chose)
6. Marque les commandes room service / laundry comme delivered
7. Escalade vers un ticket si besoin d'un manager
8. Fin de journée : notes "Today" pour le shift suivant

Ce qu'il voit : toutes les données de son organisation (hôtel). Pas d'accès aux autres hôtels du portfolio HOAIY.

Role DB : member.role = 'staff'.

3. Manager / GM (General Manager)

C'est qui : le directeur de l'hôtel ou un chef de service (F&B manager, head of spa).

Son quotidien :

• Tout ce que fait un staff, plus :
• Analytics : occupation, RevPAR, revenus par canal, conversion, satisfaction
• Invite de nouveaux staff dans son org
• Modifie les catégories de menu et les prix
• Décide des priorités sur les tickets escaladés
• Configure les paramètres hôtel (nom, horaires, upsells proposés)

Ce qu'il voit : toutes les données de son org + les analytics agrégées.

Role DB : member.role = 'manager'.

4. Admin HOAIY

C'est qui : l'équipe HOAIY qui configure et maintient la plateforme pour tous les hôtels clients.

Son quotidien :

• Onboarde un nouvel hôtel (créer org, configurer domaine si custom, inviter owner)
• Configure les intégrations PMS (tester la connexion, faire le full sync initial)
• Débugue les intégrations quand un webhook échoue
• Consulte la doc Signoz pour l'observabilité cross-hôtels
• Gère la facturation (qui paie quoi, plan Free/Pro/Enterprise)
• Support niveau 2 (quand un GM ne sait pas pourquoi son Mews sync a cassé)

Ce qu'il voit : toutes les organisations (contrairement aux autres acteurs qui sont scopés à leur org), plus les dashboards techniques (queues BullMQ, logs Signoz, facturation Stripe).

Role DB : member.role = 'admin' sur une organisation dédiée "HOAIY HQ" (pas de role "superadmin" cross-org — on utilise une org admin spéciale dont l'équipe HOAIY est membre, avec des procedures dédiées qui bypassent le scoping).

5. Owner (fondateur HOAIY, CEO hôtel client)

C'est qui : niveau au-dessus de admin. Peut désactiver une org, changer le plan de facturation, transférer la propriété.

Role DB : member.role = 'owner'.

Acteurs systèmes

6. IA Concierge (Azure OpenAI)

C'est qui : un LLM (GPT-4 classe) branché via @elysiajs/ai-sdk qui répond aux guests en 24/7.

Son rôle :

• Premier niveau de support pour toutes les demandes guest (chat PWA)
• Appelle des tools pour agir : create_room_service_order, book_spa, get_hotel_info, escalate_to_staff
• Génère des titres et résumés de conversations pour le cardex
• Passe la main au staff quand la demande sort de son périmètre (audience passe de guest_ai à guest_staff)

Ce qu'il voit : le profil du guest courant (nom, room, dates), les menus de l'hôtel, les FAQ configurées par le staff. Pas les autres guests, pas les données staff.

7. PMS (Mews, Opera, Cloudbeds, …)

C'est qui : le système de gestion hôtelière du client. Optionnel mais ultra-répandu.

Son rôle :

• Source des données (rooms, guests, réservations) via full sync quotidien + webhooks
• Destination des mises à jour Bell (check-in, check-out, post charges, room status) via bridges
• Agrège les canaux (Booking, Expedia, Airbnb, ...) qu'on lit via le champ CommanderOrigin

Bell est master : si le PMS est down 24h, Bell continue à fonctionner, on rattrape la sync quand il revient.

8. Stripe

C'est qui : la passerelle de paiement.

Son rôle :

• Héberge le Payment Element inline intégré dans la PWA
• Envoie des webhooks signés HMAC pour confirmer les paiements
• Gère les refunds quand une commande est annulée

Alternative envisagée : Stripe Checkout redirect. Rejeté — on veut garder le guest dans le flow app.

Permissions synthétiques

Implémenté via protectedProcedure, staffProcedure, managerProcedure, adminProcedure, ownerProcedure dans les middlewares Elysia.

Prochaine étape

• Spec fonctionnelle — détail des modules et features
• Flows — parcours critiques en diagrammes