first commit

README.md

@@ -0,0 +1,90 @@
+# EPI-Support Monitor
+
+Interne Überwachungs- und **Auswertungsplattform** für die Tickets auf
+`epi-helpdesk.zammad.com`. Die Anwendung ruft regelmäßig alle sichtbaren Tickets
+über die Zammad-API ab, vergleicht sie mit dem letzten Stand und protokolliert
+**Änderungen durch die Support-Agenten** (Status, Bearbeiter, Priorität,
+Schließung, neue Antworten). Optional gibt es E-Mail-Alerts.
+
+Das interne Dashboard bietet:
+
+* **Übersicht** – alle Tickets mit Statusfilter und „ungelesene Änderungen“
+* **Änderungs-Verlauf** – Feed + Timeline pro Ticket (wer/was/wann geändert)
+* **Auswertung** – KPIs (Aufkommen, offen/geschlossen, eskaliert), Median/Ø/P90
+  von Reaktions- und Lösungszeit, Zeitverlauf pro Monat (SVG-Diagramm) sowie
+  Verteilungen nach Status, Priorität, Gruppe und **Agent**; Zeitraumfilter
+  (30/90/180/365 Tage/gesamt)
+* **Excel-Export** – komplette Auswertung als `.xlsx` (KPIs, Verteilungen,
+  Monatswerte, Tickets, Änderungen)
+* **Konversation lesen** – vollständiger Nachrichtenverlauf je Ticket
+  (Absenderrolle, Datum, Text). HTML wird sicher zu Text bereinigt – keine
+  nachgeladenen Bilder/Tracking, kein eingebetteter Schadcode.
+* **Antworten & neue Tickets** – direkt aus der Plattform an EPI; jede
+  Schreibaktion läuft über eine **Bestätigungsseite** (Schutz vor
+  versehentlichem Senden). Schreibzugriff nutzt CSRF (Session) bzw. den
+  `ZAMMAD_TOKEN`.
+
+> **Hinweis zum Versand:** Der Sende-Pfad (`create_article`/`create_ticket`,
+> Artikeltyp `web`) ist gebaut und geprüft, aber bewusst **nicht live getestet**,
+> um keine echten Nachrichten an EPI auszulösen. Der erste echte Versand sollte
+> kontrolliert erfolgen; sollte EPI den Artikeltyp ablehnen, ggf. auf `note`
+> umstellen (in `app/zammad.py`).
+
+Da auf der Zammad-Instanz „API password access" deaktiviert ist, meldet sich
+die App per **Session-Login** an (wie der Browser). Sobald ein persönlicher
+**API-Token** verfügbar ist, einfach `ZAMMAD_TOKEN` in der `.env` setzen – dann
+wird der Token bevorzugt verwendet.
+
+## Architektur
+
+| Komponente | Aufgabe |
+|------------|---------|
+| `episupport-poller` (systemd) | Hintergrund-Abruf alle `POLL_INTERVAL_SECONDS`, Änderungserkennung, E-Mail |
+| `episupport-web` (systemd, gunicorn) | Flask-Dashboard auf `127.0.0.1:8071` |
+| Apache `conf-available/episupport.conf` | Reverse-Proxy `srhnweb/episupport` → gunicorn |
+| `data/episupport.db` (SQLite, WAL) | Ticket-Snapshots, Änderungs-Log, Abrufprotokoll |
+
+## Deployment auf SRHNWEB
+
+```bash
+# 1. Dateien auf den Server bringen, Zielordner /var/www/html/episupport
+#    (z. B. per scp/rsync/git)
+
+# 2. Setup ausführen
+sudo bash /var/www/html/episupport/deploy/setup.sh
+
+# 3. Zugangsdaten eintragen
+sudo nano /var/www/html/episupport/.env       # ZAMMAD_USER / ZAMMAD_PASSWORD
+sudo systemctl restart episupport-poller episupport-web
+```
+
+Danach erreichbar unter **`http(s)://srhnweb/episupport`**.
+
+### Updates einspielen
+Neue Dateien nach `/var/www/html/episupport` kopieren, dann erneut
+`sudo bash deploy/setup.sh` (installiert Abhängigkeiten neu und startet Dienste).
+
+## Konfiguration (`.env`)
+Siehe `.env.example`. Wichtig: `ZAMMAD_USER`/`ZAMMAD_PASSWORD` **oder**
+`ZAMMAD_TOKEN`. E-Mail-Benachrichtigung über `NOTIFY_ENABLED=true` + SMTP-Daten.
+
+## Lokaler Test (Entwicklung)
+```bash
+python -m venv venv && venv/bin/pip install -r requirements.txt
+cp .env.example .env          # ausfüllen
+venv/bin/python run_poller.py # einmal laufen lassen -> Basis-Snapshot
+venv/bin/python wsgi.py       # Dashboard auf http://127.0.0.1:8071/episupport
+```
+
+## Logs
+```bash
+journalctl -u episupport-poller -f
+journalctl -u episupport-web -f
+```
+
+## Sicherheit
+- `.env` enthält Zugangsdaten → Rechte 640, nicht ins Git committen (`.gitignore`).
+- Zugriff aufs Dashboard ggf. in `episupport-apache.conf` per `Require ip` aufs
+  interne Netz beschränken.
+- Für den Dauerbetrieb einen eigenen, einzeln widerrufbaren API-Token statt des
+  Passworts verwenden.