From 7972917a841ed26f394f517e62371badc8770202 Mon Sep 17 00:00:00 2001 From: Eduard Wisch Date: Sun, 16 Aug 2026 19:56:33 +0200 Subject: [PATCH] README: Pruefwerkzeuge, Schnellstart und die Whitelist-Pflicht dokumentiert Der Abschnitt "Neues Tool hinzufuegen" sagte "Kein Eingriff in App-Logik, Sync oder Datenbank". Das stimmt fuer Sync und Datenbank, hat aber zweimal zu genau dem Fehler gefuehrt, der jetzt behoben ist: JEDER neue Ergebnis-Schluessel muss in BEIDE Feldtabellen (messfelder.ts UND netdiagKundenfelder() im Modul), sonst verschwindet der Wert im Kunden-PDF spurlos. Steht jetzt als Punkt 4 samt der Vorgeschichte da. Ausserdem ergaenzt: - quickRun beim Hinzufuegen eines Werkzeugs, mit der Begruendung, warum es ausdruecklich gesetzt und nicht hergeleitet werden darf - die Pruefwerkzeuge unter tools/ (render-chart, pruefe-monitor, test-recommend) samt dem Grund fuer render-chart: der Emulator hat keine WLAN-Hardware, deshalb ging die erste Diagramm-Fassung unbemerkt unlesbar in den Einsatz - neuer Abschnitt "Ohne Geraet pruefen" (Mock, WLAN-Demomodus, Renderer) - Architektur-Liste auf den Ist-Stand (monitor.ts, toolparams.ts, messfelder.ts, wifi/, overlay/toast, die Werkzeug-Unterrouten) - Mock-Zweig als Pflicht bei neuen nativen Methoden, mit der Begruendung - Bedienung: Schnellstart und Sprung zum Ergebnis --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 20de2de..6361ef0 100644 --- a/README.md +++ b/README.md @@ -41,27 +41,81 @@ src/lib/ 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/ (folgt: SIP, FreePBX, RTP) + 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/ protokoll/[id]/ einstellungen/ + 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) + +```bash +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/test-recommend.mjs # Kanalempfehlung +``` + +`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//.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". -Kein Eingriff in App-Logik, Sync oder Datenbank — das Ergebnis ist generisches -JSON. Braucht das Tool eine neue native Messroutine, eine Methode im -Kotlin-Plugin ergänzen. +> 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 @@ -70,5 +124,20 @@ Kotlin-Plugin ergänzen. 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).