# Info-Board Neu - Datenmodell

## Ziel

Das Datenmodell trennt klar zwischen:

- Mandanten und Benutzern
- Bildschirmen und ihrer technischen Laufzeitinformation
- Medien und Playlists
- Steuerbefehlen und Rueckmeldungen

Das Modell ist so ausgelegt, dass:

- jede Firma nur ihren eigenen Monitor bzw. Kanal pflegt
- die Administration alle Monitore zentral sehen und steuern kann
- Offline-Betrieb der Player moeglich bleibt
- Zeitsteuerung mit `valid_from` und `valid_until` sauber abbildbar ist

## Kernentitaeten

### `tenant`

Repraesentiert eine Firma bzw. einen abgeschotteten Inhaltsbereich.

Felder:

- `id`
- `slug`
- `name`
- `active`
- `created_at`
- `updated_at`

Hinweise:

- ein Tenant kann spaeter mehrere Screens haben, auch wenn zunaechst meist 1:1 gearbeitet wird
- alle Medien und Playlists sind einem Tenant zugeordnet

### `user`

Repraesentiert einen Benutzer der Firmen- oder Admin-Oberflaeche.

Felder:

- `id`
- `tenant_id` nullable fuer globale Admins
- `username`
- `email`
- `password_hash`
- `role` (`admin`, `tenant_user`)
- `active`
- `last_login_at`
- `created_at`
- `updated_at`

Regeln:

- `tenant_user` darf nur Daten des eigenen Tenants sehen und bearbeiten
- `admin` darf alle Tenants und alle Screens verwalten

### `screen`

Repraesentiert einen physischen Monitor bzw. einen Player-Client.

Felder:

- `id`
- `tenant_id`
- `slug`
- `name`
- `description`
- `location`
- `hardware_name`
- `enabled`
- `rotation` (`0`, `90`, `180`, `270`)
- `resolution_width`
- `resolution_height`
- `fallback_dir`
- `snapshot_interval_seconds`
- `offline_overlay_enabled`
- `created_at`
- `updated_at`

Hinweise:

- der `slug` dient als technische Kennung fuer Konfiguration, API und MQTT
- `fallback_dir` beschreibt die lokale oder synchronisierte Fallback-Quelle auf dem Client

### `screen_registration`

Optionale Trennung zwischen fachlichem Screen und technischer Registrierung.

Felder:

- `id`
- `screen_id`
- `device_uuid`
- `hostname`
- `api_token_hash`
- `mqtt_client_id`
- `last_seen_at`
- `last_ip`
- `player_version`
- `os_version`
- `created_at`
- `updated_at`

Zweck:

- Wiedererkennung eines konkreten Geraets
- sichere Kommunikation mit API und Broker
- technische Inventarisierung

### `provisioning_job`

Repraesentiert einen Provisionierungslauf fuer einen neuen oder neu aufzubauenden Screen.

Felder:

- `id`
- `screen_id`
- `requested_by_user_id`
- `target_ip`
- `target_port`
- `remote_user`
- `auth_mode` (`password`, `key`)
- `provided_secret_ref`
- `ssh_key_fingerprint` nullable
- `status` (`queued`, `running`, `succeeded`, `failed`, `cancelled`)
- `stage` (`connect`, `bootstrap`, `key_install`, `package_install`, `deploy`, `verify`, `done`)
- `log_excerpt` nullable
- `error_message` nullable
- `started_at` nullable
- `finished_at` nullable
- `created_at`
- `updated_at`

Regeln:

- das eigentliche Passwort wird nicht im Klartext in der Datenbank gespeichert
- `provided_secret_ref` verweist auf einen kurzlebigen oder extern geschuetzten Secret-Eintrag
- pro Job soll klar erkennbar sein, in welchem Schritt ein Fehler aufgetreten ist

### `screen_group`

Optionale logische Gruppierung von Screens.

Felder:

- `id`
- `slug`
- `name`
- `description`
- `created_at`
- `updated_at`

### `screen_group_member`

Zuordnung eines Screens zu einer Gruppe.

Felder:

- `id`
- `screen_group_id`
- `screen_id`
- `created_at`

Zweck:

- praktische Zielauswahl fuer Kampagnen und Provisionierungsaktionen

### `media_asset`

Repraesentiert ein verwaltetes Medium.

Felder:

- `id`
- `tenant_id`
- `screen_id` nullable
- `title`
- `description`
- `type` (`image`, `video`, `pdf`, `web`)
- `source_kind` (`upload`, `remote_url`)
- `storage_path` nullable bei reinen Web-URLs
- `original_url` nullable
- `mime_type`
- `checksum`
- `size_bytes`
- `enabled`
- `created_by_user_id`
- `created_at`
- `updated_at`

Regeln:

- `upload` bedeutet: Datei liegt im Medien-Storage
- `remote_url` bedeutet: Quelle ist extern und wird vom Player oder Server gecacht
- `screen_id` kann optional gesetzt werden, wenn ein Medium nur fuer einen Monitor gedacht ist

### `playlist`

Repraesentiert eine logische Playlist eines Screens.

Felder:

