dolibarr.netdiag/README.md

NetDiag — Netzwerk-Diagnose für Dolibarr

Dolibarr-Modul für die Ablage von Netzwerk-Diagnose-Protokollen. Erfasst per mobiler App (siehe Projekt NetzwerkDiagnose/app) gefundene Geräte, Ports und Messungen und hängt die Protokolle dauerhaft an Kunde und Auftrag.

Funktionen

• Datenmodell: Protokoll → Geräte → Messungen (llx_netdiag_*)
• Tab Netzwerk-Diagnose an Kunde (thirdparty) und Auftrag (commande)
• JSON-API unter /custom/netdiag/api/ für die mobile App. Anmeldung ausschließlich über das zentrale Auth-Modul awlauth (Brute-Force-Bremse, gemeinsame Sitzungsliste, „Gerät abmelden"). Der modul-eigene JWT-Pfad ist mit v1.2.0 entfallen: er stellte Tokens aus, die an der awlauth-Sitzungsliste vorbeiliefen — „Gerät abmelden" hatte darauf keine Wirkung. Ohne aktives awlauth antwortet die Anmeldung mit 503 statt auf einen zweiten Weg auszuweichen. Die Gültigkeit bestimmt allein AWLAUTH_TTL im awlauth-Setup (Standard 7 Tage)
• PDF-Protokoll, wird im Dokumentenarchiv (ECM) abgelegt
• Zwei Sichten auf dieselben Messdaten: die Technikeransicht zeigt alles, das Kunden-PDF nur eine Whitelist (siehe „Neue Messart" unten)
• Rechtesystem: netdiag → protocol → read/write/delete
• Mehrsprachig (de_DE, en_US)
• QR-Code zum App-Download in der Modul-Einrichtung

Installation

1. Verzeichnis netdiag/ nach htdocs/custom/ auf den Dolibarr-Server kopieren. Auf dem Produktivsystem übernimmt das die Forgejo-Pipeline (.forgejo/workflows/deploy.yml) — Commit mit [deploy] in der Message synct das Modul automatisch auf den Server.
2. In Dolibarr: Einrichtung → Module → NetDiag aktivieren.
3. Beim Aktivieren werden die Tabellen llx_netdiag_protocol, llx_netdiag_device, llx_netdiag_measurement angelegt. Voraussetzung: das Modul AWL-Auth muss aktiv sein — ohne es gibt es keine Anmeldung an der API (seit v1.2.0, siehe oben).
4. Benutzern das Recht NetDiag → Protokolle lesen/schreiben geben.

API-Endpunkte

Alle unter https://<dolibarr>/custom/netdiag/api/:

Endpunkt	Methode	Zweck
auth.php	POST {login,password}	Anmeldung → {token,expiresIn,user}
customers.php	GET ?q= / ?id=	Kundensuche / Kundendetail
orders.php	GET ?open=1&q= / ?id=	Auftragsliste / Auftragsdetail
protocols.php	GET ?id=	Protokoll mit Geräten + Messungen
protocols.php	POST {action:"sync",protocol:{…}}	Protokoll anlegen/aktualisieren (idempotent über clientUuid)
pdf.php	GET ?id=&jwt=	Protokoll-PDF streamen

Authentifizierung per Authorization: Bearer <token> oder ?jwt=<token>. Jeder Endpunkt prüft ein Recht — protocols.php im GET-Zweig protocol read oder write: die Rechte sind in Dolibarr einzeln vergebbar, und ein Techniker mit Schreib- ohne ausdrückliches Leserecht darf nicht ausgesperrt werden (das fiele erst beim Kunden auf).

?jwt= in der URL ist nur für den PDF-Download da (der Browser kann dort keinen Header setzen). Langzeit-Token in URLs landen in Zugriffs- und Proxy-Logs — Ablösung steht in ROADMAP_UMSETZUNG.md, Phase L5.

Neue Messart aus der App aufnehmen

Die App schickt Messergebnisse als freies JSON. Damit ein Feld beim Kunden ankommt, sind drei Stellen in lib/netdiag.lib.php zu pflegen:

Funktion	Zweck	Wenn vergessen
netdiagKundenfelder()	Whitelist + Beschriftung + Einheit	Feld verschwindet im Kunden-PDF spurlos, übrig bleibt die Ampel
netdiagToolName()	Klarname des Werkzeugs	beim Kunden steht „[netzwerk] meintool"
eigener PDF-Zweig	Werkzeuge mit Listenergebnis	alle Zeilen landen als |-Kette in EINER Tabellenzelle
netdiagPdfText()	Unicode aus der App	Pfeile/Häkchen werden wortlos zu „?" (Core-Font, KB #1092)
netdiagKundentext()	Rohwerte übersetzen/entschärfen	englische API-Werte im deutschen Abnahmedokument

Spiegelbildlich dazu app/src/lib/messfelder.ts in der App.

Feldnamen immer aus dem erzeugenden Code der App ablesen (types.ts, die run()-Rümpfe der Werkzeuge), nie aus dem Kopf und nie aus selbst geschriebenen Testdaten — das ist hier schon zweimal schiefgegangen (KB #1084). Braucht die Messart eine eigene Tabellendarstellung im PDF, einen Zweig in lib/netdiag_pdf.lib.php ergänzen (Vorbilder: netdiagPdfStressTest, netdiagPdfWifiKanal) — sonst wird das Ergebnis zu einer |-getrennten Zeile zusammengeschoben.

Einrichtung

Einrichtung → Module → NetDiag → Einstellungen:

• Token-Gültigkeit (Sekunden)
• App-Download-URL (APK) — wird als QR-Code angezeigt

Lizenz

GPLv3