# Guide de lecture du portail

<EnBref
  pourQui="Toute personne qui arrive sur le portail, et toute personne qui veut y ajouter une page."
  contenu="L'organisation des onglets, la façon de lire une page, quatre gabarits de page prêts à copier et un parcours de lecture pour chaque profil."
  donnees="Aucune donnée : cette page décrit le portail lui-même."
  maj="09/11/2026, à revoir quand un onglet est ajouté."
/>

Le portail rassemble beaucoup de pages : plus de 150. Ce guide explique comment elles s'articulent, ce que vous trouverez en haut et en bas de chacune, et par où commencer selon votre rôle dans l'équipe.

## Organisation du portail

```mermaid
flowchart TB
  accTitle: Organisation des onglets du portail
  accDescr: L'onglet Hackathon mène aux Problématiques. Chaque problématique renvoie vers DataViz, Sites, Analyses et Données supplémentaires. DataViz et Analyses s'appuient sur les Données du SSP Cloud. Les Sites puisent dans les Données du SSP Cloud et les Données supplémentaires. Codes et API donne les scripts pour charger les données du SSP Cloud et les sources supplémentaires.
  H["Hackathon<br/>cadre, experts, guide, glossaire"] --> P["Problématiques<br/>P1 à P5 et propositions de projets"]
  P --> V["DataViz<br/>données croisées par problématique"]
  P --> S["Sites<br/>6 fiches d'exemple et 2 872 sites"]
  P --> A["Analyses<br/>29 analyses de valeurs"]
  P --> X["Données supplémentaires<br/>76 sources publiques vérifiées"]
  V --> D["Données SSP Cloud<br/>748 fichiers décrits"]
  A --> D
  S --> D
  S --> X
  C["Codes et API<br/>scripts R, IGN, accès S3"] --> D
  C --> X
```

<CommentLire>
Les flèches vont de la question vers la donnée. On part en haut d'une problématique, on descend vers les visualisations et les analyses, puis vers les fichiers qui les alimentent. Codes et API, en bas, sert à charger ces fichiers.
</CommentLire>

