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)
• ioredis pour le cache Valkey
• TypeScript strict
• Pas de DB Postgres (le snapshot Vigilance vit en cache, refresh toutes les 15 min)

Source de données

• Provider par défaut : weatherref-france-vigilance-meteo-departement chez Opendatasoft.
  • URL : https://public.opendatasoft.com/api/explore/v2.1/catalog/datasets/weatherref-france-vigilance-meteo-departement/records
  • Pas d'auth, JSON propre, ~1 000 records par snapshot (départements × phénomènes × échéances J/J1)
  • Licence Ouverte 2.0
• Migration possible : API Vigilance Météo France officielle (portail-api.meteofrance.fr) si fraîcheur Opendatasoft insuffisante. Nécessite un token sur le portail Météo France. Abstraction vigilance.ts à découper en deux implémentations le jour venu.

Schéma cache

Clé Valkey	TTL	Contenu
info-canicule:vigilance:snapshot	VIGILANCE_CACHE_TTL (défaut 900s)	VigilanceSnapshot complet (fetchedAt + productDatetime + alerts[])

Le prefix info-canicule: est injecté par ioredis (keyPrefix), donc la clé réelle côté Valkey est info-canicule:info-canicule:vigilance:snapshot. Compatible avec l'ACL ~info-canicule:* côté VPS.

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.
• 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).
• 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 Authorization: Bearer ${METEOFRANCE_API_KEY}.
• 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 « 24 h » sur les pages dept ne s'affiche plus (skip silencieux), pas d'impact sur 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.