122 lines
6.5 KiB
Markdown
122 lines
6.5 KiB
Markdown
# MPM – Modulare Web-Management-Plattform
|
||
|
||
Zentrale, webbasierte Management-Plattform, über die eigenständige Web-Applikationen als **Module** integriert, verwaltet und Benutzern zugewiesen werden können.
|
||
|
||
**Status: Phase 9 – Administration (abgeschlossen)**
|
||
|
||
## Architektur-Überblick
|
||
|
||
```
|
||
Internet
|
||
│
|
||
▼
|
||
Docker container (restricted-capability root supervisor; services run as app)
|
||
┌─────────────────────────────────────────────┐
|
||
│ Supervisor (Prozessmanager) │
|
||
│ ├── Nginx (Reverse Proxy, :8080) │
|
||
│ │ ├── / -> Management-Frontend │
|
||
│ │ └── /api/ -> Management-Backend │
|
||
│ └── NestJS Management-Backend (127.0.0.1:3000)│
|
||
│ (ab Phase 3: + Modul-Prozesse) │
|
||
└─────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
PostgreSQL (eigener Container, persistentes Volume)
|
||
```
|
||
|
||
- Der MPM-Managementcontainer verwaltet Modul-Stacks über den Docker-Socket. Modulcode erhält selbst keinen Socketzugriff.
|
||
- Neue Module laufen in eigenen Compose-Stacks. Die App und optionale Datenbanken haben getrennte Container und persistente Volumes.
|
||
- Der Docker-Socket ermöglicht weitreichende Hoststeuerung. Daher dürfen nur vertrauenswürdige Administratoren Module installieren; der Socket wird nie in Modulcontainer durchgereicht.
|
||
- PostgreSQL liegt außerhalb des Applikationscontainers in einem persistenten Volume.
|
||
|
||
Details: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · Phasen: [`docs/PHASES.md`](docs/PHASES.md)
|
||
|
||
## Schnellstart (Docker)
|
||
|
||
```bash
|
||
# 1. Umgebung prüfen (.env liegt mit Entwicklungs-Defaults bei)
|
||
# Für Produktion: Werte ändern und COOKIE_SECURE=true setzen.
|
||
|
||
# 2. Bauen und starten
|
||
docker compose up --build -d
|
||
|
||
# 3. Öffnen
|
||
# Die Adresse aus MARKETPLACE_PUBLIC_URL öffnen, z. B. http://127.0.0.1:8080
|
||
# Anmeldung: ADMIN_USERNAME / ADMIN_PASSWORD aus .env
|
||
# API-Dokumentation (Swagger): <MARKETPLACE_PUBLIC_URL>/api/docs
|
||
```
|
||
|
||
Definition of Done Phase 1: Webseite erreichbar ✓ Login möglich ✓ Admin-Dashboard sichtbar ✓
|
||
|
||
## Lokale Entwicklung
|
||
|
||
```bash
|
||
# PostgreSQL starten
|
||
docker compose up -d postgres
|
||
|
||
# Backend (http://127.0.0.1:3000, Swagger: /api/docs)
|
||
cd apps/platform-backend
|
||
npm install
|
||
npm run start:dev
|
||
# Hinweis: dafür in .env DATABASE_URL auf 127.0.0.1 umstellen
|
||
|
||
# Frontend (http://localhost:5173, /api wird an das Backend proxied)
|
||
cd apps/platform-frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## Projektstruktur
|
||
|
||
```
|
||
MPM/
|
||
├── apps/
|
||
│ ├── platform-backend/ # NestJS – Management-API (Auth, RBAC, Health, Audit)
|
||
│ └── platform-frontend/ # React/Vite/Tailwind – Management-UI
|
||
├── docker/ # Nginx- & Supervisor-Konfiguration
|
||
├── docs/ # Architektur- & Phasen-Dokumentation
|
||
├── modules/ # Installierbare Module (ab Phase 3)
|
||
├── Dockerfile # Multi-Stage-Build des Management-Containers
|
||
└── docker-compose.yml # PostgreSQL + MPM; Module erhalten eigene Compose-Stacks
|
||
```
|
||
|
||
## Tech-Stack
|
||
|
||
| Bereich | Technologie |
|
||
|---|---|
|
||
| Frontend | React 19, TypeScript, Vite, Tailwind CSS, React Router, TanStack Query, Zod |
|
||
| Backend | NestJS 11, TypeScript, REST `/api/v1`, OpenAPI/Swagger |
|
||
| Datenbank | PostgreSQL 18 (Schemas: `management`, ab Phase 3 pro Modul) |
|
||
| Betrieb | Docker Compose, Nginx, MPM-Managementcontainer und separate Modul-Stacks |
|
||
| Sicherheit | Argon2id, HttpOnly/Secure/SameSite-Cookies, serverseitige Sessions, CSRF-Schutz, IP-basiertes Rate Limiting, Audit-Log, Helmet, RBAC |
|
||
|
||
## Funktionen
|
||
|
||
### Phase 1 – Grundgerüst
|
||
Login/Logout mit serverseitigen Sessions, Rollen (ADMIN/USER), IP-basiertes Rate Limiting, Health-Monitoring, Audit-Log, Migrationen mit Advisory-Lock, responsive Management-UI mit Design-System.
|
||
|
||
### Phase 2 – Benutzerverwaltung
|
||
Vollständige Benutzer-CRUD-API (nur Admin) mit Duplikat-Schutz, Schutz des letzten Admins, sofortiger Session-Sperrung bei Deaktivierung, Passwort-Reset, eigenes Passwort ändern, Benutzerverwaltungs-UI (Tabelle, Modals, Toasts) und Profil-Seite.
|
||
|
||
### Phase 3 – Modul-System
|
||
Modul-Registry mit Manifest-Vertrag (`module.json`, Zod-validiert), ZIP-Installation mit Zip-Slip-Schutz, eigene Compose-Stacks je Modul, Lifecycle (INSTALLED/STARTING/RUNNING/STOPPED/ERROR/DISABLED), Healthchecks mit Startup-Grace, Modulverwaltungs-UI und persistente Datenvolumes.
|
||
|
||
### Phase 4 – Gateway & Routing
|
||
Dynamisches Routing `/<slug>` auf einem eigenen Modulhost über Nginx → Modul-Gateway (Middleware): getrennte Browser-Session, Modul-Status-Check, Permission-Check (fail-closed), Proxy zu internen Ports. Der Einstieg erfolgt über einen authentifizierten Einmal-Ticket-Redirect vom Plattformhost. Module müssen Assets und APIs unter `/<slug>/` bereitstellen; die Management-API ist auf dem Modulhost nicht erreichbar. Sichere Identitätsübergabe über Header, Startup-Recovery mit Autostart nach Container-Neustarts.
|
||
|
||
### Phase 5 – Berechtigungssystem
|
||
Zweistufiges Rechtekonzept: Plattform-Rollen (ADMIN/USER) + Modul-Berechtigungen (`user_module_permissions`, GRANTED/DENIED). Admin-API für Zuweisungen, Gateway prüft Berechtigungen fail-closed, Dashboard zeigt nur freigegebene Module als Kacheln.
|
||
|
||
### Phase 6 – Modul-API & SDK
|
||
Verbindlicher Modul-API-Vertrag (`/health`, `/api/manifest`, `/api/me`) mit `platform-module-sdk`: Module erhalten die Benutzer-Identität sicher über Gateway-Header (Session-Cookie wird nie weitergereicht). Demo-Modul als Referenzimplementierung.
|
||
|
||
### Phase 8 – Modul-SDK
|
||
`packages/platform-module-sdk`: `createModuleServer` verdrahtet den kompletten Vertrag plus fachliche Routen; dazu Manifest-Validierung, Laufzeit-Config, strukturiertes Logging (mit Secret-Schwärzung) und ein interner Plattform-API-Client. Module binden das SDK als Einzeldatei ein (Vendor-Pattern). Phase 7 (Kalender) wurde zugunsten der Einbindung bestehender Projekte übersprungen.
|
||
|
||
### Phase 9 – Administration
|
||
Audit-Log-UI (Filter + Paginierung), Systemeinstellungen (Whitelist-Schlüssel, Inline-Bearbeitung), erweiterter Systemstatus mit Gesamtstatus und allen Modul-Healths. Alle Endpunkte nur für Admins (RBAC verifiziert).
|
||
|
||
## Annahme
|
||
|
||
„ChatCM" wurde als **shadcn-artige Komponentenbasis** interpretiert: Tailwind CSS plus zentral gepflegte, wiederverwendbare UI-Komponenten (`apps/platform-frontend/src/components/ui`).
|