# Guide du projet Booking

Ce document décrit la structure, la configuration, les conventions et les bonnes pratiques pour travailler sur ce projet PHP « Booking ».

Sommaire:
- Présentation et architecture
- Installation et exécution locale
- Base de données et initialisation
- Routage, pages et composants UI
- API publiques et authentification
- Assets front (CSS/JS)
- Conventions de code et sécurité
- Tests et vérifications manuelles
- Déploiement
- Ajout de fonctionnalités (pages, API, services)

---

1) Présentation et architecture
- Version: application PHP procédurale légère avec quelques services dédiés.
- Point d’entrée UI: www/index.php
  - Sélection de page via paramètre GET ?page=… avec whitelisting dans $allowed.
  - Inclusions: www/includes/bootstrap.php (session, SPDO, helpers, layout, etc.).
- Organisation principale:
  - config/config.php → credentials MySQL (hors webroot)
  - www/class/spdo.php → wrapper PDO singleton + helpers (fetchAllAssoc, fetchOne, fetchValue…)
  - www/includes/* → utilitaires communs: auth.php, ui.php, pagination.php, layout.php, helpers.php
  - www/pages/* → vues/écrans back-office (réservations, clients, logements, tarifs…)
  - www/api/* → endpoints JSON (ex: availability.php, booking.php, unit.php, etc.)
  - www/core/* → services métiers (ex: AvailabilityService.php)
  - www/public/assets/* → statiques front (app.css, app.js)
  - www/cron/* → scripts CRON (ex: ics_pull.php)
  - .junie/guidelines.md → ce fichier

2) Installation et exécution locale
Prérequis:
- PHP ≥ 8.1 recommandé (strict_types utilisé)
- Extensions: pdo_mysql, json, mbstring, openssl
- MySQL/MariaDB (compat. MySQL 5.7+)

Étapes:
1. Cloner le repo.
2. Configurer la base: créer un schéma MySQL et un utilisateur.
3. Éditer config/config.php pour renseigner DB_HOST, DB_NAME, DB_USER, DB_PASSWORD, DB_PORT.
4. Importer les données (voir section « Base de données »).
5. Démarrer un serveur local en pointant sur le dossier www:
   - php -S localhost:8000 -t www
6. Accéder à l’application: http://localhost:8000/

Notes:
- En dev, l’affichage d’erreurs est activé dans includes/bootstrap.php. En prod, il faudra le désactiver (voir Déploiement).

3) Base de données et initialisation
- Fichiers SQL au root de www:
  - dump.sql → dump global de référence
  - gites.sql, tarifs.sql, saisons.sql → datasets ou schémas thématiques
  - delete_safe_customer.sql → utilitaire SQL spécifique
- Procédure d’initialisation locale:
  - mysql -u <user> -p <db> < www/dump.sql
  - Ajuster si besoin selon votre environnement.
- Connexion: via SPDO (singleton) qui lit config/config.php.
- Journalisation erreurs PHP: les logs applicatifs sont écrits dans var/logs/ (racine du projet, hors web root). Vérifiez les permissions d’écriture de ce répertoire.

4) Routage, pages et composants UI
- Routage simple dans www/index.php:
  - $page = $_GET['page'] ?? 'dashboard';
  - $allowed contient la liste blanche. Si non listée, fallback sur dashboard.
  - layout_header()/layout_footer() entourent les pages.
- Layout & UI:
  - Head inclus Bootstrap 5.x via CDN, app.css local et Bootstrap Icons.
  - Barre latérale définie dans includes/layout.php (liens vers pages).
  - Helpers UI dans includes/ui.php (badges, alertes) et helpers dans includes/helpers.php.
- Authentification UI:
  - require_login() redirige vers /login.php si non connecté.
  - Session stocke user_id, user_name, property_id, property_name.

5) API publiques et authentification
- Endpoints JSON dans www/api/* (exemples):
  - availability.php
  - booking.php
  - unit.php
  - check_available.php, change_status.php, update_field.php, rate_calendar_fetch.php, rate_upsert_bulk.php, config_upsert.php, config_delete.php, channel_import_run.php, calcul_charge.php
- Conventions générales:
  - Headers JSON et CORS gérés au début de chaque endpoint.
  - Sessions démarrées si nécessaire (session_start) pour usage back-office.
  - require_property_auth():
    - Back-office: utilise la session courante (property_id).
    - Front/public: exiger ?property=<id> + header X-API-Key valide; vérifie aussi le domaine (allowed_domains dans property).
  - Réponses: JSON UTF-8; gérer exceptions avec http_response_code approprié.
- Service de disponibilité: www/core/AvailabilityService.php assemble la légende, les jours et la matrice par logement.

6) Assets front (CSS/JS)
- www/public/assets/app.css et app.js contiennent le style et JS spécifiques.
- Bootstrap et Bootstrap Icons via CDN.
- Pour modifier le menu latéral ou le thème, éditer includes/layout.php et app.css.

7) Conventions de code et sécurité
- PHP strict_types=1 en tête des fichiers PHP.
- Accès DB: passer par SPDO::getInstance() et toujours utiliser des requêtes préparées (fetchOne, fetchAllAssoc, fetchValue, executeQuery, insertQuery).
- Échappement/HTML: utiliser htmlspecialchars pour tout contenu dynamique (voir layout_header pour le titre, etc.).
- CSRF:
  - Génération: csrf_token() / csrf_field()
  - Vérification POST: check_csrf()
- Auth & sessions:
  - Utiliser require_login() côté back-office pour protéger les pages.
  - Utiliser require_property_auth() côté API.
- Validation des entrées: caster/valider dates (Y-m-d), entiers (intval), listes autorisées, etc.
- Configuration: ne jamais commiter des secrets réels; stocker les identifiants dans config/config.php (hors webroot). Fournir un exemple anonymisé si besoin.
- Style: s’inspirer de PSR-12, indentations cohérentes, noms explicites, fonctions petites et ciblées.

8) Tests et vérifications manuelles
- Il n’y a pas de suite de tests automatisés ni de build out-of-the-box (pas de composer.json ni de runner).
- Avant de soumettre une correction:
  - Vérifier l’affichage des pages clés: dashboard, booking_list, availability, unit_list, customer_list, rate_list.
  - Tester le login/logout et l’accès redirigé si non authentifié.
  - Tester au moins un endpoint API (ex: /api/availability.php?property=<id>&date_from=YYYY-MM-01&date_to=YYYY-MM-28) avec un header X-API-Key valide, ou via session back-office.
  - Vérifier l’absence d’erreurs PHP (logs/console) et la cohérence UI.
- Si vous ajoutez des tests, placez-les dans un dossier tests/ à la racine ou sous www/tests/, et documentez comment les exécuter (phpunit, pest, etc.).

9) Déploiement
- Cible serveur web: pointer la racine du VirtualHost sur le dossier www/.
- PHP en production:
  - Désactiver display_errors et display_startup_errors; conserver error_reporting mais rediriger vers un fichier de logs.
  - Vérifier les permissions d’écriture du répertoire de logs (var/logs/, hors web root) ou configurer un répertoire externe.
- Configurer config/config.php avec les identifiants de prod (ne pas commiter).
- S’assurer que .gitignore exclut tout secret si ajouté.
- CORS/API: mettre à jour allowed_domains dans la table property pour sécuriser les appels front.
- CRON: si nécessaire, planifier www/cron/ics_pull.php avec PHP CLI et journaliser la sortie.

10) Ajout de fonctionnalités
- Ajouter une page back-office:
  1. Créer un fichier dans www/pages/<nom>.php.
  2. Ajouter <nom> dans le tableau $allowed de www/index.php.
  3. Ajouter un lien dans includes/layout.php si nécessaire.
  4. Protéger la page: appeler require_login() ou s’appuyer sur www/index.php qui l’appelle déjà.
  5. Pour les formulaires POST: ajouter csrf_field() et vérifier via check_csrf().

- Ajouter un endpoint API JSON:
  1. Créer www/api/<resource>.php.
  2. Envoyer les bons headers (Content-Type: application/json; CORS si besoin).
  3. require_once spdo.php et includes/auth.php.
  4. Déterminer le property_id via require_property_auth().
  5. Retourner toujours du JSON (succès/erreur) avec codes HTTP adaptés.

- Ajouter une logique métier réutilisable:
  - Placer un service dans www/core/ (ex: <Feature>Service.php) et l’appeler depuis pages/* et/ou api/*.

Conseils pratiques
- Centraliser les libellés/couleurs/statuts en base et utiliser les helpers existants (helpers.php, ui.php).
- Pour les tarifs, s’appuyer sur get_pricing_days() et config_get() pour respecter les overrides propriété/unité.
- Éviter les duplications de SQL; factoriser via helpers SPDO.

Annexes
- Technologies:
  - PHP 8+, MySQL, Bootstrap 5, Bootstrap Icons
- Emplacements clés:
  - Auth: www/includes/auth.php
  - Layout: www/includes/layout.php
  - Service dispo: www/core/AvailabilityService.php
  - Router: www/index.php
  - Assets: www/public/assets/

En cas de doute, conservez la simplicité, la sécurité (CSRF, XSS, requêtes préparées) et la lisibilité.