1. Décision produit recommandée Il ne faut pas choisir exclusivement entre le parcours HotelRunner et celui de Reservit. La meilleure approche est un parcours hybride. Entrée principale : dates d’abord Sur la page d’accueil ou dans le widget intégré au site de l’hôtel : arrivée ; départ ; nombre de chambres ; adultes ; enfants et âges ; code promotionnel éventuel ; bouton « Voir les disponibilités ». C’est le parcours le plus naturel, car la disponibilité réelle, le prix et les restrictions dépendent des dates et de l’occupation. Résultats : chambres d’abord Après la recherche, l’utilisateur voit : les types de chambres disponibles ; les photographies ; les caractéristiques principales ; la capacité ; les équipements ; les conditions d’annulation ; les plans tarifaires ; le prix total du séjour ; les taxes et frais ; les avantages de la réservation directe ; le nombre de chambres restantes ; un comparateur entre les offres ; un bouton de sélection très visible. Parcours secondaire : chambre d’abord Depuis une page de chambre du site principal, le bouton « Réserver cette chambre » ouvre le moteur avec : la chambre déjà sélectionnée ; un calendrier montrant les dates disponibles ; les tarifs à partir de ; la possibilité de modifier les dates et l’occupation. On obtient ainsi le meilleur des deux approches : dates d’abord depuis la page générale ; chambre d’abord depuis une fiche de chambre ; conservation des paramètres dans l’URL ; liens profonds utilisables dans les campagnes publicitaires ; widget intégrable au site de l’hôtel ; expérience adaptée aux téléphones. 2. Ce que la plateforme doit devenir reservation.energiedin.ma ne sera pas seulement un formulaire de réservation. Le plan prévoit quatre composants réunis dans une même application. Moteur de réservation directe Il comprend : recherche de disponibilités ; sélection de plusieurs chambres ; plans tarifaires ; promotions et codes promotionnels ; suppléments et services ; panier ; blocage temporaire du stock ; paiement ou garantie ; confirmation ; modification ou annulation selon les conditions ; e-mails transactionnels ; interface arabe, française et anglaise ; devise MAD et devises d’affichage supplémentaires. Mini-PMS et back-office Le personnel pourra gérer : le planning ; les arrivées et départs ; les réservations ; les clients ; les chambres ; les types de chambres ; les tarifs ; les restrictions ; les promotions ; les paiements ; les annulations ; les notes internes ; l’historique des opérations ; les réservations directes et OTA depuis le même écran. Noyau de channel manager Il sera chargé de : pousser les prix vers les plateformes ; pousser les disponibilités ; pousser les restrictions ; importer les nouvelles réservations ; importer les modifications ; importer les annulations ; rapprocher les chambres et plans tarifaires ; suivre l’état de chaque canal ; relancer les synchronisations échouées ; éviter les doublons ; limiter le risque de surbooking. Couche d’intégration Elle permettra de remplacer un fournisseur sans refaire l’application : Application métier ↓ Modèle canonique de distribution ↓ Interface ChannelConnector ↓ ├── BookingDirectConnector ├── ExpediaDirectConnector ├── CertifiedGatewayConnector ├── AirbnbConnector ├── HotelbedsConnector └── FutureConnector 3. Point critique : la connexion directe aux OTA Il faut distinguer deux notions : être techniquement préparé pour Booking.com et Expedia ; être commercialement et techniquement autorisé à utiliser leurs API de production. Booking.com impose un processus d’intégration pour ses Connectivity Partners, des fonctionnalités minimales, des tests et des conditions de certification. Ses API couvrent notamment les prix, disponibilités, restrictions et réservations, mais les établissements doivent également autoriser explicitement le fournisseur de connectivité. Expedia demande également l’inscription comme partenaire de connectivité, l’obtention d’identifiants, le respect de prérequis techniques et, lorsqu’il y a traitement de données de carte, des exigences PCI et TLS. Expedia a aussi fait évoluer ses interfaces de gestion des réservations vers une API GraphQL avec environnement de test et processus de certification. La plateforme ne pourra donc pas honnêtement être déclarée « connectée directement à Booking.com et Expedia » avant l’obtention des accès et la certification. Stratégie retenue Le plan prévoit deux voies parallèles. Voie A — Mise sur le marché par une passerelle certifiée Une passerelle de channel management en marque blanche fournit rapidement les connexions aux OTA. Par exemple, Channex propose une API unifiée, des webhooks, une offre white-label et des connexions annoncées avec Booking.com, Expedia, Airbnb et d’autres canaux. Le fournisseur devra néanmoins être comparé contractuellement à d’autres solutions avant adoption définitive. Avantages : commercialisation plus rapide ; API homogène ; moins de certifications initiales ; Booking.com et Expedia disponibles à travers un partenaire existant ; développement du moteur de réservation indépendant des contraintes OTA. Voie B — Connecteurs directs En parallèle : candidature au programme Booking.com Connectivity Partner ; candidature au programme Expedia Connectivity Partner ; développement dans leurs environnements de test ; certification ; activation progressive des établissements ; remplacement éventuel de la passerelle canal par canal. La même interface interne sera utilisée dans les deux cas. Le reste de l’application ne saura pas si Booking.com est connecté directement ou par un intermédiaire. 4. Architecture technique retenue Monolithe modulaire Pour un hébergement sous WHM/cPanel, le choix recommandé est un monolithe modulaire, et non des microservices. Cela signifie : une seule application déployable ; une seule base métier ; des modules internes bien séparés ; des workers asynchrones ; une API propre ; la possibilité d’extraire un service plus tard sans complexifier prématurément le projet. Les microservices ajouteraient immédiatement : plusieurs déploiements ; plusieurs bases ou files ; des problèmes de cohérence distribuée ; davantage de supervision ; des coûts d’exploitation disproportionnés. Stack proposée Backend Laravel 13 PHP 8.4 MySQL 8 ou MariaDB compatible Redis ou Valkey files de travaux Laravel scheduler Laravel webhooks signés API REST versionnée tests PHPUnit ou Pest Laravel 13 est compatible avec PHP 8.3 à 8.5. Son starter kit React officiel repose sur Inertia, React, TypeScript, Tailwind CSS et les composants shadcn/ui, ce qui convient à une interface moderne sans imposer un serveur Node permanent en production. Frontend React 19 ; TypeScript strict ; Inertia ; Tailwind CSS ; shadcn/ui ; Vite ; composants accessibles ; interface responsive ; prise en charge RTL pour l’arabe ; design system interne ; calendrier optimisé pour mobile ; skeleton loaders ; transitions discrètes ; récapitulatif du séjour toujours accessible. Production Node.js ne servira qu’à compiler les ressources avec Vite. Le site public sera servi par Apache ou LiteSpeed via PHP-FPM, ce qui est beaucoup plus compatible avec cPanel qu’un processus Next.js permanent. 5. Modules applicatifs Le plan prévoit notamment les modules suivants : Identity Organizations Properties UsersAndRoles HotelCatalog Rooms Guests Inventory Rates Availability Promotions Extras Reservations Payments Distribution ChannelMappings Notifications Reports Audit Settings Localization Observability Chaque module aura : ses services métier ; ses modèles ; ses politiques d’autorisation ; ses événements ; ses commandes ; ses tests ; ses interfaces ; un périmètre clairement défini. Le code de synchronisation ne sera pas mélangé aux contrôleurs du moteur de réservation. 6. Modèle de données principal Le modèle prévoit notamment : Organisation et établissements organizations properties property_settings users roles permissions property_user Même en commençant avec un seul hôtel, les données seront structurées pour accueillir plusieurs établissements. Catalogue hôtelier room_types physical_rooms room_type_images amenities room_type_amenity occupancy_rules bed_configurations extras Il faut séparer : le type de chambre vendu, par exemple « Suite Junior » ; la chambre physique, par exemple « Suite 204 ». Les OTA vendent généralement un inventaire au niveau du type de chambre, tandis que le PMS peut affecter une chambre physique plus tard. Prix et inventaire rate_plans rate_plan_room_types daily_rates daily_inventory restrictions inventory_ledger availability_snapshots promotions promotion_rules taxes fees Réservations reservations reservation_rooms reservation_guests reservation_nights reservation_extras reservation_status_history reservation_holds reservation_notes reservation_sources Paiements payment_intents payments refunds payment_webhook_events payment_methods payment_transactions Distribution channels channel_connections channel_room_mappings channel_rate_plan_mappings channel_reservation_mappings channel_sync_jobs channel_sync_attempts channel_webhook_events outbox_messages inbox_messages dead_letter_messages reconciliation_runs 7. Moteur d’inventaire et prévention du surbooking La partie la plus importante du système n’est pas l’apparence du calendrier. C’est la cohérence de l’inventaire. Source unique de vérité L’inventaire interne sera la source métier de référence : stock vendable – chambres confirmées – chambres temporairement bloquées – chambres hors service – éventuel stock de sécurité = disponibilité à distribuer Blocage temporaire Lorsqu’un client commence le checkout : le serveur revalide la disponibilité ; il ouvre une transaction ; il verrouille les lignes de stock concernées ; il crée un hold temporaire ; il décrémente la disponibilité vendable ; il fixe une expiration ; il libère le stock en cas d’abandon ou d’échec de paiement. Un simple panier conservé dans le navigateur ne suffit pas. Protection contre la concurrence Le plan prévoit : transactions SQL ; verrouillage pessimiste des lignes critiques ; clés d’idempotence ; contraintes uniques ; recalcul serveur avant confirmation ; expiration atomique des holds ; tests lançant plusieurs réservations simultanées sur le dernier stock disponible. 8. Architecture de synchronisation OTA Modèle canonique Booking.com, Expedia et les autres canaux n’utilisent pas exactement les mêmes concepts. L’application utilisera donc un modèle commun comprenant : établissement ; type de chambre ; plan tarifaire ; occupation ; date ; stock ; prix ; minimum de séjour ; maximum de séjour ; fermeture à l’arrivée ; fermeture au départ ; stop-sell ; politique d’annulation ; réservation ; modification ; annulation. Chaque connecteur traduira ce modèle dans le format de son canal. Flux sortant Lorsqu’un tarif ou un stock change : la modification est écrite en base ; un événement est ajouté à l’outbox dans la même transaction ; un worker récupère l’événement ; les messages proches sont regroupés ; le connecteur envoie la mise à jour ; l’accusé de réception est enregistré ; la santé du canal est mise à jour ; les échecs sont relancés avec backoff. Flux entrant Lorsqu’une réservation OTA arrive : le webhook est authentifié ; le corps brut est archivé de manière sécurisée ; l’identifiant externe est vérifié ; le message est enregistré dans l’inbox ; un traitement idempotent crée ou modifie la réservation ; l’inventaire est recalculé ; les autres canaux reçoivent le nouveau stock ; l’accusé de traitement est envoyé. Booking.com prévoit la récupération, la modification et l’annulation des réservations ainsi que des mécanismes d’accusé de réception. Sa documentation mentionne également un mécanisme de secours par courrier électronique lorsqu’une réservation n’est pas récupérée ou acquittée dans le délai prévu. Robustesse Les mécanismes prévus sont : inbox idempotente ; outbox transactionnelle ; numéro de version des événements ; retries exponentiels ; jitter ; circuit breaker ; dead-letter queue ; relance manuelle ; full sync ; delta sync ; journal d’audit ; rapprochement périodique entre le stock local et le stock distant ; alertes en cas de divergence ; tableau de santé par canal. 9. Gestion des prix Le moteur pourra gérer : prix par nuit ; prix par occupation ; adulte supplémentaire ; enfant supplémentaire ; tarifs dérivés ; tarifs remboursables ; tarifs non remboursables ; petit-déjeuner inclus ou non ; promotions ; codes privés ; offres long séjour ; early booking ; last minute ; tarifs entreprise ; prix par jour de la semaine ; saisons ; taxes incluses ou exclues ; frais fixes ou proportionnels ; minimum et maximum de séjour ; fermeture à l’arrivée ; fermeture au départ ; stop-sell ; délai avant arrivée ; limite de réservation future. Booking.com distingue plusieurs modèles de tarification et exige que les partenaires prennent correctement en charge les structures de prix et de disponibilité utilisées pendant leur certification. 10. Paiements Le système utilisera une interface indépendante du prestataire : interface PaymentGateway { public function createIntent(...); public function confirm(...); public function capture(...); public function cancel(...); public function refund(...); public function verifyWebhook(...); } Cela permettra d’intégrer selon le contrat retenu : CMI ; NAPS ; Payzone ; un autre acquéreur ; éventuellement plusieurs prestataires par établissement. CMI, NAPS et Payzone proposent des solutions marocaines de paiement ou des interfaces pour l’intégration marchande. Les conditions commerciales, modes de tokenisation et capacités de remboursement devront être validés directement avec le prestataire choisi. La plateforme ne stockera jamais : le numéro complet de carte ; le cryptogramme CVV ; les données sensibles brutes des cartes virtuelles OTA. Elle privilégiera : page de paiement hébergée ; champs hébergés ; tokenisation ; 3-D Secure ; webhooks signés ; journalisation sans données sensibles ; rapprochement des paiements ; remboursements partiels et complets. Les obligations PCI DSS restent applicables selon la manière dont les données de paiement transitent dans le système. 11. Back-office prévu Le back-office comprendra notamment : Tableau de bord arrivées du jour ; départs ; clients présents ; réservations récentes ; revenu ; taux d’occupation ; réservations par canal ; paiements en attente ; alertes de synchronisation ; erreurs nécessitant une intervention. Planning hôtelier Un tape chart avec : chambres physiques en lignes ; jours en colonnes ; réservations déplaçables sous contrôle ; couleurs par statut ; chambres hors service ; filtres ; vue jour, semaine et mois ; ouverture rapide de la fiche réservation. Calendrier prix et stock Il permettra les modifications en masse : période ; jours de la semaine ; type de chambre ; plan tarifaire ; prix ; stock ; minimum de séjour ; CTA/CTD ; stop-sell ; aperçu des canaux concernés. Centre de distribution Pour chaque canal : état de la connexion ; date du dernier message reçu ; date du dernier envoi réussi ; erreurs ; mappings manquants ; retard de file ; événements en dead-letter ; bouton de resynchronisation ; rapport de divergence ; historique technique. 12. UX et qualité internationale Le moteur public devra respecter plusieurs règles. Transparence commerciale Le prix total doit apparaître le plus tôt possible, avec distinction claire entre : prix des chambres ; taxes ; frais ; suppléments ; acompte à payer ; solde à l’hôtel ; conditions d’annulation. Mobile first Sur téléphone : formulaire compact ; calendrier plein écran ; filtres dans une bottom sheet ; récapitulatif sticky ; bouton principal accessible au pouce ; paiement sans déplacement horizontal ; champs avec autocomplete ; aucune modale inutile. Accessibilité L’objectif est WCAG 2.2 niveau AA : navigation clavier ; focus visible ; contrastes suffisants ; libellés explicites ; messages d’erreur associés aux champs ; lecteur d’écran ; réduction des animations ; alternatives textuelles ; interface RTL cohérente. Performance Les objectifs comprennent : pages légères ; images AVIF/WebP ; tailles d’images adaptées ; chargement différé ; cache des recherches ; CDN éventuel ; prévention des décalages visuels ; suivi LCP, INP et CLS selon les Core Web Vitals. 13. Sécurité et conformité Le socle de sécurité sera basé sur : OWASP ASVS ; OWASP Top 10 ; OWASP API Security Top 10 ; MFA pour les administrateurs ; contrôle d’accès par établissement ; permissions fines ; rate limiting ; protection CSRF ; Content Security Policy ; cookies sécurisés ; rotation des sessions ; chiffrement des secrets ; validation stricte des webhooks ; journaux d’audit ; sauvegardes chiffrées ; restauration testée. OWASP ASVS fournit une base structurée pour vérifier les contrôles de sécurité des applications web, tandis que l’OWASP API Security Top 10 couvre les risques propres aux interfaces API. Pour les données personnelles au Maroc, le projet devra intégrer les obligations relatives à la loi 09-08 et les formalités applicables auprès de la CNDP : finalités, information des clients, durée de conservation, sécurité, accès, rectification et encadrement des transferts éventuels. 14. Installation sur WHM/cPanel Arborescence recommandée Exemple : /home/UTILISATEUR/ ├── apps/ │ ├── reservation/ │ └── reservation-staging/ ├── logs/ ├── backups/ └── public_html/ Le sous-domaine devra pointer vers : /home/UTILISATEUR/apps/reservation/public Il ne doit jamais pointer vers la racine Laravel. Prérequis PHP 8.4 ; PHP-FPM ; Composer 2 ; MySQL ou MariaDB ; Redis ou Valkey ; Node.js pour le build ; Git ; accès SSH ; SSL automatique ; cron ; Supervisor ou service systemd pour les workers ; possibilité de modifier le document root ; sauvegardes hors du répertoire public. cPanel permet la gestion de versions PHP, des tâches cron et des déploiements Git. L’exploitation fiable des files Laravel nécessite toutefois des workers persistants correctement supervisés ; Laravel recommande un gestionnaire de processus tel que Supervisor pour redémarrer les workers en cas d’arrêt. Scheduler Un seul cron système : * * * * * cd /home/UTILISATEUR/apps/reservation && php artisan schedule:run >> /dev/null 2>&1 Laravel recommande ce principe : un cron par minute déclenche le scheduler applicatif, qui décide ensuite quelles tâches exécuter. Workers Mode recommandé : queue-critical queue-reservations queue-payments queue-channel-inbound queue-channel-outbound queue-notifications queue-default Les réservations entrantes et les changements de stock ne doivent pas attendre derrière l’envoi d’un e-mail ou la génération d’un rapport. Un mode cron peut servir temporairement lorsque Supervisor est indisponible, mais ce n’est pas la configuration de production recommandée pour un channel manager. 15. Feuille de route prévue dans le pack Le développement est séparé en 15 phases. Phase 0 — Préflight vérifier le serveur ; inventorier PHP, Composer, Node, MySQL et Redis ; confirmer le document root ; identifier le fournisseur de paiement ; déterminer la stratégie OTA ; créer le journal des décisions ; ne développer aucune fonctionnalité tant que l’environnement n’est pas documenté. Phase 1 — Fondation initialisation Laravel ; React et TypeScript ; authentification ; rôles et permissions ; établissement ; design system ; français, anglais et arabe ; CI locale ; qualité de code ; premiers tests. Phase 2 — Catalogue types de chambres ; chambres physiques ; équipements ; images ; capacités ; règles enfants ; suppléments ; taxes et frais. Phase 3 — Inventaire et tarifs stock journalier ; ledger ; plans tarifaires ; tarifs journaliers ; tarifs dérivés ; restrictions ; éditions groupées. Phase 4 — Disponibilités moteur de recherche ; calcul des prix ; occupation ; plusieurs chambres ; promotions ; cache ; explication détaillée du prix. Phase 5 — Moteur public parcours dates d’abord ; parcours chambre d’abord ; résultats ; filtres ; comparateur ; panier ; responsive ; accessibilité ; intégration au site. Phase 6 — Holds et réservations blocage temporaire ; checkout ; client ; conditions ; confirmation ; annulation ; tests de concurrence. Phase 7 — Paiement adaptateur ; environnement de test ; 3-D Secure ; webhooks ; acomptes ; captures ; remboursements ; réconciliation. Phase 8 — Back-office planning ; réservations ; affectation des chambres ; arrivées et départs ; notes ; paiements ; exports ; audit. Phase 9 — Noyau channel manager modèle canonique ; adaptateurs ; mappings ; outbox ; inbox ; retries ; dead-letter ; réconciliation ; simulateur de canal. Phase 10 — Passerelle OTA certifiée intégration sandbox ; création d’une connexion ; mapping des chambres ; mapping des plans ; envoi ARI ; import des réservations ; modifications ; annulations ; vérification du surbooking. Phase 11 — Durcissement et lancement audit sécurité ; tests de charge ; sauvegarde et restauration ; observabilité ; alertes ; staging ; procédure de rollback ; répétition du lancement. Phase 12 — Booking.com direct Seulement après acceptation comme partenaire et accès aux environnements requis. Phase 13 — Expedia direct Même principe : accès partenaire, sandbox, conformité et certification. Phase 14 — Distribution avancée Airbnb selon les accès disponibles ; Hotelbeds ; autres grossistes ; Google Hotel Ads ; liens gratuits de réservation ; CRM ; revenue management ; multiétablissement avancé. Google demande également de passer par un partenaire de connectivité approuvé ou d’obtenir l’accès approprié à ses interfaces Hotel Prices/Travel Partner pour la distribution des tarifs et des liens de réservation. 16. Méthode d’exécution avec Codex Il ne faut pas demander à Codex de construire toute la plateforme dans une seule exécution. Mise en place Déposer les quatre documents du pack à la racine du projet : reservation.energiedin.ma/ ├── PLAN_MAITRE_RESERVATION_ENERGIEDIN.md ├── PROMPT_MAITRE_CODEX_RESERVATION_ENERGIEDIN.md ├── PROMPTS_PHASES_CODEX_RESERVATION_ENERGIEDIN.md └── CHECKLIST_RESERVATION_ENERGIEDIN.md Première session Copier dans Codex le contenu de : PROMPT_MAITRE_CODEX_RESERVATION_ENERGIEDIN.md La première session doit uniquement : inspecter le répertoire ; inspecter l’environnement ; lire le plan ; créer les fichiers de gouvernance ; formaliser les décisions ; exécuter la phase 0 ; produire un rapport ; ne pas improviser l’intégration OTA. Sessions suivantes Utiliser ensuite les prompts contenus dans : PROMPTS_PHASES_CODEX_RESERVATION_ENERGIEDIN.md Chaque phase impose à Codex de : lire l’état du projet ; vérifier les décisions existantes ; ne traiter que la phase demandée ; exécuter les migrations ; écrire les tests ; lancer les tests ; vérifier le build frontend ; mettre à jour la documentation ; présenter les fichiers modifiés ; signaler les risques et éléments restant à traiter. Cette méthode évite qu’une longue session Codex produise rapidement beaucoup de code incohérent ou remplace des décisions prises lors des phases précédentes. 17. Résultat visé À l’issue du plan, reservation.energiedin.ma devra pouvoir : recevoir des réservations depuis le site officiel ; rechercher le stock et le prix en temps réel ; gérer plusieurs chambres dans une même réservation ; accepter ou garantir un paiement ; créer automatiquement la réservation ; diminuer immédiatement le stock ; transmettre la nouvelle disponibilité aux canaux ; recevoir les réservations OTA ; importer les modifications et annulations ; répercuter le nouveau stock sur tous les autres canaux ; identifier et relancer les synchronisations échouées ; offrir au personnel un planning et un back-office complets ; conserver une piste d’audit ; fonctionner en français, anglais et arabe ; évoluer vers plusieurs hôtels. Le choix central du plan est donc : moteur de réservation hybride + mini-PMS + noyau de channel manager indépendant + passerelle certifiée au lancement + connecteurs directs après agrément. C’est la voie la plus réaliste pour obtenir rapidement une plateforme exploitable sans enfermer reservation.energiedin.ma dans un prestataire unique ni prétendre disposer d’accès Booking.com ou Expedia qui n’auraient pas encore été accordés. DÉCISIONS AUTORITAIRES 2026-07-14 Lire `docs/DECISIONS_IMPLEMENTATION.md` avant ce document. Les choix React/Inertia, Channex, mono-hôtel et migration d'anciens PMS éventuellement mentionnés ci-dessous sont obsolètes.