monitor/Visualization.md

Neuausrichtung: Vom Status-Monitor zum "Büro" (Visualisierungsplan)

Dieses Dokument beschreibt den Plan für die Umwidmung von monitor von einer einfachen Server-Status-Tabelle zu einer spielerischen, realistisch anmutenden Büro-Visualisierung, in der Agenten (Menschen oder automatisierte Systeme) ihre Arbeit an einem Kanban-Board und über Monitor-Wände sichtbar machen.

Offene Detailfragen, die vor bzw. während der Umsetzung geklärt werden müssen, sind in Detailfragen.md gesammelt. Dieser Plan verweist an den relevanten Stellen auf die jeweilige Fragen-Nummer dort (z. B. [F3]).

---

1. Vision

Statt einer Tabelle mit Hostname/IP/Status zeigt die Startseite künftig eine Illustration eines modernen Büros:

• Eine Wand mit einem Kanban-Board: Klebezettel (Tickets) erscheinen, wandern durch Spalten und werden abgeschlossen. Die Zettel sind nicht einzeln lesbar, aber Anzahl/Spalte sind erkennbar. Klick auf das Board öffnet ein Modal mit den echten Issues.
• Eine zweite Wand mit drei Monitoren:
  1. Event-Monitor: Log-artige Meldungen in Gelb (Warnung) / Rot (Fehler).
  2. System-Monitor: Kacheln/Icons pro überwachtem System, grün = OK, rot = Fehler.
  3. KPI-Monitor: Dashboard im Grafana-Stil mit Kennzahlen/Zeitreihen. Klick auf einen Monitor öffnet ein Modal mit Detailinformationen (Eventliste, Verlauf, etc.).
• Zwei Türen, durch die "externe" Rollen (z. B. Kunden, User) das Büro betreten/verlassen können, ohne einen eigenen Schreibtisch zu haben.
• 8 Schreibtische zwischen den Wänden, an denen Mitarbeitende (= Agenten oder reale Personen) sitzen. Schreibtisch-Deko ist rollenabhängig (Manager: Familienfoto, Entwickler:in: Fantasy-Motive, Product Owner:in: Blume, ...) [F1].
• Animierte Abläufe: Mitarbeitende laufen zum Board/Monitor, tippen dort, kehren zum Schreibtisch zurück. Aktive Agenten tippen an der Tastatur, ihr Bildschirm zeigt scrollenden Text. Untätige Agenten lesen Zeitung oder gehen in eine Kaffee-Ecke.

Die Grundidee: Der Zustand des überwachten Systems (Tickets, Events, Server-Status, KPIs) wird nicht mehr tabellarisch, sondern als kleine "Lebenswelt" dargestellt, bleibt aber über Klicks jederzeit in Rohform/Detailform einsehbar.

2. Ist-Zustand

Aktuell (siehe html/mon.html, html/script.js, check_fds.sh):

• check_fds.sh pingt Hosts aus hosts.conf, schreibt Ergebnisse zeilenweise in status.txt, verschickt bei Fehlern Mails via mail_fds.py.
• html/mon.html + script.js lesen status.txt per fetch() und rendern eine Tabelle.
• Keine Datenbank, kein Backend-Prozess, kein API. Rein statisches Hosting + Cronjob.

Diese Bausteine (Ping-Check, Mailversand) bleiben als eine mögliche Datenquelle unter mehreren bestehen, werden aber nicht mehr die einzige Sicht auf das System sein. Der Systemmonitor auf der Wand kann z. B. weiterhin status.txt/Nachfolgeformat auswerten.

3. Zielarchitektur – Überblick

                       ┌─────────────────────────────┐
   entfernte Agenten → │        REST-API (Backend)    │
   (melden Status via  │  Tickets / Events / Systeme /│
   HTTP)                │  KPIs / Agenten-Status       │
                       └──────────────┬────────────────┘
                                      │ liest/schreibt
                                      ▼
                       ┌─────────────────────────────┐
                       │  Persistenz (Dateien/SQLite) │  [F11]
                       └──────────────┬────────────────┘
                                      │ liefert JSON
                                      ▼
                       ┌─────────────────────────────┐
                       │  Frontend (HTML/CSS/JS)      │
                       │  Büro-Szene (SVG/Canvas)     │
                       │  - Kanban-Board               │
                       │  - Monitor-Wand                │
                       │  - Schreibtische + Agenten     │
                       │  - Modals für Detailansichten  │
                       └─────────────────────────────┘

