morz-infoboard/PLAN.md

# Info-Board Neu - Architekturplan

## Zielbild

Das neue System ersetzt die bestehende `pictur`-/LXDE-basierte Loesung durch eine schlanke, zentral verwaltete Signage-Plattform.

Ziele:

- moeglichst wenig Ballast auf den Player-Clients
- Anzeige von Bildern, Videos, PDFs und Webseiten
- flexible Playlist pro Monitor
- Fallback auf sequentielle Anzeige aller Medien aus einem konfigurierten Verzeichnis
- mandantenfaehige Pflegeoberflaeche pro Monitor/Firma
- Admin-Oberflaeche fuer Gesamtsteuerung aller Monitore
- autonomer Offline-Betrieb bei Serverausfall
- einfache Verteilung per Ansible
- moeglichst geringe Abhaengigkeit vom Unterbau innerhalb Debian-/Raspberry-Pi-OS-Welt

## Basisentscheidungen

### Betriebssystem

- Player-Basis: aktuelles Raspberry Pi OS Lite auf Debian-13-Basis
- Server-Basis: Debian-artiges System, bevorzugt containerisiert
- keine volle Desktop-Umgebung auf den Playern

### Display-Stack

- fuer Version 1 X11 statt Wayland
- Grund: konservativer, besser vorhersehbar fuer Chromium-Kiosk, Screenshot-Erzeugung, Watchdogs und Raspberry-spezifische Display-Steuerung
- kein LXDE, kein LightDM als Komfortschicht, nur ein minimaler X11-Kiosk-Stack

### Container-Strategie

- Server: Docker Compose ist sinnvoll und empfohlen
- Player: kein Voll-Docker-Ansatz fuer den Grafikpfad in Version 1
- Player besser als native Dienste mit systemd + Chromium-Kiosk

## Gesamtarchitektur

Das System besteht aus zwei Hauptteilen:

1. zentraler Server fuer Verwaltung, API, Medien, Rechte und Steuerung
2. schlanke Player-Clients auf den Monitoren

### Server-Komponenten

- Reverse Proxy
- Backend API
- Admin-Oberflaeche
- mandantenbezogene Management-Oberflaeche
- PostgreSQL
- MQTT-Broker
- Dateispeicher fuer Uploads, Vorschaubilder und Screenshots

### Player-Komponenten

- `player-agent` als nativer systemd-Dienst
- `player-ui` als lokale Web-Anwendung
- Chromium im Kiosk-Modus, der nur die lokale `player-ui` rendert
- lokaler Cache fuer Playlist, Medien und Status

## Rollenmodell

### Monitor-/Firmen-Oberflaeche

Jede Firma sieht nur den ihr zugeordneten Monitor bzw. Kanal.

Funktionen:

- Medien hochladen
- Medien loeschen und ordnen
- Playlist pflegen
- Anzeigedauer je Eintrag festlegen
- `valid_from` und `valid_until` setzen
- lokale Vorschau des eigenen Monitors sehen

### Admin-Oberflaeche

Die Administration der Schule sieht und steuert die gesamte Anlage.

Funktionen:

- Inhalte aller Monitore verwalten
- Monitore global uebersichtlich sehen
- Vorschau/Screenshots aller Monitore sehen
- Reload des Players ausloesen
- Seite neu laden
- Dienste neu starten
- Monitore rebooten
- Monitore an- und ausschalten

## Datenmodell

### Zentrale Entitaeten

- `tenant`
- `screen`
- `user`
- `media_asset`
- `playlist`
- `playlist_item`
- `screen_status`
- `screen_snapshot`
- `device_command`
- `sync_state`

### Wichtige Felder

#### `screen`

- `id`
- `name`
- `tenant_id`
- `location`
- `rotation`
- `resolution`
- `enabled`

#### `media_asset`

- `id`
- `tenant_id`
- `type` (`image`, `video`, `pdf`, `web`)
- `source_kind` (`upload`, `remote_url`)
- `storage_path`
- `original_url`
- `checksum`
- `mime_type`
- `created_at`

#### `playlist_item`

- `id`
- `playlist_id`
- `screen_id`
- `order_index`
- `type`
- `src`
- `duration`
- `valid_from`
- `valid_until`
- `load_timeout`
- `cache_policy`
- `on_error`
- `enabled`

#### `screen_status`

- `screen_id`
- `online`
- `last_heartbeat`
- `current_item`
- `current_type`
- `current_since`
- `last_sync_at`
- `server_connected`
- `cache_state`
- `error_state`

#### `screen_snapshot`

- `screen_id`
- `captured_at`
- `image_path`

## Playlist-Konzept

### Unterstuetzte Typen

- Bild
- Video
- PDF
- Webseite
- Verzeichnisreferenz als Fallback-/Sammelquelle

### Pro Eintrag steuerbar

- Dauer
- Gueltigkeit ueber `valid_from` und `valid_until`
- Reihenfolge
- Timeout fuer das Laden
- Cache-Strategie
- Fehlerverhalten (`skip`, `retry`, `fallback`)

### Fallback-Regel

Wenn keine aktive Playlist vorhanden ist oder kein gueltiges Item aktiv ist, zeigt der Player alle Medien aus einem konfigurierten Fallback-Verzeichnis nacheinander an.

Eigenschaften:

- deterministische Reihenfolge, standardmaessig alphabetisch
- medientypgerechte Anzeigezeiten
- funktioniert komplett lokal aus dem Cache oder Dateisystem

## Offline- und Cache-Strategie

Offline-Betrieb ist Pflicht.

Der Player speichert lokal:

- die letzte gueltige Playlist
- alle noetigen Medien
- letzten bekannten Status
- letzte Server-/Sync-Metadaten

Bei Serverausfall:

