docs: reorganize project documentation

docs/notifications.md

@@ -0,0 +1,117 @@
+# Powiadomienia Web Push
+
+Powiadomienia obejmują:
+
+- nowe ostrzeżenia meteorologiczne IMGW,
+- poranny brief dnia,
+- wieczorny brief z prognozą na jutro,
+- testowe powiadomienie wysyłane z `/settings`.
+
+Konfiguracja użytkownika znajduje się w widoku `/settings`.
+
+## Wymagania
+
+Do wysyłki Web Push potrzebne są klucze VAPID:
+
+```bash
+WEB_PUSH_VAPID_PUBLIC_KEY=
+WEB_PUSH_VAPID_PRIVATE_KEY=
+WEB_PUSH_VAPID_SUBJECT=mailto:admin@example.com
+```
+
+Klucze można wygenerować poleceniem:
+
+```bash
+npx web-push generate-vapid-keys
+```
+
+Endpointy harmonogramu wymagają też sekretu crona w produkcji:
+
+```bash
+NOTIFICATIONS_CRON_SECRET=
+```
+
+## Preferencje Subskrypcji
+
+Subskrypcja Web Push zapisuje:
+
+- endpoint subskrypcji przeglądarki,
+- województwo,
+- język interfejsu,
+- czy ostrzeżenia są aktywne,
+- czy aktywny jest brief poranny,
+- czy aktywny jest brief na jutro,
+- współrzędne i nazwę lokalizacji,
+- opcjonalny powiat TERYT.
+
+Ostrzeżenia meteo są filtrowane po powiecie TERYT, jeśli lokalizacja go dostarcza. W przeciwnym razie używany jest fallback wojewódzki.
+
+## Worker Self-Hosted
+
+Worker powiadomień uruchamia się osobno od aplikacji:
+
+```bash
+npm run notifications:worker
+```
+
+Wymaga równolegle działającej aplikacji Next.js. Domyślnie odpytuje:
+
+```bash
+http://127.0.0.1:3000
+```
+
+Jeśli aplikacja działa pod innym adresem albo portem, ustaw:
+
+```bash
+WTR_APP_URL=http://127.0.0.1:4000
+```
+
+Worker wczytuje `.env` i `.env.local`. Zmienne ustawione bezpośrednio w shellu mają pierwszeństwo.
+
+## Harmonogram
+
+Domyślna konfiguracja:
+
+```bash
+NOTIFICATIONS_WARNING_INTERVAL_MINUTES=5
+NOTIFICATIONS_MORNING_BRIEF_TIME=07:00
+NOTIFICATIONS_TOMORROW_BRIEF_TIME=18:00
+```
+
+Worker:
+
+- sprawdza nowe ostrzeżenia co 5 minut,
+- po 07:00 czasu `Europe/Warsaw` wywołuje `/api/notifications/daily-brief`,
+- po 18:00 czasu `Europe/Warsaw` wywołuje `/api/notifications/tomorrow-brief`,
+- nie blokuje jednego harmonogramu błędem drugiego.
+
+Endpointy harmonogramu nie uruchamiają się same bez workera albo zewnętrznego crona.
+
+## Zewnętrzny Cron
+
+Jeśli nie używasz `npm run notifications:worker`, zewnętrzny cron powinien wywoływać:
+
+```text
+GET /api/notifications/check
+GET /api/notifications/daily-brief
+GET /api/notifications/tomorrow-brief
+```
+
+W produkcji dodaj jeden z nagłówków:
+
+```http
+Authorization: Bearer <NOTIFICATIONS_CRON_SECRET>
+x-cron-secret: <NOTIFICATIONS_CRON_SECRET>
+```
+
+## Platformy
+
+- iOS/iPadOS wymaga dodania PWA do ekranu początkowego i uruchomienia aplikacji z ikony.
+- Android i desktop nie są blokowane wymogiem `standalone`, jeśli przeglądarka obsługuje Web Push.
+- GPS i powiadomienia wymagają bezpiecznego kontekstu HTTPS poza wyjątkami typu `localhost`.
+
+## Ograniczenia
+
+Obecny `lib/push-store.ts` przechowuje subskrypcje i historię wysyłek w pamięci procesu. Po restarcie procesu te dane znikają. Produkcja wymaga trwałego magazynu, np. bazy danych albo KV.
+
+Powiadomienie testowe jest wysyłane na konkretny endpoint subskrypcji przekazany z `/settings`, a nie broadcastowane do wszystkich urządzeń.