التوقعات والتخزين المؤقت

يمكن للزوار العاديين تخطيها. تشرح كيف يخزّن الموقع ويحدّث بيانات الطقس لمن يشغّلون أو يدمجون meridian. ببساطة: متصفحك يتذكر قراءة حديثة؛ الخادم يتذكر قراءات مشتركة حتى لا نستدعي مزود الطقس عند كل نقرة.

نطاقات يطلبها العميل: current (الآن)، hourly (جدول زمني)، daily (جدول زمني)، minutely (هطول — API فقط؛ تفاصيل المدينة لا تحمّل minutely اليوم). نطاقات الخادم فقط: geocode (ذاكرة بحث مدن مفتاح geocode:{query})، alert (حمولات تنبيه فردية). كل نطاق طقس يستخدم مفتاح ذاكرة {lat},{lon},{scope}؛ geocode بسلسلة الاستعلام.

L0 — localStorage المتصفح meridian:weather-cache، بنية {cityId: {scope: {payload, fetchedAt}}} (الكتابة تحتاج موافقة وظيفية). L1 — Map في الذاكرة على عملية الخادم. L2 — SQLite weather_snapshots مع fetched_at وexpires_at وstale_until. العميل يقرأ L0 ثم يستدعي API؛ الخادم يقرأ L1 ثم L2 ثم upstream OpenWeather.

fresh — ضمن expires_at. acceptable — بعد expires لكن ضمن stale_until (قد يُقدَّم). expired — بعد stale_until، يشغّل upstream إن سمحت الحصة. emergency — الحصة محجوبة لكن يُقدَّم snapshot 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 يسقط على API 2.5 /weather إن فشل One Call current. Geocode يستخدم OpenWeather geocoding API (limit 5). التطبيع في src/lib/one-call.js ينتج حمولات واجهة متسقة.

POST /api/weather/batch يقبل { cities: [{ lat, lon, scopes?: string[], id?, lang?, maxAgeMs?, trigger? }], trigger?, lang? }. النطاقات لكل مدينة (city.scopes)، وليس مصفوفة scopes عليا. لوحة التحكم تحمّل current + daily معًا في دفعة واحدة (بلا requestIdleCallback). تفاصيل المدينة تجمع current + hourly + daily فقط. المعالج يباعد المدن ~100ms لتجنب حدود المعدل المفاجئة.

استجابات API تتضمن meta: cacheLayer (memory، database، upstream)، freshness، fetchedAt، ageMs، upstreamCallAvoided، source. ترويسة X-Cache تعكس hit/miss حيث ينطبق. «حُدّث منذ X» في الواجهة تستخدم meta.fetchedAt.

عند تجاوز الحدود اليومية أو بالدقيقة، تتوقف استدعاءات upstream ويُعاد بيانات L2 emergency stale إن وُجدت. إعادة فتح مدينة ضمن TTL تكلف صفر استدعاء upstream.

إصابات ذاكرة قاعدة L2 تُسجّل في api_call_log مع cache_hit=1 ولا تزيد عداد upstream اليومي. إصابات ذاكرة L1 تُقدَّم لكن لا تُحفظ عمدًا في SQLite — تُطلق عند كل إعادة mount SSR/عميل وستُرهق meridian.db تحت file watchers.

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