Documentation Système · Mai 2026
Yanature & Nature Discoveries
— Logique Opérationnelle
Architecture complète du système de gestion des tours, guides et réservations. Configuration, disponibilité, planning, affectation et exclusivités.
3 portails web
2 Google Sheets
1 API Google Apps Script
Cloudflare Pages
01
Vue d'ensemble & Architecture
3 portails web communiquent avec une API centrale (Google Apps Script) qui lit et écrit dans 2 Google Sheets. Aucune base de données externe — tout vit dans Google Sheets.
👩💼
Portail Admin
portal.yanature.com
🤝
Portail Partenaires
partners.yanature.com
🧭
Formulaire Guides
guide.yanature.com
⇄
⚙️
Google Apps Script
API centrale unifiée
AvailabilityAPI.gs
GuideAvailability.gs
⇄
📊
Master Data
Bookings · TourConfig · Planning
👥
Guide Management
Paiements · Grades · Reviews
👩💼
Portail Admin
portal.yanature.com
Planning hebdo, affectation guides, validation, settings tours, paiements.
Shannon uniquement
🤝
Portail Partenaires
partners.yanature.com
Consulter disponibilités, soumettre demandes de réservation (groupe ou privatif).
Hôtels · Agences
🧭
Formulaire Guides
guide.yanature.com
Chaque guide soumet ses dispo AM/PM via son lien unique. Alimente l'algorithme d'affectation.
Guides
02
Structure des Google Sheets
Deux spreadsheets distinctes servent de base de données. Aucun redéploiement nécessaire pour changer des données — tout est mis à jour en temps réel.
📊 YN + ND Master Data
| Onglet | Rôle |
|---|
MASTER | Tous les bookings clients |
TourConfig | Source de vérité — tours, jours, horaires, capacité |
TourTimeOverrides | Overrides d'horaires par période (été/hiver etc.) |
TOUR_TEMPLATE | Override open/closed par jour de semaine |
BOOKING_REQUESTS | Demandes partenaires en attente de confirmation |
VALIDATED_PLANNING | Planning validé avec guides assignés + standbys |
GUIDE_AVAILABILITY | Disponibilités soumises par les guides |
WOO_QUEUE | Queue des bookings WooCommerce entrants |
👥 Guide Management
| Onglet | Rôle |
|---|
PAYMENTS | Historique des paiements par guide |
GRADE_CONFIG | Grille de grades et taux horaires |
GUIDE_CONFIG | Profil individuel, grade, taux spécifique |
FUEL_RATES | Taux de remboursement carburant |
REVIEWS | Avis clients liés à chaque guide |
Séparation des responsabilités
Master Data = opérationnel (bookings, planning, tours). Guide Management = RH & finance. Les portails lisent les deux via le même GAS.
03
TourConfig — Source de vérité
TourConfig est l'unique référence pour savoir quels tours existent, quand ils tournent, et comment ils peuvent être réservés. Configurable dans le portail admin → Settings.
📋 Champs de TourConfig
| Champ | Type | Description | Exemple |
|---|
tour_name | TEXT | Identifiant unique (MAJUSCULES) | MORNE BRABANT |
display_name | TEXT | Nom affiché aux partenaires | Morne Brabant |
group | TEXT | Catégorie dans le portail | Hiking / Kayak / Other |
skill | TEXT | Compétence guide requise | HIKING / KAYAK / CANYONING |
slot | TEXT | Créneau journalier | AM ou PM |
days | LIST | Jours de la semaine actifs | MON,WED,FRI,SAT,SUN |
default_time | TIME | Heure de départ par défaut | 06:50 |
capacity | INT | Places max par groupe | 12 |
company | TEXT | Entité opératrice | Yanature / Nature Discoveries |
active | BOOL | Tour actif dans tout le système | TRUE / FALSE |
needs_2_guides | BOOL | Nécessite 2 guides ensemble | TRUE (Canyoning) |
on_request | BOOL | Sur demande uniquement, jamais automatique | TRUE (Pieter Both) |
group_booking | BOOL | Réservable en groupe par les partenaires | TRUE |
exclusive_booking | BOOL | Réservable en privatif | TRUE (Morne Brabant) |
⚠ Une ligne par slot
Un même tour peut avoir plusieurs lignes — une par créneau. Ex : MORNE BRABANT AM et MORNE BRABANT PM sont deux lignes distinctes avec leurs propres jours et horaires.
Effet immédiat de active = FALSE
Le tour disparaît instantanément du planning, du dropdown partenaire et de toute disponibilité. Aucun redéploiement nécessaire. Réactivation = retour immédiat.
04
Logique de disponibilité (2 couches)
La disponibilité d'un créneau est résolue par deux couches superposées. TourConfig établit la base permanente. TOUR_TEMPLATE permet des fermetures/ouvertures temporaires sans modifier la config.
1
🟢 Couche 1 — TourConfig (base permanente)
Définit quels tours existent et quels jours de la semaine ils tournent. Un tour active=TRUE avec days=MON,WED,FRI est automatiquement ouvert ces 3 jours, chaque semaine, indéfiniment.
MORNE BRABANT | AM | active=TRUE | days=MON,TUE,WED,THU,FRI,SAT,SUN → ouvert 7j/7
2
🟠 Couche 2 — TOUR_TEMPLATE (override opérationnel)
Permet de fermer ou rouvrir un créneau rapidement. Utile pour les jours fériés, sous-effectif, maintenance. Une cellule vide = TourConfig s'applique. Ne peut jamais rouvrir un tour désactivé (active=FALSE).
MORNE BRABANT | AM | MON=open | TUE=closed | MER=(vide→TourConfig=open) | ...
🔀 Algorithme de résolution — ordre de priorité
function isSlotOpen(hike, slot, dayOfWeek):
// Règle 1 : tour désactivé → TOUJOURS fermé
if TourConfig[hike|slot].active == FALSE:
return CLOSED
// Règle 2 : TOUR_TEMPLATE a la priorité si renseigné
override = TOUR_TEMPLATE[hike|slot][dayOfWeek]
if override == "open" → return OPEN
if override == "closed" → return CLOSED
// Règle 3 : cellule vide → TourConfig fait foi
return dayOfWeek in TourConfig[hike|slot].days ? OPEN : CLOSED
🕐 TourTimeOverrides — horaires par période
Onglet séparé de TOUR_TEMPLATE. Permet de définir des horaires de départ différents sur une période calendaire précise (ex: juillet plus tôt pour la chaleur).
MORNE BRABANT
AM
2026-07-01
2026-08-31
06:00
KAYAK SUNRISE
AM
2026-11-01
2026-03-31
05:00
N'affecte que l'heure de départ affichée — pas l'ouverture ou la fermeture du créneau.
05
Flux de réservation partenaires
Les partenaires accèdent avec un compte approuvé par Shannon. Ils peuvent soumettre des demandes en mode Groupe ou Privatif — toujours en attente de confirmation.
🏔 Mode Groupe
1
Disponibilité temps réel
Créneaux ouverts selon TourConfig + TOUR_TEMPLATE. Compteur de places restantes basé sur les bookings dans MASTER. Tours filtrés : group_booking=TRUE.
2
Demande de réservation
Partenaire remplit : nom client, nb pax, notes. La demande part dans BOOKING_REQUESTS avec statut pending.
3
Confirmation par Shannon
Shannon voit la demande dans le portail admin et confirme ou rejette. Le partenaire reçoit la réponse.
⭐ Mode Privatif
1
Tours disponibles
Seuls les tours avec exclusive_booking=TRUE. Configuré dans Settings → Bookable as → Private.
2
Condition d'ouverture
Un créneau privatif n'est bookable que si un guide standby est confirmé dans VALIDATED_PLANNING pour ce jour précis.
3
Demande envoyée
Même flux que groupe, avec flag booking_type=exclusive. Shannon assigne le guide standby au tour privatif.
Impossible de faire une erreur depuis le portail partenaire
Toute demande passe par Shannon. Il est impossible de booker un tour désactivé, un créneau fermé, un type de booking non configuré, ou de dépasser la capacité. L'AvailabilityAPI filtre tout en amont.
06
Planning & affectation des guides
Chaque semaine, Shannon génère un planning d'affectation. Le système auto-assigne en tenant compte des disponibilités, compétences, bookings existants et équité de charge.
📥 Disponibilité guide — 3 états
| Valeur | Signification | Dans le dropdown |
|---|
true | Disponible ce créneau | ✓ Available |
false | Explicitement indispo | ⚠ Force assign |
null | N'a pas soumis ses dispos | ⚠ Not submitted |
Dans la grille planning, les disponibles apparaissent en haut du dropdown, les force-assign en bas avec un séparateur.
🛡 Compétences par guide
| Skill | Tours concernés |
|---|
HIKING | Morne Brabant, Tamarind Falls, Black River Gorges… |
KAYAK | Tous les Kayak (Sunrise, Dolphin, River, Sunset…) |
CANYONING | Canyoning uniquement |
EBIKE | E-Bike Wild South & Mahebourg |
PIETER_BOTH | Pieter Both (technique, accès restreint) |
Un guide sans le skill requis n'apparaît jamais dans le dropdown de ce tour.
🤖 Algorithme Auto-assign — ordre de priorité
// ÉTAPE 1 : Trier les slots à assigner
1. Slots avec clients déjà bookés → priorité ABSOLUE (bonus −10 000)
2. Slots avec le moins de guides dispos → ressource rare en premier (évite les deadlocks)
3. Par date croissante
// ÉTAPE 2 : Choisir le meilleur guide pour chaque slot
score = (rang_soumission × 10) // récompense soumission précoce
− (8 × total_sorties_semaine) // équité de charge
− (50 × sorties_même_tour) // évite répétition même tour
// ÉTAPE 3 : Fallback si aucun guide disponible
Pool 1 : guides disponibles (dispo=true)
Pool 2 : guides non soumis (dispo=null)
Pool 3 : guides indispos (dispo=false) ← dernier recours
👥 Standbys
Guides sans tour assigné mais disponibles ce jour-là. Shannon les ajoute manuellement dans la ligne Standby de la grille planning.
Rôle
Guides "on call" — prêts à prendre un tour de dernière minute ou à faire une exclu privatif.
Stockage
Sauvegardés dans
VALIDATED_PLANNING avec
hike=__STANDBY__ lors de la validation.
Communication
Le guide voit "Standby" dans son planning communiqué — il sait qu'il est on call sans tour fixé.
✅ Validation du planning
👩💼
Re-validate
Bouton dans le portail
→
💾
VALIDATED_PLANNING
Écrit guides + standbys
→
🌐
Dispo partenaires
Basée sur planning réel
→
⭐
Exclusivités
Standbys visibles
07
Réservations privées (Exclusivités)
Un partenaire peut réserver un tour en privatif — un guide dédié uniquement à son groupe. La disponibilité dépend directement des guides standbys planifiés par Shannon.
🔗 Chaîne de dépendances
⚙️
Settings
exclusive_booking=TRUE sur le tour
→
👩💼
Shannon
Assigne un standby + Re-validate
→
🤝
Partenaire
Voit "★ Guide on standby"
→
📩
Demande envoyée
booking_type = exclusive
Règle d'or de l'exclusivité
Un créneau privatif n'est visible et bookable par le partenaire
que si un guide standby est confirmé dans VALIDATED_PLANNING pour ce jour précis. Sans standby validé → le partenaire voit "No guide yet", aucun bouton.
Indépendant de la capacité groupe
La disponibilité privatif est calculée depuis TourConfig (jours où le tour tourne) et non depuis l'AvailabilityAPI. Un créneau groupe "full" peut toujours être bookable en privatif si un standby existe.
Weeks futures sans planning
Pour les semaines non encore planifiées, le partenaire voit "No guide yet" pour tous les jours. Shannon doit d'abord planifier et valider les standbys pour que les exclus s'ouvrent.
⚙️ Configuration par tour
Dans Settings → chaque tour → Bookable as :
Attention : après avoir coché "Private" et sauvegardé, penser à Re-validate le planning si des standbys ont déjà été assignés — sinon ils n'apparaîtront pas côté partenaire.
08
Déploiements & Google Apps Script
Les portails sont hébergés sur Cloudflare Pages (statique, ultra-rapide). L'API est un Google Apps Script déployé comme Web App publique.
☁️ Cloudflare Pages — portails
| Projet CF | URL live | Dossier local |
|---|
portal | portal.yanature.com | yanature-portal/ |
partners | partners.yanature.com | yanature-to-booking/ |
guide | guide.yanature.com | yanature-guide-form/ |
planning | planning.yanature.com | yanature-planning/ |
# Déployer (depuis le dossier du portail)
npx wrangler pages deploy . --project-name portal
📜 Google Apps Script
| Fichier | Rôle |
|---|
AvailabilityAPI.gs | Disponibilité créneaux (routes tours, standby_days) |
GuideAvailability.gs | Guides, planning, bookings, TourConfig, paiements |
Déployer le GAS
Apps Script → Déployer → Gérer les déploiements →
Nouvelle version → Déployer. Toujours créer une nouvelle version, ne jamais écraser l'existant.
📌 Quand redéployer quoi ?
| Action | Portail CF | GAS | Google Sheet |
|---|
| Modifier un tour (activer, horaire…) | — | — | Modifier TourConfig directement ✓ |
| Fermer un jour dans TOUR_TEMPLATE | — | — | Modifier TOUR_TEMPLATE directement ✓ |
| Changer le code HTML/JS d'un portail | Déployer ✓ | — | — |
| Ajouter une route GAS, fix de bug .gs | — | Nouvelle version ✓ | — |
| Ajouter un guide (liste GUIDES dans GAS) | — | Nouvelle version ✓ | — |
Yanature Operations System · Documentation interne · Mis à jour Mai 2026