screenCockpit Center-Pairing (Magic-Link)
Was
Im Dashboard unter Digital Experience → DOOH Video gibt es die Karte screenCockpit. Ein Center kann sich dort mit genau einem Standort in screenCockpit (DOOH-Signage-Plattform) verbinden: Verbinden, Verbindung testen, Trennen. Gespeichert werden pro Center Standort-ID, Name, Code, Berechtigungen und der verschlüsselte API-Key.
Bewusst nicht Teil des Pairings: Playlist-Editor und Content-Push-Assistent im Dashboard. Read-only Playlist-Liste am verbundenen Standort: siehe unten.
Warum
screenCockpit vergibt API-Keys pro Standort. Bisher musste ein Admin Keys von Hand anlegen und weitergeben. Der Magic-Link-Flow (wie bei AgencyOS) vermeidet Copy-Paste von Geheimnissen: Die Freigabe passiert einmalig in screenCockpit, cockpitOS übernimmt den Key automatisch.
Wer ist betroffen
- Center-Betrieb / Redaktion (Rollen mit Redaktions- und Technikzugriff und Center-Zugang): verbinden, testen, trennen.
- IT / Betrieb: Env-Variablen setzen, Key bei Bedarf in screenCockpit widerrufen.
Ablauf
- Dashboard
POST /api/centers/{centerId}/screencockpit/connectruft screenCockpitPOST /api/agencyos/magic-linkauf (HeaderX-AgencyOS-Secret,returnUrl= Dashboard-DOOH-Seite mitscreencockpit=return¢erId=…). Antwort:token,magicLink. - Das Dashboard speichert den Link als
PENDING(lokal 14 Minuten gültig, screenCockpit: ca. 15 Minuten) und öffnetmagicLinkin einem neuen Tab. - Admin meldet sich in screenCockpit an, wählt den Standort und klickt Zugriff erlauben; screenCockpit leitet zurück zur
returnUrl(agencyos=connected|rejected). - Die Karte pollt
GET …/screencockpit/status(alle 4 s, solangePENDING). Der Server fragtGET /api/agencyos/magic-link/status?token=…ab. - Bei
completedliefert screenCockpit denapiKeynur einmal. cockpitOS verschlüsselt ihn sofort (AES-256-GCM) und liest danachGET /api/v1/contextfür Standort-ID/-Name/-Code und Scopes. - Link-Token und Magic-Link-URL werden gelöscht, Status
CONNECTED.
Robustheit:
- Paralleles Polling (mehrere Tabs): atomarer Claim (
poll_claimed_at, 15 s), damit nur ein Request den einmaligen Key abholt. - Key da, Kontext-Abruf scheitert: Verbindung wird trotzdem gespeichert (Key ist nicht erneut abrufbar);
…/testzieht Standort-Mapping nach. completedohne Key (bereits abgeholt): StatusFAILED, Hinweis „Bitte neu verbinden“.- Netzwerkfehler beim Poll: Link bleibt
PENDING, nächster Poll versucht es erneut. - Bereits verbunden:
connectantwortet 409; zuerst trennen.
API (Dashboard, Session + Center-Zugriff)
Alle Routen unter /api/centers/{centerId}/screencockpit/…; Rollen wie Redaktion/Technik (EDITORIAL_AND_TECH_ROLES) plus assertCenterAccess. Antworten enthalten nie den API-Key oder das Magic-Link-Token.
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /connect | Magic-Link starten (oder gültigen offenen Link wiederverwenden) |
| GET | /status | Status; pollt bei PENDING screenCockpit und übernimmt den Key |
| POST | /test | GET /api/v1/context mit gespeichertem Key, aktualisiert Standort + last_tested_at |
| POST | /disconnect | Link und Key lokal löschen (funktioniert auch ohne Env-Konfiguration) |
| GET | /playlists | Read-only Proxy zu screenCockpit GET /api/v1/playlists?locationId=… (Key X-Api-Key, Scopes siehe oben) |
| GET, PUT | /idle-source | Idle-Quelle des Kiosks: { idleDoohSource: cockpit | screencockpit, idleScreenCockpitPlaylistId }. PUT mit screencockpit verlangt eine Playlist-ID. Der Kiosk liest die Items serverseitig über GET /api/v1/playlists/{id}/items?activeOnly=true (siehe Kiosk-Idle). Hinweis: GET …/playlists liefert pro Playlist itemCount (gesamt); die Items-API mit activeOnly=true kann weniger Zeilen zurückgeben (Zeitplan upstream in screenCockpit). cockpitOS mappt VIDEO/IMAGE mit abspielbarer URL: http(s)://… oder root-relative /uploads/… (wird gegen SCREENCOCKPIT_BASE_URL absolut gemacht) — Abweichungen erscheinen in Render-Logs unter [dooh-idle-screencockpit]. |
Standard-Magic-Link-Keys haben oft content:push und status:read. Für die Playlist-Übersicht im Dashboard braucht der Key playlists:read (oder weiterhin content:push, das Listen erlaubt). Fehlt beides, zeigt die UI einen Hinweis zum Neu-Verbinden mit erweiterter Freigabe in screenCockpit.
Team-Regeln (Kiosk vs. Wand-Player): DOOH & Signage — Zuständigkeiten.
Datenmodell
Tabelle center_screencockpit_links (Prisma CenterScreenCockpitLink), ein Eintrag pro Center, ON DELETE CASCADE. Rein additiv, keine Änderung an ShoppingCenter-Spalten. Siehe db_structure.md. Migration: packages/database/migrations/20261019120000_center_screencockpit_link_SAFE.sql.
Status: PENDING, CONNECTED, REJECTED, EXPIRED, FAILED.
Betrieb (Env, keine Secrets in Doku)
| Variable | Pflicht | Bedeutung |
|---|---|---|
SCREENCOCKPIT_BASE_URL | ja | Basis-URL der screenCockpit-Instanz, z. B. https://… (nur Origin wird genutzt) |
SCREENCOCKPIT_AGENCYOS_MAGIC_LINK_SECRET | in Produktion ja | Gleicher Wert wie AGENCYOS_MAGIC_LINK_SECRET bei screenCockpit; wird als X-AgencyOS-Secret gesendet |
SCREENCOCKPIT_TOKEN_KEY | empfohlen | Schlüssel für die Verschlüsselung der gespeicherten API-Keys. Fehlt er, wird NEXTAUTH_SECRET genutzt (bei dessen Rotation muss neu verbunden werden) |
Ohne Konfiguration zeigt die Karte einen Hinweis; connect/test antworten 503. Das Ziel (SCREENCOCKPIT_BASE_URL) ist fest per Env — keine nutzergelieferten URLs, daher kein SSRF-Pfad. Magic-Link-URLs aus der Antwort müssen http(s) sein.
So testen
- Env setzen (Render
mallos-dashboardbzw..env.local), Migration einspielen. - Dashboard → Digital Experience → DOOH Video, Center wählen → Mit screenCockpit verbinden.
- In screenCockpit Standort wählen, Zugriff erlauben. Zurück im Dashboard: Status Verbunden, Standort sichtbar.
- Verbindung testen → Erfolgsmeldung; mit widerrufenem Key → Hinweis „neu verbinden“.
- Trennen → Karte zeigt wieder Mit screenCockpit verbinden.
Automatische Tests: pnpm --filter @mall-os/dashboard exec vitest run src/lib/screencockpit.
Code
apps/dashboard/src/lib/screencockpit/—config.ts,client.ts(HTTP),link-state.ts(reine Logik),link-service.ts(Orchestrierung),link-store.ts(Prisma),secret-crypto.ts,route-helpers.tsapps/dashboard/src/components/screencockpit/— Karte + Hook- Vertrag der Gegenseite: Repo
smg-dooh-light,docs/AGENCYOS_INTEGRATION.md
Nicht in dieser Lieferung
MCP-Tool/AgencyOS-Route für Playlists: bewusst nicht ergänzt. Content-Push-Assistent und Schreibzugriff folgen in Epic PR-2 (Skizze in project_specs.md, Abschnitt „Content-Push nach screenCockpit“).
Nutzer-Sicht: DOOH-Modus im Kiosk, Zuständigkeiten.
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/screencockpit-center-pairing