Ergaenze Player- und Serverkonzept

README.md

@@ -17,6 +17,8 @@ Die Trennung von `/srv/docker/infoboard-netboot` ist sinnvoll, damit:
 - Technologieentscheidungen: `TECH-STACK.md`
 - Template-/Kampagnenkonzept: `docs/TEMPLATE-KONZEPT.md`
 - Provisionierungskonzept: `docs/PROVISIONIERUNGSKONZEPT.md`
+- Player-Konzept: `docs/PLAYER-KONZEPT.md`
+- Server-Konzept: `docs/SERVER-KONZEPT.md`
 
 ## Projektstruktur
 

ansible/README.md

@@ -0,0 +1,8 @@
+# Ansible
+
+Hier liegen spaeter Rollen, Playbooks und Inventories fuer:
+
+- Erstinstallation neuer Screens
+- Updates bestehender Screens
+- Server-Deployment
+- Display-spezifische Konfigurationen

docs/PLAYER-KONZEPT.md

@@ -0,0 +1,299 @@
+# Info-Board Neu - Player-Konzept
+
+## Ziel
+
+Der Player ist eine moeglichst schlanke Display-Appliance fuer Raspberry Pi OS Lite.
+
+Er soll:
+
+- Bilder, Videos, PDFs und Webseiten anzeigen
+- globale Kampagnen, tenantbezogene Playlists und Fallback sauber priorisieren
+- bei Serverausfall autonom weiterlaufen
+- per MQTT steuerbar sein
+- per Ansible einfach ausrollbar sein
+- moeglichst wenige Laufzeitabhaengigkeiten haben
+
+## Leitprinzip
+
+Chromium ist nur Renderer, nicht Steuerzentrale.
+
+Das bedeutet:
+
+- Chromium zeigt nur die lokale `player-ui`
+- die `player-ui` entscheidet, was angezeigt wird
+- der `player-agent` verwaltet Sync, Cache, Kommandos und Status
+- externe URLs werden nie unkontrolliert direkt als Hauptbrowserziel verwendet
+
+## Komponenten
+
+### `player-agent`
+
+Implementierung:
+
+- bevorzugt in `Go`
+- als einzelnes Binary auslieferbar
+
+Aufgaben:
+
+- Registrierung beim Server
+- Abruf von Konfiguration, Playlist, Kampagne und Medienmanifest
+- lokaler Mediencache
+- MQTT-Kommunikation
+- Heartbeat und Statusmeldungen
+- Screenshot-Erzeugung
+- Ausfuehrung von Admin-Kommandos
+- Ueberwachung von Chromium und `player-ui`
+
+### `player-ui`
+
+Implementierung:
+
+- lokale Web-Anwendung
+- von Chromium im Kiosk dargestellt
+
+Aufgaben:
+
+- Playlist-Logik lokal darstellen
+- Prioritaet `campaign > tenant_playlist > fallback` umsetzen
+- Bilder, Videos, PDFs und Webseiten anzeigen
+- Lade-Timeouts und Fehlerpfade umsetzen
+- Offline-/Degraded-Overlay anzeigen
+- Renderer-seitige Healthchecks liefern
+
+### Chromium
+
+Aufgabe:
+
+- reine Darstellung der lokalen `player-ui`
+
+Vorgaben:
+
+- Kiosk-Modus
+- Vollbild
+- moeglichst ohne weitere Browser-Interaktion
+- Neustart durch systemd/Watchdog erlaubt
+
+## Laufzeitmodell
+
+## Startreihenfolge
+
+1. Basis-System bootet
+2. X11-Minimalstack startet
+3. `player-agent` startet
+4. `player-ui` ist lokal erreichbar
+5. Chromium startet auf lokaler URL
+6. Agent fuehrt ersten Sync und Registrierungsablauf aus
+
+## Lokaler Zustand
+
+Der Player haelt lokal vor:
+
+- aktuelle Konfiguration
+- letzte gueltige Playlist
+- letzte gueltige Kampagne
+- lokales Medienmanifest
+- heruntergeladene Medien
+- Status-/Snapshot-Metadaten
+
+Empfohlene Pfade:
+
+- `/etc/signage/config.yml`
+- `/var/lib/signage/cache/`
+- `/var/lib/signage/media/`
+- `/var/lib/signage/state/`
+- `/var/log/signage/`
+
+## Inhaltsprioritaet
+
+Die Anzeigeentscheidung erfolgt immer in dieser Reihenfolge:
+
+1. aktive globale Kampagne fuer diesen Screen
+2. normale tenantbezogene Playlist
+3. lokaler Fallback aus dem konfigurierten Verzeichnis
+
+### Kampagnenmodus
+
+Wenn eine gueltige Kampagne fuer den Screen aktiv ist:
+
+- zeigt der Player nur den Kampagneninhalt
+- der Firmencontent wird temporär uebersteuert
+- nach Ablauf oder Deaktivierung springt der Player automatisch zurueck
+
+### Tenant-Playlist-Modus
+
+Wenn keine Kampagne aktiv ist:
+
+- wird die tenantbezogene Playlist ausgewertet
+- nur aktive und zeitlich gueltige Elemente werden angezeigt
+
+### Fallback-Modus
+
+Wenn weder Kampagne noch gueltige Playlist-Inhalte verfuegbar sind:
+
+- werden alle Dateien aus dem Fallback-Verzeichnis nacheinander angezeigt
+
+## Medientypen
+
+### Bild
+
+- lokal oder aus Cache
+- Anzeige fuer definierte Dauer
+
+### Video
+
+- lokal oder aus Cache
+- entweder feste Dauer oder bis Medienende
+
+### PDF
+
+- lokal oder aus Cache
+- Anzeige ueber Browser/PDF-Renderer
+
+### Webseite
+
+- live geladen oder kontrolliert zwischengespeichert
+- immer mit `load_timeout`
+- nie rohe Browser-Fehlerseite dauerhaft stehen lassen
+
+## Fehlerverhalten
+
+### Grundregeln
+
+- Fehler eines einzelnen Items duerfen den Player nicht blockieren
+- jeder Fehler fuehrt zu `retry`, `skip` oder `fallback`
+- haengende Browserfehlerseiten muessen aktiv verhindert werden
+
+### Typische Fehlerfaelle
+
+- Medium fehlt lokal
+- externe URL nicht erreichbar
+- PDF fehlerhaft
+- Video unlesbar
+- Webseite liefert 404/500 oder timeout
+
+### Reaktion
+
+- Fehler loggen
+- Status aktualisieren
+- ggf. Overlay auf `degraded`
+- zum naechsten Element wechseln oder definierte Retry-Logik ausfuehren
+
+## Offline-Verhalten
+
+Offline-Betrieb ist Standardfall, nicht Sonderfall.
+
+Wenn der Server nicht erreichbar ist:
+
+- laeuft die Wiedergabe lokal weiter
+- letzte gueltige Daten bleiben aktiv
+- Overlay zeigt den Verbindungszustand an
+- Heartbeats und Status koennen lokal zwischengespeichert oder spaeter aktualisiert werden
+
+## Overlay-Konzept
+
+Das Overlay soll klein und unaufdringlich sein.
+
+Zustaende:
+
+- `online`
+- `degraded`
+- `offline`
+
+Moegliche Anzeige:
+
+- kleines Symbol in Ecke
+- optional Text wie `offline - letzter Sync vor 2h`
+
+## Orientierung und Display-Konfiguration
+
+Jeder Screen hat:
+
+- fachliche Orientierung: `portrait` oder `landscape`
+- technische Rotation: `0`, `90`, `180`, `270`
+
+Diese Werte beeinflussen:
+
+- Chromium-Startkonfiguration
+- X11-/Display-Setup
+- Asset-Auswahl bei Kampagnen
+- Darstellung in der `player-ui`
+
+## Watchdogs
+
+### Agent-Watchdog
+
+- systemd Restart-Strategie
+- eigener Healthcheck fuer Sync und Broker-Verbindung
+
+### Renderer-Watchdog
+
+- Ueberwachung von Chromium
+- Erkennung haengender Darstellungen
+- geordneter Neustart bei Freeze oder Crash
+
+## Screenshots und Status
+
+Der Player erzeugt Screenshots:
+
+- bei Item-Wechsel
+- zyklisch
+- auf Admin-Anforderung
+
+Der Player meldet Status:
+
+- aktuelles Item
+- Quelle (`campaign`, `tenant_playlist`, `fallback`)
+- Fehlerstatus
+- letzter Sync
+- Heartbeat
+
+## MQTT-Kommandos auf dem Player
+
+Mindestens zu unterstuetzen:
+
+- `reload`
+- `restart_player`
+- `reboot`
+- `display_on`
+- `display_off`
+- `refresh_snapshot`
+- `clear_cache`
+
+## Minimaler Paketbedarf
+
+Auf dem Player anzustreben:
+
+- Raspberry Pi OS Lite
+- Xorg-Minimalstack
+- Chromium
+- eigenes Go-Binary
+- systemd
+
+Vermeiden:
+
+- LXDE/LXQt
+- LightDM, wenn nicht zwingend noetig
+- mehrere externe Viewer
+- schwergewichtige Laufzeitstapel auf dem Geraet
+
+## Zielstruktur im Repo
+
+Empfohlene Unterstruktur fuer den Player:
+
+- `player/agent/`
+- `player/ui/`
+- `player/systemd/`
+- `player/config/`
+- `player/scripts/`
+
+## Testfaelle fuer den Player
+
+- lokaler Start ohne Server
+- späterer Verbindungsaufbau zum Server
+- Wechsel zwischen Kampagne, Playlist und Fallback
+- kurzer Netzverlust
+- kaputte Web-URL
+- defektes PDF
+- Neustart von Chromium
+- Screenshot-Erzeugung
+- Rotation/Portrait/Landscape

