Dolibarr-Modul NetDiag — Netzwerk-Diagnose-Protokolle, JSON-API für die NetDiag-App
Eduard Wisch
0b3db47ec1
Vorab: drei Punkte der Roadmap-Liste waren Fehlannahmen. Eine Analyse mit anschließender Gegenprüfung (jeder Befund musste einen Widerlegungsversuch überstehen) hat sie ausgeräumt, bevor Code geändert wurde: - "ab Seite 2 alles nach rechts verschoben" existiert nicht. Nachgemessen am Prod-PDF ND2026-0015 mit pdftotext -bbox: Seite 1 und Seite 2 beginnen beide bei 16,0 mm. Die echten Umbruchfehler waren andere. - measure_status validieren war seit Phase 1 erledigt. - Werkzeug-IDs / Teilnetz-Gruppierung / TCPDF-Fußzeile: verworfen, die vorgeschlagenen Änderungen hätten das PDF verschlechtert. PDF (alle Punkte am mehrseitigen Dokument nachgeprüft): - Tabellenkopf der Geräteliste wird auf Folgeseiten wiederholt. Vorher standen ab Seite 2 unbeschriftete Spalten — bei leeren MAC/Hostname-Feldern vier namenlose Spalten. - Messungs-Titelzeile und Ergebnis werden zusammengehalten. Vorher blieb die Überschrift samt Ampel am Seitenende allein zurück, darunter ein leerer, unten offener Rahmen; in einem Testlauf über 61 Umbruchlagen 5-mal (~8 %). - Spalte "Gerätetyp" hatte 15 mm, ließ aber 10 Zeichen zu — "Chromecast/TV" lief bis 199,0 mm bei 195 mm Tabellenkante über den Rahmen in den Druckrand. - Deutsche Bezeichnungen mit Einheiten statt roher JSON-Schlüssel: aus "VerlustProzent: 0 | MinMs: 4.4 | UptimeSek: 8123456" wird "Paketverlust: 0 % | Kürzeste Antwortzeit: 4.4 ms | Betriebszeit: 94 Tage 1 Std". Als Whitelist (netdiagKundenfelder(), gemeinsam für Karte und PDF) — interne Felder wie arpAvailable, mdnsOk, probed, answered fallen damit automatisch heraus. - "ARP-Tabelle nicht lesbar (/proc/net/arp) — braucht Root" wird beim Drucken zu einem kundentauglichen Satz. Altdaten stehen so in der DB, deshalb Ersetzung beim Drucken statt nur in der App. Gerätemerkmale (der eigentliche Roadmap-Punkt): Der Techniker sah in der App "Drucker HP, Port 9100", im Kundenprotokoll stand nur die IP. Die Felder fehlten dabei nicht in der Übertragung, sondern durchgängig — ein Fix allein in der API wäre folgenlos geblieben, weil Dolibarrs setSaveQuery() nur deklarierte $fields schreibt. Ergänzt über die ganze Kette: sql/llx_netdiag_device.sql + neue Migration llx_netdiag_device_v2.sql (ADD COLUMN IF NOT EXISTS, wiederholbar, läuft bei jedem Modul-Update), NetDiagDevice::$fields + Properties, api/protocols.php POST und GET, Kartenansicht und PDF. Neu: netbios_name, mdns_name, mdns_services, custom_name, open_ports, found_via, last_seen. Im PDF steht jetzt statt "192.168.178.20" die Zeile "Brother HL-L2350DW · Brother · Drucker · 80,443,9100" — der Name kommt aus mDNS, obwohl der Hostname leer ist. Sprachschlüssel Vendor -> NetDiagVendor: Die Gegenprüfung hielt den Punkt für falsch (Translate::load() ist first-wins, im CLI-Test kam "Hersteller"), im Browser stand in der Kartenansicht aber "Lieferant" — im HTTP-Kontext lädt Dolibarr vorher andere Sprachdateien als im CLI. Statt der Ursache nachzugehen jetzt ein eigener, kollisionsfreier Schlüssel; im Browser gegengeprüft. Nebenbei: doppeltes "OK OK" beim Status 0 im PDF. Gegen das Test-Dolibarr geprüft: Sync über die echte API (Login, POST, GET), Felder in der DB kontrolliert, Kartenansicht im Browser, mehrseitiges PDF gerendert und angesehen, Migration zweimal ausgeführt (idempotent). |
||
|---|---|---|
| .forgejo/workflows | ||
| admin | ||
| api | ||
| class | ||
| core/modules | ||
| langs | ||
| lib | ||
| sql | ||
| ChangeLog.md | ||
| netdiag_object_tab.php | ||
| netdiagindex.php | ||
| netdiagprotocol_card.php | ||
| 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 (JWT-Auth) - PDF-Protokoll, wird im Dokumentenarchiv (ECM) abgelegt
- Rechtesystem:
netdiag → protocol → read/write/delete - Mehrsprachig (de_DE, en_US)
- QR-Code zum App-Download in der Modul-Einrichtung
Installation
- Verzeichnis
netdiag/nachhtdocs/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. - In Dolibarr: Einrichtung → Module → NetDiag aktivieren.
- Beim Aktivieren werden die Tabellen
llx_netdiag_protocol,llx_netdiag_device,llx_netdiag_measurementangelegt und ein JWT-Schlüssel erzeugt. - 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>.
Einrichtung
Einrichtung → Module → NetDiag → Einstellungen:
- Token-Gültigkeit (Sekunden)
- App-Download-URL (APK) — wird als QR-Code angezeigt
Lizenz
GPLv3