| Onglet | La question à laquelle il répond | Commencer par |
|---|---|---|
| Hackathon | Quel est le cadre, qui peut m'aider ? | [Présentation](/hackathon) |
| Problématiques | Sur quoi travailler ? | [Les cinq problématiques](/problematiques) |
| DataViz | Que disent les données, croisées par problématique ? | [Vue d'ensemble](/dataviz) |
| Sites | Que sait-on d'un site précis ? | [Sites d'exemple](/sites) |
| Analyses | Quelles valeurs a-t-on déjà lues dans les fichiers ? | [Vue d'ensemble](/analyses) |
| Données SSP Cloud | Que contient chaque fichier fourni ? | [Vue d'ensemble](/donnees-ssp) |
| Données supplémentaires | Quelles sources publiques ajouter ? | [Par où commencer](/sources/par-ou-commencer) |
| Codes et API | Comment charger les données ? | [Codes et API](/codes) |

<CommentLire>
Une ligne par onglet du menu du haut. La colonne du milieu dit à quoi sert l'onglet ; la dernière donne la page d'entrée conseillée.
</CommentLire>

## Comment lire une page

Les pages suivent toutes le même ordre de lecture. Quatre repères reviennent.

1. **En haut, l'encadré « En bref ».** Il dit en quatre lignes pour qui est la page, ce qu'elle contient, quelles données elle utilise et quand elle a été mise à jour. S'il ne vous concerne pas, passez à la page suivante.
2. **Le contenu**, découpé en sections courtes, avec des titres qui posent une question ou annoncent un résultat.
3. **Sous chaque graphique ou tableau, « Comment lire ».** Une ou deux phrases qui disent ce que représente chaque axe, chaque couleur ou chaque colonne, et la source (le fichier du bucket).
4. **En bas, la section « Limites ».** Ce que les données ne permettent pas de dire, et les précautions avant de réutiliser un chiffre.

Voici à quoi ressemblent ces repères :

<EnBref
  titre="En bref (exemple)"
  pourQui="Data scientists qui travaillent sur P2."
  contenu="La saisonnalité des passages sur les sentiers des ENS."
  donnees="Fréquentation/Compteurs ENS (bucket SSP Cloud)."
  maj="09/11/2026."
/>

<CommentLire>
Exemple : chaque barre est un mois ; sa hauteur est le nombre moyen de passages par jour. Source : fichier des compteurs du bucket.
</CommentLire>

<Limites titre="À garder en tête (exemple)">
- Un compteur compte des passages, pas des personnes.
</Limites>

### Les conventions du portail

| Repère | Ce qu'il signifie |
|---|---|
| **(déduit)** | Valeur calculée ou estimée à partir des données (ratio, moyenne, projection), pas lue telle quelle. À vérifier avant de la citer. |
| **interprété** | Lecture ou proposition de l'équipe du portail, pas un fait mesuré. |
| <Src n={26} /> | Pastille d'une source supplémentaire : le titre s'affiche au survol, le clic ouvre sa fiche. |
| <Problems ids="P2" labels={false} /> | Problématique concernée ; le clic ouvre sa page. |
| <Terme mot="ENS" /> | Mot défini dans le [glossaire](/hackathon/glossaire) : définition au survol ou au clavier, Échap pour la masquer. |
| Source : `dossier/fichier` | Chemin du fichier dans le bucket du SSP Cloud ; voir [Données SSP Cloud](/donnees-ssp). |

<CommentLire>
À gauche le repère tel qu'il apparaît dans les pages, à droite sa signification. Ces repères ont le même sens partout.
</CommentLire>

## Les quatre gabarits de page

Pour ajouter une page, copiez le gabarit qui correspond, puis remplacez les textes entre crochets. Chaque gabarit respecte l'ordre de lecture commun. Les composants `EnBref`, `CommentLire`, `Limites`, `Parcours` et `Terme` sont disponibles dans toutes les pages `.mdx` sans import. Dans un fichier `.md`, qui n'accepte pas les composants, utilisez l'encadré `:::info{title="En bref"}`.

### 1. Page de données

Pour décrire un fichier ou une famille de fichiers du bucket (onglet Données SSP Cloud).

````mdx
---
title: "[Nom de la famille de données]"
sidebar_label: "[Libellé court]"
sidebar_icon: "database"
description: "[Une phrase : ce que contiennent les fichiers et à quoi ils servent.]"
---

<EnBref
  pourQui="[Data scientists, développeurs…]"
  contenu="[Les fichiers, leurs colonnes, leur période et un exemple de chargement.]"
  donnees="[Dossier du bucket, par exemple Fréquentation/…]"
  maj="[JJ/MM/AAAA]"
/>

[Deux ou trois phrases : d'où viennent les données, qui les produit, ce qu'elles mesurent.]

## Les fichiers

| Fichier | Lignes | Période | Granularité |
|---|---:|---|---|
| `[dossier/fichier.csv]` | [12 345] | [2021-2025] | [commune, jour] |

<CommentLire>
[Une ligne par fichier. « Granularité » dit à quel niveau chaque ligne se situe.]
</CommentLire>

## Les colonnes

| Colonne | Type | Exemple | Sens |
|---|---|---|---|
| `[code_insee]` | texte | 38185 | [Code de la commune] |

<CommentLire>
[Comment repérer la clé de jointure et les colonnes utiles.]
</CommentLire>

## Charger les données

```python
import duckdb
duckdb.sql("SELECT * FROM '[fichier.parquet]' LIMIT 5")
```

## Pièges

- [Encodage, doublons, codes de communes anciens…]

## Limites

<Limites>
- [Ce que ces données ne couvrent pas : période, territoire, unité.]
</Limites>
````

### 2. Fiche de site

Pour un site touristique (onglet Sites). Ces fiches sont des fichiers `.md` : l'encadré « En bref » s'écrit avec `:::info`. Le bloc entre les marqueurs `AUTO` est rempli par le script de génération : ne rien écrire dedans à la main.

````md
---
title: "[Nom du site]"
sidebar_label: "[Nom court]"
sidebar_icon: "map-pin"
description: "[Type de site, enjeu principal. Toute la donnée disponible et un plan de recherche.]"
site_key: "[cle-du-site]"
---

:::info{title="En bref"}
- **Pour qui** : [équipes qui travaillent sur P1, P3…]
- **Ce que vous trouverez** : fiche d'identité, enjeux de flux, données du SSP Cloud, sources publiques, plan de recherche.
- **Données utilisées** : [fichiers du bucket, BD TOPO, API Géo, sources publiques].
- **Mise à jour** : [JJ/MM/AAAA] ; bloc « Données du SSP Cloud » régénéré par script.
:::

[Deux phrases de présentation.]

## Fiche d'identité

| | |
|---|---|
| **Type** | [Lac, station, monument…] |
| **Commune** | [Nom (code INSEE), habitants] |
| **Centre** | [latitude N ; longitude E (source)] |
| **Accès** | [Route, transports en commun] |

## Enjeux de flux

- [Enjeu, rattaché à une problématique P1 à P5.]

<!-- AUTO:donnees-ssp:START -->
<!-- AUTO:donnees-ssp:END -->

## Plan de recherche

1. **[Question]**
   Données : [fichiers]. Livrable : [carte, indicateur…].

## Manques et à qui les demander

- **[Donnée manquante]** : [organisme ou expert].

## Limites

- [Chiffres à vérifier, période couverte, sources secondaires.]
````

### 3. Page DataViz

Pour une visualisation qui croise plusieurs fichiers autour d'une problématique (onglet DataViz). Le nom de fichier commence par un numéro pour l'ordre : `09-dataviz/[NN]-[nom].mdx`, publié à l'adresse `/dataviz/[nom]`. Les composants de visualisation disponibles sont listés dans le registre `src/components/dataviz/index.ts`.

````mdx
---
title: "[Question posée, par exemple : quand les sentiers saturent-ils ?]"
sidebar_label: "[Libellé court]"
sidebar_icon: "chart-line"
description: "[Ce que la visualisation croise et pour quelle problématique.]"
---

<EnBref
  pourQui="[Équipes P2, chargés de mission…]"
  contenu="[Le croisement proposé et ce qu'il montre.]"
  donnees="[Fichier 1 du bucket ; fichier 2 du bucket]"
  maj="[JJ/MM/AAAA] ; agrégats calculés par [script]"
/>

<Problems ids="[P2]" />

## La question

[Deux phrases : ce que l'on cherche et pourquoi ces fichiers.]

## La visualisation

{/* Composant de visualisation du registre datavizComponents, ou diagramme Mermaid. */}

```mermaid
xychart-beta
  title "[Titre du graphique]"
  x-axis [jan, fev, mar]
  y-axis "[Unité]" 0 --> 100
  bar [20, 45, 80]
```

<CommentLire>
[Ce que représentent les axes, les couleurs, l'unité.] Source : `[dossier/fichier]` (bucket SSP Cloud).
</CommentLire>

## Ce qu'on en retient

- [Constat 1, avec son chiffre.]
- [Constat 2 (déduit), si le chiffre est calculé.]

## Pour aller plus loin

- [Lien vers l'analyse détaillée, la fiche de données, la problématique.]

## Limites

<Limites>
- [Période, couverture, biais de mesure.]
</Limites>
````

### 4. Page d'analyse

Pour présenter des valeurs lues dans un fichier : saisonnalité, pics, comparaisons (onglet Analyses).

````mdx
---
title: "[Thème analysé]"
sidebar_label: "[Libellé court]"
sidebar_icon: "chart-column"
description: "[Les valeurs analysées et la période.]"
---

<EnBref
  pourQui="[Data scientists, jury…]"
  contenu="[Les analyses de la page, en une phrase.]"
  donnees="[Fichiers du bucket]"
  maj="[JJ/MM/AAAA], produit par scripts/analyse_ssp.py"
/>

## [Analyse 1 : question]

**Méthode.** [Filtre, agrégation, unité.]

```mermaid
xychart-beta
  title "[Titre]"
  x-axis [2021, 2022, 2023]
  y-axis "[Unité]" 0 --> 1000
  line [400, 650, 900]
```

<CommentLire>
[Axes, unité, période.] Source : `[dossier/fichier]` (bucket SSP Cloud).
</CommentLire>

**Résultat.** [Une phrase avec le chiffre clé ; « (déduit) » s'il est calculé.]

## Limites

<Limites>
- [Données manquantes, changement de méthode de comptage, valeurs aberrantes écartées.]
</Limites>
````

## Parcours de lecture par profil

Quatre parcours, de cinq étapes chacun. Ils partent du même point, la présentation du hackathon, puis divergent selon ce que vous avez à produire.

### Data scientist

<Parcours
  titre="Parcours data scientist"
  etapes={[
    { titre: "Choisir une problématique", lien: "/problematiques", duree: "10 min", description: "Les cinq questions et leurs cas d'usage." },
    { titre: "Voir les données croisées", lien: "/dataviz", duree: "15 min", description: "Les rapprochements déjà faits entre fichiers, par problématique." },
    { titre: "Lire les analyses", lien: "/analyses", duree: "20 min", description: "Saisonnalité, pics, population présente : ce que disent déjà les valeurs." },
    { titre: "Ouvrir les fichiers", lien: "/donnees-ssp", duree: "30 min", description: "Colonnes, volumes, périodes de chacun des 748 fichiers." },
    { titre: "Éviter les pièges", lien: "/sources/pieges", duree: "10 min", description: "Les erreurs relevées dans les sources avant de s'y fier." },
  ]}
/>

### Développeur

<Parcours
  titre="Parcours développeur"
  etapes={[
    { titre: "Accéder au SSP Cloud et au dépôt", lien: "/hackathon/deposer-son-code", duree: "10 min", description: "Stockage S3, clés d'accès en variables d'environnement." },
    { titre: "Parcourir les scripts", lien: "/codes", duree: "15 min", description: "Un script par API : authentification et paquets nécessaires." },
    { titre: "Charger les transports", lien: "/codes/transport-data-gouv", duree: "20 min", description: "Catalogue des jeux GTFS et temps réel couvrant l'Isère." },
    { titre: "Ajouter les fonds de carte", lien: "/codes/ign", duree: "15 min", description: "BD TOPO, géocodage, serveurs MCP de l'IGN." },
    { titre: "Outils d'accès aux données", lien: "/sources/outils-d-acces-aux-donnees", duree: "15 min", description: "API data.gouv.fr, exports Parquet, API Géo." },
  ]}
/>

### Chargé de mission tourisme

<Parcours
  titre="Parcours chargé de mission tourisme"
  etapes={[
    { titre: "Comprendre les problématiques", lien: "/problematiques", duree: "10 min", description: "Ce que les territoires attendent du hackathon." },
    { titre: "Ouvrir la fiche d'un site connu", lien: "/sites", duree: "15 min", description: "Lac de Paladru, Bastille, Les 2 Alpes… et toute la donnée disponible." },
    { titre: "La grille Optimum touristique", lien: "/sites/optimum-touristique", duree: "10 min", description: "Les trois dimensions pour juger d'un niveau de fréquentation." },
    { titre: "Regarder les visualisations", lien: "/dataviz", duree: "15 min", description: "Les croisements de données, lisibles sans code." },
    { titre: "Vérifier un mot", lien: "/hackathon/glossaire", duree: "5 min", description: "Les sigles du portail expliqués simplement." },
  ]}
/>

### Jury

<Parcours
  titre="Parcours jury"
  etapes={[
    { titre: "Le cadre du hackathon", lien: "/hackathon", duree: "5 min", description: "Organisateur, territoire, ressources mises à disposition." },
    { titre: "Les cinq problématiques", lien: "/problematiques", duree: "10 min", description: "Les questions auxquelles les équipes répondent." },
    { titre: "Les projets proposés", lien: "/propositions", duree: "10 min", description: "Six projets réalisables en deux jours, avec leurs pièges." },
    { titre: "Ce que montrent déjà les données", lien: "/dataviz", duree: "10 min", description: "Pour situer les résultats présentés par les équipes." },
    { titre: "Les données disponibles", lien: "/hackathon/donnees-fournies", duree: "5 min", description: "Pour juger de ce qui était faisable avec les données fournies." },
  ]}
/>

<CommentLire>
Chaque parcours se lit de haut en bas. Le numéro donne l'ordre conseillé, le badge une durée indicative de lecture. Le titre de chaque étape est un lien vers la page.
</CommentLire>

## Limites

<Limites>
- Les durées sont indicatives : elles supposent une lecture rapide, sans manipuler les données.
- Les pages générées par script (Données SSP Cloud, Analyses, blocs `AUTO` des fiches de sites) suivent le gabarit au fil de leur régénération ; certaines anciennes pages n'ont pas encore tous les repères.
- Les gabarits décrivent une structure ; ils ne remplacent pas la relecture par un expert du domaine.
</Limites>