Add guest push notifications and queue alerts

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.
+