# 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}` |
| `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