Die REST-API ist die zentrale neue Komponente: Sie ist die Schnittstelle, über die entfernte Agenten ("ich habe Ticket X abgeholt", "ich melde Event Y", "System Z ist down") ihren Zustand melden. Das Frontend fragt diese Daten (oder eine daraus abgeleitete Aggregation) ab und übersetzt sie in Animation und Board-Zustand.

4. Komponenten im Detail

4.1 Büro-Layout

Statische Grundszene (Wände, Türen, Schreibtische, Monitor-Rahmen) als SVG oder Canvas-Layer, darüber bewegliche Elemente (Personen, Klebezettel, Bildschirminhalte) als eigene Layer/Objekte, damit die Basis-Grafik nicht bei jedem Update neu gezeichnet werden muss.

Offene Fragen zu Stil (Pixel-Art / flach-illustrativ / isometrisch) und Auflösung/Responsivität: siehe [F9].

4.2 Kanban-Board

• Spalten sind konfigurierbar, mindestens aber die im Issue genannte "Testing"-Spalte muss existieren. Vorschlag: Backlog → In Arbeit → Testing → Fertig [F3].
• Jede Karte auf dem Board entspricht einem Ticket-Datensatz aus der API (/tickets).
• Visuell: Klebezettel-Icons, Farbe/Größe kann Priorität andeuten, Text ist absichtlich nicht lesbar (nur Spalten-Zugehörigkeit und Vorhandensein zählt).
• Klick auf das Board öffnet ein Modal mit der Liste aller Tickets in der jeweiligen Spalte, inkl. echtem Titel/Beschreibung/Verlinkung auf die Quelle (z. B. Codeberg-Issue) [F4].

4.3 Monitor-Wand

1. Event-Monitor: rollendes Log, neue Einträge oben, Farbe nach Schweregrad (gelb = Warnung, rot = Fehler, ggf. grün/grau = info) [F5].
2. System-Monitor: eine Kachel pro überwachtem System/Host, grün/rot, optional Icon-Typ je System (Server, Datenbank, Service, ...) [F6].
3. KPI-Monitor: Kennzahlen-Kacheln + einfache Zeitreihen-Charts im Grafana-Look [F7].

Jeder Monitor ist klickbar und öffnet ein Modal mit tieferen Informationen (volle Eventliste mit Filter/Suche, Systemverlauf, KPI-Detailcharts).

4.4 Mitarbeitende / Agenten

• Jeder Schreibtisch ist einer Rolle zugeordnet; Rollen sind über ein erweiterbares Set definiert (Name, Icon/Aussehen, Schreibtisch-Deko, erlaubte Aktionen) [F1], [F2].
• Zustandsmaschine pro Agent (Vorschlag): idle_at_desk → walking_to_board → interacting_with_board → walking_to_monitor → interacting_with_monitor → walking_back → idle_at_desk sowie parallel dazu idle-Varianten: reading_newspaper, at_coffee_corner, talking_to_colleague, working (tippt, Bildschirm scrollt Text).
• Auslöser für Zustandswechsel sind Ereignisse aus der REST-API (neues Ticket, Ticket bewegt, neuer Event, Systemstatus geändert, Agent meldet "arbeite an Ticket X").
• Mapping "welcher Mensch/Avatar reagiert auf welches Ereignis" [F8].
• Externe Rollen (Kunde, User) erscheinen nicht an einem Schreibtisch, sondern betreten/ verlassen die Szene durch eine der zwei Türen, wenn ein entsprechendes Ereignis eintrifft (z. B. "neue Support-Anfrage") [F2].

4.5 Interaktivität

• Kanban-Board-Klick → Modal mit Issue-Liste der Spalte.
• Monitor-Klick → Modal mit Event-/Status-/KPI-Detail.
• Modals sind reines HTML/CSS/JS ohne fremde UI-Bibliothek, per <dialog>-Element oder einfachem Overlay-Div umgesetzt.

5. Technischer Ansatz

Vorgabe aus dem Issue: kein Framework, keine externen Laufzeit-Bibliotheken, nur PHP, Python, HTML, CSS, JavaScript (Vanilla). Für die Visualisierung von KPI-Zeitreihen kann eine schlanke Open-Source-Bibliothek sinnvoll sein – Optionen zur Auswahl [F10]:

Option	Lizenz	Größe	Bemerkung
Kein Chart-Lib, eigenes SVG/Canvas-Zeichnen	–	0	volle Kontrolle, mehr Eigenaufwand
uPlot	MIT	~45 KB	sehr klein, schnell, für Zeitreihen gemacht
Chart.js	MIT	~200 KB	verbreitet, viele Chart-Typen, einfache API
D3.js	ISC	~250 KB (Vollpaket, modular kleiner)	maximale Flexibilität, steilere Lernkurve

