morz-infoboard/docs/PLAYER-AGENT-LIFECYCLE.md

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
• Logs werden als stabile key=value-Ereignisse ausgegeben
• Stop erfolgt signalgesteuert ueber SIGINT oder SIGTERM

Health-Snapshot

Der Laufzeitsnapshot enthaelt mindestens:

• status
• 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.

Strukturierte Log-Ereignisse

Der Agent emittiert in v1 mindestens diese Ereignisse:

• event=agent_starting
• event=agent_configured
• event=heartbeat_tick
• 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
• Backend-Reachability-Pruefung
• Snapshot-Persistenz
• Kommandos oder Sync-Status

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