- `id`
- `tenant_id`
- `screen_id`
- `name`
- `is_active`
- `default_duration_seconds`
- `fallback_enabled`
- `fallback_dir`
- `shuffle_enabled`
- `created_at`
- `updated_at`

Regeln:

- pro Screen gibt es in v1 genau eine aktive Playlist
- spaeter koennen mehrere Playlists mit Umschaltung moeglich werden

### `display_template`

Repraesentiert ein globales Admin-Template zur monitoruebergreifenden Orchestrierung.

Beispiele:

- Schriftzug ueber mehrere Monitore
- saisonales Motiv auf allen Monitoren
- Veranstaltungslayout fuer einen befristeten Zeitraum

Felder:

- `id`
- `slug`
- `name`
- `description`
- `template_type` (`message_wall`, `full_screen_media`, `screen_specific_scene`)
- `enabled`
- `created_by_user_id`
- `created_at`
- `updated_at`

### `template_scene`

Repraesentiert die konkrete Auspraegung eines Templates fuer einen oder mehrere Screens.

Felder:

- `id`
- `display_template_id`
- `screen_id` nullable
- `screen_slot` nullable
- `type` (`image`, `video`, `pdf`, `web`, `html`)
- `src`
- `duration_seconds`
- `load_timeout_seconds`
- `cache_policy`
- `on_error`
- `layout_json`
- `created_at`
- `updated_at`

Hinweise:

- `screen_id` erlaubt die direkte Zuweisung zu einem konkreten Monitor
- `screen_slot` erlaubt spaeter abstrakte Wand-Slots wie `row1-col2`
- `layout_json` kann z. B. Textpositionen, Farben oder Teilbereiche des Gesamtmotivs beschreiben

### `campaign`

Repraesentiert eine aktivierbare globale Kampagne auf Basis eines Templates.

Felder:

- `id`
- `display_template_id`
- `name`
- `description`
- `priority`
- `active`
- `valid_from` nullable
- `valid_until` nullable
- `override_mode` (`replace_tenant_content`, `replace_all`, `merge_reserved_slots`)
- `created_by_user_id`
- `created_at`
- `updated_at`

Regeln:

- Kampagnen ueberschreiben in v1 standardmaessig den Firmencontent
- nach Ende oder Deaktivierung greift automatisch wieder der tenantbezogene Normalbetrieb

### `template_assignment`

Repraesentiert die Zuordnung einer Kampagne oder eines Templates zu einem oder mehreren Screens.

Felder:

- `id`
- `campaign_id`
- `screen_id`
- `enabled`
- `created_at`
- `updated_at`

Zweck:

- Auswahl einzelner Monitore, Gruppen oder aller Monitore

### `playlist_item`

Repraesentiert einen einzelnen Eintrag in einer Playlist.

Felder:

- `id`
- `playlist_id`
- `screen_id`
- `order_index`
- `media_asset_id` nullable
- `type` (`image`, `video`, `pdf`, `web`, `dir`)
- `src`
- `title`
- `duration_seconds`
- `load_timeout_seconds`
- `cache_policy` (`required`, `prefer_cache`, `no_cache`)
- `on_error` (`skip`, `retry`, `fallback`)
- `retry_count`
- `valid_from` nullable
- `valid_until` nullable
- `enabled`
- `created_at`
- `updated_at`

Regeln:

- `media_asset_id` wird bei verwalteten Medien gesetzt
- `src` enthaelt den effektiven Pfad oder die URL, damit der Player auch ohne Join-Struktur arbeiten kann
- `type=dir` erlaubt definierte Verzeichnisreferenzen innerhalb der Playlist

### `playlist_item_dir_rule`

Optionale Zusatzregel fuer `type=dir`.

Felder:

- `id`
- `playlist_item_id`
- `directory_path`
- `sort_mode` (`name_asc`, `name_desc`, `mtime_asc`, `mtime_desc`, `shuffle`)
- `per_item_duration_seconds`
- `recursive`
- `file_filter` nullable

Zweck:

- sauberere Modellierung fuer Verzeichnisbasierte Fallbacks oder Einschuebe

### `screen_status`

Repraesentiert den letzten bekannten Laufzeitstatus eines Players.

Felder:

- `screen_id`
- `online`
- `server_connected`
- `mqtt_connected`
- `last_heartbeat_at`
- `last_sync_at`
- `current_playlist_id`
- `current_playlist_item_id` nullable
- `current_content_source` (`campaign`, `tenant_playlist`, `fallback`)
- `current_campaign_id` nullable
- `current_item_type` nullable
- `current_item_label` nullable
- `current_item_started_at` nullable
- `current_item_duration_seconds` nullable
- `cache_state` (`ok`, `stale`, `missing`, `error`)
- `overlay_state` (`online`, `degraded`, `offline`)
- `error_code` nullable
- `error_message` nullable
- `player_version`
- `uptime_seconds`
- `free_disk_bytes` nullable
- `temperature_celsius` nullable
- `updated_at`

Hinweise:

- `screen_status` ist eine verdichtete Sicht fuer Dashboard und Ueberwachung
- historische Verlaeufe koennen spaeter separat gespeichert werden

### `screen_snapshot`