Empfehlung: eigenes SVG-Zeichnen für die Büro-Szene (da es kein "normales Chart" ist), und für den KPI-Monitor testweise uPlot oder gar kein Lib (einfache Balken/Sparklines selbst gezeichnet), da es am kleinsten ist und zur "keine externen Tools"-Vorgabe passt. Endgültige Entscheidung liegt beim Repo-Besitzer [F10].

Backend/API: PHP und/oder Python sind laut Vorgabe beide erlaubt; welche Sprache für die REST-API führend sein soll, ist zu klären [F12], da das Hosting-Setup (statisch vs. Prozess/CGI) davon abhängt.

6. REST-API (Entwurf)

Ziel: Entfernte Agenten melden ihre Aktivitäten selbstständig; die API muss gut dokumentiert und erweiterbar sein, damit sie auch als "Anleitung" für Agenten dienen kann.

6.1 Ressourcen (Entwurf, erweiterbar)

• POST /api/v1/tickets – neues Ticket anlegen (Spalte = Backlog)
• PATCH /api/v1/tickets/{id} – Ticket verschieben (column), zuweisen (assignee), schließen
• GET /api/v1/tickets – aktueller Board-Zustand
• POST /api/v1/events – neues Event melden (severity: info|warning|error, message, source)
• GET /api/v1/events – Eventliste (für Modal, mit Paging/Filter)
• POST /api/v1/systems/{id}/status – Systemstatus melden (status: ok|error, detail)
• GET /api/v1/systems – aktuelle Systemstatus-Übersicht
• POST /api/v1/kpis/{key} – KPI-Datenpunkt melden (value, timestamp)
• GET /api/v1/kpis – aktuelle KPI-Werte/Verläufe
• POST /api/v1/agents/{id}/activity – Agent meldet Zustand (state: working|idle|..., current_ticket, role)
• GET /api/v1/agents – aktuelle Agenten-/Mitarbeiterliste inkl. Rolle und Zustand

Alle POST/PATCH-Endpunkte lösen serverseitig ein Ereignis aus, das vom Frontend (Polling oder später Server-Sent Events, [F13]) abgeholt wird und eine Animation triggert (z. B. Agent läuft zum Board).

6.2 Erweiterbarkeit

• Neue Ressourcentypen (z. B. weitere Monitor-Typen) sollen ergänzt werden können, ohne bestehende Endpunkte zu brechen (Versionierung über /api/v1/, additive Felder).
• Rollen, Event-Kategorien und Board-Spalten sind über Konfiguration (nicht Code) erweiterbar, soweit sinnvoll umsetzbar [F1], [F3].

6.3 Authentifizierung

Agenten benötigen einen Auth-Mechanismus (z. B. API-Key pro Agent), um Fremdzugriffe/Fake- Meldungen zu verhindern. Details (Token-Verwaltung, Rotation, Scopes) siehe [F14].

6.4 Dokumentation

Die API wird in einem eigenen API.md (oder docs/API.md) vollständig dokumentiert (Endpunkte, Request-/Response-Schemas, Fehlercodes, Auth, Beispiele), sodass diese Doku direkt als Anleitung an die Agenten weitergegeben werden kann. Dies entsteht als eigener Umsetzungsschritt (siehe Roadmap, Phase 1).

7. Datenmodell (grober Entwurf)

• Ticket: id, title, description, column, priority, assignee_agent_id, source_ref, created_at, updated_at
• Event: id, severity, message, source, created_at
• System: id, name, type, status, last_check_at, detail
• KPI: key, label, unit, current_value, history[]
• Agent: id, display_name, role, state, current_ticket_id, desk_index, last_seen_at
• Role: key, label, desk_decoration, avatar, allowed_states (erweiterbar, siehe [F1])

Persistenzform (Dateien/JSON vs. SQLite vs. andere) ist zu klären [F11], sollte aber ohne externe Datenbankserver (nur PHP/Python-Standardbibliothek) auskommen, um die "keine externen Tools"-Vorgabe einzuhalten.

8. Teststrategie

