## 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
/var/www/html/scripts/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/process/changes/` for future regressions.