# v2.md — Refonte : carte des aires de pique-nique (Node.js + MongoDB) Ce document décrit comment reconstruire l'application actuelle (un prototype en deux scripts PHP) en une **v2** propre et intégrée : - un **backend Node.js / Express** unique, - une base **MongoDB** (la vraie base de données, fini le « `data/` est la base »), - toutes les routes API préfixées par **`/api`**, - les pages HTML servies statiquement depuis **`./public`** à la racine **`/`**. Le but n'est **pas** d'ajouter des fonctionnalités mais de reprendre **exactement** celles du prototype, mieux structurées : un vrai modèle de données, une API REST, un frontend découplé, et un grabber (scraper) planifié. > Deux documents voisins (`API.md`, `APP.md`) décrivent une variante « JSON sur > disque » et un portage mobile. **Ce `v2.md` les remplace pour la cible web** : > il assume MongoDB comme source de vérité. Les règles métier (contrat > équipements, normalisation, algorithmes d'itinéraire) y sont **identiques**. --- ## 1. Inventaire exhaustif des fonctionnalités actuelles Tout ce que fait le prototype aujourd'hui, à reproduire à l'identique en v2. Source : `index.php` (frontend + rendu inline), `note.php` (notes), `lieux.php` (scraper). ### 1.1 Carte - **C1** — Carte plein écran, fond de tuiles **OpenStreetMap**, clustering des markers (`leaflet.markercluster`). - **C2** — Vue initiale **France entière** : centre `[46.5, 2]`, zoom `6`. - **C3** — **Permalink de l'état carte** : à chaque `moveend`, l'URL est mise à jour (`?lat&lon&z`) via `history.replaceState`. Au chargement, si `lat/lon/z` présents, on restaure cette vue. - **C4** — Un marker par aire. Au clic → **popup** contenant : - le **titre** (lien vers `pique-nique.info/AireDetail.php?lieu={id}`), - la **1ʳᵉ photo** (`width=150`) si disponible, - la **liste des équipements actifs** (texte), - un lien **📷 Street View** (`google.com/maps/@?api=1&map_action=pano&viewpoint={lat},{lon}`), - un bloc **« étape »** (distance/durée depuis le départ d'itinéraire, si itinéraire actif), - un bloc **notation** (moyenne + vote). - **C5** — À l'ouverture d'une popup, l'URL reçoit `?lieu={id}` ; à la fermeture, le paramètre est retiré. - **C6** — **Restauration du lieu ouvert** au chargement : `?lieu={id}` → `clusterGroup.zoomToShowLayer(marker, …)` puis ouverture de la popup. - **C7** — Bouton **géolocalisation 📍** : recentre (zoom 14) + marker « 📍 Vous êtes ici » (via `navigator.geolocation`, alerte si refus/erreur). ### 1.2 Recherche (barre en haut à droite) > **Changement UX v2** — dans le prototype, cette barre et le panneau itinéraire > (§1.6) sont **affichés en même temps**. En v2 on **unifie** en un seul panneau à > deux modes exclusifs (« Lieu » / « Itinéraire »), cf. §6.1. Le comportement de > chaque champ reste identique. - **S1** — Champ « Rechercher un lieu ou une ville… ». - **S2** — **Autocomplete combiné** (debounce 300 ms, min 2 caractères) : - lieux locaux dont le `nom` contient la saisie (préfixe 🍽️, max 5), match **insensible aux accents** (`normaliser` = NFD + suppression diacritiques + lowercase), - villes via **Photon (komoot)** filtrées `country === 'France'` (préfixe 🏙️, max 5). - **S3** — Bouton **×** pour vider (sur la barre **et** les champs Départ/Arrivée), navigation clavier (↑/↓/Entrée/Échap). - **S4** — Sélection d'une suggestion → recentre (zoom 14) + popup au point avec bouton **« 🧭 Itinéraire depuis ici »** qui pré-remplit le **Départ**. - **S5** — Validation au clavier (`change`) sans suggestion : match local d'abord (zoom 15), sinon fallback **Nominatim** (`countrycodes=fr`, zoom 13 + popup), sinon alerte « Ville non trouvée ». ### 1.3 Filtres équipements (toolbar verticale) - **E1** — 9 boutons emoji, **contrat figé** (ordre + emoji), cf. §3.4. - **E2** — Filtrage **AND** : un lieu n'apparaît que s'il possède **tous** les équipements sélectionnés. - **E3** — État des filtres dans l'URL : `?eq=` **répété**, toggle par bouton, bouton actif visuellement marqué. ### 1.4 Filtre par note (bouton ⭐) - **N1** — Ouvre une **modale** « note min / note max » (1–5, défaut min 3 / max 5). - **N2** — Validation → ne garde que les lieux dont `note_avg ∈ [min, max]` ; les lieux **sans avis** (`note_avg == null`) sont **exclus**. `min`/`max` réordonnés si inversés. - **N3** — Re-clic sur ⭐ quand le filtre est actif → le **retire** (pas de modale). ### 1.5 Notation (dans la popup d'un lieu) - **R1** — À l'ouverture : `GET note.php?id=` → moyenne en **étoiles** (`★`/`☆`, arrondi) + `X/5 (N avis)` ou « pas encore d'avis ». - **R2** — Rangée « Votre note » : 5 étoiles, survol → highlight progressif. - **R3** — Clic sur une étoile → `POST note.php {id, note}` → réaffiche la moyenne **mise à jour**. ### 1.6 Itinéraire (panneau bas-gauche, repliable) > **Changement UX v2** — fusionné avec la barre de recherche §1.2 en un panneau à > deux modes exclusifs (cf. §6.1) : on ne voit jamais les deux formulaires en même > temps. Le pliage/dépliage `localStorage` (I0) est remplacé par la bascule de mode. - **I0** — Panneau **repliable**, état persisté (`localStorage 'itineraire-collapsed'`). - **I1** — Champ **Départ** + autocomplete Photon + ×. - **I2** — Bouton **swap ⇅** (échange Départ/Arrivée). - **I3** — Champ **Arrivée** + autocomplete Photon + ×. - **I4** — **Mode** voiture 🚗 / vélo 🚲 (radio). Changer de mode **recalcule** l'itinéraire si Départ + Arrivée renseignés. - **I5** — Lien « **Indiquer une heure de départ** » → révèle « Heure de départ » + « Position à ». - **I6** — **Slider distance** 5→50 km (pas 5, défaut 10) : « Aires à moins de X km » (+ suffixe « de ma position à HH:MM » quand le filtre temporel est actif). - **I7** — Bouton **🧭 Itinéraire** (état loading). - **I8** — **Liste des itinéraires** : chaque ligne = `X km` + durée ; clic → sélectionne (les autres tracés passent à opacité 0.25). - **I9** — Lien **« Voir dans maps »** → Google Maps directions (`travelmode` = `driving`/`bicycling` selon le mode). - **I10** — **Filtrage des aires par la ligne** : seules les aires à **moins de X km de la polyligne** restent visibles (`turf.pointToLineDistance`). - **I11** — **Filtre temporel** : si « heure départ » + « position à » renseignées, on estime la position sur le trajet à l'heure cible et on ne garde que les aires à **moins de X km de CE point** ; un marker « 📍 HH:MM » est posé sur le trajet. - **I12** — Bloc **« étape »** dans chaque popup quand un itinéraire existe : distance/durée OSRM depuis le **départ** du trajet jusqu'à l'aire. - **I13** — **Permalink itinéraire** : `?from&to&mode&dist&start&target` (+ `lieu`), restauré au chargement (recalcule l'itinéraire). ### 1.7 Correction de coordonnées - **O1** — Si un **override** de coordonnées existe pour un lieu, il **remplace** la lat/lon issue du scraping. (Aujourd'hui : `data/coords/{id}.json`.) ### 1.8 Scraper (`lieux.php`) - **G1** — Parcourt tous les départements (`01..19`, `21..95`, `2A`, `2B`, `971`, `972`, `973`, `974`, `976`). - **G2** — **Phase 1** : télécharge la page de recherche de chaque département, extrait les ids via regex `AireDetail\.php\?lieu=(\d+)`. - **G3** — **Phase 2** : pour chaque id inconnu, scrape la fiche détail (nom, description, latitude, longitude, photos, équipements) via XPath sur des labels texte précis. - **G4** — **Idempotent & incrémental** : la présence d'un fichier fait sauter le fetch. Throttle **200 ms** entre deux fiches. - **G5** — Scraping **fragile par nature** : un fetch raté renvoie `null` et la fiche est ignorée (jamais d'écriture partielle). --- ## 2. Architecture cible v2 Un **seul process Node** : 1. sert l'**API REST** sous `/api/*`, 2. sert le **frontend statique** (`public/`) à la racine `/`, 3. héberge le **grabber** planifié (cron in-process) qui alimente MongoDB. ``` ┌───────────────────────────────────────────┐ Navigateur │ Serveur Node / Express │ ┌─────────────┐ GET / │ ┌──────────────┐ ┌────────────────────┐ │ │ public/ │◄───────┤ │ static files │ │ Routes /api/* │ │ │ index.html │ │ │ (./public) │ │ lieux, notes, │ │ │ + app.js │───────►│ └──────────────┘ │ equipements, │ │ │ (Leaflet) │ /api/… │ │ (geocode/route) │ │ └─────┬───────┘ JSON │ ┌────────────┴─────────┐ │ │ │ │ │ Services (store, │ │ │ │ │ │ notes, grabber) │──────────┼─┼──► MongoDB │ │ └──────────────────────┘ │ │ (lieux, notes, │ │ ┌──────────────────────┐ │ │ departements) │ │ │ Cron → grabber │──scrape──┼─┼──► pique-nique.info │ │ └──────────────────────┘ │ │ │ services tiers (directs OU proxifiés via /api) │ │ ▼ └───────────────────────────────────────────┘ Photon / Nominatim / OSRM / tuiles OSM ``` Le backend absorbe les **3 points d'I/O** du prototype : 1. le **dump inline** de `index.php` → `GET /api/lieux`, 2. **`note.php`** (lecture/écriture des notes) → `/api/lieux/:id/notes`, 3. la **normalisation** PHP (équipements forcés, override coords, moyenne, exclusion `Logo Pinterest`) → désormais dans MongoDB / la couche service. --- ## 3. Modèle de données MongoDB C'est le **changement structurant** de la v2 : les JSON-sur-disque deviennent des collections MongoDB. On conserve `id` (l'identifiant source de pique-nique.info, une **chaîne** numérique) comme `_id`. ### 3.1 Collection `lieux` Un document par aire. On **dénormalise** ce qui est coûteux à recalculer (coords effectives, équipements actifs triés, moyenne des notes) pour que l'API réponde sans agrégation lourde. ```jsonc { "_id": "1", // id source (string) "nom": "Jardins de la Corderie Royale", "description": "Quatre tables sont installées...", "latitude": 45.941205, // number (parsé depuis le scrap) "longitude": -0.954939, // number "location": { "type": "Point", // GeoJSON pour requêtes bbox/geo "coordinates": [-0.954939, 45.941205] }, // [lon, lat] "photos": ["https://www.pique-nique.info/photos/corderie.jpg", "..."], "equipements": { // map complète nom → bool (inclut inactifs) "Table & banc": true, "Wc": true, "Parking": true, "Poubelle": true, "Barbecue": false, "Camping-car": true, "Point eau": true, "Aire de jeux": true, "Acces handicape": true }, "equipementsActifs": ["Acces handicape","Camping-car","Parking","..."], // triés, sans "Logo Pinterest" "coordsOverride": { "latitude": 45.9412, "longitude": -0.9549 }, // null si aucun override "noteAvg": 4.0, // dénormalisé ; null si 0 avis "noteCount": 1, // dénormalisé "source": "pique-nique.info", "scrapedAt": "2026-05-10T07:32:00.000Z", "updatedAt": "2026-05-10T07:32:00.000Z" // pour ?updated_since= } ``` **Règles de normalisation (identiques à `index.php`, appliquées à l'écriture) :** - `latitude/longitude` = override s'il existe, sinon valeurs scrapées ; converties en `number`. `location.coordinates = [lon, lat]`. - `equipements` : les **9 clés du contrat** (§3.4) sont **forcées** (à `false` si absentes). - `equipementsActifs` = clés `true`, **`Logo Pinterest` exclu**, **triées A→Z**. - Un lieu **sans latitude/longitude** exploitable est marqué invalide et **exclu** des réponses liste (équivalent du `continue` PHP). On peut soit ne pas l'insérer, soit poser un flag `valid: false` et filtrer dans les requêtes. **Index :** ```js db.lieux.createIndex({ location: "2dsphere" }); // bbox / near db.lieux.createIndex({ equipementsActifs: 1 }); // filtre équipements db.lieux.createIndex({ noteAvg: 1 }); // filtre note db.lieux.createIndex({ updatedAt: 1 }); // sync incrémentale // nom : index texte optionnel ; la recherche accent-insensitive reste surtout côté client ``` ### 3.2 Collection `notes` Un document **par avis** (remplace `data/notes/{id}.json`). Plus propre qu'un tableau embarqué : insertion concurrente sûre, agrégation simple. ```jsonc { "_id": ObjectId, "lieuId": "1", "note": 4, "date": "2026-05-10T07:04:28.000Z" } ``` ```js db.notes.createIndex({ lieuId: 1 }); ``` > À chaque insertion d'avis, on **recalcule** `noteAvg`/`noteCount` et on les > **écrit sur le document `lieux`** correspondant (dénormalisation, §5.3). La > collection `notes` reste la source de vérité. ### 3.3 Collection `departements` (cache du scraper) Remplace `data/departements/{NN}.json`. Sert le cache de Phase 1 avec un **TTL** pour redécouvrir les nouvelles aires. ```jsonc { "_id": "17", // code département "ids": ["1","2","3","..."], // ids extraits par la regex "html": "…", // (optionnel) HTML brut, pour re-extraire sans refetch "fetchedAt": "2026-05-10T06:47:00.000Z" } ``` > **Différence assumée avec `lieux.php`** : le PHP cache la page département « pour > toujours ». En v2 on applique un **TTL** (défaut 7 jours) sur `fetchedAt` : au-delà, > on refetch pour découvrir les aires ajoutées en amont. Les fiches `lieux`, elles, > restent en cache permanent (présence = skip). ### 3.4 Contrat des équipements (FIGÉ — ne pas modifier sans intention) Ordre et emojis **identiques** à `$equipements_importants` de `index.php`. Ces 9 clés sont garanties sur chaque lieu et pilotent la toolbar. ```js // backend + frontend partagent cette constante (exposée aussi via GET /api/equipements) export const EQUIPEMENTS = [ { key: "Table & banc", emoji: "🪑" }, { key: "Wc", emoji: "🚻" }, { key: "Parking", emoji: "🅿️" }, { key: "Poubelle", emoji: "🗑️" }, { key: "Barbecue", emoji: "🔥" }, { key: "Camping-car", emoji: "🚐" }, { key: "Point eau", emoji: "🚰" }, { key: "Aire de jeux", emoji: "🎠" }, { key: "Acces handicape", emoji: "♿" }, ]; ``` --- ## 4. Stack technique | Domaine | Choix | Rôle | |---|---|---| | Runtime | **Node.js ≥ 20** (fetch natif) | | | Serveur HTTP | **Express** | API `/api/*` + static `./public` | | Base de données | **MongoDB** (driver officiel `mongodb`, ou **Mongoose**) | Source de vérité | | Validation | **zod** | Params/bodies (note, bbox, eq…) | | Scraping HTML | **cheerio** | Remplace `DOMDocument`/`DOMXPath` | | Planification | **node-cron** (in-process) | Lance le grabber | | Sécurité | `helmet`, `cors`, `express-rate-limit` | | | Logs | `pino` (+ `pino-http`) | | > **Driver `mongodb` vs Mongoose** : le modèle est simple et l'écriture est faite > par le grabber. Le driver natif suffit et évite une couche. Mongoose est un > confort si l'on veut des schémas/validation centralisés — au choix de l'équipe. > Les exemples ci-dessous utilisent le **driver natif**. --- ## 5. API REST (`/api/*`) Toutes les réponses en `application/json; charset=utf-8`. CORS ouvert (à restreindre en prod). ### 5.1 `GET /api/lieux` Liste normalisée (équivalent du dump de `index.php`). Par défaut renvoie **tout** le dataset (le frontend actuel charge tout d'un coup), avec des filtres serveur optionnels. Query params (tous optionnels) : | Param | Type | Effet | |---|---|---| | `bbox` | `minLon,minLat,maxLon,maxLat` | Restreint à l'emprise (`$geoWithin`/`2dsphere`) | | `eq` | répétable (`?eq=Wc&eq=Parking`) | Lieux ayant **TOUS** ces équipements (`$all`) | | `note_min` / `note_max` | 1–5 | Filtre sur `noteAvg` (exclut `null`) | | `updated_since` | ISO 8601 | `updatedAt >= …` (sync incrémentale) | Réponse (objet « format liste », strictement ce que le front consomme) : ```jsonc { "count": 6045, "lieux": [ { "id": "1", "nom": "...", "lat": 45.941205, "lon": -0.954939, "photos": ["..."], "equipements": ["Acces handicape","Camping-car","Parking","..."], // = equipementsActifs "note_avg": 4.0, "note_count": 1 } ] } ``` Projection Mongo → objet liste (mapping `_id→id`, `latitude→lat`, etc.) fait dans la couche service. ### 5.2 `GET /api/lieux/:id` Détail (ajoute `description`). `404` si l'id n'existe pas. ```jsonc { "id":"1","nom":"...","description":"...","lat":45.94,"lon":-0.95, "photos":["..."],"equipements":["Parking","Wc","..."], "note_avg":4.0,"note_count":1 } ``` ### 5.3 `GET /api/lieux/:id/notes` (équivalent `note.php?id=`, GET) ```jsonc { "id": "1", "count": 1, "average": 4.0 } ``` ### 5.4 `POST /api/lieux/:id/notes` (équivalent `note.php`, POST) Body JSON : `{ "note": 4 }` (entier **1–5**). - `400` si `id` non numérique (`/^\d+$/`) ou `note` hors [1,5]. - Insère `{ lieuId, note, date: new Date() }` dans `notes`, **recalcule** `average`/`count`, met à jour `noteAvg`/`noteCount` sur le doc `lieux`, renvoie : ```jsonc { "id": "1", "count": 2, "average": 4.5 } ``` > `average` = moyenne arrondie à **2 décimales**, `null` si aucun avis (identique > au PHP). ### 5.5 `GET /api/equipements` Renvoie la liste `EQUIPEMENTS` (§3.4) pour piloter la toolbar sans la coder en dur. ```jsonc [ { "key": "Table & banc", "emoji": "🪑" }, { "key": "Wc", "emoji": "🚻" }, ... ] ``` ### 5.6 (Optionnel) Proxys géocodage / routing Le prototype appelle Photon / Nominatim / OSRM **directement** depuis le navigateur. On peut le **garder tel quel** en v2 (simple) ou proxifier via `/api` pour respecter les quotas et ajouter du cache : - `GET /api/geocode?q=...&kind=auto|exact` → Photon (autocomplete) / Nominatim (résolution). - `GET /api/route?profile=car|bike&coords=lon,lat;lon,lat[;...]` → OSRM, applique le `durationFactor` (car 0.9 / bike 1.0) et le **fallback d'endpoints** (§7.2). > Recommandation : commencer **sans proxy** (appels directs, comme aujourd'hui), > ajouter le proxy plus tard si les quotas posent problème. ### 5.7 (Optionnel) `POST /api/admin/grab` Déclenche un grab manuel (protégé par `ADMIN_TOKEN`). Utile pour le premier remplissage et les tests. --- ## 6. Frontend statique (`./public`) Le `index.php` actuel mélange **rendu serveur** (le `foreach` PHP qui construit `$lieux` et l'injecte dans `const lieux = …`) et **frontend** (Leaflet, filtres, itinéraire). En v2 on **sépare** : - Le PHP disparaît : `public/index.html` est une page statique. - Le bloc `const lieux = ` est remplacé par un **`fetch('/api/lieux')`** au démarrage. - La toolbar (aujourd'hui rendue par le `foreach` PHP sur `$equipements_importants`) est construite en JS depuis `GET /api/equipements` (ou une constante partagée). - Les appels `note.php` deviennent `/api/lieux/:id/notes`. - **Tout le reste du JS est repris tel quel** : Leaflet + markercluster, Turf, autocomplete Photon, `computeRoute`, filtre temporel, permalinks (`history.replaceState`). Aucune logique métier ne change. ### 6.1 Recherche unifiée à deux modes (une seule zone à la fois) Le prototype affiche **deux formulaires de recherche simultanément** : la barre « Lieu/ville » (haut-droite) et le panneau « Itinéraire » (bas-gauche). En v2 on les **fusionne en un panneau unique** avec une bascule ; **un seul mode est visible à la fois** : - **Mode « 🔍 Lieu »** (par défaut) : le champ de recherche lieu/ville seul (autocomplete combiné 🍽️/🏙️, cf. S2). Le formulaire itinéraire est masqué. - **Mode « 🧭 Itinéraire »** : les champs Départ / swap / Arrivée / mode / heures / slider / liste des tracés (cf. §1.6). La barre de recherche lieu est masquée. ``` ┌──────────────────────────────┐ │ [ 🔍 Lieu ] [ 🧭 Itinéraire ]│ ← segmented control (une seule zone active) ├──────────────────────────────┤ │ … contenu du mode courant … │ └──────────────────────────────┘ ``` Règles de bascule : - Un **segmented control** (2 onglets) en tête du panneau bascule le mode ; l'autre formulaire est retiré du DOM/masqué (`hidden`), il n'existe **jamais** deux champs de saisie actifs en même temps. - Le bouton **« 🧭 Itinéraire depuis ici »** d'une popup de lieu/ville (S4) bascule automatiquement en mode Itinéraire **et** pré-remplit le Départ (remplace l'ancien `setAsDeparture` qui dépliait le panneau). - Le mode courant remplace l'ancien état `itineraire-collapsed` : il est **persisté** (`localStorage 'search-mode' = 'lieu' | 'itineraire'`) et ajouté au **permalink** (`?panel=lieu|itineraire`) pour restauration au chargement (I13). - Passer d'un mode à l'autre **ne réinitialise pas** l'état de l'autre : les champs Départ/Arrivée et le tracé calculé sont conservés (juste masqués), donc revenir en mode Itinéraire réaffiche le dernier itinéraire. De même, un itinéraire actif **continue de filtrer les markers** même en mode Lieu (le filtrage §1.6 I10/I11 n'est pas lié à la visibilité du formulaire). Impact sur le code repris de `index.php` : - Les blocs `#search` et `#itineraire` deviennent deux panneaux enfants d'un même conteneur `#searchPanel` ; on supprime `#btnCollapse`/`#btnExpand` au profit du segmented control. - `setupAutocomplete` reste inchangé ; on l'initialise sur les trois champs comme avant (le masquage n'empêche pas l'init). - `restoreItineraireFromURL()` lit en plus `?panel=` pour choisir le mode initial ; si `from`/`to` sont présents dans l'URL, on force le mode Itinéraire. `public/` : ``` public/ index.html # ex-index.php, sans PHP ; + toolbar + panneau itinéraire + #map app.js # tout le