docs/SERVER-KONZEPT.md

@@ -0,0 +1,269 @@
+# Info-Board Neu - Server-Konzept
+
+## Ziel
+
+Der Server ist die zentrale Steuer- und Verwaltungsinstanz der Plattform.
+
+Er soll:
+
+- Benutzer, Firmen und Screens verwalten
+- Medien und Playlists bereitstellen
+- globale Templates und Kampagnen steuern
+- Provisionierung neuer Screens ausloesen
+- Status, Screenshots und Heartbeats sammeln
+- MQTT und HTTPS sauber trennen
+
+## Grundprinzip
+
+Der Server ist die Quelle der fachlichen Wahrheit.
+
+Der Player bleibt trotzdem lauffaehig, wenn der Server temporaer nicht erreichbar ist.
+
+Das bedeutet:
+
+- Server verwaltet Konfiguration und Inhalte zentral
+- Player fuehrt lokal und robust aus
+- Server sendet Steuerimpulse, Player synchronisiert aktiv nach
+
+## Hauptkomponenten
+
+### Reverse Proxy
+
+Aufgaben:
+
+- TLS-Terminierung
+- Routing fuer API und Web-UIs
+- optionale Auth-/Header-Regeln
+
+### Backend-API
+
+Bevorzugte Sprache:
+
+- `Go`
+
+Aufgaben:
+
+- Authentifizierung und Autorisierung
+- CRUD fuer Tenants, Users, Screens, Medien, Playlists
+- Verwaltung globaler Templates und Kampagnen
+- Player-Sync-Endpunkte
+- Speicherung von Status und Screenshots
+- Start von Provisionierungsjobs
+
+### Admin-UI
+
+Aufgaben:
+
+- Gesamtübersicht aller Screens
+- Vorschau und Status
+- Template-/Kampagnenverwaltung
+- Kommandos und Provisionierung
+
+### Tenant-UI
+
+Aufgaben:
+
+- Uploads und Medienverwaltung pro Firma
+- Pflege der monitorbezogenen Playlist
+- Vorschau des eigenen Screens
+
+### Datenbank
+
+Empfehlung:
+
+- PostgreSQL
+
+Aufgaben:
+
+- Speicherung fachlicher Daten
+- Status, Jobs, Revisionen, Zuordnungen
+
+### MQTT-Broker
+
+Empfehlung:
+
+- Mosquitto
+
+Aufgaben:
+
+- Heartbeats
+- Statusmeldungen
+- Events
+- Kommandos und ACKs
+
+### Dateispeicher
+
+Aufgaben:
+
+- Uploads
+- Screenshots
+- ggf. serverseitig vorbereitete Medien
+
+V1:
+
+- Dateisystem ausreichend
+
+## Fachliche Bereiche
+
+## 1. Mandanten und Benutzer
+
+Der Server trennt:
+
+- globale Admins
+- tenantgebundene Nutzer
+
+Regel:
+
+- Firmen sehen nur ihren Bereich
+- Admins sehen alles
+
+## 2. Screen-Verwaltung
+
+Der Server kennt jeden Screen mit:
+
+- ID
+- Name
+- Klasse
+- Orientierung
+- Rotation
+- Tenant-Zuordnung
+- technischem Registrierungsstatus
+
+## 3. Medienverwaltung
+
+Der Server verwaltet:
+
+- Uploads
+- externe Medienreferenzen
+- Metadaten
+- tenant- oder screenspezifische Zuordnung
+
+## 4. Playlist-Verwaltung
+
+Der Server verwaltet tenantbezogene Inhalte pro Screen.
+
+Wichtige Felder:
+
+- Reihenfolge
+- Dauer
+- `valid_from`
+- `valid_until`
+- Fehlerstrategie
+- Cache-Politik
+
+## 5. Template- und Kampagnenverwaltung
+
+Der Server stellt den globalen Orchestrierungsbereich bereit.
+
+Funktionen:
+
+- Templates erstellen
+- Szenen pflegen
+- Zielgruppen waehlen
+- Kampagnen aktivieren/deaktivieren
+- Zeitfenster setzen
+- Uebersteuerung sichtbar machen
+
+## 6. Provisionierung
+
+Der Server startet Provisionierungsjobs fuer neue Screens.
+
+Aufgaben:
+
+- Eingaben aus Admin-UI entgegennehmen
+- Job anlegen
+- Secret-Handling absichern
+- Worker oder Jobrunner starten
+- Fortschritt speichern
+- Fehler sauber rueckmelden
+
+## API-Bereiche
+
+Die API soll mindestens diese Domänen haben:
+
+- `auth`
+- `tenants`
+- `users`
+- `screens`
+- `media`
+- `playlists`
+- `templates`
+- `campaigns`
+- `player`
+- `commands`
+- `provisioning`
+
+## Revisionsmodell
+
+Der Server arbeitet mit Revisionen, damit Player effizient synchronisieren koennen.
+
+Mindestens:
+
+- `config_revision`
+- `playlist_revision`
+- `media_revision`
+- `campaign_revision`
+
+## Status- und Vorschaukonzept
+
+Der Server speichert:
+
+- letzten bekannten Heartbeat
+- letzten Status
+- letzten Screenshot
+- aktuelle Inhaltsquelle pro Screen
+
+Die Admin-UI soll damit erkennen:
+
+- online/offline
+- normaler tenantbezogener Betrieb
+- globale Kampagnen-Uebersteuerung
+- Fallback-Betrieb
+- Fehlerzustand
+
+## Provisionierungsjobrunner
+
+Die Provisionierung soll nicht direkt in Web-Requests laufen.
+
+Stattdessen:
+
+- API legt Job an
+- dedizierter Worker/Jobrunnner arbeitet ihn ab
+- Fortschritt wird in DB gespeichert
+
+## Docker-Compose-Zielbild
+
+Sinnvolle Komponenten in `compose/`:
+
+- `reverse-proxy`
+- `backend`
+- `postgres`
+- `mosquitto`
+- optional `worker`
+
+## Sicherheitsgrundsaetze
+
+- Root-Bootstrap-Geheimnisse nur kurzlebig oder referenziert speichern
+- API- und MQTT-Zugaenge getrennt behandeln
+- alle Admin-Kommandos auditieren
+- Tenant-Trennung strikt serverseitig erzwingen
+
+## Zielstruktur im Repo
+
+Empfohlene Unterstruktur fuer den Server:
+
+- `server/backend/`
+- `server/admin-ui/`
+- `server/tenant-ui/`
+- `server/worker/`
+- `compose/`
+
+## Testfaelle fuer den Server
+
+- Tenant sieht nur eigene Daten
+- Admin sieht alle Daten
+- Kampagne ueberschreibt tenantbezogenen Content korrekt
+- Screen-Provisionierung legt Job sauber an
+- Player-Sync ueber Revisionen funktioniert
+- MQTT-Kommandos werden protokolliert
+- Screenshot-Upload erscheint im Admin-Dashboard

player/README.md

@@ -0,0 +1,11 @@
+# Player
+
+Hier liegen spaeter die Komponenten fuer den Screen-Client.
+
+Geplant:
+
+- `agent/` fuer den `player-agent`
+- `ui/` fuer die lokale `player-ui`
+- `systemd/` fuer Units
+- `config/` fuer Beispielkonfigurationen
+- `scripts/` fuer lokale Hilfsskripte

server/README.md

@@ -0,0 +1,10 @@
+# Server
+
+Hier liegen spaeter die zentralen Server-Komponenten.
+
+Geplant:
+
+- `backend/` fuer API und Fachlogik
+- `admin-ui/` fuer die Admin-Oberflaeche
+- `tenant-ui/` fuer die Firmenoberflaeche
+- `worker/` fuer Provisionierungs- und Hintergrundjobs