docs: reorganize project documentation

docs/weather-logic.md

@@ -0,0 +1,95 @@
+# 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`.
+
+## 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.