# Info-Board Neu - Player-Agent Lifecycle und Health-Modell

## Ziel

Dieses Dokument beschreibt die erste belastbare Laufzeitstufe des `player/agent` fuer v1.

Es legt fest, wie der Agent seinen internen Zustand fuehrt, welche strukturierten Log-Ereignisse er ausgibt und wie ein kontrollierter Stop funktioniert.

## V1-Entscheidung

- der Agent fuehrt zunaechst ein internes Health-Modell ohne externen HTTP-Endpunkt
- Lifecycle-Wechsel werden ueber einen in-memory Snapshot verfolgt
- Server-Erreichbarkeit wird getrennt vom Lifecycle als eigener Connectivity-Zustand gefuehrt
- Logs werden als stabile `key=value`-Ereignisse ausgegeben
- Stop erfolgt signalgesteuert ueber `SIGINT` oder `SIGTERM`

## Health-Snapshot

Der Laufzeitsnapshot enthaelt mindestens:

- `status`
- `server_connectivity`
- `screen_id`
- `server_base_url`
- `mqtt_broker`
- `heartbeat_every_seconds`
- `started_at`
- `last_heartbeat_at`

Der Snapshot dient in v1 der internen Laufzeitbeobachtung und Testsicherheit.

## Statusmodell

Fuer die aktuelle Ausbaustufe gelten diese Stati:

- `starting` vor dem Start der Run-Loop
- `running` sobald Konfiguration uebernommen und der erste Heartbeat verarbeitet wurde
- `stopped` nach kontrolliertem Verlassen der Run-Loop

Ein separater Fehlerstatus wird in dieser Stufe noch nicht eingefuehrt.
Technische Startfehler bleiben weiterhin normale Rueckgabefehler beim Initialisieren oder Starten.

## Connectivity-Modell

Getrennt vom Lifecycle fuehrt der Agent fuer die Server-Erreichbarkeit aktuell diese Zustaende:

- `unknown` vor dem ersten erfolgreichen oder fehlgeschlagenen Status-Report
- `online` nach einem erfolgreich bestaetigten HTTP-Status-Report
- `degraded` nach einem fehlgeschlagenen HTTP-Status-Report

Damit bleibt der Lifecycle sauber von Netz- und Gegenstellenproblemen getrennt.
Ein Report-Fehler stoppt den Agenten nicht, sondern veraendert nur den Connectivity-Zustand.

## Strukturierte Log-Ereignisse

Der Agent emittiert in v1 mindestens diese Ereignisse:

- `event=agent_starting`
- `event=agent_configured`
- `event=heartbeat_tick`
- `event=status_report_sent`
- `event=status_report_failed`
- `event=agent_stopped`

Ziel ist keine vollstaendige Logging-Plattform, sondern ein stabiler, maschinenlesbarer Anfang fuer lokale Verifikation, spaetere Journald-Auswertung und Device-Debugging.

## Heartbeat-Verhalten

- beim Start wird direkt ein erster Heartbeat verarbeitet und geloggt
- danach laeuft der Heartbeat im konfigurierten Intervall weiter
- jeder Heartbeat aktualisiert `last_heartbeat_at`

Das direkte erste Tick-Verhalten vereinfacht lokale Checks und Tests, weil ein frisch gestarteter Agent sofort einen nachvollziehbaren Lebensnachweis liefert.

## Shutdown-Verhalten

- `cmd/agent` erstellt einen signalgebundenen Context
- bei `SIGINT` oder `SIGTERM` verlaesst die Run-Loop kontrolliert den Ticker
- vor Rueckkehr wird `event=agent_stopped` geloggt und der Snapshot auf `stopped` gesetzt

## V1-Abgrenzung

Nicht Teil dieser Stufe:

- externer Health-Endpunkt
- MQTT-Verbindungsstatus
- Snapshot-Persistenz
- Kommandos oder Sync-Status

Die erste Backend-Reachability-Pruefung ist in dieser Stufe bereits ueber den HTTP-Status-Report abgebildet.
Ein expliziter `offline`-Zustand, MQTT-Reachability und weitergehende Schwellenlogik folgen spaeter.

Diese Punkte folgen erst, wenn echte Netzwerk- und Sync-Funktionalitaet eingebaut wird.