Commit 8: Plugin-System (Scanner erweitern, Geräte importieren, Icons)

apps/backend/plugins/README.md

@@ -0,0 +1,78 @@
+# LaunchPad-Plugins
+
+Jeder Unterordner hier ist ein Plugin. Erkannt wird alles, was eine
+`index.js` mit einem passenden Default-Export enthält – kein Rebuild des
+Docker-Images nötig, dieser Ordner wird zur Laufzeit als Volume eingebunden
+(siehe `docker-compose.yml`). Nach dem Hinzufügen/Ändern eines Plugins
+reicht ein Neustart des Backend-Containers:
+
+```bash
+docker compose restart backend
+```
+
+## Minimalstruktur
+
+```
+apps/backend/plugins/mein-plugin/
+└── index.js
+```
+
+```js
+export default {
+  name: "mein-plugin",
+  version: "1.0.0",
+  description: "Kurze Beschreibung, erscheint unter Admin -> Plugins",
+
+  // optional: Scanner erweitern
+  setup(ctx) {
+    ctx.registerSoftwareSignature({
+      name: "Meine Software",
+      category: "Sonstiges",
+      icon: "🔧", // Emoji oder Icon-URL
+      matches: (input) => !!input.body && /meine-software/i.test(input.body),
+    });
+  },
+
+  // optional: eigene Geräte-Importquelle
+  async importDevices() {
+    return [
+      { hostname: "beispiel", ip: "192.168.1.99", source: "plugin" },
+    ];
+  },
+};
+```
+
+Beide Funktionen (`setup`, `importDevices`) sind optional – ein Plugin kann
+nur die eine, nur die andere, oder beide implementieren. Reines JavaScript
+(ESM), kein Build-Schritt nötig.
+
+## Was Plugins aktuell können
+
+- **Scanner registrieren**: `ctx.registerSoftwareSignature(...)` in `setup()`
+  fügt der automatischen Softwareerkennung (siehe `apps/backend/src/scanner/softwareDetection.ts`)
+  eine zusätzliche Signatur hinzu, inklusive eigenem Icon. Wird bei jedem
+  Geräte-Scan berücksichtigt.
+- **Geräte importieren**: `importDevices()` liefert eine Liste von Geräten,
+  die per Knopfdruck unter Admin -> Plugins importiert werden
+  (`POST /api/plugins/:name/import`). Abgeglichen wird wie bei Scans über
+  MAC/IP – ein erneuter Import überschreibt keine Gerätefelder, die der
+  Nutzer zwischenzeitlich geändert hat, außer den scan-eigenen (siehe
+  `upsertDeviceFromScan`).
+- **Icons bereitstellen**: über `icon` an einer registrierten Signatur. Wird
+  als Startwert für neu angelegte Dienste übernommen (wie `category` –
+  niemals nachträglich überschrieben, siehe README Hauptprojekt).
+
+## Was (noch) nicht geht
+
+- Eigene Admin-Menüpunkte/Unterseiten (aktuell erscheinen alle Plugins
+  gesammelt auf einer Seite unter Admin -> Plugins, keine eigene Route pro
+  Plugin).
+- Kein Sandboxing: Plugin-Code läuft mit vollem Zugriff im Backend-Prozess.
+  Nur Plugins aus vertrauenswürdiger Quelle einbinden.
+
+## Beispiel-Plugins
+
+- `example-signatures/` – registriert zwei zusätzliche Software-Signaturen
+  (Homebridge, Uptime Kuma).
+- `static-import/` – importiert Geräte aus einer lokalen `devices.json`
+  (standardmäßig leer, siehe `devices.example.json` für das Format).