- Wiedergabe laeuft lokal weiter
- ein kleines Overlay-Symbol zeigt den Offline-Zustand an
- Heartbeat wird lokal gepuffert oder beim Wiederverbinden aktualisiert

### Overlay-Zustaende

- gruen: online
- gelb: Verbindung instabil oder Daten veraltet
- rot: keine Verbindung zum Server

## Vermeidung von Chromium-Haengern

Chromium rendert niemals direkt externe Medien- oder Playlist-URLs.

Stattdessen:

- Chromium zeigt nur `http://127.0.0.1:<port>/player`
- die lokale `player-ui` kapselt alle Medien und Fehlerzustande
- externe Medien werden vorher geladen oder lokal gespiegelt, wo immer moeglich

Konsequenzen:

- keine haengenden 404-Fehlerseiten als Hauptansicht
- Timeouts pro Inhalt moeglich
- bei Fehlern: Skip oder Fallback statt Stehenbleiben
- lokaler Watchdog kann Anzeige und Browser neu initialisieren

## Vorschaukonzept

Eine Vorschau ist sinnvoll, aber nicht als permanenter Livestream.

Empfohlene Umsetzung:

- Screenshot bei Item-Wechsel
- zusaetzlicher Screenshot in Intervallen, z. B. alle 30 bis 60 Sekunden
- Anzeige des letzten Screenshots in Admin- und Firmen-Oberflaeche
- ergaenzt durch strukturierte Statusdaten

Statusdaten:

- aktuelles Item
- Typ
- Startzeit
- Restlaufzeit
- letzter Heartbeat
- letzter Sync
- Fehlerstatus

## Kommunikation

### HTTPS

Fuer:

- Login
- Uploads
- API-Aufrufe
- Playlist-Bearbeitung
- Download von Medien und Konfiguration
- Abruf von Screenshots und Status

### MQTT

Fuer:

- Heartbeat
- Statusmeldungen
- Kommandos
- Acknowledgements
- Hinweis auf Playlist-Aenderungen

### MQTT-Topics

- `signage/screen/<screen-id>/heartbeat`
- `signage/screen/<screen-id>/status`
- `signage/screen/<screen-id>/event`
- `signage/screen/<screen-id>/command`
- `signage/screen/<screen-id>/ack`

### Befehle

- `reload`
- `restart_player`
- `reboot`
- `display_on`
- `display_off`
- `refresh_snapshot`
- `clear_cache`

## Player-Aufbau

### `player-agent`

Aufgaben:

- Registrierung des Geraets
- HTTPS-Sync
- MQTT-Kommunikation
- Cache-Verwaltung
- Befehlsausfuehrung
- Screenshot-Erzeugung
- Ueberwachung lokaler Dienste

### `player-ui`

Aufgaben:

- lokale Wiedergabeoberflaeche
- Darstellung von Bild, Video, PDF und Web
- Auswertung von Zeitfenstern
- Umschalten zwischen Playlist und Fallback
- Offline-/Fehler-Overlay

## Server-Aufbau

### Kernkomponenten

- API-Backend
- Admin-Frontend
- Tenant-Frontend
- MQTT-Broker
- Datenbank
- Media-Storage

### Betriebsform

- bevorzugt per Docker Compose
- klare Trennung von persistenten Daten, Konfiguration und Deploy-Code

## Minimale Abhaengigkeiten auf dem Player

Das Ziel ist ein moeglichst kleiner Satz an Laufzeitabhaengigkeiten.

Bevorzugt:

- Raspberry Pi OS Lite
- Xorg-Minimalstack
- Chromium
- ein eigenes Player-Binary oder eine sehr schlanke Laufzeit
- systemd

Vermeiden:

- voller Desktop
- mehrere externe Viewer wie `feh`, `vlc`, `wmctrl`, `xdg-open`
- Python-/Node-Laufzeiten mit grossem Paketbaum direkt auf dem Client, wenn vermeidbar

## Ansible-Zielstruktur

### Rollen

- `signage_base`
- `signage_player`
- `signage_display`
- `signage_server`

### Konfigurationspfade auf dem Client

- `/etc/signage/config.yml`
- `/var/lib/signage/cache/`
- `/var/lib/signage/media/`
- `/var/lib/signage/state/`
- `/var/log/signage/`

## Migrationsstrategie

1. Architektur finalisieren
2. Datenmodell finalisieren
3. Minimalen Player-Prototyp bauen
4. Server-Minimalversion bauen
5. Referenz-Raspi aufsetzen
6. Offline-/Netzfehler-/Timeout-Szenarien testen
7. Management-Oberflaechen ausbauen
8. Ansible-Rollen erstellen
9. Einen Pilotmonitor migrieren
10. Restliche Monitore sukzessive migrieren

## Teststrategie

Zu testen sind mindestens:

- kurzer Netzverlust
- kompletter Serverausfall
- MQTT-Ausfall bei funktionierendem HTTPS
- HTTPS-Ausfall bei funktionierendem MQTT
- kaputte URL in Playlist
- defekte PDF-Datei
- grosses Video
- Wechsel von `valid_from`/`valid_until` waehrend des laufenden Betriebs
- Reload aus der Admin-Oberflaeche
- Dienstneustart aus der Admin-Oberflaeche
- Reboot aus der Admin-Oberflaeche
- Display an/aus
- Screenshot-Erzeugung unter Last

## Projektstruktur-Empfehlung

Ein separates Projektverzeichnis ist sinnvoll, um die neue Architektur sauber von der bestehenden Netboot-Struktur zu trennen.

Empfohlener Pfad:

- `/srv/docker/info-board-neu`

Dieses Verzeichnis sollte mindestens enthalten:

- `PLAN.md`
- `TODO.md`
- spaeter `compose/`, `ansible/`, `server/`, `player/`, `docs/`