feat: build production-ready wtr weather PWA

README.md

@@ -0,0 +1,88 @@
+# wtr.
+
+**Pogoda z danych IMGW. Prosto. Pięknie. Aktualnie.**
+
+`wtr.` to nowoczesna pogodowa PWA dla Polski oparta o publiczne dane IMGW. Aplikacja prezentuje bieżące odczyty synoptyczne, stacje hydrologiczne oraz ostrzeżenia w spokojnym, mobilnym interfejsie z gradientami, kartami glassmorphism i subtelnymi animacjami.
+
+## 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
+```
+
+## Dane IMGW
+
+Aplikacja korzysta wyłącznie 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`
+
+Przeglądarka pobiera dane przez whitelistowane proxy w `app/api/imgw/[...path]/route.ts`. Pozwala to ujednolicić cache, błędy API i bezpiecznie obsłużyć hydro bez mixed content.
+
+## Ograniczenia API
+
+Publiczny endpoint synoptyczny IMGW udostępnia najnowszy pomiar, a nie pełną prognozę godzinową lub wielodniową i nie historię odczytów. `wtr.` nie generuje fikcyjnych prognoz. Widok stacji prezentuje aktualne parametry i jawnie opisany snapshot pomiarowy. Brakujące wartości są oznaczane jako `Brak danych`.
+
+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 IMGW, offline fallback
+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.