AGENTS.md

Projekt

wtr. to mobilna PWA pogodowa dla Polski. Pokazuje bieżące pomiary synoptyczne, dane hydrologiczne i ostrzeżenia z publicznego API IMGW oraz oddzielnie oznaczoną prognozę modelową Open-Meteo. Open-Meteo Geocoding służy także do wyszukiwania miejscowości, a Nominatim / OpenStreetMap do opcjonalnego reverse geocodingu po zgodzie GPS użytkownika.

Stack: Next.js App Router, React, TypeScript, Tailwind CSS, TanStack Query, Zustand, Framer Motion, Recharts i Lucide React. PWA korzysta z manifestu oraz własnego service workera.

Najważniejsze katalogi:

app/ - routing, layout, globalne style i route handlery proxy.
components/ - komponenty pogody, prognozy, hydro, ostrzeżeń, layoutu, UI i stanów ekranu.
hooks/ - hooki TanStack Query.
lib/ - fetchery, normalizacja danych, tłumaczenia, helpery i store Zustand.
types/ - typy danych IMGW, prognozy oraz lokalizacji.
public/ - manifest, service worker i ikony PWA.

Komendy

Wymagany jest Node.js 20.9 lub nowszy.

npm install
npm run dev
npm run lint
npm run build
npm run start

Repozytorium nie ma obecnie skryptu testów, osobnego skryptu type-check ani formattera. npm run build uruchamia kontrolę TypeScript wykonywaną przez Next.js. Nie opisuj ani nie uruchamiaj nieistniejących komend jako standardowego workflow.

Konwencje kodu

Używaj TypeScript konsekwentnie i importów absolutnych @/....
Komponenty i typy nazywaj PascalCase, funkcje oraz hooki camelCase; hooki zaczynają się od use.
Trzymaj routing w app/, komponenty funkcjonalne w odpowiednim podkatalogu components/, zapytania Query w hooks/, fetchery i normalizację w lib/, a typy danych w types/.
Dodawaj "use client" tylko tam, gdzie komponent lub moduł korzysta z hooków, stanu przeglądarki albo interakcji.
Dane zewnętrzne pobieraj przez route handlery Next.js. Nie omijaj allowlisty w app/api/imgw/[...path]/route.ts.
Traktuj IMGW jako źródło bieżących pomiarów, hydro i ostrzeżeń. Prognozę Open-Meteo pokazuj oddzielnie jako prognozę modelową. Nie generuj fikcyjnych danych ani nie przedstawiaj prognozy jako pomiaru IMGW.
synop.suma_opadu jest akumulowaną sumą opadu. Nie używaj jej jako sygnału, że pada w tej chwili, ani do sterowania animacją deszczu.
GPS wymaga świadomej zgody użytkownika i HTTPS. Zaokrąglaj współrzędne przed użyciem i utrzymuj widoczną atrybucję OpenStreetMap dla reverse geocodingu Nominatim.
Normalizuj zewnętrzne odpowiedzi i obsługuj null, puste pola oraz błędne wartości. Brak danych pokazuj jawnie zamiast uzupełniać estymacją.
Dla pobierania danych używaj TanStack Query z sensownym queryKey, cache i retry. W UI zachowuj loading, error, retry oraz empty states.
Teksty interfejsu dodawaj równolegle po polsku i angielsku w lib/i18n.tsx. Nazw stacji i treści IMGW nie tłumacz automatycznie.
Trwałe preferencje użytkownika zapisuj przez istniejący store Zustand w lib/store.ts lub istniejące klucze localStorage.
Zachowuj mobile-first UI, dostępność klawiatury, aria-label, focus states oraz spokojny styl glassmorphism.
Nie edytuj ręcznie next-env.d.ts; plik jest generowany przez Next.js.

Obsługa błędów:

Route handlery zwracają kontrolowane odpowiedzi JSON z kodem HTTP.
Fetchery w lib/ rzucają Error, a komponenty prezentują czytelny stan błędu i retry.
Projekt nie ma warstwy logowania aplikacyjnego. Nie dodawaj przypadkowych console.log.

Instrukcje dla agenta

Przed zmianą przeczytaj pliki w obszarze funkcji i sprawdź git status.
Utrzymuj mały zakres zmian. Nie refaktoruj niezwiązanych modułów i nie cofaj cudzych zmian.
Nie dodawaj mocków jako źródła danych pogodowych. Przy zmianie źródeł API zaktualizuj route handler, typy, normalizację, UI i README.
Przy zmianach PWA sprawdź spójność public/manifest.json, public/sw.js i rejestracji service workera.
Przed zakończeniem uruchom co najmniej npm run lint i npm run build. Jeśli dodano testy, uruchom także ich skrypt.
Sprawdź git diff --check oraz git status. Nie commituj wygenerowanego churnu w next-env.d.ts.
Ważne decyzje o źródłach danych, ograniczeniach API, uruchamianiu i wdrożeniu dokumentuj krótko w README.md.

Utrzymywanie pliku

Aktualizuj AGENTS.md w tej samej zmianie, gdy zmieniają się: struktura projektu, komendy, konwencje, zależności, sposób uruchamiania, testowania lub istotne decyzje architektoniczne.

Jeśli ten plik jest nieaktualny, niepełny albo sprzeczny z kodem, popraw go zamiast ślepo go przestrzegać. Zachowuj go krótkim i praktycznym: bez historii czatu, dziennika zmian i ogólnych porad niezwiązanych z repozytorium.

4.7 KiB Raw Blame History