Prévisions et cache

Les visiteurs quotidiens peuvent ignorer cette page. Elle explique comment le site stocke et rafraîchit les données météo pour ceux qui exploitent ou intègrent meridian. En termes simples : votre navigateur retient un relevé récent ; le serveur retient aussi des relevés partagés pour ne pas appeler le fournisseur météo à chaque clic.

Scopes demandables par le client : current (maintenant), hourly (chronologie), daily (chronologie), minutely (précipitations — API uniquement ; détail ville ne charge pas minutely aujourd’hui). Scopes serveur uniquement : geocode (cache recherche ville clé geocode:{query}), alert (payloads d’alerte individuels). Chaque scope météo utilise la clé cache {lat},{lon},{scope} ; geocode par chaîne de requête.

L0 — localStorage navigateur meridian:weather-cache, structure {cityId: {scope: {payload, fetchedAt}}} (écritures nécessitent consentement fonctionnel). L1 — Map en mémoire sur le processus serveur. L2 — SQLite weather_snapshots avec fetched_at, expires_at, stale_until. Le client lit L0 puis appelle l’API ; le serveur lit L1 puis L2 puis upstream OpenWeather.

fresh — dans expires_at. acceptable — après expires mais dans stale_until (peut encore être servi). expired — au-delà de stale_until, déclenche upstream si quota le permet. emergency — quota bloqué mais snapshot L2 expiré/acceptable servi quand même pour que les utilisateurs voient encore des données.

current — fresh 1h, stale 2h (remplacé par platform_settings.refresh_interval_ms et stale_cache_max_ms ; admin peut définir 10m–2h). hourly — fresh 2h, stale 6h. daily — fresh 6h, stale 12h. minutely — fresh 15m, stale 30m. geocode — fresh 7d, stale 30d. alert — fresh 1h, stale 6h.

Principal : One Call API 4.0 (onecall/current, timeline/1h, timeline/1day, timeline/1min). Le scope current bascule sur API 2.5 /weather si One Call current échoue. Geocode utilise l’API geocoding OpenWeather (limit 5). Normalisation dans src/lib/one-call.js produit des payloads UI cohérents.

POST /api/weather/batch accepte { cities: [{ lat, lon, scopes?: string[], id?, lang?, maxAgeMs?, trigger? }], trigger?, lang? }. Les scopes sont par ville (city.scopes), pas un tableau scopes de niveau supérieur. Le tableau de bord charge current + daily ensemble en un lot (pas de requestIdleCallback). Détail ville batch uniquement current + hourly + daily. Le handler espace les villes ~100ms pour éviter les limites de débit en rafale.

Les réponses API incluent meta : cacheLayer (memory, database, upstream), freshness, fetchedAt, ageMs, upstreamCallAvoided, source. L’en-tête X-Cache reflète hit/miss le cas échéant. « Mis à jour il y a X » dans l’UI utilise meta.fetchedAt.

Quand les limites journalières ou par minute sont dépassées, les appels upstream s’arrêtent et des données L2 emergency stale sont renvoyées si disponibles. Rouvrir une ville dans le TTL coûte zéro appel upstream.

Les hits cache base L2 journalisent dans api_call_log avec cache_hit=1 et n’incrémentent pas le compteur upstream journalier. Les hits mémoire L1 sont servis mais intentionnellement non persistés dans SQLite — ils se déclenchent à chaque remontage SSR/client et feraient tourner meridian.db sous file watchers.

temperature, feelsLike, description, condition, icon (code OpenWeather), humidity, pressure, dewPoint, uvi, clouds, visibility, windSpeedKmh, windGustKmh, windDeg, sunrise, sunset, alertIds, city, country, timezone, updatedAt, source.