# 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//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.