# Architecture : paquets, contrat, stockage

::::summary{title="En bref" audience="Développeurs." reading="7 min" updated="12 novembre 2026"}

Les paquets et leurs couches, la règle qui les garde, le contrat du domaine, le style séparé, ce qui reste sur l'appareil, ce qui est publié, le routage.

:::details[Données utilisées]
Aucune ; cette page décrit le code.
:::

::::

<ARetenir illustration="/matching/illustrations/mode-transport.svg" titre="Ce qu'il faut retenir">
- **Tout le code est dans des paquets** (`packages/*`), rangés en couches ; les applications `app/` et `widget/` ne sont plus que des coquilles (environ 120 lignes dans `app/src/`, 36 dans `widget/src/`, tests à part).
- **Un paquet n'importe que les couches en dessous de lui** ; un gardien, lancé par `pnpm check` avant chaque envoi, refuse tout écart.
- **Un contrat unique**, `packages/core/src/types.ts`, et **un seul paquet touche au stockage du navigateur** : `@flux/stockage`. Rien n'est envoyé à un serveur.
</ARetenir>

## Le monorepo

L'application, le widget, leurs paquets et Storybook partagent un espace pnpm à la racine du dépôt (`pnpm-workspace.yaml` : `app`, `widget`, `packages/*`, `storybook`).
Le portail de documentation `docs/` a son propre espace et n'en fait pas partie ; il héberge pourtant cette documentation (`docs/04-plutotla/`).

**Règle d'or** : une application ne contient que ce qui la rend déployable (point d'entrée, assemblage des routes, thème, fichiers publics, configuration de build et de déploiement). Aucun écran, aucun calcul, aucun accès au stockage.

À la racine : `app/` et `widget/` (les deux coquilles), `packages/` (les douze paquets), `storybook/`, les deux gardiens `scripts/check-styles.mjs` et `scripts/check-architecture.mjs`, et les fichiers de configuration communs.

<details>
<summary>L'arborescence complète du dépôt</summary>

```
/
├── app/                       @flux/app : les coquilles des deux applications (publique : PWA + Tauri ; gestionnaire)
│   ├── src/App.tsx            routeur par fragment (#/…) sur les routes de routes.tsx
│   ├── src/routes.tsx         application publique : routesVisiteur + itinéraires (galerie, récit, Composer)
│   ├── src/main.tsx           styles du design system, <ThemeEclaireurs>, service worker
│   ├── src/stockages.ts       stockages communs aux deux applications (même origine, mêmes données locales)
│   ├── gestion/index.html     page de l'application du gestionnaire (construite dans dist/gestion/)
│   ├── src/gestion/           sa coquille : routes.tsx (espace gestionnaire + éditeur des sorties + projection), main.tsx
│   ├── public/, scripts/icones/, src-tauri/, vercel.json, vite.config.ts
├── widget/                    @flux/widget-app : la coquille du site du widget
│   ├── src/App.tsx            routeur par chemin : routesWidget
│   ├── src/main.tsx           styles, <ThemeEclaireurs>
│   ├── src/embed.ts           entrée du script d'intégration : réexporte @flux/widget/embed
│   ├── public/examples/, scripts/, vercel.json, vite.config.ts
├── packages/
│   ├── core/                  @flux/core : contrat (types.ts) et logique pure ; visiteur/, gestion/, services/, partenaires/
│   ├── data/                  @flux/data : jeu, index léger, services, climat, jeu compact ; script Python ; zod ; météo
│   ├── design-system/         @flux/design-system : palette, jetons (tokens.css), thème Mantine, polices
│   ├── illustrations/         @flux/illustrations : Éclaireurs, plaquettes, jeu des goûts (SVG + composants)
│   ├── ui/                    @flux/ui : composants génériques sur Mantine, un dossier par composant ; encodeur QR (@flux/ui/qr)
│   ├── stockage/              @flux/stockage : clés plutot-la:*, saisies, profils, appareil, « Mon lieu », sauvegarde, partage, partenaires
│   ├── widget/                @flux/widget : moteur du widget, composant WidgetPlutotLa, élément <plutot-la-widget> (sans Mantine)
│   ├── visiteur/              @flux/visiteur : écrans visiteur, profil et jeu des goûts, contexte, routesVisiteur
│   ├── gestionnaire/          @flux/gestionnaire : écrans et composants gestionnaire, contexte, routesGestionnaire
│   ├── projection/            @flux/projection : deux téléphones côte à côte (#/projection du gestionnaire)
│   ├── widget-editeur/        @flux/widget-editeur : accueil, éditeur, exemples, page partenaire, routesWidget
│   └── itineraires/           @flux/itineraires : sorties composées (galerie, récit sur carte, « Composer le mien », éditeur)
├── storybook/                 @flux/storybook : Storybook 10 (histoires des paquets, écrans, composants du portail)
├── scripts/check-styles.mjs   gardien du « CSS séparé »
├── scripts/check-architecture.mjs   gardien des couches
├── interne/plans/plan-packages.md           plan de l'architecture en paquets
├── AGENTS.md                  règles de contribution (applications et paquets)
├── biome.json, lefthook.yml, tsconfig.base.json, vitest.config.ts, pnpm-workspace.yaml
└── docs/                      portail de documentation du hackathon (espace séparé)
    └── 04-plutotla/           cette documentation (onglet « Plutôt là », route /plutotla)
```

</details>

## Les couches

Les paquets sont rangés en couches, de bas en haut. Un paquet n'importe qu'un paquet d'une couche **en dessous** de la sienne, jamais une application, jamais un autre paquet « fonctionnalité ».

