# 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. "Agenten" (registrierte Agenten) und "Online" (davon praesent, isAgentPresent()) sind als erste zwei KPI-Kacheln immer sichtbar, direkt aus der Agentenliste abgeleitet statt gemeldet (Issue #39) - darueber hinaus ist F7 inhaltlich weiterhin offen, ohne gemeldete KPIs zeigt die Wand nur diese beiden Kacheln. 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. ✅ erledigt: `detectDoorVisits()` (`html/js/office-scene.js`) erkennt die drei Anlaesse aus F2 (neues per Codeberg-Sync angelegtes Backlog-Ticket, Ticket erreicht `fertig`, Ticket erreicht `done`) durch Diff zweier Ticket-Snapshots; `office-render.js` laesst dafuer einen `user`-Besucher an der linken Tuer erscheinen, zum Board laufen, kurz interagieren und wieder hinausgehen (`DOOR_VISIT_STAGES`), unabhaengig vom Daten-Refresh-Takt. Die Tuer leuchtet waehrenddessen kurz auf (`.door-active`). Registrierte `user`-Agenten (Ueberlauf, Phase 5) bleiben wie bisher an ihrem festen Ruheplatz vor der Tuer stehen, wenn sie nicht gerade einen Besuch absolvieren. 8. **Phase 7 – Tests & Feinschliff**: Unit-Testabdeckung komplettieren, Migration/Abschaltung der alten Tabellenansicht klären ([F16]). ✅ erledigt: `html/mon.html`/`script.js`/ `styles.css` sind entfallen (F16: "kann entfallen"), `check_fds.sh`/`mail_fds.py`/ `status.txt` speisen weiterhin unveraendert den System-Monitor. Unit-Tests fuer die Phase-6-Logik sind in `tests/frontend/office-scene.test.js` ergaenzt (weiterhin 100 % Line-Coverage). E2E-Tests mit Playwright sind bewusst noch nicht Teil dieser Phase (siehe Abgrenzung im zugehoerigen Issue) und bleiben ein offener Folgeschritt. 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.