wtr/README.md

# wtr.

`wtr.` to mobilna PWA pogodowa z pełnym trybem dla Polski i globalną prognozą modelową przez Open-Meteo.

Aplikacja pokazuje bieżącą analizę IMGW Hybrid dla Polski, modelowe warunki bieżące Open-Meteo poza Polską, prognozę godzinową i 7-dniową, ostrzeżenia IMGW dla Polski, dane hydro oraz deterministyczne briefy pogodowe bez użycia zewnętrznego modelu AI.

## Najważniejsze funkcje

- Bieżące warunki: IMGW Hybrid w Polsce, Open-Meteo jako modelowe warunki bieżące poza Polską.
- Prognoza modelowa 7 dni: IMGW ALARO dla Polski oraz Open-Meteo jako globalny provider i fallback.
- Globalne wyszukiwanie miejscowości oraz opcjonalny wybór lokalizacji GPS.
- Ostrzeżenia IMGW dla Polski z filtrowaniem meteo po powiecie TERYT, gdy lokalizacja go dostarcza.
- Powiadomienia Web Push o nowych ostrzeżeniach, porannym briefie dnia i wieczornym briefie na jutro.
- Widoki dashboardu, prognozy szczegółowej dnia, ostrzeżeń, hydro, stacji i ustawień.
- PWA z manifestem, własnym service workerem i podstawowym fallbackiem offline.
- Interfejs po polsku i angielsku.

## Stack

- Next.js App Router, React, TypeScript
- Tailwind CSS
- TanStack Query
- Zustand
- Framer Motion
- Recharts
- Lucide React
- `web-push`
- SQLite przez `better-sqlite3` dla trwałego magazynu subskrypcji Web Push
- własny service worker i manifest PWA

## Szybki Start

Wymagany jest Node.js 20.9 lub nowszy.

```bash
npm install
npm run dev
```

Aplikacja będzie dostępna pod adresem `http://localhost:3000`.

## Konfiguracja

Do podstawowego uruchomienia aplikacji pogodowej nie są potrzebne klucze API. Publiczne dane IMGW, Open-Meteo i Nominatim są pobierane przez route handlery Next.js.

Powiadomienia Web Push wymagają zmiennych środowiskowych:

```bash
WEB_PUSH_VAPID_PUBLIC_KEY=
WEB_PUSH_VAPID_PRIVATE_KEY=
WEB_PUSH_VAPID_SUBJECT=mailto:admin@example.com
NOTIFICATIONS_CRON_SECRET=
WTR_APP_URL=http://127.0.0.1:3000
WTR_DATABASE_PATH=./data/wtr.sqlite
NOTIFICATIONS_WARNING_INTERVAL_MINUTES=5
NOTIFICATIONS_BRIEF_INTERVAL_MINUTES=5
NOTIFICATIONS_MORNING_BRIEF_TIME=07:00
NOTIFICATIONS_TOMORROW_BRIEF_TIME=18:00
```

Przykład znajduje się w [.env.example](.env.example).

## Komendy

| Komenda                        | Opis                                                                                    |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `npm run dev`                  | Uruchamia serwer deweloperski Next.js.                                                  |
| `npm run lint`                 | Uruchamia ESLint.                                                                       |
| `npm run format`               | Formatuje obsługiwane pliki przez Prettier.                                             |
| `npm run format:check`         | Sprawdza formatowanie Prettier bez zapisywania zmian.                                   |
| `npm run test`                 | Uruchamia testy jednostkowe logiki pogodowej przez Vitest.                              |
| `npm run test:watch`           | Uruchamia Vitest w trybie obserwowania zmian.                                           |
| `npm run typecheck`            | Uruchamia `tsc --noEmit`.                                                               |
| `npm run build`                | Buduje aplikację produkcyjnie i uruchamia kontrolę TypeScript wykonywaną przez Next.js. |
| `npm run start`                | Uruchamia zbudowaną aplikację.                                                          |
| `npm run notifications:worker` | Uruchamia self-hostowany worker powiadomień. Wymaga działającej aplikacji Next.js.      |

Testy jednostkowe korzystają z Vitest i obejmują kluczową logikę pogodową, m.in. briefy, jednostki, ikony prognozy oraz dopasowanie ostrzeżeń do regionu. Formatowanie jest obsługiwane przez Prettier.

## CI

Repozytorium używa Gitea Actions. Workflow znajduje się w [.gitea/workflows/ci.yml](.gitea/workflows/ci.yml) i uruchamia się przy pushu do `main` oraz przy pull requestach.

Pipeline działa na `ubuntu-latest`, instaluje zależności przez `npm ci`, a następnie uruchamia:

- `npm run lint`,
- `npm run format:check`,
- `npm run typecheck`,
- `npm run test`,
- `npm run build`.

Na instancji Gitea musi być włączony Actions runner kompatybilny z etykietą `ubuntu-latest`.

CI jest ostateczną bramką jakości po pushu. Lokalnie dobieraj komendy proporcjonalnie do ryzyka zmiany: dokumentacja zwykle wymaga tylko przeglądu diffu, drobne zmiany UI nie wymagają rutynowego builda, a pełny zestaw `lint`, `typecheck` i `build` zostaw dla zmian wysokiego ryzyka.

## Struktura Projektu

```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/         szczegółowa dokumentacja techniczna
```

## Dokumentacja

- [Architektura i przepływ danych](docs/architecture.md)
- [Wewnętrzne endpointy API](docs/api.md)
- [Źródła danych i cache](docs/data-sources.md)
- [Logika pogody i fallbacki](docs/weather-logic.md)
- [Powiadomienia Web Push](docs/notifications.md)
- [Wdrożenie i uruchamianie](docs/deployment.md)

## Status i Ograniczenia

- `lib/push-store.ts` przechowuje subskrypcje Web Push i historię wysyłek w lokalnym SQLite. Na self-hostingu zadbaj o trwały katalog dla `WTR_DATABASE_PATH` i backup pliku bazy.
- Oficjalne ostrzeżenia pogodowe i dane hydrologiczne są obsługiwane tylko dla Polski przez IMGW. Poza Polską aplikacja pokazuje prognozę modelową Open-Meteo i briefy bez oficjalnych alertów.
- Endpoint IMGW Hybrid używany przez dashboard pochodzi z publicznego frontendu `meteo.imgw.pl`, a nie ze stabilnie opisanej dokumentacji `danepubliczne.imgw.pl`.
- Publiczne API IMGW potrafi zwrócić `404` z komunikatem `No products were found` dla pustych list ostrzeżeń; aplikacja traktuje to jako brak ostrzeżeń.
- Prognoza jest prognozą modelową, nie pomiarem IMGW. Bieżące pomiary, modelowe warunki bieżące i prognozy są w UI rozdzielane.