115 lines
4.5 KiB
Markdown
115 lines
4.5 KiB
Markdown
# wtr.
|
|
|
|
`wtr.` to mobilna PWA pogodowa dla Polski oparta o publiczne dane IMGW oraz jawnie oznaczoną prognozę modelową łączącą IMGW ALARO z Open-Meteo.
|
|
|
|
Aplikacja pokazuje bieżącą analizę IMGW Hybrid, pomiary synoptyczne, prognozę godzinową i 7-dniową, ostrzeżenia meteorologiczne i hydrologiczne, dane hydro oraz deterministyczne briefy pogodowe bez użycia zewnętrznego modelu AI.
|
|
|
|
## Najważniejsze funkcje
|
|
|
|
- Bieżące warunki z lokalnej analizy IMGW Hybrid, z opisanym fallbackiem do stacji synoptycznej.
|
|
- Prognoza modelowa 7 dni: IMGW ALARO dla dostępnych godzin oraz Open-Meteo jako uzupełnienie i fallback.
|
|
- Wyszukiwanie miejscowości w Polsce oraz opcjonalny wybór lokalizacji GPS.
|
|
- Ostrzeżenia IMGW 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_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 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. |
|
|
|
|
Repozytorium nie ma obecnie skryptu testów ani formattera.
|
|
|
|
## 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 typecheck`,
|
|
- `npm run build`.
|
|
|
|
Na instancji Gitea musi być włączony Actions runner kompatybilny z etykietą `ubuntu-latest`.
|
|
|
|
## 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.
|
|
- 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 i prognozy są w UI rozdzielane.
|