76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# Architektura i Przepływ Danych
|
|
|
|
`wtr.` jest aplikacją Next.js App Router z komponentami React, cache'owaniem przez TanStack Query i stanem preferencji w Zustand.
|
|
|
|
## Struktura
|
|
|
|
```text
|
|
app/ routing, layout, route handlery i strony
|
|
components/ komponenty widoków, UI, stanów, prognozy, hydro i ostrzeżeń
|
|
hooks/ hooki TanStack Query
|
|
lib/ fetchery, normalizacja danych, Web Push, i18n, store i helpery
|
|
types/ typy danych IMGW, prognozy, lokalizacji i powiadomień
|
|
public/ manifest, service worker i ikony PWA
|
|
scripts/ worker powiadomień dla self-hostingu
|
|
docs/ dokumentacja techniczna
|
|
```
|
|
|
|
## Routing
|
|
|
|
Najważniejsze widoki:
|
|
|
|
- `/` - dashboard pogody, wyszukiwarka lokalizacji, hero, prognoza, briefy i ostrzeżenia regionalne,
|
|
- `/warnings` - pełny widok ostrzeżeń meteo i hydro,
|
|
- `/hydro` - stacje hydrologiczne,
|
|
- `/settings` - język, motyw, widoczność sekcji aplikacji i dashboardu, lokalizacja powiadomień i Web Push,
|
|
- `/station/[id]` - szczegóły stacji,
|
|
- `/offline` - fallback offline.
|
|
|
|
## Przepływ Danych
|
|
|
|
1. Komponenty UI wywołują hooki z `hooks/`.
|
|
2. Hooki używają TanStack Query i fetcherów z `lib/`.
|
|
3. Fetchery pobierają dane przez route handlery w `app/api/`.
|
|
4. Route handlery walidują parametry, odpytują zewnętrzne usługi, ustawiają cache i normalizują błędy.
|
|
5. Moduły w `lib/` normalizują odpowiedzi do typów z `types/`.
|
|
6. Komponenty prezentują loading, error, retry oraz empty states.
|
|
|
|
## Stan Aplikacji
|
|
|
|
Zustand w `lib/store.ts` przechowuje trwałe preferencje użytkownika w `localStorage`, m.in.:
|
|
|
|
- ulubione stacje,
|
|
- wybraną stację albo lokalizację,
|
|
- ustawienia powiadomień,
|
|
- tryb wyboru województwa dla alertów,
|
|
- widoczność opcjonalnych sekcji dashboardu,
|
|
- widoczność opcjonalnych sekcji aplikacji w nawigacji.
|
|
|
|
Język interfejsu jest przechowywany osobno w `localStorage` pod kluczem `wtr:language`.
|
|
|
|
## PWA i Offline
|
|
|
|
Manifest znajduje się w `public/manifest.json`, a service worker w `public/sw.js`.
|
|
|
|
Service worker:
|
|
|
|
- cache'uje powłokę aplikacji,
|
|
- obsługuje fallback `/offline` dla nawigacji i zapisuje udane nawigacje do cache,
|
|
- cache'uje statyczne assety Next.js, style, skrypty, fonty, obrazy, manifest i ikony,
|
|
- cache'uje wybrane odpowiedzi API: `/api/imgw/*`, `/api/imgw-current`, `/api/current-weather`, `/api/forecast`,
|
|
- obsługuje zdarzenia `push` i kliknięcia w powiadomienia.
|
|
|
|
Rejestracja service workera działa w buildzie produkcyjnym.
|
|
|
|
## i18n
|
|
|
|
Interfejs jest dostępny po polsku i angielsku. Teksty są w `lib/i18n.tsx`. Nazwy stacji i oryginalne treści IMGW nie są automatycznie tłumaczone.
|
|
|
|
## Zasady Integracji
|
|
|
|
- Dane zewnętrzne przechodzą przez route handlery Next.js.
|
|
- IMGW pozostaje źródłem bieżących pomiarów, hydro i ostrzeżeń dla Polski.
|
|
- Poza Polską Open-Meteo jest źródłem modelowych bieżących warunków i prognozy.
|
|
- Prognoza modelowa jest opisana oddzielnie i nie jest przedstawiana jako pomiar IMGW ani oficjalny alert.
|
|
- Braki danych są pokazywane jawnie, bez generowania fikcyjnych wartości.
|