Pronósticos y caché

Los visitantes habituales pueden omitir esta página. Explica cómo el sitio almacena y actualiza datos del tiempo para quienes operan o integran meridian. En términos simples: tu navegador recuerda una lectura reciente; el servidor también recuerda lecturas compartidas para no llamar al proveedor del tiempo en cada clic.

Scopes solicitables por el cliente: current (ahora), hourly (línea temporal), daily (línea temporal), minutely (precipitación — solo API; detalle de ciudad no carga minutely hoy). Scopes solo servidor: geocode (caché de búsqueda de ciudad clave geocode:{query}), alert (payloads de alerta individuales). Cada scope del tiempo usa clave de caché {lat},{lon},{scope}; geocode por cadena de consulta.

L0 — localStorage del navegador meridian:weather-cache, estructura {cityId: {scope: {payload, fetchedAt}}} (escrituras necesitan consentimiento funcional). L1 — Map en memoria en el proceso del servidor. L2 — SQLite weather_snapshots con fetched_at, expires_at, stale_until. El cliente lee L0 luego llama a la API; el servidor lee L1 luego L2 luego upstream OpenWeather.

fresh — dentro de expires_at. acceptable — pasado expires pero dentro de stale_until (puede seguir sirviéndose). expired — más allá de stale_until, dispara upstream si la cuota lo permite. emergency — cuota bloqueada pero snapshot L2 caducado/aceptable servido igual para que los usuarios sigan viendo datos.

current — fresh 1h, stale 2h (anulado por platform_settings.refresh_interval_ms y stale_cache_max_ms; admin puede poner 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). El scope current recurre a API 2.5 /weather si One Call current falla. Geocode usa la API de geocodificación OpenWeather (limit 5). Normalización en src/lib/one-call.js produce payloads UI coherentes.

POST /api/weather/batch acepta { cities: [{ lat, lon, scopes?: string[], id?, lang?, maxAgeMs?, trigger? }], trigger?, lang? }. Los scopes son por ciudad (city.scopes), no un array scopes de nivel superior. El panel carga current + daily juntos en un lote (sin requestIdleCallback). Detalle de ciudad agrupa solo current + hourly + daily. El manejador espacia ciudades ~100ms para evitar límites de ráfaga.

Las respuestas API incluyen meta: cacheLayer (memory, database, upstream), freshness, fetchedAt, ageMs, upstreamCallAvoided, source. La cabecera X-Cache refleja hit/miss cuando aplique. «Actualizado hace X» en la UI usa meta.fetchedAt.

Cuando se superan límites diarios o por minuto, las llamadas upstream se detienen y se devuelven datos L2 emergency stale si están disponibles. Reabrir una ciudad dentro del TTL cuesta cero llamadas upstream.

Los aciertos de caché de base L2 registran en api_call_log con cache_hit=1 y no incrementan el contador upstream diario. Los aciertos de memoria L1 se sirven pero intencionalmente no se persisten en SQLite — se disparan en cada remontaje SSR/cliente y harían girar meridian.db bajo file watchers.

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