Add guest push notifications and queue alerts

docs/deployment/docker.md

@@ -79,6 +79,16 @@ To enable Horizon (dashboard, smart balancing):
 docker compose --profile horizon up -d horizon
 ```
 
+## 6. Scheduler & cron jobs
+
+The compose stack ships a `scheduler` service that runs `php artisan schedule:work`, so all scheduled commands defined in `App\Console\Kernel` stay active. For upload health monitoring, keep the helper script from `cron/upload_queue_health.sh` on the host (or inside a management container) and add a cron entry:
+
+```
+*/5 * * * * /var/www/html/cron/upload_queue_health.sh
+```
+
+This wrapper logs to `storage/logs/cron-upload-queue-health.log` and executes `php artisan storage:check-upload-queues`, which in turn issues guest-facing upload alerts when queues stall or fail repeatedly. In containerised environments mount the repository so the script can reuse the same PHP binary as the app, or call the artisan command directly via `docker compose exec app php artisan storage:check-upload-queues`.
+
 The dashboard becomes available at `/horizon` and is protected by the Filament super-admin auth guard.
 
 ## 6. Persistent data & volumes

docs/ops/guest-notification-ops.md

@@ -0,0 +1,68 @@
+## Guest Notification & Push Ops Guide
+
+This runbook explains how to keep the guest notification centre healthy, roll out web push, and operate the new upload health alerts.
+
+### 1. Database & config prerequisites
+
+1. Run the latest migrations so the `push_subscriptions` table exists:
+   ```bash
+   php artisan migrate --force
+   ```
+2. Generate VAPID keys (using `web-push` or any Web Push helper) and store them in the environment:
+   ```
+   PUSH_ENABLED=true
+   PUSH_VAPID_PUBLIC_KEY=<base64-url-key>
+   PUSH_VAPID_PRIVATE_KEY=<base64-url-key>
+   PUSH_VAPID_SUBJECT="mailto:ops@example.com"
+   ```
+3. Redeploy the guest PWA (Vite build) so the runtime config exposes the new keys to the service worker.
+
+### 2. Queue workers
+
+Push deliveries are dispatched on the dedicated `notifications` queue. Ensure one of the queue workers listens to it:
+
+```bash
+docs/queue-supervisor/queue-worker.sh default,notifications
+```
+
+If Horizon is in use just add `notifications` to the list of queues for at least one supervisor. Monitor `storage/logs/notifications.log` (channel `notifications`) for transport failures.
+
+### 3. Upload health alerts
+
+The `storage:check-upload-queues` command now emits guest-facing alerts when uploads stall or fail repeatedly. Schedule it every 5 minutes via cron (see `cron/upload_queue_health.sh`) or the Laravel scheduler:
+
+```
+*/5 * * * * /var/www/html/cron/upload_queue_health.sh
+```
+
+Tune thresholds with the `STORAGE_QUEUE_*` variables in `.env` (see `.env.example` for defaults). When an alert fires, the tenant admin toolkit also surfaces the same issues.
+
+### 4. Manual API interactions
+
+- Register push subscription (from browser dev-tools):
+  ```
+  POST /api/v1/events/{token}/push-subscriptions
+  Headers: X-Device-Id
+  Body: { endpoint, keys:{p256dh, auth}, content_encoding }
+  ```
+- Revoke subscription:
+  ```
+  DELETE /api/v1/events/{token}/push-subscriptions
+  Body: { endpoint }
+  ```
+- Inspect per-guest state:
+  ```bash
+  php artisan tinker
+  >>> App\Models\PushSubscription::where('event_id', 123)->get();
+  ```
+
+### 5. Smoke tests
+
+After enabling push:
+
+1. Join a published event, open the notification centre, and enable push (browser prompt must appear).
+2. Trigger a host broadcast or upload-queue alert; confirm the browser shows a native notification and that the notification drawer refreshes without polling.
+3. Temporarily stop the upload workers to create ≥5 pending assets; re-run `storage:check-upload-queues` and verify guests receive the “Uploads werden noch verarbeitet …” message.
+
+Document any deviations in `docs/changes/` for future regressions.
+

docs/prp/07-guest-pwa.md

@@ -41,6 +41,8 @@ Core Features
   - Header bell opens a drawer that merges upload queue stats with server-driven notifications (photo highlights, major achievements, host broadcasts, upload failure hints, feedback reminders).
   - Data fetched from `/api/v1/events/{token}/notifications` with `X-Device-Id` for per-device read receipts; guests can mark items as read/dismissed and follow CTAs (internal routes or external links).
   - Pull-to-refresh + background poll every 90s to keep single-day events reactive without WS infrastructure.
+  - When push is available (VAPID keys configured) the drawer surfaces a push toggle, persists subscriptions via `/push-subscriptions`, and the service worker refreshes notifications after every push message.
+  - Operations playbook: see `docs/ops/guest-notification-ops.md` for enabling push, required queues, and cron health checks.
 - Privacy & legal
   - First run shows legal links (imprint/privacy); consent for push if enabled.
   - No PII stored; guest name is optional free text and not required by default.
@@ -103,6 +105,8 @@ API Touchpoints
 - POST `/api/v1/photos/{id}/like` — idempotent like with device token.
 - GET `/api/v1/events/{token}/notifications` — list guest notifications (requires `X-Device-Id`).
 - POST `/api/v1/events/{token}/notifications/{notification}/read|dismiss` — mark/dismiss notification with device identity.
+- POST `/api/v1/events/{token}/push-subscriptions` — register a browser push subscription (requires `X-Device-Id` + VAPID public key).
+- DELETE `/api/v1/events/{token}/push-subscriptions` — revoke a stored push subscription by endpoint.
 
 Limits (MVP defaults)
 - Max uploads per device per event: 50

docs/queue-supervisor/README.md

@@ -62,6 +62,8 @@ services:
 
 Scale workers by increasing `deploy.replicas` (Swarm) or adding `scale` counts (Compose v2).
 
+> **Heads-up:** Guest push notifications are dispatched on the `notifications` queue. Either add that queue to the default worker (`queue-worker.sh default,notifications`) or create a dedicated worker so push jobs are consumed even when other queues are busy.
+
 ### 3. Optional: Horizon container
 
 If you prefer Horizon’s dashboard and auto-balancing, add another service: