LaunchPad/docs/ROADMAP.md

# Roadmap

Geplante Reihenfolge der nächsten Commits, aufbauend auf dem lauffähigen
Grundgerüst aus Commit 1.

## ✅ Commit 2 — Geräte- & Dienste-API (erledigt)

- REST-Endpunkte (Fastify) für `GET/POST/PATCH/DELETE` auf `devices` und `services`
- Zod-Validierung der Request-Bodies (`packages/shared/src/schemas.ts`)
- Repository-Layer über Drizzle (`apps/backend/src/db/repositories`)

## ✅ Commit 3 — Suche im Frontend (erledigt)

- Anbindung von `rankServices` aus `packages/shared` an echte Backend-Daten
- TanStack Query für Datenhaltung (`apps/frontend/src/hooks/useServices.ts`)
- Tastatur-Navigation (Pfeiltasten wählen, Enter öffnet Dienst in neuem Tab, Escape leert Suche)
- Neue UI-Komponente `ResultsList` in `packages/ui`

> TanStack Router wird bewusst erst mit dem Adminbereich (Commit 6) eingeführt,
> da es vorher keine zweite Route gibt, die er sinnvoll verwalten könnte.

## ✅ Commit 4 — Kategorien & Favoriten (erledigt)

- Kategorien-API: Erstellen, Umbenennen, Löschen, Bulk-Reorder (`PATCH /api/categories/reorder`)
- Löschen einer Kategorie setzt `category` bei betroffenen Diensten auf `null`,
  löscht die Dienste aber nicht
- Favoriten-Toggle direkt in der Trefferliste des Frontends (Stern anklicken,
  per `useMutation` + Cache-Invalidierung)

> Die eigentliche Kategorien-*Verwaltungsoberfläche* (Erstellen/Umbenennen/
> Drag & Drop in der UI) wandert in Commit 6 (Adminbereich) – die Startseite
> bleibt bewusst die minimalistische Suche, kein Verwaltungs-UI dort.

## ✅ Commit 5 — Scanner (erledigt)

- `apps/backend/src/scanner/`: DNS-Kandidaten-Auflösung, TCP-Portscan (80, 443 +
  typische Ports), HTTP-Titel-/Favicon-Extraktion, Softwareerkennung per
  Signatur-Liste, FritzBox-TR-064-Client (inkl. selbst implementierter
  HTTP-Digest-Authentifizierung)
- `POST /api/scan/devices/:id` und `POST /api/scan/fritzbox` – ausschließlich
  manuell auslösbar, kein automatischer/zeitgesteuerter Scan
- `upsertDeviceFromScan` / `upsertServiceFromScan` in den Repositories:
  garantiert, dass Benutzerfelder (displayName, category, favorite, order,
  alias, icon) bei erneuten Scans nie überschrieben werden – End-to-End getestet
  (Service manuell umbenannt/kategorisiert/favorisiert, erneut gescannt,
  Werte blieben erhalten)

> Alle Module wurden gegen echte, lokal gestartete Test-Server verifiziert
> (Port-Erkennung, Titel/Favicon-Parsing, Softwareerkennung, kompletter
> FritzBox-SOAP-/Digest-Auth-Ablauf inkl. Fehlerfall bei falschem Passwort).
> Ein Test gegen eine echte FritzBox war in dieser Umgebung nicht möglich.

## ✅ Commit 6 — Adminbereich (erledigt)

- TanStack Router (code-basiert): `/` (Startseite) + `/admin/*`
- Menüpunkte wie spezifiziert: Dashboard, Geräte, Dienste, Scanner, Kategorien,
  Plugins, Einstellungen, Logs
- Geräte-Seite: anlegen, löschen, **„Jetzt scannen"-Button** pro Gerät
- Dienste-Seite: Inline-Bearbeitung von Name/Kategorie/Alias/Reihenfolge, Favoriten-Toggle
- Kategorien-Seite: anlegen, umbenennen, löschen, **natives Drag & Drop** (kein
  zusätzliches Package nötig)
- Scanner-Seite: FritzBox-Trigger + Sammel-Scan aller Geräte
- Logs-Seite: Scan-Historie (neue `scan_logs`-Tabelle, jeder Scan-Versuch wird protokolliert)
- Einstellungen: Live-Backend-Status + Theme-Umschalter
- Plugins: ehrlicher Hinweis, dass das Plugin-System noch nicht existiert
  (statt einer vorgetäuschten Funktion)

> Verifiziert per Docker-Build-Simulation (Frontend + Backend inkl.
> `pnpm deploy --prod`) und Backend-Smoke-Test aller von den Admin-Seiten
> verwendeten Endpunkte. Die UI selbst konnte in dieser Umgebung nicht in
> einem echten Browser durchgeklickt werden (kein Browser-Tool verfügbar) –
> Verifikation stützt sich auf erfolgreichen TypeScript-/Vite-Build und
> Codeprüfung.

## ✅ Commit 7 — PWA (erledigt)

- `vite-plugin-pwa` mit generiertem Manifest (`manifest.webmanifest`) und
  Service Worker (Workbox, `generateSW`-Modus)
- Echte Icons (192/512, jeweils normal + maskable, `apple-touch-icon.png`,
  `favicon.svg`) unter `apps/frontend/public/`
- App-Shell wird precached; `/api/*` läuft über `NetworkFirst` mit 3s-Timeout
  und Cache-Fallback – Suche funktioniert damit auch offline mit dem zuletzt
  geladenen Datenstand
