# 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`.

Jednostka wiatru wybierana w `/settings` dotyczy prezentacji w UI, briefach i powiadomieniach. Dane źródłowe oraz progi logiki pogody pozostają liczone w `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.

```text
/?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.