# wtr. **Pogoda z danych IMGW. Prosto. Pięknie. Aktualnie.** `wtr.` to nowoczesna pogodowa PWA dla Polski oparta o publiczne dane IMGW i jawnie oznaczoną prognozę modelową Open-Meteo. Aplikacja prezentuje bieżące odczyty synoptyczne, prognozę godzinową i 7-dniową, stacje hydrologiczne oraz ostrzeżenia w spokojnym, mobilnym interfejsie z gradientami, kartami glassmorphism i subtelnymi animacjami. Każdy dzień prognozy można otworzyć w animowanym widoku szczegółowym z przebiegiem godzinowym oraz wykresami temperatury i opadu. Interfejs jest dostępny po polsku i angielsku. Wybrany język jest zapisywany lokalnie w przeglądarce. Oryginalne treści ostrzeżeń oraz nazwy stacji pochodzą bezpośrednio z API IMGW i nie są automatycznie tłumaczone. Wyszukiwarka na stronie głównej obsługuje miejscowości w całej Polsce. Nazwa miejscowości jest rozpoznawana przez Open-Meteo Geocoding API oparte o GeoNames, natomiast wyświetlany pomiar pogody nadal pochodzi wyłącznie z najbliższej rzeczywistej stacji IMGW. Interfejs jawnie pokazuje nazwę tej stacji oraz przybliżoną odległość. Użytkownik może opcjonalnie udostępnić położenie GPS. Pozycja jest zaokrąglana do trzech miejsc po przecinku, czyli około 100 metrów, a nazwa miejscowości jest ustalana przez Nominatim / OpenStreetMap. Po zgodzie aplikacja wybiera lokalizację, najbliższą stację IMGW i prognozę. Geolocation API wymaga bezpiecznego kontekstu HTTPS. Wyjątkiem jest `localhost`; wejście z iPhone przez lokalny adres typu `http://192.168.x.x:3000` nie uruchomi systemowego pytania Safari. ## Stack - Next.js z App Router i TypeScript - Tailwind CSS oraz komponenty w stylu shadcn/ui - Framer Motion - Recharts - Lucide React - TanStack Query - Zustand z trwałym stanem `localStorage` - własny service worker, manifest i offline fallback ## Uruchomienie Wymagany jest Node.js 20.9 lub nowszy. ```bash npm install npm run dev ``` Aplikacja będzie dostępna pod adresem `http://localhost:3000`. Sprawdzenie jakości i build produkcyjny: ```bash npm run lint npm run build npm run start ``` ## Źródła danych Bieżące pomiary i komunikaty pochodzą z rzeczywistych publicznych danych IMGW: - dane synoptyczne: `https://danepubliczne.imgw.pl/api/data/synop` - pojedyncza stacja synoptyczna: `https://danepubliczne.imgw.pl/api/data/synop/id/{id}` - dane hydrologiczne: `https://danepubliczne.imgw.pl/api/data/hydro/` - ostrzeżenia meteorologiczne: `https://danepubliczne.imgw.pl/api/data/warningsmeteo` - ostrzeżenia hydrologiczne: `https://danepubliczne.imgw.pl/api/data/warningshydro` - dane meteorologiczne: `https://danepubliczne.imgw.pl/api/data/meteo/` - lista produktów: `https://danepubliczne.imgw.pl/api/data/product` Prognoza godzinowa i 7-dniowa pochodzi z Open-Meteo Forecast API: `https://api.open-meteo.com/v1/forecast`. Jest prezentowana oddzielnie od bieżących pomiarów IMGW i podpisana w interfejsie jako prognoza modelowa. Do wyszukiwania nazw miejscowości używany jest endpoint `https://geocoding-api.open-meteo.com/v1/search`. Przed wdrożeniem komercyjnym należy sprawdzić aktualne warunki korzystania z Open-Meteo lub zastąpić usługę własnym dostawcą. Opcjonalny reverse geocoding dla GPS korzysta z publicznego endpointu Nominatim: `https://nominatim.openstreetmap.org/reverse`. Wywołanie następuje wyłącznie po zgodzie użytkownika. Interfejs pokazuje atrybucję OpenStreetMap. Przed wdrożeniem o większym ruchu należy sprawdzić aktualną politykę użycia publicznej instancji Nominatim lub zastąpić ją własną usługą. Przeglądarka pobiera dane przez route handlery Next.js. Proxy IMGW w `app/api/imgw/[...path]/route.ts` pozwala ujednolicić cache, błędy API i bezpiecznie obsłużyć hydro bez mixed content. Prognozę obsługuje `app/api/forecast/route.ts`, a reverse geocoding GPS `app/api/locations/reverse/route.ts`. ## Ograniczenia API Publiczny endpoint synoptyczny IMGW udostępnia najnowszy pomiar, a nie pełną prognozę godzinową lub wielodniową i nie historię odczytów. Dlatego prognoza pochodzi z Open-Meteo i jest wyraźnie oddzielona od pomiarów IMGW. `wtr.` nie generuje fikcyjnych prognoz. Widok stacji prezentuje aktualne parametry i jawnie opisany snapshot pomiarowy. Brakujące wartości są oznaczane jako `Brak danych`. Pole `suma_opadu` z endpointu synoptycznego jest prezentowane jako akumulowana suma opadu. Nie służy do wnioskowania, że w danej chwili pada, ani do uruchamiania animacji deszczu. Czas aktualizacji parametrów hydrologicznych może się różnić. Interfejs pokazuje czas pomiaru, aby starsze odczyty nie wyglądały na bieżące. ## Struktura projektu ```text app/ routing, layout, proxy danych, offline fallback components/forecast/ prognoza godzinowa i dzienna Open-Meteo components/charts/ wykresy odczytów i szczegółów prognozy components/dashboard dashboard aplikacji components/weather/ hero, stacje, metryki i szczegóły components/warnings/ alerty meteo i hydro components/hydro/ lista stacji hydrologicznych components/ui/ bazowe komponenty interfejsu components/states/ loading, empty i error states hooks/ zapytania TanStack Query lib/ API, normalizacja, helpery i stan types/ typy danych IMGW public/ manifest, ikony i service worker ``` ## PWA i offline Manifest znajduje się w `public/manifest.json`, a service worker w `public/sw.js`. Rejestracja service workera działa w buildzie produkcyjnym. Powłoka aplikacji ma podstawowy offline fallback. Odpowiedzi API mogą być dostępne z pamięci urządzenia przy braku sieci, ale UI nadal prezentuje czas pomiaru i status świeżości. ## Wdrożenie na Vercel 1. Umieść repozytorium w serwisie Git. 2. Importuj projekt do Vercel jako aplikację Next.js. 3. Nie dodawaj kluczy API: publiczne endpointy IMGW ich nie wymagają. 4. Wdróż standardowym poleceniem builda `npm run build`. Proxy IMGW działa jako route handler Next.js i jest zgodne z hostingiem Vercel. ## Bezpieczeństwo zależności Projekt używa stabilnego Next.js `16.2.6`. `npm audit --omit=dev` raportuje obecnie umiarkowane zgłoszenie `GHSA-qx2v-qp2m-jg93` dla PostCSS `8.4.31` bundlowanego bezpośrednio przez najnowszy Next.js. Główna konfiguracja projektu korzysta z poprawionego PostCSS `8.5.x`, ale wewnętrznej kopii Next.js nie należy ręcznie podmieniać. Po publikacji poprawki upstream należy zaktualizować Next.js i ponownie uruchomić audyt.