info-canicule/CLAUDE.md

# CLAUDE.md — info-canicule

## Objectif

Site d'utilité publique qui affiche en temps réel la Vigilance Météo France par département
+ les conseils officiels (canicule, orages, vent, pluie, neige, avalanches, vagues-submersion).

Hébergé sur le VPS Nocleus partagé (réseau `shared-net`, cache Valkey ACL `info-canicule`).

## Stack

- Astro 5 SSR (`output: 'server'`, adapter `@astrojs/node` mode standalone)
- TailwindCSS 3 (via `@astrojs/tailwind`) + `@tailwindcss/typography`
- `@astrojs/sitemap` (statiques) + `src/pages/sitemap-departements.xml.ts` (les 96 dépts dynamiques)
- `@sentry/astro` opt-in via `SENTRY_DSN` (cible GlitchTip, sample 0.1, source maps non uploadées). Si DSN absent, intégration omise.
- ioredis pour le cache Valkey
- TypeScript strict
- Pas de DB Postgres (toutes les données vivent en cache Valkey, refresh à la demande)
- Tests Playwright (`tests/`, `pnpm test:e2e` / `test:e2e:local`)
- OG image générée au build par `scripts/build-og-image.mjs` (sharp, devDep)

## Sources de données

Quatre flux indépendants, tous cachés en Valkey :