• Für jede neu erzeugte Codedatei wird eine Testabdeckung von mindestens 60 % angestrebt (Unit-/Integrationstests, Sprache passend zur Datei: PHPUnit für PHP, pytest für Python, ein einfacher JS-Test-Runner für Frontend-Logik, siehe [F15] zur Klärung, ob Test-Tooling als Ausnahme von der "keine Bibliotheken"-Vorgabe gilt).
• Für alle wichtigen Funktionen (Board-Interaktion, Monitor-Interaktion, API-Endpunkte, Agent-Zustandswechsel) wird zusätzlich ein E2E-Test mit Playwright erstellt. Der Playwright-Runner ist bereits vorhanden und wird nicht neu aufgesetzt, nur die Testfälle werden ergänzt.
• Coverage-Messung wird pro Sprache mit dem jeweils naheliegenden Bordmittel umgesetzt (z. B. coverage.py für Python, Xdebug/PCOV für PHP, c8/istanbul falls ein JS- Test-Runner zum Einsatz kommt) – konkrete Wahl siehe [F15].

9. Migrationsplan / Phasen

1. Phase 0 – Grundlagen & Klärung: Detailfragen klären (Detailfragen.md), Tech-Entscheidungen fixieren (Backend-Sprache, Persistenz, Chart-Lib). ✅ erledigt.
2. Phase 1 – REST-API: Datenmodell, Endpunkte, Auth, Persistenz, API.md-Dokumentation, Tests (≥60 % Coverage). ✅ erledigt (PR #5).
3. Phase 2 – Statische Büro-Szene: SVG/Canvas-Grundlayout (Wände, Türen, 8 Schreibtische, Board-Rahmen, 3 Monitor-Rahmen) ohne Animation, gespeist mit statischen/Demo-Daten. ✅ erledigt (PR #7).
4. Phase 3 – Kanban-Board live: Board zeigt echte Ticket-Daten aus der API, Klick-Modal mit Issue-Details. ✅ erledigt: html/js/office-api.js laedt GET /api/v1/tickets, office-scene.js aggregiert/gruppiert sie je Spalte, Klick auf eine Spalte oeffnet ein Modal mit Titel/Beschreibung/Codeberg-Link je Ticket (F4).
5. Phase 4 – Monitor-Wand live: Event-, System- und KPI-Monitor zeigen echte Daten, Klick-Modals. ✅ erledigt: Events/Systeme/KPIs kommen live von der API, ein neuer SSE-Endpoint (GET /api/v1/stream, F13) stoesst Frontend-Updates an (Polling-Fallback in office-realtime.js), KPI-Monitor zeichnet eine eigene SVG-Sparkline (F10, kein Chart-Lib) sobald KPIs gemeldet wurden - vorher weiterhin der Platzhalter aus Phase 2 (F7 ist inhaltlich weiterhin offen).
6. Phase 5 – Agenten & Animation: Zustandsmaschine, Laufwege, Tipp-/Lese-/Kaffee-Animation, Reaktion auf neue Ticket-/Event-/Systemstatus-Meldungen. ✅ erledigt: resolveAgentVisualState bildet die von der API gemeldeten Zustaende auf Ort/Pose ab, Agenten-Avatare sind eine eigenstaendige, per CSS transition animierte Schicht (office-render.js), idle-Varianten (Zeitung/Kaffee-Ecke/Schwaetzchen) werden rein kosmetisch client-seitig zufaellig ausgeloest (F8), eine AnimationQueue serialisiert Update-Animationen bei vielen gleichzeitigen Ereignissen (F9).
7. Phase 6 – Externe Rollen & Türen: Betreten/Verlassen durch Türen für Kunden/User-Events. Noch offen - Phase 5 platziert Agenten ohne Schreibtisch (Rolle user, Ueberlauf) bereits an einem Ruheplatz vor der linken Tuer, ein echtes Betreten/Verlassen mit Tuer-Animation anlaesslich konkreter Backlog/Fertig/Done-Ereignisse (F2) ist aber noch nicht umgesetzt.
8. Phase 7 – Tests & Feinschliff: Unit-/E2E-Testabdeckung komplettieren, Migration/ Abschaltung der alten Tabellenansicht klären ([F16]). Noch offen - insbesondere die in Abschnitt 8 vorgesehenen Playwright-E2E-Tests fuer Board-/Monitor-Interaktion fehlen noch, html/mon.html besteht laut F16 weiterhin bis zur expliziten Abschaltung.

Jede Phase liefert ein für sich lauffähiges Zwischenergebnis, sodass die Umwidmung schrittweise (und überprüfbar per PR) erfolgen kann, statt in einem Großumbau.

10. Offene Punkte

Alle offenen Detailfragen sind gesammelt in Detailfragen.md. Vor Beginn von Phase 1 sollten mindestens die technischen Grundsatzfragen (Backend-Sprache, Persistenz, Auth-Mechanismus) geklärt sein; die übrigen Fragen (Rollen-Details, Deko, Farbschema, ...) können auch schrittweise während der jeweiligen Phase geklärt werden.