```mermaid
flowchart BT
  accTitle: Les couches des paquets de Plutôt là
  accDescr: De bas en haut. Domaine, pur et sans React : core, puis data qui dépend de core. Interface : le design system, les illustrations et ui, qui dépend des deux autres. Services : stockage, seul paquet qui touche au stockage du navigateur, au-dessus de core et data. Intégration : widget, le script posé chez les partenaires, sans Mantine, au-dessus de stockage. Fonctionnalités : visiteur, gestionnaire, projection, éditeur du widget et itinéraires, qui ne s'importent pas entre eux. En haut, les coquilles : app assemble l'application publique (visiteur et itinéraires), app/gestion celle du gestionnaire (gestionnaire, projection, éditeur des sorties) ; widget assemble l'éditeur du widget et le script d'intégration.
  subgraph APPS["Applications (coquilles)"]
    APP["app/<br/>publique : PWA + Tauri"]
    GAPP["app/gestion/<br/>gestionnaire"]
    WAPP["widget/<br/>site du widget"]
  end
  subgraph FONC["Fonctionnalités (React)"]
    VIS["@flux/visiteur"]
    GES["@flux/gestionnaire"]
    PRO["@flux/projection"]
    EDI["@flux/widget-editeur"]
    ITI["@flux/itineraires"]
  end
  subgraph INT["Intégration (sans Mantine)"]
    WID["@flux/widget"]
  end
  subgraph SER["Services"]
    STO["@flux/stockage"]
  end
  subgraph INTF["Interface"]
    UI["@flux/ui"]
    ILL["@flux/illustrations"]
    DS["@flux/design-system"]
  end
  subgraph DOM["Domaine (pur, sans React)"]
    DATA["@flux/data"]
    CORE["@flux/core"]
  end
  APP --> VIS
  APP --> ITI
  GAPP --> GES
  GAPP --> PRO
  GAPP --> ITI
  WAPP --> EDI
  WAPP --> WID
  VIS --> STO
  GES --> STO
  ITI --> STO
  EDI --> WID
  VIS --> UI
  GES --> UI
  PRO --> UI
  EDI --> UI
  ITI --> UI
  WID --> STO
  STO --> DATA
  UI --> ILL
  UI --> DS
  UI --> CORE
  ILL --> CORE
  DATA --> CORE
```

:::howto{caption="Source : package.json de chaque paquet, table COUCHES de scripts/check-architecture.mjs"}
Une flèche va d'un paquet vers une couche dont il dépend ; seules les flèches principales sont dessinées (un paquet fonctionnalité lit aussi core, data, le design system et les illustrations). Le widget d'intégration ne dépend ni de `@flux/ui` ni de Mantine : il est posé dans le site d'un partenaire.
:::

## Le gardien de l'architecture

`scripts/check-architecture.mjs` est lancé par `pnpm check`, donc par le crochet git avant chaque envoi. Il échoue si :

| Règle | Ce qui est refusé |
| --- | --- |
| 1 | un fichier de `packages/` importe `app/` ou `widget/`, ou un chemin relatif qui sort de son paquet (on importe `@flux/<paquet>` et les `exports` de son `package.json`) |
| 2 | un paquet dépend d'une couche au-dessus de la sienne, d'un autre paquet « fonctionnalité » ou d'un paquet absent de la table des couches |
| 3 | une coquille dépasse 300 lignes (`app/src/` hors de `app/src/gestion/`, `app/src/gestion/`, `widget/src/`), ou contient un dossier `ecrans/`, `logique/` ou `composants/` |
| 4 | un fichier hors de `@flux/stockage` appelle `localStorage`, `sessionStorage` ou `indexedDB` |
| 5 | `@flux/widget` dépend de Mantine, directement ou par un autre paquet |
| 6 | le portail (`docs/src`, `docs/scripts`) recopie une fonction du service unique `@flux/core/services`, ou lit `packages/*/src` ailleurs que dans `docs/scripts/matching/build_moteur.mjs` |

:::howto{caption="Source : scripts/check-architecture.mjs, interne/plans/plan-packages.md"}
Les exceptions sont écrites dans le script, chacune avec sa raison : les tests de `@flux/core` lisent le vrai jeu de `packages/data` par un chemin relatif, les tests relisent le stockage du navigateur de test, et le design system efface une ancienne clé de Mantine au démarrage.
:::

## Les paquets

Douze paquets : deux pour le domaine (`core`, `data`), trois pour l'interface (`design-system`, `illustrations`, `ui`), un service (`stockage`), un d'intégration (`widget`) et cinq fonctionnalités (`visiteur`, `gestionnaire`, `projection`, `widget-editeur`, `itineraires`).

<details>
<summary>Le détail des douze paquets : couche, contenu, entrées</summary>

