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