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)
• Anmeldung per AWL-Konto (seit 1.4.0, braucht awlauth ≥ 1.6.0): die App öffnet die awlauth-Anmeldeseite im Chrome-Tab und ist ohne Eingabe drin, wenn das Handy in Chrome schon angemeldet ist. Der Einmal-Code kommt über das Schema de.data-it-solution.netdiag:/sso zurück und wird mit PKCE in api/sso.php eingelöst. NetDiag trägt sich beim ersten Aufruf selbst in awlauth ein („Angebundene Apps“)
• 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}
sso.php	GET	Anmeldung per AWL-Konto eingerichtet? → {available,clientId,redirectUri,authorizePath} (legt die App in awlauth beim ersten Aufruf an)
sso.php	POST {code,code_verifier}	Einmal-Code der awlauth-Seite einlösen (PKCE) → wie auth.php
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=	Protokoll-PDF streamen (nur Bearer-Header)
update.php	GET / GET ?download=1	neueste APK-Version aus der Registry / APK streamen
applog.php	POST	Debug-Log der App entgegennehmen

Authentifizierung ausschliesslich per Authorization: Bearer <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).

Token gehört nicht in die Adresszeile (seit v1.3.0). Eine URL mit ?jwt= steht in jedem Zugriffs- und Proxy-Log, und das Token gilt sieben Tage für die gesamte Kunden-API. netdiag_api_read_token() nimmt einen Query-Token deshalb nur noch an, wenn der Endpunkt es ausdrücklich verlangt.

Genau eine solche Stelle gibt es, befristet: update.php?download=1. Die im Feld installierten App-Fassungen bauen die Download-Adresse mit dem Token darin — wer den Zweig sofort schließt, sperrt genau die Geräte vom Update aus, die die neue APK bräuchten. Zu entfernen, sobald der Rollout bestätigt ist; der Hinweis steht im Code an beiden Stellen (api/update.php, api/netdiag_api.lib.php).

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 dreimal schiefgegangen (KB #1084). Beim dritten Mal war es eine Namenskollision: port gehört bereits dem SNMP-Werkzeug („Switch-Port"), ein SIP-Port unter demselben Schlüssel wäre im Kundendokument als „Switch-Port: 5060" erschienen. Vor dem Eintragen prüfen, ob der Schlüssel schon vergeben ist, und im Zweifel im Werkzeug umbenennen (zielPort). Braucht die Messart eine eigene Tabellendarstellung im PDF, einen Zweig in lib/netdiag_pdf.lib.php ergänzen (Vorbilder: netdiagPdfStressTest, netdiagPdfWifiKanal, netdiagPdfSip) — sonst wird das Ergebnis zu einer |-getrennten Zeile zusammengeschoben.

Einrichtung

Einrichtung → Module → NetDiag → Einstellungen:

• App-Download-URL (APK) — wird als QR-Code angezeigt

Die Gültigkeit der Anmeldung steht bewusst nicht hier, sondern allein in AWLAUTH_TTL im awlauth-Setup (Standard 7 Tage). Zwei Stellschrauben für dieselbe Sache sind eine Fehlerquelle — die hiesige hätte nach der Umstellung auf awlauth still gar nichts mehr getan (Feld mit v1.2.0 entfernt).

Nicht im Formular, aber nötig für die Update-Funktion: die Konstante NETDIAG_FORGEJO_TOKEN (Lesezugriff auf die Paket-Registry). Ohne sie antwortet update.php mit „Update-Funktion nicht konfiguriert".

Lizenz

GPLv3