| Paquet | Couche | Contenu | Entrées (`exports`) |
| --- | --- | --- | --- |
| `@flux/core` | domaine | le contrat (`types.ts`) et toute la logique pure, testée : affluence, alternatives, itinéraires, expériences, profils ; l'état de l'adresse et les communes du visiteur ; la logique du gestionnaire (anticiper, estimations, itinéraires bis, signalements, avis) ; le service unique « une demande, une réponse » ; le contrat et les préréglages des partenaires du widget | `.`, `./visiteur`, `./gestion`, `./services`, `./partenaires`, `./declarations` |
| `@flux/data` | domaine | le jeu de données embarqué, l'index léger, les services, la climatologie, la météo, le jeu compact du portail. Voir les [données](/plutotla/donnees) | `.`, `./leger` (code des applications), `./compact` (portail, sans zod) |
| `@flux/design-system` | interface | `ThemeEclaireurs`, `theme`, palette, jetons `--ecl-*`, contrastes, points de rupture, polices | `.`, `./styles.css`, `./tokens.css` |
| `@flux/illustrations` | interface | Éclaireurs, plaquettes des questions, jeu des goûts, illustrations par type de sortie | `.`, `./svg/*` |
| `@flux/ui` | interface | composants génériques sur Mantine, un dossier par composant (dont graphiques et champs de l'espace gestionnaire), encodeur QR sans dépendance | `.`, `./qr`, `./styles.css` |
| `@flux/stockage` | services | le **seul** paquet qui touche au stockage du navigateur : liste unique des clés, `stockageNavigateur`, `profilsLocaux`, appareil, cache météo, « Mon lieu », sauvegarde (export et import), partage du profil de groupe, partenaires du widget, sorties composées | `.`, `./cles`, `./sauvegarde`, `./partage`, `./partenaires`, `./sorties` |
| `@flux/widget` | intégration | moteur du widget (résumé d'un lieu), composant `WidgetPlutotLa`, élément `<plutot-la-widget>` en Shadow DOM, code d'intégration ; **sans Mantine** | `.`, `./embed`, `./composant`, `./exemple`, `./moteur`, `./snippet` |
| `@flux/visiteur` | fonctionnalité | écrans visiteur, profil et jeu des goûts, contexte, hooks de carte, `routesVisiteur` et `creerRoutesVisiteur` | `.` |
| `@flux/gestionnaire` | fonctionnalité | écrans et composants gestionnaire, contexte, `routesGestionnaire` et `creerRoutesGestionnaire` (écrans chargés à la demande), coquille seule pour les écrans d'un autre paquet | `.` (routes), `./ecrans`, `./cadre` |
| `@flux/projection` | fonctionnalité | page de démonstration « deux téléphones » | `.` |
| `@flux/widget-editeur` | fonctionnalité | accueil du site du widget, éditeur des partenaires, exemples, page d'un partenaire, `routesWidget` | `.` (routes), `./ecrans` |
| `@flux/itineraires` | fonctionnalité | sorties composées : galerie, récit défilant sur une carte, « Composer le mien », éditeur du gestionnaire | `.`, `./routes` |

:::howto{caption="Source : packages/*/package.json et packages/*/src/index.ts"}
Une ligne par paquet, de bas en haut. Un paquet fonctionnalité exporte des routes et des écrans, jamais un routeur : l'application choisit le sien (par fragment pour `app/`, par chemin pour `widget/`).
:::

</details>

Conventions d'un paquet : un `package.json` avec des `exports` explicites, un `src/index.ts`, aucune étape de compilation (Vite et Vitest lisent le TypeScript), les tests à côté du code (`*.test.ts`, `*.test.tsx`), un `.module.css` à côté de chaque composant ou écran, des histoires Storybook pour chaque composant et chaque écran.

**Écrans dans Storybook** : la rubrique « Écrans » montre les vraies routes de `@flux/visiteur`, `@flux/gestionnaire` et `@flux/widget-editeur` (fichiers `Ecrans.stories.tsx` de chaque paquet), en téléphone et en ordinateur, avec le jeu embarqué. L'heure est fixée et la météo est la climatologie du lieu, pour des captures reproductibles.

<details>
<summary>Autres exports de @flux/core</summary>

Besoins d'accès : `evaluerAccesSite`, `evaluerAccesExperience`, `experiencesAdaptees`, `BESOINS_ACCES`, `LIBELLES_BESOIN`, `AVERTISSEMENT_ACCES`. Modules `profil` (`AXES_GOUT`, `QUESTIONS_LUDIQUES`, `profilDepuisChoix`, `agregerGroupe`), `apprentissage` (`mettreAJourProfil`, `expliquerProfil`), `identite` (`identiteDuLieu`, `offreDuLieu`), `personnalisation` (`proposerPersonnalise`, `proposerBouquet`, `planifierBouquet`, `evaluerServices`), `moments` (`momentAlternatif`, `calendrier14Jours`, `urlOpenMeteo`), `circuits` (`construireCircuit`), et dans `alternatives` : `garantirEnvies`, `couvertureEnvies`, `estGardeePourEnvie`, `risqueDeRebond`, `varierOrdre`, `separerMemeEndroit`.

</details>

<details>
<summary>Versions des outils et dépendances</summary>

Les paquets exposent leur source TypeScript directement (`"exports": { ".": "./src/index.ts" }`) : pas d'étape de compilation entre paquets, Vite et Vitest lisent le TypeScript.

Le QR code est encodé par `@flux/ui` lui-même (`packages/ui/src/qr/`), et Open-Meteo est appelé avec `fetch`. Versions (catalogue de `pnpm-workspace.yaml`) : React 19.3, React Router 8.5, Vite 8.3, TypeScript 6.0, Vitest 5.1, zod 4.6, Biome 2.6, Tauri 2.12, happy-dom 21, Mantine 9.7.5 (`@mantine/core`, `@mantine/hooks`), `postcss-preset-mantine`, Storybook 10.6.6, polices `@fontsource-variable/fredoka` et `@fontsource-variable/nunito`.

</details>

## Le contrat du domaine

`packages/core/src/types.ts` est **le** contrat. Les paquets l'implémentent (core), le remplissent (data) ou l'affichent (ui, app) ; il ne change que sur décision, car tout le reste en dépend.

```mermaid
classDiagram
  accTitle: Les types principaux du contrat
  accDescr: Le jeu de données contient des sites, des expériences, des profils, des alternatives conseillées, un calendrier, des sources et la climatologie des stations. Un site a un identifiant de lieu, des compteurs proches qui pointent vers un profil et des services relevés autour de lui. Une demande de visite vise un site et peut nommer son départ. Une estimation peut porter un signalement, qui a une date de création et de levée. Une alternative contient un site, une estimation et des expériences. Un itinéraire a des étapes. Le stockage garde signalements, itinéraires bis et avis.
  class JeuDeDonnees {
    version
    genereLe
    sites : Site[]
    experiences : Experience[]
    profils : ProfilAffluence[]
    alternativesConseillees
    calendrier
    sources
    climat
  }
  class Site {
    id, lieuId, nom, categorie, type
    commune, insee, position, precision
    surfrequente, itineraireBis
    arretsTc, parkings, scoreDonnees, sources
    services
  }
  class ServicesSite {
    rayonM, toilettes, bancs, eau, jeux
    ombre, fauteuil, chiens, source
  }
  class CompteurProche {
    id, nom, distanceM
    profilId
    confiance
  }
  class ProfilAffluence {
    mois[12], jourSemaine[7], heure[24]
    vacances, source, jours
  }
  class DemandeVisite {
    siteId, date, heure, groupe
    mode, depart, departLibelle, envies
    besoins
  }
  class EstimationAffluence {
    niveau, indice, raisons, confiance
  }
  class Signalement {
    siteId, niveau, motif, auteur
    debut, fin, creeLe, leveLe
  }
  class Alternative {
    distanceKm, dureeMin, similarite
    score, raisons, conseilleeParOffice
  }
  class Itineraire {
    mode, distanceKm, dureeMin
    liens, coucherDuSoleil
  }
  class Stockage {
    <<interface>>
    signalements
    itinerairesBis
    avis
    exporter()
    importer()
  }
  JeuDeDonnees "1" --> "*" Site
  JeuDeDonnees "1" --> "*" ProfilAffluence
  JeuDeDonnees "1" --> "*" Experience
  Site "1" --> "*" CompteurProche
  Site --> ServicesSite : services
  Site --> Site : lieuId
  CompteurProche --> ProfilAffluence : profilId
  DemandeVisite --> Site : siteId
  EstimationAffluence --> Signalement : si signalée
  Alternative --> Site
  Alternative --> EstimationAffluence
  Alternative --> "*" Experience
  Itineraire --> "*" EtapeItineraire
  Stockage --> "*" Signalement
  Stockage --> "*" ItineraireBis
  Stockage --> "*" Avis
```

:::howto{caption="Source : packages/core/src/types.ts"}
Chaque boîte est un type de `types.ts` (champs abrégés) ; les flèches disent « contient » ou « pointe vers ». La flèche `Site → Site : lieuId` relie une entrée à l'entrée principale de son lieu.
:::

<details>
<summary>Champs du contrat ajoutés au fil du projet</summary>

| Champ | Type | Sens |
| --- | --- | --- |
| `Site.lieuId` | `string`, obligatoire | identifiant du lieu : l'`id` de l'entrée principale (le site lui-même s'il est seul). Voir les [données](/plutotla/donnees) |
| `DemandeVisite.departLibelle` | `string`, facultatif | nom du départ (« votre position », une commune), repris dans les phrases |
| `Signalement.creeLe` | `string` (ISO 8601), facultatif | instant de création du signalement |
| `Signalement.leveLe` | `string` (ISO 8601), facultatif | instant où un gestionnaire l'a levé ; la fin effective est la plus tôt de `fin` et `leveLe` |
| `BesoinAcces` | `"fauteuil" \| "malvoyant" \| "chien" \| "poussette" \| "marche-limitee"` | besoins d'accès du groupe, posés en images |
| `DemandeVisite.besoins` | `BesoinAcces[]`, facultatif | lu par `proposerAlternatives` et `itineraireDeLaDemande` ; reste sur le téléphone (fragment de l'adresse) |
| `Site.services` | `ServicesSite`, facultatif | toilettes, bancs, eau, jeux, part d'ombre, accès en fauteuil, chiens relevés autour du site, avec leur source ; une valeur absente veut dire « inconnu », jamais « non » |
| `JeuDeDonnees.climat` | `ClimatStation[]`, facultatif | normales mensuelles de 48 stations Météo-France, pour le repli sans prévision |

:::howto{caption="Source : packages/core/src/types.ts"}
Une ligne par champ ajouté au contrat. `"pedalo"` veut dire « Sur l'eau », ouvert à tous. Les règles des besoins d'accès sont sur la page [Candidats et exclusions](/matching/candidats-et-exclusions).
:::

Les autres types (profil de goûts `ProfilGouts`, groupe `ProfilGroupe` et `MembreGroupe`, carte d'identité `CarteIdentite`, prévision `PrevisionMeteo`, bouquet `BouquetExperiences`, proposition `PropositionPersonnalisee`) sont dans les modules de `@flux/core`, pas dans le contrat. Demandes ouvertes : un champ `ServicesSite.declare` unique pour « Mon lieu » et les accès vérifiés, `MembreGroupe.sante`, `Alternative.gardeePourEnvie`, `DemandeVisite.graine`.

</details>

<details>
<summary>Types énumérés, contrôle par zod, types étendus</summary>

Types énumérés : `Categorie` (5 familles), `Mode` (`pied`, `velo`, `transport`, `voiture`), `TypeExperience` (8 types, dont `pedalo` affiché « Sur l'eau »), `NiveauAffluence` (`calme`, `modere`, `charge`, `sature`), `BesoinAcces` (5 besoins).

La cohérence entre le contrat et le jeu est vérifiée deux fois : par les schémas zod au chargement, et par un test de types (`expectTypeOf`) qui échoue si un schéma s'écarte du type.

`@flux/core` rend aussi des types **étendus**, assignables au contrat : `ItineraireEstime` (avec `direct`, `jusquALArrivee`, `surPlace`, `heureDepart`, `explications`) et `EtapeEstimee` (avec `moment`, `heure`, `ecartKm`, `detourKm`). Les ajouter au contrat reste à décider.

</details>

## Stockage, aujourd'hui et demain

L'interface `Stockage` (dans le contrat) cache l'endroit où vivent les saisies : lister, enregistrer et supprimer les signalements, les itinéraires bis et les avis, puis exporter et importer le tout.

<details>
<summary>L'interface Stockage, en TypeScript</summary>

```ts
interface Stockage {
  listerSignalements(): Promise<Signalement[]>;
  enregistrerSignalement(s: Signalement): Promise<void>;
  supprimerSignalement(id: string): Promise<void>;
  listerItinerairesBis(): Promise<ItineraireBis[]>;
  enregistrerItineraireBis(i: ItineraireBis): Promise<void>;
  supprimerItineraireBis(id: string): Promise<void>;
  listerAvis(siteId?: string): Promise<Avis[]>;
  enregistrerAvis(a: Avis): Promise<void>;
  exporter(): Promise<string>;
  importer(json: string): Promise<void>;
}
```

</details>

**Sur l'appareil** : `stockageNavigateur` (`packages/stockage/src/navigateur.ts`), clé `localStorage` `plutot-la:v1`, qui contient `{ signalements, itinerairesBis, avis }`. Si le stockage est indisponible (navigation privée), les saisies restent en mémoire pour la session. Les contextes visiteur et gestionnaire relisent le stockage sur l'événement `storage` : c'est ce qui fait marcher la projection.

**Les itinéraires bis sont des sorties.** Depuis le 11 novembre 2026, ils s'éditent dans l'éditeur des sorties et sont rangés avec elles (clé `plutot-la:sorties:v1`, identifiant `bis--<site de départ>--<identifiant>`). Ce que lit le visiteur ne change pas : `listerItinerairesBis()` rend toujours des `ItineraireBis`, déduits des sorties (`packages/stockage/src/itineraires-bis.ts`). À l'ouverture de l'espace gestionnaire, `migrerItinerairesBis` (`migration-bis.ts`) range dans les sorties les itinéraires saisis à l'ancienne, sans perte : celui dont un lieu n'est plus au catalogue reste où il est.

**Les réglages publiés.** Pour atteindre tous les visiteurs sans serveur, le gestionnaire exporte ses réglages « pour publication » : un seul fichier daté (les quatre collections), envoyé à l'équipe du site. Elle relit les fichiers reçus, les fusionne (`node scripts/fusionner-reglages.mjs` : le plus récent gagne, par identifiant), dépose un fichier JSON par collection dans `app/public/reglages/` et redéploie le site. L'application les lit en lecture seule, après l'appareil (`app/src/routes.tsx`).

D'autres données vivent sur l'appareil, chacune sous sa clé : les profils (seulement après l'accord), l'identifiant de l'appareil, le cache météo, les déclarations « Mon lieu », les sorties composées et les partenaires du widget. Les profils ont une clé à part pour que l'export de l'espace gestionnaire ne contienne jamais de données de santé.

<details>
<summary>Les douze clés gardées sur l'appareil</summary>

| Clé | Contenu | Écrite par | Effacée par « Tout effacer » du visiteur |
| --- | --- | --- | --- |
| `plutot-la:v1` | signalements, avis, et les itinéraires bis saisis à l'ancienne (rangés dans les sorties à l'ouverture de l'espace gestionnaire) | interface `Stockage` | non (données des gestionnaires et avis publiés) |
| `plutot-la:profils:v1` | accord (date), goûts, groupe (besoins et santé compris) | `profilsLocaux`, **seulement après l'accord** | oui |
| `plutot-la:appareil:v1` | identifiant tiré au hasard, graine de l'anti-rebond, jamais envoyé | `appareilLocal` | oui |
| `plutotla:meteo:<lat>,<lon>` | dernière prévision Open-Meteo d'un site, avec sa date | `cacheMeteoNavigateur` | oui (garde la trace des sites consultés) |
| `plutot-la:mon-lieu:v1` | déclarations « Mon lieu » des gestionnaires, par `lieuId` | `declarationsNavigateur` (`packages/stockage/src/declarations.ts`) | non |
| `plutot-la:sorties:v1` | sorties composées créées ou modifiées dans l'éditeur des sorties, itinéraires bis compris (`bis--…`) ; l'ancienne clé `plutot-la.sorties.v1` (même format) est relue tant que la nouvelle manque, puis effacée à la première écriture | `stockageLocalSorties` (`packages/stockage/src/sorties.ts`) | non (données des gestionnaires, comprises dans l'export et l'import) |
| `plutot-la:erreurs:v1` | journal local des erreurs : 20 au plus, 7 jours au plus, sans position ni profil ([journal des erreurs](/plutotla/limites-et-suite#journal-des-erreurs)) | `installerJournalErreurs`, `noterErreur` (`packages/stockage/src/journal.ts`) | oui |
| `plutot-la:carnet:v1` | carnet des coins calmes : un tampon par lieu calme et par jour, de jour seulement, 200 au plus, sans position ; gardé sur l'appareil seulement avec l'accord du profil (sinon en mémoire, effacé à la fermeture) | `ajouterAuCarnet` (`packages/stockage/src/carnet.ts`) | oui |
| `plutot-la:langue:v1` | langue choisie (`fr` ou `en`) | `langueChoisie` (`packages/stockage/src/langue.ts`) | oui |
| `plutot-la:itineraires-bis:avant-migration:v1` | copie des itinéraires bis tels qu'ils étaient avant leur passage dans l'éditeur des sorties, jointe à l'export | `copieBisNavigateur` (`packages/stockage/src/copie-bis.ts`) | non (données des gestionnaires) |
| `plutot-la-widget:partenaires:v1` | partenaires du widget enregistrés dans l'éditeur du widget | `enregistrerPartenaire` (`packages/stockage/src/partenaires.ts`) | non |
| `plutotla-mode-couleur` | ancien choix du thème clair ou sombre : **effacé au démarrage** (plus de mode sombre) | `<ThemeEclaireurs>` | non |

:::howto{caption="Source : packages/stockage/src/cles.ts (liste unique des clés), navigateur.ts, declarations.ts, sorties.ts, partenaires.ts"}
Les profils ont une clé à part pour que l'export et l'import de l'espace gestionnaire ne contiennent jamais de données de santé (RGPD, article 9). « Tout effacer » appelle `effacerDonneesVisiteur()` : il efface les profils, l'identifiant de l'appareil, le cache météo, le journal des erreurs, le carnet et la langue choisie, et laisse ce qui appartient aux gestionnaires (saisies, « Mon lieu », sorties, partenaires du widget). Les deux préfixes (`plutot-la:` et `plutotla:`) cohabitent pour l'instant.
:::

</details>

<details>
<summary>Les réglages publiés : collections, fusion, garde-fous</summary>

| Fichier (`reglages/…`) | Contenu | Lu par |
| --- | --- | --- |
| `signalements.json` | signalements en cours ou à venir, non levés | `Stockage.listerSignalements` |
| `itineraires-bis.json` | itinéraires bis publiés | `Stockage.listerItinerairesBis` |
| `sorties.json` | sorties publiées (itinéraires bis compris) | `StockageSorties.lister` (galerie, éditeur) |
| `mon-lieu.json` | déclarations « Mon lieu » | `StockageDeclarations.lister` |

:::howto{caption="Source : COLLECTIONS_REGLAGES (packages/stockage/src/reglages.ts), exporterPourPublication et sourceFichierPublie (publie.ts)"}
Chaque fichier a la forme `{ format: "plutot-la/reglages", version: 1, collection, publieLe, documents }`. Un fichier absent, illisible ou d'un autre format ne donne aucun document ; un document invalide est écarté seul.
:::

- **Adaptateurs** : `stockageAvecReglagesPublies`, `sortiesAvecReglagesPublies` et `declarationsAvecReglagesPublies` enveloppent les stockages de l'appareil. Lecture : l'appareil d'abord, puis les documents publiés dont l'identifiant n'y est pas. Écritures, avis, export et import : l'appareil seul.
- **Source différée** (`sourceReglagesDifferee`) : le fichier n'est chargé qu'à la première lecture, puis gardé 5 minutes en mémoire ; un échec donne une liste vide et se réessaie plus tard.
- **Vérification double** : à l'export et à la lecture, avec les schémas zod de `@flux/data` ; seuls les documents publiés passent, jamais un texte avec une adresse électronique ou un téléphone. Les avis, les profils et l'appareil ne sont jamais publiés.

</details>

**Demain** : un serveur, derrière la même interface (`SourceReglages`, avec une écriture par rôle), sans toucher aux écrans.

```mermaid
flowchart LR
  accTitle: Stockage sur l'appareil, réglages publiés et cible serveur
  accDescr: Sur l'appareil, les écrans lisent et écrivent dans localStorage. Depuis le 11 novembre 2026, ils lisent aussi, en lecture seule et après l'appareil, les fichiers JSON publiés avec le site dans le dossier reglages. Plus tard, un serveur pourra remplacer ces fichiers par la même interface, avec une écriture par rôle, une connexion des gestionnaires et un journal d'audit.
  subgraph AUJ["Fait"]
    A1["Écrans"] --> A2["stockageNavigateur"] --> A3[("localStorage")]
    A1 --> A4["Adaptateurs<br/>« réglages publiés »"] --> A5[("reglages/*.json<br/>publiés avec le site")]
  end
  subgraph DEM["Cible"]
    B1["Écrans (inchangés)"] --> B2["Même interface<br/>SourceReglages"] --> B3["Serveur"]
    B3 --> B4[("Base de données")]
    B3 --> B5["Connexion des gestionnaires"]
    B3 --> B6["Journal d'audit, modération des avis"]
  end
```

:::howto{caption="Source : packages/stockage/src/reglages.ts · la cible n'est pas construite"}
À gauche, ce qui marche aujourd'hui : l'appareil passe devant le fichier publié. À droite, seul l'adaptateur changera ; les écrans appellent toujours les mêmes interfaces.
:::

Décision du 11 novembre 2026 : des **fichiers publiés** d'abord (faits et branchés), puis un **serveur dans la suite Récit**, l'outil qui fabrique ce portail, quand il en proposera un. La cible : comptes par structure (office de tourisme, gestionnaire de site, Département), droits par site ou commune, connexion par un fournisseur d'identité (<Terme mot="OIDC" />, par exemple celui du Département ou ProConnect), journal d'audit qui garde la **structure** (jamais une personne), modération et limitation des avis. Les champs `creeLe` et `leveLe` de `Signalement` sont déjà là.

## Routage

`createHashRouter` de React Router : toutes les adresses sont après `#`. Le même build marche donc à l'identique dans un navigateur, servi depuis un sous-dossier, dans la PWA et dans Tauri, sans réglage serveur.

<details>
<summary>Les adresses de l'application et leur assemblage</summary>

| Adresse | Écran |
| --- | --- |
| `#/` | Accueil visiteur |
| `#/site/:id`, `/questions`, `/affluence`, `/alternatives`, `/calendrier`, `/chemin/:versId` | Parcours visiteur ; réponses dans la requête (`?date=…&heure=…&groupe=…&mode=…&envies=…&besoins=…&depart=…&depuis=…`), plus `etape=1…7` sur l'écran des questions |
| `#/profil`, `/profil/jeu`, `/profil/groupe`, `/profil/groupe/membre/:membreId`, `/profil/groupe/contraintes`, `/profil/partager`, `/profil/importer`, `/profil/pourquoi` | « Mieux me connaître », sous la route-cadre de l'accord |
| `#/itineraires`, `/itineraires/composer`, `/itineraires/:id` | Sorties composées (visiteur) |
| Application du gestionnaire : `#/admin`, `/sites/:siteId`, `/sites/:siteId/mon-lieu`, `/itineraires`, `/itineraires/nouveau`, `/itineraires/:id`, `/avis`, `/donnees`, `/sauvegarde` | Espace gestionnaire |
| Application du gestionnaire : `#/admin/sorties`, `/admin/sorties/:id` | Éditeur des sorties et des itinéraires bis |
| Application du gestionnaire : `#/projection` | Projection mobile (grand écran) |

:::howto{caption="Source : app/src/routes.tsx, app/src/gestion/routes.tsx, routes.tsx de @flux/visiteur, @flux/gestionnaire et @flux/itineraires"}
Une ligne par groupe d'adresses. Dans l'application publique, une adresse du gestionnaire (`#/admin…`) affiche la page d'erreur du visiteur.
:::

Depuis le 11 novembre 2026, ce sont **deux applications** du même domaine, construites par le même `pnpm build` (deux passes de Vite). `app/src/routes.tsx` assemble l'application publique : `routesVisiteur` (`@flux/visiteur`) et les sorties composées (`@flux/itineraires/routes`, dans la coquille du visiteur) ; `app/src/App.tsx` en fait le routeur. `app/src/gestion/routes.tsx` assemble celle du gestionnaire, donnée aux offices de tourisme : l'espace gestionnaire avec l'éditeur des sorties (`creerRoutesGestionnaire` de `@flux/gestionnaire`), la projection (`@flux/projection`), et un renvoi vers l'application publique pour toute adresse du visiteur (« Fiche visiteur », « Voir la page visiteur »). Les deux lisent les mêmes stockages (`app/src/stockages.ts`) : sur un même appareil, les données locales sont partagées. Les fichiers construits de l'application publique ne contiennent ni `@flux/gestionnaire`, ni `@flux/projection`, ni l'éditeur des sorties. Deux paquets « fonctionnalité » ne s'importent jamais : c'est l'application qui les relie. L'accueil visiteur est hors de la route-cadre `<AttendreJeu>` (il vit sur l'index léger) ; les autres routes visiteur, dont `routesProfil`, attendent le jeu ; la route `/admin` attend `prechargerJeu()` et a sa propre page d'erreur avec « Réessayer ». Chaque espace déclare ses routes dans son paquet. L'espace visiteur exporte aussi `creerRoutesVisiteur(environnement)`, qui injecte un jeu, un stockage et une horloge pour les tests.

</details>

## Interface

L'interface est construite sur **Mantine 9** et prend le style **« Les Éclaireurs »**, tiré de l'image d'origine « Les Éclaireurs ». La présentation complète (palette, contrastes, typographie, composants, illustrations) est dans le [design system](/plutotla/design-system).

- **Trois paquets.** `@flux/design-system` porte toutes les couleurs, les jetons CSS `--ecl-*` et le thème Mantine ; `@flux/illustrations` porte les dessins ; `@flux/ui` assemble les composants. Les autres paquets ne définissent aucune couleur.
- **Un composant, un dossier** : `packages/ui/src/composants/<Nom>/` contient `Nom.tsx`, `Nom.module.css`, `Nom.stories.tsx`, `Nom.test.tsx` et `index.ts`. Les écrans des paquets fonctionnalité ont aussi chacun leur `.module.css`.
- **Le style est séparé du React.** Tout le style est dans des fichiers CSS. Sont interdits : `style={{…}}` (sauf une variable CSS calculée, `style={{ "--x": valeur }}`), les props `styles` et `sx` en objets, les « style props » de Mantine (`mt=`, `c=`…), le CSS-in-JS et toute couleur en dur hors du design system. Les variantes passent par des classes et des attributs `data-*`. Le script `scripts/check-styles.mjs` le contrôle ; `pnpm check` le lance avec `--strict`, qui refuse aussi une ombre hors élément flottant et toute règle de mode sombre.
<details>
<summary>Ordre des styles, thème clair, mobile, accessibilité, mini-carte</summary>

- **Ordre des styles** : l'entrée importe `@flux/design-system/styles.css` (Mantine dans `@layer mantine`, polices, jetons, styles globaux), puis `@flux/ui/styles.css`. Jamais `@mantine/core/styles.css` directement : hors de sa couche, Mantine passerait devant les styles du thème.
- **Toujours clair** (décision de l'équipe projet) : `<ThemeEclaireurs>` force Mantine en `light` et efface la clé `plutotla-mode-couleur` au démarrage ; aucun `prefers-color-scheme`, aucun interrupteur. `index.html` déclare `<meta name="color-scheme" content="light">` : l'ancienne valeur `light dark` expliquait probablement l'affichage sombre que personne n'avait demandé.
- **Interactif ou information** : ce qui se clique a un fond plein ou un contour 1 px (`--ecl-contour-interactif`) ; ce qui se lit est sur `--ecl-surface-info`, sans contour ; une seule ombre, `--ecl-ombre-flottant`, sous ce qui flotte. Détail : [10 · Design system](/plutotla/design-system).
- **Mobile d'abord** : conçu pour 360 à 430 px ; cibles tactiles de 48 px par défaut (44 px au moins) ; marges de sécurité iOS (`env(safe-area-inset-*)`) ; une action principale par écran, en bas.
- **Accessibilité** : contraste AA vérifié par des tests (texte 4,5:1, éléments d'interface 3:1) ; chaque carte illustrée a un libellé texte (dessin marqué décoratif) ; anneau de focus de 2 px ; mouvement réduit respecté (durées à 0) ; addon a11y de Storybook en mode erreur.
- **Mini-carte** (`MiniCarte`) : SVG sans fond de carte ni dépendance, projection locale, échelle et nord ; cible tactile de 48 px autour de chaque marqueur.
- **Choisi = soleil** : un choix sélectionné prend le fond soleil pâle `--ecl-fond-choisi`, un contour 2 px encre et une coche ; le lagon reste réservé à « calme ».

</details>

Couleurs d'affluence, tirées de l'image, du frais au chaud :

| Niveau | Icône et mot | Fond | Texte sur le fond | Dessin |
| --- | --- | --- | --- | --- |
| Calme | ✓ Calme | lagon `#2BB0AD` | encre | un Éclaireur seul |
| Modéré | − Modéré | soleil `#FFC941` | encre | trois Éclaireurs |
| Chargé | ! Chargé | corail `#FD795B` | encre | une petite foule |
| Très fréquenté (`sature`) | × Très fréquenté | rouge `#E01E1E` | papier `#FFFCF5` | une place bondée |

:::howto{caption="Source : packages/design-system/src/palette.ts et CONTRASTES.md"}
Le niveau n'est jamais porté par la couleur seule : chaque pastille a une icône et un mot, et la jauge des crans remplis. Le bloc d'affluence du résultat prend la teinte pâle du niveau (`--ecl-affluence-<niveau>-pale`), sans contour.
:::

## PWA et déploiement web

Le même build sert le web, la PWA et Tauri : chemins relatifs, un manifeste, un service worker, des icônes générées par script. Détail dans la page [Mobile](/plutotla/mobile) et, pour Vercel, dans [Développer](/plutotla/developper).

<details>
<summary>Le détail : configuration, manifeste, service worker, icônes, en-têtes</summary>

- `vite.config.ts` : `base: "./"` (chemins relatifs), pour servir le même build sur le web et dans Tauri.
- `public/manifest.webmanifest` : nom « Plutôt là », `display: standalone`, portrait, couleur crème `#FEF4E1` des Éclaireurs, icônes normales et *maskable*, raccourci vers l'espace visiteur (plus aucun vers le gestionnaire, une autre application qu'on n'installe pas).
- `public/sw.js` : service worker, un seul cache `plutot-la-v3` (changer `VERSION` force tous les appareils à repartir d'un cache vide). Il laisse passer l'application du gestionnaire, servie dans sa portée, sans la mettre en cache. Détail dans la page [Mobile](/plutotla/mobile).
- **Icônes et métadonnées** : `app/scripts/icones/generer.mjs` dessine l'Éclaireur au chapeau en autocollant sur fond encre et produit `favicon.svg` et `favicon.ico`, `icon.svg`, les PNG 192 et 512 (normaux et *maskable*), `apple-touch-icon.png`, les icônes des raccourcis, l'image de partage `og-image.png` (1 200 × 630) et `src-tauri/app-icon.png` (source de `pnpm tauri icon`). Rendu par Chrome sans tête, sans dépendance ; le script ne réécrit un fichier que si son contenu change. Usage, depuis `app/` : `node scripts/icones/generer.mjs`, puis `pnpm tauri icon src-tauri/app-icon.png`.
- `index.html` porte la description, `color-scheme: light`, la couleur du thème crème (`#FEF4E1`) et les balises Open Graph (titre, description, image) pour l'aperçu des liens partagés.
- `main.tsx` n'enregistre le service worker que dans un build web (pas en développement, pas dans Tauri).
- `vercel.json` : installation et build avec pnpm 12.15, sortie `dist`, en-têtes de cache et de sécurité. Le pas-à-pas du déploiement est dans [Développer](/plutotla/developper), section « Déployer sur Vercel ».

</details>

## Taille

Le jeu n'est pas dans le premier chargement : **457 Ko** compressés au premier chargement, contre 735 Ko avec le jeu, soit 38 % de moins.

<details>
<summary>Le détail de la mesure</summary>

L'application importe seulement `@flux/data/leger` ; l'index léger (68 Ko compressé) suffit à l'accueil, et `jeu.json` est seul dans son fichier (`jeu-*.js`, 283 Ko compressé), chargé par import dynamique en arrière-plan. Mesure du vérificateur (gzip -9 des fichiers listés dans `index.html`) : **457 Ko** au premier chargement, contre 735 Ko avec le jeu (simulation), soit 38 % de moins. Restent dans le premier chargement : zod (environ 27 Ko compressés, par `chargerServices`) et le module « Mon lieu » (environ 3 Ko). Le jeu reste sous 2 Mo (1,99 Mo) grâce à l'omission de `lieuId` quand il vaut `id` ; les services et la climatologie sont dans des fichiers à part.

</details>

## Limites

:::limits{link="/plutotla/limites-et-suite"}
- Pas de serveur : saisies, profils et cache météo restent sur l'appareil ; signalements, itinéraires bis, sorties et « Mon lieu » n'atteignent les autres téléphones qu'après un export pour publication, relu et mis en ligne par l'équipe du site.
- `stockageNavigateur.importer` écrit sans vérifier ; l'espace gestionnaire vérifie avant de l'appeler, mais d'autres appelants ne seraient pas protégés.
- Le gardien de l'architecture lit les imports par des expressions régulières : un import construit à l'exécution lui échappe.
- Les tailles de bundle viennent d'un build local, sans mesure sur un vrai réseau mobile.
- Dans la projection, le thème est appliqué aux cadres par `contentDocument` (même origine seulement) ; le lien de partage du groupe ne marcherait pas depuis Tauri (`tauri://…`).
:::