- **Vigilance** (`src/lib/vigilance.ts`) — Opendatasoft `weatherref-france-vigilance-meteo-departement` (Licence Ouverte 2.0, pas d'auth, ~1 000 records par snapshot, dépts × phénomènes × échéances J/J1). Provider Météo France officiel utilisable en fallback si la clé est dispo. URL : `https://public.opendatasoft.com/api/explore/v2.1/catalog/datasets/weatherref-france-vigilance-meteo-departement/records`.
- **Observations horaires SYNOP** (`src/lib/observations.ts`) — API Météo France, station SYNOP la plus proche du centroïde du dept, pré-calculé dans `src/data/stations-synop.json`. Alimente l'onglet « 24 h » sur les pages dept.
- **Climato quotidienne** (`src/lib/climato.ts`) — fichiers CSV gzippés `data.gouv.fr/meteofrance/.../QUOT` (`latest-2025-2026` pour l'année courante, `previous-1950-2024` pour l'historique long). 365 jours glissants par dept. Cold-fetch optimisé : on skippe `previous-1950-2024` si `latest` suffit (cf. commit `ac46637`).
- **Normales 1991-2020** (`src/lib/normales.ts`) — JSON statique `src/data/normales.json` (généré par `scripts/build-normales.mjs`), indexé par dept × day-of-year (1..366), lissage 7 jours.

Abstraction `vigilance.ts` à découper en deux implémentations (Opendatasoft / Météo France officiel) le jour où on bascule.

## Schéma cache

| Clé Valkey | TTL (frais → hard) | Contenu |
|---|---|---|
| `vigilance:snapshot` | `VIGILANCE_CACHE_TTL` (défaut 900s) → ×6 | `VigilanceSnapshot` (fetchedAt + productDatetime + alerts[]) |
| `vigilance:snapshot:fallback` | idem | Snapshot Opendatasoft de secours si provider principal échoue |
| `vigilance:snapshot:last-good` | 30 jours | Dernier snapshot connu (filet de sécurité quand tous providers KO) |
| `mf:hourly:<dept>:<hours>` | 30 min → ×6 | `HourlySeries` (obs SYNOP sur fenêtre glissante) |
| `climato:<dept>` | 24h → ×6 | `ClimatoSeries` (365 jours) |

Le prefix `info-canicule:` est injecté par ioredis (`keyPrefix`), donc la clé réelle côté Valkey est `info-canicule:<clé>` (l'ancien doc parlait d'un double prefix — c'était une erreur). Compatible avec l'ACL `~info-canicule:*` côté VPS.

**SWR** : `cacheOrFetch` stocke `{v, fu}` (valeur + freshUntil). Au-delà de `fu` mais avant l'expiration Valkey (= ttl × 6), la valeur est servie stale et un refresh est déclenché en background (lock in-process pour éviter le stampede). Un blip MF de ~25 min reste invisible côté visiteur. Voir `src/lib/cache.ts`.

**last-good** : à chaque fetch réussi, le snapshot Vigilance est aussi persisté en `:last-good` (TTL 30j). Si MF + Opendatasoft échouent en même temps et que `:snapshot`/`:fallback` sont expirés, on sert `:last-good` plutôt que de planter la page. Le visiteur voit la date du bulletin dans l'UI (déjà affichée) et constate l'ancienneté.

## Pages exposées

- `/` — home + carte/grille des dépts
- `/departement/[code]` — fiche dept avec onglets Vigilance / Observations SYNOP 24h / Climato 365j vs normales
- `/embed/` + `/embed/dept/[code]` — versions embarquables (iframe-friendly) pour intégration tierce
- `/conseils/` + `/conseils/registre-canicule` — fiches statiques
- `/api/health` — JSON `{status, cache, vigilance: {productDatetime, ageSeconds}}`. Usage : UptimeRobot + cron HC.io de fraîcheur. Pas de CORS, `Cache-Control: no-store`, renvoie 503 si Valkey KO.
- `/sitemap-index.xml` + `/sitemap-departements.xml` (les 96 dépts filtrés hors `@astrojs/sitemap` standard).

## Cache HTTP (en plus du cache Valkey)

Home et pages dept renvoient `Cache-Control: ... must-revalidate` (cf. commit `e72f25b`) pour autoriser le revalidation des CDN/navigateurs tout en bornant la fraîcheur. À garder cohérent avec le TTL Valkey.

## Pièges connus / à surveiller

- **`product_datetime` change 2× par jour** (~06h et 16h Paris). Tant que Météo France n'a pas publié le suivant, le snapshot Opendatasoft renvoie les valeurs J→J1 du bulletin courant. Inutile de poll plus vite que 15 min.
- **Echéance "J" = aujourd'hui, "J1" = demain**. Ne pas confondre avec un horizon en heures.
- **`phenomenon_id`** : 1=vent, 2=pluie, 3=orages, 5=neige/verglas, 6=canicule, 8=avalanches, 9=vagues-submersion. Pas de 4 ni 7.
- **Andorre** (`domain_id = 99`) est inclus dans le flux Vigilance mais n'est pas un département français. Mappé comme `99 — Andorre (zone Vigilance)` côté front pour ne pas l'écarter silencieusement.
- **Corse** : codes `2A` et `2B`, pas `20`. Mais pour la **climato `previous-1950-2024`**, le fichier source est encore sous code `20` (split 2A/2B post-1976) — `buildUrl()` dans `climato.ts` gère ce cas.
- **SYNOP renvoie les températures en Kelvin**. `observations.ts` les convertit via `K2C()`. Piège classique si on ajoute un nouveau champ température.
- **DROM** : pas (encore) inclus dans le mapping `departements.ts` côté front. Vigilance Métropole only pour le MVP. Pour ajouter Outre-mer : étendre `DEPARTEMENTS` + tester si `domain_id` correspond aux codes 971-978.
- **Conseils par phénomène** (`advice.ts`) : texte curated depuis sante.gouv.fr et meteofrance.fr. À relire / actualiser périodiquement (au moins 1× par an).
- **Normales 1991-2020** : fichier `src/data/normales.json` committé. Régénération via `scripts/build-normales.mjs` quand la décennie de référence Météo France change (~tous les 10 ans, prochain ~2031).
- **Cache miss au boot** : si Valkey est down, `cacheOrFetch` log un warning mais re-fetch à chaque requête — pas de fallback persistant. Acceptable pour un service stateless, mais surveiller la latence Opendatasoft.

## Déploiement

Pattern Reteno : push main → CI Forgejo SSH au VPS → `git fetch && reset --hard && make env && docker compose up -d --build --wait`.

Le `.env.tmpl` est commit, le `.env` réel est matérialisé par `make env` (pass-cli, vault `Infra`).

## Météo France API — rotation API Key

- Vault item : `Infra/Météo France API`, field `api_key` (hidden) + `created_at` + `expires_at`.
- Le portail (portail-api.meteofrance.fr) propose une **API Key longue durée** (durée choisie à la création, max ~10 ans). Pas de flow OAuth2 client_credentials dispo gratuitement → on n'utilise QUE l'API Key, pas de refresh automatique.
- Code : `src/lib/meteofrance-auth.ts` — header `apikey: ${METEOFRANCE_API_KEY}` (PAS `Authorization: Bearer`, qui est le format des tokens OAuth2 courts du portail).
- Rotation : avant l'expiration notée dans le vault, regénérer côté portail, copier dans le vault, `make env` côté VPS, `docker compose up -d --force-recreate app`.
- Si la clé expire / est révoquée : l'onglet « Observations 24 h » (SYNOP) sur les pages dept ne s'affiche plus (skip silencieux), pas d'impact sur Vigilance, Climato ni le reste du site. Erreur loggée côté serveur uniquement.
- Si on veut être alerté : prévoir un cron HC.io qui curl `/api/vigilance` non, qui curl un endpoint test `MF` (à coder). Pour l'instant : se reposer sur la date `expires_at` du vault item.