a849977fcc
Some checks are pending
Deploy info-canicule / deploy (push) Waiting to run
Le portail Météo France ne propose pas le flow client_credentials gratuit (seulement token OAuth2 court 1h, pas viable, ou API Key longue durée). On simplifie : un seul env METEOFRANCE_API_KEY → Authorization: Bearer. - lib/meteofrance-auth.ts : suppression du cache token + flow refresh - .env.tmpl : ref unique vers vault Infra/Météo France API/api_key - vault item recréé avec api_key (hidden) + created_at + expires_at - CLAUDE.md projet : section rotation API key L onglet 24 h n apparaît qu une fois api_key non vide dans le vault. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
58 lines
4.2 KiB
Markdown
58 lines
4.2 KiB
Markdown
# 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.
|