Repraesentiert eine Vorschauaufnahme des aktuellen Bildschirminhalts.

Felder:

- `id`
- `screen_id`
- `captured_at`
- `storage_path`
- `width`
- `height`
- `mime_type`
- `source` (`scheduled`, `item_change`, `manual`)

Regeln:

- in der UI wird typischerweise nur der letzte Snapshot angezeigt
- aeltere Snapshots koennen nach Zeit oder Anzahl aufgeraeumt werden

### `device_command`

Repraesentiert einen an einen Screen gesendeten Befehl.

Felder:

- `id`
- `screen_id`
- `command_type` (`reload`, `restart_player`, `reboot`, `display_on`, `display_off`, `refresh_snapshot`, `clear_cache`)
- `payload_json`
- `requested_by_user_id`
- `requested_at`
- `delivery_state` (`queued`, `sent`, `acknowledged`, `failed`, `expired`)
- `delivered_at` nullable
- `acknowledged_at` nullable
- `result_code` nullable
- `result_message` nullable

Zweck:

- nachvollziehbare Fernsteuerung mit Audit-Trail

### `sync_state`

Repraesentiert den Synchronisationsstand eines Screens.

Felder:

- `screen_id`
- `config_revision`
- `playlist_revision`
- `media_revision`
- `last_successful_sync_at`
- `last_failed_sync_at` nullable
- `last_error_message` nullable

Zweck:

- Erkennung, ob ein Player auf dem aktuellen Stand ist

## Beziehungen

- ein `tenant` hat viele `users`
- ein `tenant` hat viele `screens`
- ein `tenant` hat viele `media_assets`
- ein `screen` hat genau eine aktive `playlist` in v1
- eine `playlist` hat viele `playlist_items`
- ein `display_template` hat viele `template_scenes`
- ein `display_template` hat viele `campaigns`
- eine `campaign` hat viele `template_assignments`
- ein `screen` hat viele `provisioning_jobs`
- eine `screen_group` hat viele `screen_group_members`
- ein `screen` hat genau einen aktuellen `screen_status`
- ein `screen` hat viele `screen_snapshots`
- ein `screen` hat viele `device_commands`
- ein `screen` hat genau einen aktuellen `sync_state`

## Zugriffsregeln

### Tenant-User

Ein `tenant_user` darf:

- nur den eigenen `tenant` sehen
- nur den eigenen `screen` bzw. die dem Tenant zugeordneten Screens sehen
- nur eigene Medien hochladen und pflegen
- nur eigene Playlists bearbeiten
- nur die Vorschau des eigenen Screens sehen

Ein `tenant_user` darf nicht:

- andere Tenants sehen
- globale Steuerkommandos senden
- andere Screens administrieren

### Admin

Ein `admin` darf:

- alle Tenants, Screens, Medien und Playlists sehen
- globale Steuerbefehle senden
- Vorschau und Status aller Screens sehen
- neue Screens und Benutzer anlegen

## Revisions- und Caching-Modell

Damit Offline-Betrieb einfach bleibt, arbeitet der Player nicht gegen beliebige Einzelobjekte, sondern gegen Revisionen.

Sinnvoll sind mindestens:

- `playlist_revision`
- `media_revision`
- `config_revision`
- `campaign_revision`

Der Player kann damit erkennen:

- ob neue Konfiguration vorliegt
- ob Medien nachgeladen werden muessen
- ob die lokale Kopie noch gueltig ist
- ob sich globale Uebersteuerungen geaendert haben

## Prioritaetsmodell der Inhaltsauswahl

Der Player wertet Inhalte in dieser Reihenfolge aus:

1. aktive Kampagne mit gueltigem Zeitfenster und Assignment fuer den Screen
2. aktive tenantbezogene Playlist des Screens
3. Fallback-Verzeichnis

Eine Kampagne ist aktiv, wenn:

- `active = true`
- `valid_from` leer oder erreicht ist
- `valid_until` leer oder noch nicht abgelaufen ist
- eine `template_assignment` fuer den Screen aktiv ist

Dadurch ist die globale Uebersteuerung ein Kernbestandteil und kein nachtraeglicher Sonderfall.

## Beispiel fuer aktive Playlist-Auswertung

Ein `playlist_item` ist aktiv, wenn:

- `enabled = true`
- `valid_from` leer oder in der Vergangenheit liegt
- `valid_until` leer oder in der Zukunft liegt

Wenn kein aktives Item existiert:

- greift die globale Fallback-Regel des Screens oder der Playlist

## Beispiel fuer Admin-Steuerung

Wenn ein Admin `reload` ausloest:

1. Ein `device_command` wird gespeichert
2. der Befehl wird per MQTT an den Screen signalisiert
3. der Player fuehrt den Reload aus
4. der Player sendet ein ACK
5. `device_command.delivery_state` wird aktualisiert

## Offene spaetere Erweiterungen

- mehrere Screens pro Tenant in der Firmenoberflaeche
- Vorlagen und globale Playlists
- Historie der Statusdaten als Zeitreihe
- Geplante Kampagnen mit Prioritaeten
- serverseitige Konvertierung oder Transkodierung von Medien