feat: marketplace modules and isolated container management

KI_SETUP.md

@@ -0,0 +1,113 @@
+# Arbeitsplatz-Setup für KI-Assistenten
+
+Diese Datei beschreibt, wie MPM auf einem neuen Arbeitsplatz eingerichtet und angepasst wird. Lies sie zusammen mit `README.md`, `docs/ARCHITECTURE.md` und `docs/MODULE-MARKETPLACE.md`, bevor du Änderungen vornimmst.
+
+## Projektziel und Architektur
+
+MPM ist eine Management-Plattform für Benutzer, Rollen und externe Module. Das Frontend ist React/Vite/TypeScript, das Backend NestJS/TypeScript, die Plattformdaten liegen in PostgreSQL. Die Plattform wird mit Docker Compose gestartet. Installierte Module laufen in eigenen Compose-Projekten mit eigenen Containern und persistenten Volumes; MPM verwaltet deren Start, Stop, Health, Disable und Remove. Der Docker-Socket wird nur vom MPM-Backend verwendet und niemals an Modulcontainer weitergereicht.
+
+Wichtige Verzeichnisse:
+
+- `apps/platform-frontend`: React-Oberfläche
+- `apps/platform-backend`: API, Authentifizierung, Marketplace und Modulverwaltung
+- `packages/platform-module-sdk`: SDK-Vertrag für Module
+- `modules/demo`: Referenzmodul
+- `docker`: Nginx- und Supervisor-Konfiguration
+- `docs`: Architektur und Modul-/Marketplace-Verträge
+
+Änderungen an Modulinstallation oder Container-Lifecycle müssen den Compose-Stack, persistente Daten, Gateway-Netzwerk und Fehler-/Recovery-Pfade berücksichtigen. Lies dafür `module-container-manager.ts`, `module-installer.ts`, `modules.service.ts` sowie die Modul-Dokumentation.
+
+## Voraussetzungen
+
+Für den üblichen Betrieb:
+
+- Git
+- Docker Desktop mit Linux-Containern und Docker Compose v2; unter Windows ist ein aktiviertes WSL2-Backend empfehlenswert
+- VS Code und ein KI-Assistent mit Zugriff auf den geöffneten Projektordner
+
+Für lokale Frontend-/Backend-Entwicklung außerhalb von Docker zusätzlich Node.js 24 und npm. Die Module haben eigene Laufzeit- und Build-Anforderungen gemäß ihrem Manifest.
+
+## Beim ersten Öffnen auf einem neuen Arbeitsplatz
+
+1. Repository auschecken und den aktuellen Arbeitsbranch verwenden. Den vorhandenen Branch nicht ungefragt auf `main` umbenennen oder lokale Änderungen verwerfen.
+2. `git status --short --branch` prüfen. Nicht committete Änderungen gehören möglicherweise dem Nutzer; niemals resetten, stashen, überschreiben oder entfernen, ohne vorher genau zu prüfen.
+3. Docker Desktop starten und sicherstellen, dass Linux-Container und Compose v2 funktionieren.
+4. `.env` nur anlegen, wenn sie noch nicht vorhanden ist: `.env.example` kopieren und ausschließlich lokale Entwicklungswerte eintragen. Eine vorhandene `.env` nie ersetzen oder ausgeben.
+5. Secrets dieses Arbeitsplatzes getrennt halten. Keine Passwörter, OAuth-Secrets, Zugriffstokens, Cookies oder privaten Schlüssel in Quellcode, Dokumentation, Kommandoausgaben, Commits oder Issues übernehmen. Beispielwerte in `.env.example` sind Platzhalter.
+6. Bei rein lokaler HTTP-Entwicklung `NODE_ENV=development` und `COOKIE_SECURE=false` verwenden. In Produktion muss HTTPS aktiv sein und `COOKIE_SECURE=true` gesetzt werden.
+7. Für OAuth-Entwicklung sind pro Provider eigene OAuth-Clientdaten mit passender Callback-URL nötig. Ohne OAuth-Konfiguration können die übrigen Plattformfunktionen lokal verwendet werden; Provider dürfen nicht mit unvollständiger Konfiguration gesetzt werden. Bei aktivem OAuth einen dauerhaften `MARKETPLACE_TOKEN_ENCRYPTION_KEY` mit mindestens 32 Zeichen lokal generieren und geheim halten.
+8. `APP_PORT` bei Bedarf anpassen, falls 8080 belegt ist. `MARKETPLACE_PUBLIC_URL` muss die vom Browser erreichbare Basisadresse samt Port enthalten, etwa `http://127.0.0.1:8080`.
+9. `DOCKER_SOCKET_GID` ist hostabhängig. Docker Desktop verwendet häufig `0`; bei Linux ist die tatsächliche Gruppe des Docker-Sockets zu verwenden. Änderungen daran erst nach Prüfung der Docker-Berechtigungen vornehmen.
+
+Die Datenbankverbindung innerhalb des Compose-Netzwerks verwendet den Hostnamen `postgres`. Bei Backend-Ausführung direkt auf dem Host muss `DATABASE_URL` auf `127.0.0.1:5432` zeigen. Niemals den Compose-internen Hostnamen `postgres` für einen Backendprozess auf dem Host verwenden.
+
+## Plattform mit Docker starten
+
+Im Projektstamm:
+
+```powershell
+docker compose up --build -d
+docker compose ps
+```
+
+Danach die in `APP_PORT` konfigurierte Adresse öffnen (Standard `http://localhost:8080`). Das initiale Admin-Konto wird beim ersten Datenbankstart aus `ADMIN_USERNAME`, `ADMIN_EMAIL` und `ADMIN_PASSWORD` angelegt. Spätere Änderungen dieser Variablen ändern ein bereits angelegtes Datenbankkonto nicht automatisch.
+
+Logs und Neustart:
+
+```powershell
+docker compose logs -f platform
+docker compose logs -f postgres
+docker compose restart platform
+```
+
+Für normale Neustarts oder Updates kein `docker compose down -v` verwenden: `-v` löscht persistente Datenbank- und Moduldaten.
+
+## Lokale Entwicklung ohne Plattform-Container
+
+PostgreSQL zuerst starten:
+
+```powershell
+docker compose up -d postgres
+```
+
+Dann in separaten Terminals:
+
+```powershell
+Set-Location apps/platform-backend
+npm ci
+npm run start:dev
+```
+
+```powershell
+Set-Location apps/platform-frontend
+npm ci
+npm run dev
+```
+
+Der Backendprozess benötigt gültige Variablen aus `.env`; beim lokalen Start muss `DATABASE_URL` auf `127.0.0.1` zeigen. Falls die Entwicklungsumgebung `.env` nicht automatisch lädt, Variablen sicher über die lokale Shell/VS-Code-Konfiguration einlesen; keine Secrets in Startskripte committieren.
+
+## Arbeitsregeln für Änderungen
+
+- Vor Änderungen relevante `AGENTS.md`-Dateien, Dokumentation und betroffene Implementierungen lesen.
+- Vor jedem Commit Status und Diff prüfen. Nur die beabsichtigten Dateien aufnehmen; Nutzeränderungen nicht stillschweigend verwerfen.
+- Keine echten Zugangsdaten in Ausgaben oder Dokumentation schreiben. Wenn ein Secret versehentlich in einen Commit gelangt ist, es als kompromittiert behandeln und rotieren; bloßes Löschen aus der aktuellen Datei reicht nicht.
+- API-Änderungen auf DTO/Validierung, Authentifizierung, RBAC, CSRF, Audit und Frontend-Verwendung prüfen.
+- Containeränderungen auf Windows/Docker Desktop und Linux, Restart/Stop/Remove, Netzwerk-Neuerstellung, Datenpersistenz und Logs prüfen.
+- Datenbankänderungen als neue Migration ergänzen; bestehende Migrationen nicht nachträglich umschreiben, wenn sie schon angewendet sein könnten.
+- UI-Änderungen an bestehenden Komponenten und Dark-/Light-Theme-Konventionen ausrichten.
+- Abhängigkeiten nur bei Bedarf ändern und Lockfiles konsistent halten.
+- Keine Builds, Tests, Deployments, Commits oder Pushes ausführen, wenn der Nutzer das nicht angefordert hat. Wenn er Verifikation verlangt, die tatsächlich ausgeführten Befehle und Ergebnisse angeben.
+- Bei einem gewünschten Push Ziel-Remote und Branch verifizieren, den kompletten Commit-Diff auf Secrets prüfen und keine Force-Pushes ausführen, außer der Nutzer weist sie ausdrücklich an.
+
+## Häufige Arbeitsplatzprobleme
+
+- **Port belegt:** `APP_PORT` in `.env` ändern und `MARKETPLACE_PUBLIC_URL` synchron anpassen. PostgreSQL-Port 5432 kann für reine Compose-Nutzung bei Bedarf ebenfalls hostseitig angepasst werden; dann muss die lokale `DATABASE_URL` mitziehen.
+- **Backend startet nicht:** Prüfen, ob alle Pflichtvariablen gesetzt sind, `ADMIN_PASSWORD` mindestens 10 Zeichen hat, `DATABASE_URL` den richtigen Host verwendet und PostgreSQL gesund ist.
+- **OAuth-Callback schlägt fehl:** Externe Callback-URL muss exakt zur Provider-Konfiguration passen, inklusive Schema, Host, Port und Pfad `/api/v1/marketplace/oauth/<provider>/callback`. Redirect-URL und `MARKETPLACE_PUBLIC_URL` müssen übereinstimmen.
+- **Modulcontainer lassen sich nicht steuern:** Docker Desktop muss laufen; Socket-Mount und `DOCKER_SOCKET_GID` prüfen. Docker-Socket-Zugriff ist privilegiert; keine Erhöhung für Modulcontainer aktivieren.
+- **Modul kann nach Stop nicht starten:** MPM-Logs und den Modul-Compose-Stack prüfen; Containerstatus, Gateway-Netz und Volume-Status erfassen. Nicht als Erstes Datenvolumes löschen.
+- **Windows-Dateirechte oder Pfade:** Docker Compose läuft in Linux-Containern; Datei- und Socketpfade aus Docker Desktop/WSL berücksichtigen und möglichst nicht zwischen Windows- und WSL-Dateisystemen hin- und herkopieren.
+
+## Dokumente zum Modulvertrag
+
+Vor Implementierung oder Anpassung eines Marketplace-Moduls außerdem `docs/MODULE-MARKETPLACE.md`, `modules/README.md` und `packages/platform-module-sdk/README.md` lesen. Das Modulmanifest und dessen Compose-/Health-/Datenvolume-Angaben sind Teil der Integrationsschnittstelle.