Onboarding hôtel

Durée cible : 2-4 heures de config, 1-2 jours de vérifications. Le playbook ci-dessous est la marche à suivre standard de l'équipe onboarding HOAIY.

Checklist rapide

• Créer l'organization
• Inviter le owner (GM de l'hôtel)
• Remplir les infos hôtel (nom, adresse, devise, fuseau)
• Remplir le champ aiContext pour le concierge IA
• Configurer l'intégration PMS (Mews en priorité)
• Tester la connexion + full sync initial
• Configurer les webhooks Mews côté Mews (manuel dans leur dashboard)
• Inviter les staff (réception + managers)
• Uploader le menu (catégories + items)
• Configurer le branding (logo, couleurs primaires si custom)
• Tester le flow check-in avec un vrai guest de test
• Premier vrai check-in avec un guest client

Étape 1 — Créer l'organization

Accès : admin HOAIY via bell-staff.hoaiy.com/admin/organizations.

Name        : Hôtel Oceania Paris Porte de Versailles
Slug        : oceania-paris
Metadata    :
  address   : 52 rue d'Oradour-sur-Glane, 75015 Paris
  timezone  : Europe/Paris
  currency  : EUR
  locale    : fr-FR

La création génère un organizationId UUID. Notez-le, vous en aurez besoin pour les étapes suivantes.

Étape 2 — Inviter le owner

Admin HOAIY clique "Invite owner" → formulaire :

Email : gm@oceania-paris.com
Role  : owner

Better Auth envoie un email d'invitation au GM. Le GM clique le lien, fait son signup, devient automatiquement member avec role owner de l'org.

Étape 3 — Infos hôtel

Le GM (ou admin HOAIY en son nom) complète via bell-staff.hoaiy.com/admin/system/general :

Étape 4 — Contexte IA

Étape critique pour que le concierge IA soit bon. Dans /admin/system/ai :

AI Context (markdown accepté) :

# Hôtel Oceania Paris Porte de Versailles

## Horaires

- Réception : 24h/24
- Petit-déjeuner : 6h30 - 10h30 (buffet) / 10h30 - 12h en chambre
- Bar : 17h - 2h
- Restaurant : 19h - 22h30
- Spa : 10h - 21h (sur réservation)
- Room service : 24h/24

## Pratique

- WiFi : "Oceania-Guest", password "Welcome2026"
- Piscine : non
- Parking : 24 €/nuit, sous-sol 2 accessible par badge
- Animaux : acceptés (20 €/nuit), pas dans les zones de restauration
- Fumeurs : toutes chambres non-fumeurs, terrasses autorisées

## Spécialités

- Chef Pierre Lacombe étoilé depuis 2022
- Menu dégustation 7 plats : 145 €
- Carte des vins 200 références
- Cuisine méditerranéenne revisitée

## À ne JAMAIS faire

- Ne propose jamais de remboursement, de geste commercial, de voucher
- Ne prends jamais d'engagement sur les disponibilités sans confirmer via tools
- Si le guest se plaint (chambre, service, bruit), ESCALADE vers le staff

C'est le GM qui le maintient à jour. Le contenu est injecté dans le system prompt à chaque conversation (voir AI architecture).

Étape 5 — Intégration Mews

Pré-requis côté Mews

Le GM (ou admin HOAIY) doit obtenir auprès de Mews :

• Client Token : identifie l'app Bell
• Access Token : identifie la propriété (l'hôtel)
• Platform URL : https://api.mews-demo.com (sandbox) ou https://api.mews.com (prod)

Pour un hôtel nouveau sur Mews : Mews doit créer l'intégration "Bell by HOAIY" dans son dashboard. Demande à faire par email à integrations@mews.com avec :

• Nom de l'hôtel client
• Nos deux tokens (que Mews connaît)
• Capabilities nécessaires (toutes : rooms, guests, reservations, orders, webhooks)

Délai habituel : 3-5 jours ouvrés pour que Mews active l'accès Connector complet (sinon on n'a que les Integration Webhooks, insuffisant).

Config dans Bell

Dans /admin/system/integrations :

Provider       : Mews
Name           : Mews - Oceania Paris
Client Token   : ****** (collé, chiffré en DB)
Access Token   : ****** (collé, chiffré en DB)
Platform URL   : https://api.mews-demo.com

Clic "Test connection" → Bell appelle configuration/get → retourne le nom de la propriété. Si le nom correspond, valider.

Full sync initial

Clic "Run full sync". Ça enqueue un job BullMQ qui :

1. getRooms() → upsert toutes les chambres
2. getReservations({ states: ["confirmed", "checked_in"] }) → sur 60 jours
3. Batch getGuests(ids) par chunks de 1000 → upsert tous les guests mentionnés

Durée : 30 secondes à 5 minutes selon la taille de l'hôtel. Logs visibles dans /admin/system/integrations/<id>/logs.

Webhooks Mews

À configurer manuellement côté Mews (leur dashboard), pas automatisé :

Endpoint : https://bell-api.hoaiy.com/webhooks/mews Events à activer :

• ReservationCreated
• ReservationUpdated
• ReservationStateChanged
• CustomerUpdated
• ResourceUpdated (room status)
• ServiceOrderUpdated

Secret : généré par Bell à la config (affiché une seule fois, visible ensuite masqué dans /admin/system/integrations). Le GM colle ce secret dans Mews.

Test : créer une réservation dans Mews sandbox → vérifier le log d'ingestion Bell dans les 10 secondes.

Hôtel sans PMS

Skipper cette étape. Bell fonctionne, les guests sont créés manuellement dans le cardex.

Étape 6 — Inviter les staff

Dans /admin/users :

Emails     : reception1@oceania-paris.com, reception2@oceania-paris.com
Role       : staff
Send      : invitation emails

Ou via CSV bulk import (à implémenter MVP+).

Le GM (en role owner) peut aussi déléguer à un manager (head of reception) qui a le droit d'inviter des staff.

Étape 7 — Uploader le menu

Dans /admin/menu-manager :

Create category "Petit-déjeuner" (type: breakfast)
  - Add item : "Petit-déjeuner continental" - 28 € - "Café ou thé, viennoiseries, pain, beurre, confiture, jus d'orange"
  - Add item : "Œufs brouillés au saumon" - 18 €
  ...

Create category "Room Service" (type: room_service)
  - Add item : "Club sandwich poulet" - 24 €
  - Add item : "Burger maison" - 28 €
  ...

Create category "Soins Spa" (type: spa)
  - Add item : "Massage signature 55 min" - 150 € - duration: 55
  - Add item : "Massage 80 min" - 210 € - duration: 80
  ...

Option : CSV import pour les gros menus (20+ items). Template dispo dans /admin/menu-manager/import.

Les items peuvent être is_featured: true → apparaissent mis en avant dans la PWA home guest.

Étape 8 — Branding (optionnel)

Dans /admin/system/branding :

• Logo (PNG transparent, 512×512 recommandé) → inlined dans les emails et affiché dans la PWA
• Couleur primaire (hex) → si custom, override le orange Bell par défaut dans la PWA de cet hôtel
• Domaine custom (ex: bell.oceania-paris.com au lieu de bell-app.hoaiy.com) — MVP+ (CNAME + cert Let's Encrypt via Traefik auto)

Par défaut les hôtels utilisent le branding Bell (logo HOAIY + orange). Option premium pour la gamme Enterprise.

Étape 9 — Test du flow check-in

Guest de test

1. Créer manuellement un guest dans /dashboard/cardex :

   First name : Test
   Last name  : HOAIY
   Email      : test-onboarding@hoaiy.com
   Phone      : +33 6 00 00 00 00

2. Cliquer "Envoyer check-in email"
3. Ouvrir l'email (Gmail test-onboarding@hoaiy.com)
4. Cliquer le lien → PWA ouvre sur /auth/fast-check-in?email=...
5. Compléter le formulaire → créer un password
6. Remplir upsells (tester avec un cocktail par exemple)
7. Payer avec carte test Stripe 4242 4242 4242 4242
8. Arrive sur /auth/waiting avec "À très vite"
9. Dashboard staff : cliquer "Confirmer arrivée"
10. PWA auto-déblocked via SSE

Vérifications

• DB : guest.check_in_status = "arrived", room.status = "occupied"
• Mews : réservation marquée "checked_in" (bridge PMS)
• Mews : order créée pour le cocktail (bridge post-charges)
• PWA guest : arrive sur la home, peut ouvrir le chat, commander room service
• Dashboard staff : voir la commande en temps réel

Étape 10 — Premier vrai check-in

Coordonner avec le GM :

• Un guest qui arrive demain (on veut tester en conditions réelles, pas sous stress)
• Staff briefé : attendre le click "Confirmer arrivée" côté dashboard quand le guest se présente à la réception
• HOAIY disponible en support pendant les 24h suivantes pour dépanner

Ce qu'on surveille pendant la première semaine

Via Signoz dashboards :

• Error rate > baseline ? → bug potentiel spécifique à cet hôtel
• Latence p95 sync Mews ? → il se peut que cet hôtel ait beaucoup de données (grand hôtel)
• Queues BullMQ qui backup ? → scale workers ou investiguer

Runbook si ça casse

Email check-in ne part pas

1. Vérifier /admin/system/integrations/<id>/logs — des erreurs Reacher ?
2. Vérifier queue email dans Bull Board (bell-api.hoaiy.com/admin/queues)
3. Si DLQ : consulter le job failed, voir l'erreur exacte
4. Vérifier quota Gmail Workspace (seuil 500/jour)

Mews sync fail

1. /admin/system/integrations/<id>/logs — dernière erreur
2. Si 401/403 : credentials Mews expirés → renouveler
3. Si 429 : rate limit, Mews rate-limite à ~60 req/min → réduire concurrency worker
4. Si 5xx : Mews down (status.mews.com)

Webhooks Mews pas reçus

1. Vérifier côté Mews dashboard : l'endpoint est bien https://bell-api.hoaiy.com/webhooks/mews
2. Vérifier le secret : côté Mews === côté Bell (chiffré en DB mais visible une fois à la config)
3. Trigger un event manuel dans Mews (ex: update une résa) → voir logs Bell ingestion
4. Si aucun log : DNS ou Traefik bloque ? Utiliser ngrok en dev pour tester

Bridge PMS échoue

1. Bull Board → queue pms-bridge → jobs failed
2. Retry manuel
3. Si ça persiste : logs Signoz → span job.check-in → voir l'erreur exacte Mews
4. Si Mews retourne "reservation not found" : la réservation a peut-être été annulée côté Mews entre le sync et le bridge

Durée totale onboarding

Total standard : 3-4 heures actives, 1-2 jours d'attente si Mews est à activer.

Documents remis au client

À l'issue de l'onboarding, HOAIY envoie au GM :

• DPA (Data Processing Agreement) signé
• Guide rapide staff (PDF, 2 pages) : comment utiliser le cardex, les chats, les actions quotidiennes
• Accès au /docs interne (bell-docs.hoaiy.com avec compte staff)
• Contact support : support@hoaiy.com, Slack dédié si plan Enterprise

Lien

• Auth
• Intégration Mews
• AI architecture (aiContext)
• Monitoring