# 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](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 ``-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](https://github.com/leeoniya/uPlot) | MIT | ~45 KB | sehr klein, schnell, für Zeitreihen gemacht | | [Chart.js](https://www.chartjs.org/) | MIT | ~200 KB | verbreitet, viele Chart-Typen, einfache API | | [D3.js](https://d3js.org/) | 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](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](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.