Prognosen & Cache

Alltagsbesucher können diese Seite überspringen. Sie erklärt, wie die Seite Wetterdaten speichert und aktualisiert — für Betreiber oder Integratoren von meridian. Kurz: Ihr Browser merkt sich eine aktuelle Messung; der Server merkt sich gemeinsame Messungen, damit wir nicht bei jedem Klick den Wetteranbieter aufrufen.

Vom Client anfragbare Scopes: current (jetzt), hourly (Zeitleiste), daily (Zeitleiste), minutely (Niederschlag — nur API; Stadt-Detail lädt minutely heute nicht). Nur-Server-Scopes: geocode (Stadtsuche-Cache mit Schlüssel geocode:{query}), alert (einzelne Warnungs-Payloads). Jeder Wetter-Scope nutzt Cache-Schlüssel {lat},{lon},{scope}; geocode nach Abfragestring.

L0 — Browser localStorage meridian:weather-cache, Struktur {cityId: {scope: {payload, fetchedAt}}} (Schreiben braucht funktionale Einwilligung). L1 — In-Memory-Map im Serverprozess. L2 — SQLite weather_snapshots mit fetched_at, expires_at, stale_until. Client liest L0, dann API; Server liest L1, dann L2, dann Upstream OpenWeather.

fresh — innerhalb expires_at. acceptable — nach expires, aber innerhalb stale_until (kann noch ausgeliefert werden). expired — über stale_until, löst Upstream aus, wenn Quota es erlaubt. emergency — Quota blockiert, aber abgelaufener/akzeptabler L2-Snapshot wird trotzdem ausgeliefert, damit Nutzer noch Daten sehen.

current — fresh 1h, stale 2h (überschrieben durch platform_settings.refresh_interval_ms und stale_cache_max_ms; Admin kann 10m–2h setzen). 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.

Primär: One Call API 4.0 (onecall/current, timeline/1h, timeline/1day, timeline/1min). Current-Scope fällt auf API 2.5 /weather zurück, wenn One Call current fehlschlägt. Geocode nutzt OpenWeather Geocoding API (limit 5). Normalisierung in src/lib/one-call.js liefert konsistente UI-Payloads.

POST /api/weather/batch akzeptiert { cities: [{ lat, lon, scopes?: string[], id?, lang?, maxAgeMs?, trigger? }], trigger?, lang? }. Scopes sind pro Stadt (city.scopes), kein top-level scopes-Array. Dashboard lädt current + daily zusammen in einem Batch (kein requestIdleCallback). Stadt-Detail batcht nur current + hourly + daily. Der Handler staffelt Städte ~100ms auseinander, um Burst-Rate-Limits zu vermeiden.

API-Antworten enthalten meta: cacheLayer (memory, database, upstream), freshness, fetchedAt, ageMs, upstreamCallAvoided, source. X-Cache-Header spiegelt hit/miss wo zutreffend. „Vor X aktualisiert“ in der UI nutzt meta.fetchedAt.

Sind Tages- oder Minutenlimits überschritten, stoppen Upstream-Aufrufe und emergency-stale L2-Daten werden zurückgegeben, wenn verfügbar. Eine Stadt innerhalb der TTL erneut öffnen kostet null Upstream-Aufrufe.

L2-Datenbank-Cache-Hits loggen in api_call_log mit cache_hit=1 und erhöhen den täglichen Upstream-Zähler nicht. L1-Speicher-Hits werden ausgeliefert, aber absichtlich nicht in SQLite persistiert — sie feuern bei jedem SSR/Client-Remount und würden meridian.db unter File-Watchern belasten.

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