wtr/docs/weather-logic.md

Logika Pogody i Fallbacki

wtr. rozdziela bieżące pomiary, lokalną analizę IMGW Hybrid, prognozę modelową i ostrzeżenia. Prognoza nie jest przedstawiana jako pomiar IMGW.

Bieżące Warunki

Dashboard hero korzysta z publicznego endpointu IMGW Hybrid oficjalnego portalu meteo.imgw.pl przez /api/imgw-current.

Normalizacja w lib/imgw-current-api.ts:

• bierze pod uwagę tylko rekordy Type_Ten_Minutes i Type_Hour,
• wymaga realnych wartości liczbowych dla pełnego rekordu pogodowego,
• nie traktuje null jako kompletnej wartości,
• preferuje pełny rekord 10-minutowy,
• jeśli pełny rekord 10-minutowy jest o ponad 2 godziny starszy od pełnego rekordu godzinowego, wybiera świeższy rekord godzinowy,
• zachowuje lokalny opad MERGE jako częściową analizę, jeśli nie ma pełnych parametrów.

Jeśli Hybrid nie dostarcza pełnych danych, UI jawnie korzysta z fallbacku synop. Gdy najbliższa stacja jest oddalona o co najmniej 30 km, aplikacja ostrzega, że lokalne warunki mogą się różnić.

Prognoza Modelowa

Route handler /api/forecast pobiera równolegle:

• pełne 7 dni Open-Meteo,
• godzinowe IMGW ALARO.

W godzinach pokrytych przez ALARO parametry IMGW mają pierwszeństwo. Open-Meteo dostarcza prawdopodobieństwo opadu i dalszy horyzont do 7 dni. Awaria ALARO pozostawia działający fallback Open-Meteo.

Dashboard pokazuje:

• regułowy brief dnia,
• najbliższe 24 przyszłe godziny,
• wykresy pełnego bieżącego dnia.

Widok szczegółowy dnia korzysta z pełnego zestawu godzin dla wybranej daty.

Ostrzeżenia

Ostrzeżenia meteorologiczne IMGW zawierają kody powiatów TERYT. Ostrzeżenia hydrologiczne zawierają jawne województwa. Normalizacja odbywa się przez lib/provinces.ts i lib/warning-regions.ts.

Zasady UI:

• lokalny obszar jest priorytetyzowany,
• ostrzeżenia meteo są pokazywane przed hydrologicznymi,
• jeśli lokalizacja ma powiat TERYT, meteo jest filtrowane po powiecie,
• jeśli powiat nie jest znany, stosowany jest fallback wojewódzki,
• dashboard pokazuje kompaktowo tylko aktywne i nadchodzące ostrzeżenia meteo dla wybranego obszaru,
• wygasłe ostrzeżenia są filtrowane po validTo względem czasu przeglądarki.

Briefy

Brief dnia i brief na jutro są generowane deterministycznie w lib/weather-brief.ts. Nie są odpowiedzią modelu AI i nie wymagają klucza OpenAI API.

Brief dnia analizuje najbliższe 24 godziny prognozy modelowej oraz aktywne i nadchodzące ostrzeżenia meteo dla obszaru użytkownika.

Brief na jutro analizuje pełny jutrzejszy dzień prognozy. Może informować o burzach na podstawie kodów pogodowych modelu nawet wtedy, gdy IMGW nie opublikowało oficjalnego ostrzeżenia.

Opad i Pomiary Synoptyczne

Pole synop.suma_opadu jest akumulowaną sumą opadu. Nie oznacza, że pada w tej chwili, i nie steruje animacją deszczu.

IMGW Hybrid dostarcza m.in. opad 10-minutowy. Ten parametr jest prezentowany oddzielnie od akumulowanej sumy opadu stacji.

Stany Pogody

Prognoza godzinowa i dzienna rozpoznaje:

Stan	Opis w interfejsie
clear	Bezchmurnie
partlyCloudy	Częściowe zachmurzenie
cloudy	Pochmurno
fog	Mgła
drizzle	Mżawka
rain	Opady deszczu
snow	Opady śniegu
thunderstorm	Burza
unknown	Brak opisu

Bieżąca analiza IMGW Hybrid rozpoznaje bezpośrednio opad deszczu, śnieg i burzę. Gdy żadne z tych zjawisk nie występuje, hero może pokazać pomocniczy opis: Silny wiatr, Wilgotne warunki albo Spokojne warunki.

Jednostki temperatury i wiatru wybierane w /settings dotyczą prezentacji w UI, briefach i powiadomieniach. Dane źródłowe oraz progi logiki pogody pozostają liczone w °C i m/s.

Mood i Efekty Wizualne

Hero aktualnej pogody używa uproszczonego moodu do wyboru ikony, tekstu i małego akcentu stanu.

Mood	Reguła
night	godzina przed 06:00 lub od 21:00
wind	wiatr od 8 m/s
cold	temperatura do 3°C
cloudy	wilgotność od 80%
warm	temperatura od 20°C
mild	pozostałe przypadki

Warstwa efektów wizualnych jest ograniczona do subtelnych efektów informacyjnych: kropli przy lokalnym opadzie oraz błysku przy burzy. Mood hero jest heurystyką, a nie pełną klasyfikacją sterowaną kodem warunków IMGW Hybrid.

Podgląd Efektów w Development

W trybie deweloperskim można wymusić samą nakładkę efektu na karcie pogody przez parametr URL. Nie zmienia to danych pogodowych, temperatury, opisu ani ikon.

/?effect=rain
/?effect=thunderstorm
/?effect=storm
/?effect=none

Ten mechanizm działa tylko przy NODE_ENV=development, np. podczas npm run dev. Produkcyjny build ignoruje te parametry i używa wyłącznie rzeczywistych danych pogodowych.