予報とキャッシュ

一般訪問者はスキップして構いません。meridian を運用・統合する人向けに、天気データの保存と更新の仕組みを説明します。平易に言うと：ブラウザは直近の読み取りを覚え、サーバーも共有読み取りを覚えるので、クリックのたびに天気プロバイダーを呼びません。

クライアント要求可能スコープ：current（現在）、hourly（タイムライン）、daily（タイムライン）、minutely（降水 — API のみ；都市詳細は現時点で minutely を読み込まない）。サーバーのみ：geocode（都市検索キャッシュ、キー geocode:{query}）、alert（個別アラート payload）。各天気スコープのキャッシュキーは {lat},{lon},{scope}；geocode はクエリ文字列。

L0 — ブラウザ localStorage meridian:weather-cache、構造 {cityId: {scope: {payload, fetchedAt}}}（書き込みは機能同意が必要）。L1 — サーバープロセスのインメモリ Map。L2 — fetched_at、expires_at、stale_until 付き SQLite weather_snapshots。クライアントは L0 を読んでから API；サーバーは L1 → L2 → upstream OpenWeather。

fresh — expires_at 以内。acceptable — expires 超過だが stale_until 以内（配信可）。expired — stale_until 超過、クォータが許せば upstream 発火。emergency — クォータブロックだが期限切れ／acceptable の L2 スナップショットを配信しユーザーにデータを見せる。

current — fresh 1h、stale 2h（platform_settings.refresh_interval_ms と stale_cache_max_ms で上書き；管理画面で 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。

主：One Call API 4.0（onecall/current、timeline/1h、timeline/1day、timeline/1min）。current スコープは One Call current 失敗時 API 2.5 /weather にフォールバック。Geocode は OpenWeather geocoding API（limit 5）。src/lib/one-call.js で正規化し UI payload を統一。

POST /api/weather/batch は { cities: [{ lat, lon, scopes?: string[], id?, lang?, maxAgeMs?, trigger? }], trigger?, lang? } を受け付ける。スコープは都市ごと（city.scopes）、トップレベル scopes 配列ではない。ダッシュボードは current + daily を1バッチで（requestIdleCallback なし）。都市詳細は current + hourly + daily のみ。ハンドラはバースト制限回避のため都市間を約100ms 空ける。

API レスポンスに meta：cacheLayer（memory、database、upstream）、freshness、fetchedAt、ageMs、upstreamCallAvoided、source。X-Cache ヘッダーは該当時 hit/miss を反映。「X 前に更新」は meta.fetchedAt を使用。

日次または分間制限超過時、upstream 呼び出しは止まり、利用可能なら emergency stale L2 を返す。TTL 内に同じ都市を再オープンしても upstream 呼び出しはゼロ。

L2 DB キャッシュヒットは api_call_log に cache_hit=1 で記録し、日次 upstream カウンタは増やさない。L1 メモリヒットは配信するが SQLite には意図的に永続化しない — SSR/クライアント再マウントのたびに発火し、file watcher 下で meridian.db を churn させる。

temperature、feelsLike、description、condition、icon（OpenWeather code）、humidity、pressure、dewPoint、uvi、clouds、visibility、windSpeedKmh、windGustKmh、windDeg、sunrise、sunset、alertIds、city、country、timezone、updatedAt、source。