- `nginx.conf`: `sw.js`/`manifest.webmanifest` explizit von der 7-Tage-Cache-Regel
  ausgenommen (sonst kommen Updates bei installierten Nutzern nie an), korrekter
  MIME-Type für das Manifest gesetzt

> Verifiziert: Manifest gegen Installierbarkeits-Anforderungen geprüft (512er-Icon,
> maskable Icon, alle Pflichtfelder vorhanden), alle Assets über einen echten
> HTTP-Server abgerufen (200 OK, korrekte Content-Types), generierter Service-Worker-
> Code inspiziert (Precache-Liste + NetworkFirst-Route bestätigt), vollständige
> Docker-Build-Simulation durchlaufen. Die tatsächliche "Zum Homescreen hinzufügen"-
> Installation konnte mangels Browser in dieser Umgebung nicht getestet werden.

## ✅ Commit 8 — Plugin-System (erledigt)

- Plugins liegen als Ordner unter `apps/backend/plugins/*`, jeweils mit einer
  `index.js` (reines ESM, kein Build-Schritt). Werden beim Backend-Start
  geladen (`apps/backend/src/plugins/loader.ts`) und per Docker-Volume
  eingebunden – neue Plugins brauchen nur einen Container-Neustart, kein
  Image-Rebuild
- Plugin-Vertrag (`apps/backend/src/plugins/types.ts`): `setup(ctx)` zum
  Registrieren zusätzlicher Softwareerkennung (inkl. Icon), `importDevices()`
  für eigene Geräte-Importquellen
- Zwei funktionierende Beispiel-Plugins: `example-signatures` (Homebridge,
  Uptime Kuma) und `static-import` (Geräte aus lokaler `devices.json`)
- `GET /api/plugins`, `POST /api/plugins/:name/import` – Import läuft wie
  Scans ausschließlich manuell per Knopfdruck
- Frontend-Plugins-Seite zeigt echte geladene Plugins mit Capabilities und
  Import-Button (ersetzt den ehrlichen Platzhalter aus Commit 6)
- Von neuen Plugins erkannte Software liefert ein Icon, das – wie `category`
  seit Commit 5 – nur beim erstmaligen Anlegen eines Dienstes als Startwert
  übernommen wird, nie nachträglich überschrieben

> Verifiziert: beide Plugins laden nachweislich beim Start; ein echter Scan
> gegen einen Test-Server mit "Homebridge" im Response-Body wurde über die
> Plugin-Signatur erkannt, inkl. korrekt übernommenem Icon; Geräte-Import per
> Plugin getestet (`source: "plugin"`); Fehlerfälle (unbekanntes Plugin → 404,
> Plugin ohne Import-Fähigkeit → 400) geprüft; Docker-Build-Simulation
> bestanden, dabei auch verifiziert, dass ein fehlendes Plugin-Verzeichnis
> nicht zum Absturz führt, sondern nur zu einer leeren Liste.

> **Bewusst nicht umgesetzt:** eigene Admin-Routen/Menüpunkte pro Plugin
> (alle Plugins erscheinen gesammelt auf einer Seite) und Sandboxing
> (Plugin-Code läuft mit vollem Zugriff im Backend-Prozess – nur Plugins aus
> vertrauenswürdiger Quelle einbinden, siehe `apps/backend/plugins/README.md`).

Damit ist die komplette in der ursprünglichen Projektübergabe beschriebene
Funktionalität umgesetzt.

## Bugfixes aus dem ersten Praxistest (nach Commit 8)

Basierend auf echtem Testen gegen ein reales Homelab (FritzBox + gescannte
Geräte):

- **Neues Feld `visible` auf Diensten.** Scan-Treffer mit Fehlerantworten
  (404, 400, 302 als Titel) oder generischen Ladebildschirm-Titeln
  ("Loading...", der Scanner führt kein JavaScript aus) werden beim
  erstmaligen Anlegen automatisch als `visible: false` markiert – sie
  erscheinen nicht mehr in der Suche, bleiben aber unter Admin -> Dienste
  sichtbar, umschaltbar (👁️/🙈) und löschbar. Bestehende Datenbanken werden
  beim Start automatisch migriert (`ALTER TABLE ... ADD COLUMN`), keine
  Daten gehen verloren.
- **Hostname/URL/HTTPS sind jetzt im Adminbereich editierbar** (Dienste ->
  Bearbeiten) und werden ab sofort bei einem erneuten Scan eines bereits
  bekannten Dienstes **nicht mehr überschrieben** (vorher wurden diese Felder
  bei jedem Scan aufgefrischt). Nur `favicon`/`description` werden weiterhin
  aktualisiert. Achtung: Wird dabei der **Port** geändert, entsteht beim
  nächsten Scan ein neuer Eintrag für den ursprünglichen Port, da die
  Zuordnung über `deviceId + port` läuft.
- **Suchergebnisliste erscheint nur noch bei aktiver Eingabe** – vorher war
  sie auch bei leerem Suchfeld dauerhaft aufgeklappt.
- **Port wird jetzt überall mit angezeigt** (`hostname:port` statt nur
  `hostname`), in der Suche wie im Adminbereich.
- **Admin-Sidebar ist jetzt echt fixiert** (`fixed` statt `static`) – vorher
  scrollte "Zurück zur Suche" bei langem Seiteninhalt aus dem Sichtfeld.