netdiag-app/README.md

NetDiag — Diagnose-App (Android)

Mobile Netzwerk-Diagnose-App. Erfasst vor Ort beim Kunden (Handy am WLAN oder USB-C→RJ45-Adapter) Geräte, Ports und Messungen und hängt die Protokolle ans Dolibarr-Modul netdiag an Kunde und Auftrag.

Stack

SvelteKit 2 · Svelte 5 · Tailwind 4 · Vite 7 · Capacitor 6 · SQLite-Offline

Entwicklung (Browser)

npm install
npm run dev          # http://localhost:5175

Im Browser liefert ein Mock (src/lib/scanner.ts) Beispiel-Scandaten — die Oberfläche lässt sich ohne Gerät entwickeln. API-Aufrufe gehen über den Vite-Proxy an den Dolibarr-Testserver (192.168.155.11, siehe vite.config.ts).

Android-Build

npm run build
npx cap add android        # einmalig
# android/ liegt komplett im Repo — cap sync kopiert nur die Web-Assets
npx cap sync android
npx cap open android

Release-APK über CI: Commit mit [apk] in der Message → Forgejo baut und lädt die APK in die Package Registry (netdiag-apk). Siehe .forgejo/workflows/build.yml.

Architektur

src/lib/
  api.ts            JSON-API-Client (JWT, 401-Refresh, Timeout)
  auth.svelte.ts    Anmelde-Status
  db.ts             Offline-Speicher (SQLite nativ / localStorage Browser)
  sync.svelte.ts    Sync-Queue -> Dolibarr (idempotent über clientUuid)
  scanner.ts        Brücke zum nativen Plugin (+ Browser-Mock)
  protocols.ts      Protokoll-Operationen (addMeasurement, upsertDevice, …)
  messfelder.ts     Beschriftung der Ergebnisfelder — Gegenstück zur
                    Whitelist im Dolibarr-Modul (siehe „Neues Tool")
  toolparams.ts     Gedächtnis der zuletzt benutzten Werkzeug-Parameter
  stresstest.ts     Auswertung des Dauertests (überlebt App-Wechsel)
  monitor.ts        Auswertung der Geräte-Überwachung -> Verfügbarkeit
  wifi/             Kanalgraph-Geometrie, Kanalempfehlung, Bewertung, Demodaten
  overlay.svelte.ts Overlay-Stapel für den Hardware-Zurück-Knopf
  toast.svelte.ts   kurze Rückmeldungen
  backButton.svelte.ts  Hardware-Back (Single-Instance, KB #480/#549)
  updater.ts        APK-Auto-Update-Prüfung (KB #363)
  tools/            erweiterbare Tool-Plattform
    index.ts        Registry — neues Tool hier eintragen
    netzwerk/       IP-Scan, Port, Ping, IP-Konflikt, SNMP, Traceroute, Stress
    internet/       Durchsatz-Test
    telefonie/      leer — geplant: SIP-Erreichbarkeit über OPTIONS.
                    RTP-Sprachqualität bewusst NICHT (ohne aufgebautes
                    Gespräch nicht ehrlich messbar, siehe ROADMAP_UMSETZUNG.md)
src/routes/
  login/ auftraege/ kunden/ einstellungen/
  protokoll/[id]/           Hauptseite mit Werkzeugen, Geräten, Messungen
  protokoll/[id]/stresstest/ monitor/ iptest/ wifi/ wifikanal/
                            Werkzeuge mit Live-Anzeige — eigene Seite statt
                            Dialog, weil sie über Minuten/Stunden laufen
android/            natives Android-Projekt inkl. Kotlin-Plugin (einzige Quelle)
native-plugin/      nur noch Anleitung/Hinweise zum Plugin
tools/              Prüfwerkzeuge ohne Gerät (siehe unten)

Prüfwerkzeuge (tools/, laufen ohne Handy)

node tools/render-chart.mjs     # rendert die echten Diagramm-Komponenten
                                # nach .render/*.svg — ansehen, nicht annehmen
node tools/pruefe-monitor.mjs   # rechnet die Verfügbarkeits-Auswertung gegen
                                # konstruierte Fälle mit Handwerten durch
node tools/pruefe-kette.mjs           # Internet-Kette: Fehlerglied, Anmeldeseite
node tools/pruefe-dns.mjs             # DNS: NXDOMAIN ist KEIN Ausfall
node tools/pruefe-geraetediff.mjs     # Geräte-Vergleich, alle Fälle OHNE MAC
node tools/pruefe-geraeteaktionen.mjs # Sortierung nach Gerätetyp
node tools/pruefe-serveradresse.mjs   # http:// bei https-App abweisen
node tools/test-recommend.mjs   # Kanalempfehlung

Warum es diese Prüfer gibt: Der Browser-Mock liefert bei Netzwerkwerkzeugen grundsätzlich den guten Fall — er gibt sogar jedem Gerät eine MAC-Adresse, die beim Kunden nie ankommt. Wer im Mock klickt, prüft den Mock. Deshalb liegt die Bewertungslogik jeweils in einer Datei ohne Laufzeit-Import (*-bewertung.ts, geraete-diff.ts, serveradresse.ts), die Node dank Type-Stripping direkt laden kann. Jeder dieser sechs Prüfer hat mindestens einen echten Fehler gefunden (Muster und Bilanz: KB #1091).

render-chart.mjs gibt es, weil die erste Fassung der WLAN-Diagramme unbemerkt unlesbar in den Einsatz ging: der Emulator hat keine WLAN-Hardware, also war nie ein gefülltes Diagramm zu sehen. SVGs mit rsvg-convert x.svg -o x.png in ein ansehbares Bild wandeln.

Neues Tool hinzufügen

1. Datei unter src/lib/tools/<kategorie>/<id>.ts anlegen, Tool implementieren.
2. In src/lib/tools/index.ts importieren und in TOOLS eintragen.
3. quickRun: true setzen, wenn das Werkzeug ohne Eingabe sinnvoll startet (kurzer Tap startet dann sofort, langes Halten öffnet die Optionen). Ausdrücklich je Werkzeug entscheiden — es gibt kein required an den Parametern, die Pflicht steht allein im run()-Rumpf. portscan.ports hat keinen Vorgabewert und ist trotzdem optional, iperf.host hat ebenfalls keinen und ist Pflicht.
4. Jeden neuen Ergebnis-Schlüssel in BEIDE Feldtabellen eintragen:
   • src/lib/messfelder.ts (App-Anzeige)
   • netdiagKundenfelder() in dolibarr-modul/netdiag/lib/netdiag.lib.php — das ist eine harte Whitelist: was dort fehlt, verschwindet im Kunden-PDF spurlos, übrig bleibt die nackte Ampel. Ebenso den Klarnamen des Werkzeugs in netdiagToolName(), sonst steht beim Kunden „[netzwerk] meintool".

Punkt 4 ist der Schritt, der hier schon zweimal vergessen bzw. geraten wurde. Beim ersten Mal wurde die Whitelist gegen selbst erfundene Testdaten gebaut, beim zweiten Mal stand 'typ' darin statt des real gelieferten 'type' — im Abnahmebeleg für eine Netzwerkdose fehlte dadurch die Angabe, ob per LAN oder WLAN gemessen wurde. Feldnamen immer aus dem erzeugenden Code ablesen, nie aus dem Kopf. (KB #1084)

Sync und Datenbank brauchen keinen Eingriff — das Ergebnis ist generisches JSON. Braucht das Tool eine neue native Messroutine: Methode im Kotlin-Plugin, Eintrag im Interface NetDiagScannerPlugin und ein Zweig im Browser-Mock (beides in src/lib/scanner.ts) — ohne Mock lässt sich nichts ohne Gerät prüfen, und ein Mock, der nur den Gutfall zeigt, bestätigt genau die Annahme, die im Feld nicht gilt (KB #1086).

Bedienung

1. Anmelden (Dolibarr-Zugang; auf dem Gerät zusätzlich Server-URL).
2. Aufträge — aktive direkt sichtbar, abgeschlossene per Checkbox, Suche. Alternativ über Kunden suchen.
3. Auftrag/Kunde antippen → Diagnose-Protokoll öffnet sich.
4. Werkzeuge ausführen (IP-Scan füllt die Geräteliste, je Gerät weitere Tools). Bei den meisten Karten steht „Tippen startet · Halten für Optionen": kurzer Tap startet sofort mit den zuletzt benutzten Werten, langes Halten öffnet den Parameterdialog. Nach der Messung springt die Ansicht zum frischen Ergebnis.
5. Abschließen & synchronisieren — Protokoll geht ans Dolibarr, PDF landet im ECM. Offline bleibt es lokal und synct automatisch bei Verbindung.

Selten gebrauchte Aktionen (Protokoll löschen) liegen hinter den drei Punkten in der Kopfzeile — bewusst nicht neben dem grünen Abschließen-Knopf.

Ohne Gerät prüfen

• Browser (npm run dev): Mock-Scanner liefert Beispieldaten.
• WLAN-Demomodus (Einstellungen → WLAN-Demodaten): 18 erfundene Netze mit allen Grenzfällen — Mesh, Co-Channel, 40 MHz im 2,4-GHz-Band, DFS, 160 MHz, Bandrand. Nötig, weil der Emulator keine WLAN-Hardware hat und jeder Scan null Netze liefert. Gespeicherte Momentaufnahmen werden als Demo gekennzeichnet.
• Diagramme: tools/render-chart.mjs (siehe oben).