627269b7a1
Fügt Visualization.md (Zielbild, Architektur, REST-API-Entwurf, Teststrategie, Phasenplan) und Detailfragen.md (offene Detailfragen zu Rollen, Board, Monitoren, Technik, Tests, Migration) hinzu.
257 lines
14 KiB
Markdown
257 lines
14 KiB
Markdown
# 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 `<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](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).
|
||
2. **Phase 1 – REST-API**: Datenmodell, Endpunkte, Auth, Persistenz, `API.md`-Dokumentation,
|
||
Tests (≥60 % Coverage).
|
||
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.
|
||
4. **Phase 3 – Kanban-Board live**: Board zeigt echte Ticket-Daten aus der API, Klick-Modal mit
|
||
Issue-Details.
|
||
5. **Phase 4 – Monitor-Wand live**: Event-, System- und KPI-Monitor zeigen echte Daten,
|
||
Klick-Modals.
|
||
6. **Phase 5 – Agenten & Animation**: Zustandsmaschine, Laufwege, Tipp-/Lese-/Kaffee-Animation,
|
||
Reaktion auf neue Ticket-/Event-/Systemstatus-Meldungen.
|
||
7. **Phase 6 – Externe Rollen & Türen**: Betreten/Verlassen durch Türen für Kunden/User-Events.
|
||
8. **Phase 7 – Tests & Feinschliff**: Unit-/E2E-Testabdeckung komplettieren, Migration/
|
||
Abschaltung der alten Tabellenansicht klären ([F16]).
|
||
|
||
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.
|