# MPM – Phasen-Übersicht

Der Arbeitsplan sieht zehn inkrementelle Phasen vor. Nach jeder Phase muss das System startbar und testbar sein.

| Phase | Bereich | Status |
|---|---|---|
| 1 | Grundgerüst (Docker, DB, Login, Rollen) | ✅ Abgeschlossen |
| 2 | Benutzerverwaltung | ✅ Abgeschlossen |
| 3 | Modul-System (Manifest, Installation, Lifecycle) | ✅ Abgeschlossen |
| 4 | Gateway & dynamisches Routing (`/slug`) | ✅ Abgeschlossen |
| 5 | Berechtigungssystem (User ↔ Module) | ✅ Abgeschlossen |
| 6 | Modul-API (`/health`, `/api/manifest`, `/api/me`) | ✅ Abgeschlossen |
| 7 | Referenzmodul Kalender | ⏳ Übersprungen (bestehende Projekte werden stattdessen eingebunden) |
| 8 | Modul-SDK (`platform-module-sdk`) | ✅ Abgeschlossen |
| 9 | Administration (Übersichten, Audit-UI, Einstellungen) | ✅ Abgeschlossen |
| 10 | Security Hardening & Produktivbetrieb | ⏳ Geplant |

## Phase 1 – Grundgerüst (abgeschlossen)

Definition of Done:

- [x] Repository-Struktur
- [x] Docker-Setup (`docker compose up` → Plattform erreichbar)
- [x] Frontend (React, Vite, Tailwind, Design-System-Komponenten)
- [x] Backend (NestJS, REST `/api/v1`, OpenAPI/Swagger)
- [x] PostgreSQL mit persistentem Volume
- [x] Migrationen (eigener Runner mit Advisory-Lock) + Seed (Rollen, Admin)
- [x] Login / Logout (Argon2id, serverseitige Sessions, HttpOnly-Cookies)
- [x] CSRF-Schutz, Rate Limiting, Account Lockout
- [x] User-Modell & Rollen (ADMIN/USER, RBAC-Guards)
- [x] Audit-Log (LOGIN_SUCCESS, LOGIN_FAILED, LOGOUT)
- [x] Health-Endpoint (`/api/v1/health`)
- [x] Admin-Dashboard sichtbar (inkl. Systemstatus)
- [x] Backend-Unit-Tests (Auth, Session, Passwort, Validierung)

## Phase 2 – Benutzerverwaltung (abgeschlossen)

Definition of Done: Admin kann Benutzer vollständig verwalten.

- [x] `GET/POST/PATCH/DELETE /api/v1/users/*` (nur `@Roles('ADMIN')`)
- [x] Benutzerliste, Benutzer anlegen (Zod-Validierung, Duplikat-Schutz 409)
- [x] Benutzer bearbeiten (Anzeigename, E-Mail, Rolle)
- [x] Benutzer deaktivieren/aktivieren (Sessions werden sofort ungültig)
- [x] Passwort-Reset durch Admin (alle Sessions des Benutzers werden gelöscht)
- [x] Schutzregeln: keine Selbst-Deaktivierung/-Löschung, letzter aktiver Admin geschützt
- [x] Profil-Endpunkte (`GET /api/v1/profile`, `PATCH /api/v1/profile/password`)
- [x] Eigenes Passwort ändern (Verifikation des aktuellen Passworts, andere Sessions werden abgemeldet)
- [x] Frontend: Benutzerverwaltungs-Seite (Tabelle, Create/Edit/Reset/Delete-Modals, Toasts)
- [x] Frontend: Profil-Seite mit Passwortänderung
- [x] UI-Komponenten: Modal, Select, Toast (Design-System erweitert)
- [x] Backend-Tests: 49 bestanden (inkl. UsersService, ProfileService)
- [x] E2E verifiziert: CRUD, RBAC (User → 403), Login-Sperre nach Deaktivierung, Passwort-Flows

## Phase 3 – Modul-System (abgeschlossen)

Definition of Done: Modul-Datenmodell, Manifest, Installation, Registrierung, Status, Start/Stop/Restart, Healthcheck.

- [x] `modules`-Tabelle (Migration 002) mit Lifecycle-Status und eindeutigen Ports/Slugs
- [x] Manifest-Vertrag `module.json` (Zod: ID, Name, Version, Slug, Runtime, Entrypoint, Port 41000–41999, Healthcheck, apiVersion)
- [x] ZIP-Installer mit Manifest-Validierung, Größenlimit (10 MB) und **Zip-Slip-Schutz**
- [x] Modul-Prozess-Manager: Start/Stop (SIGTERM→SIGKILL) als Kindprozesse, minimale ENV (keine Plattform-Secrets), eigene Log-Dateien
- [x] Healthcheck-Service mit Startup-Grace (10 Retries × 500 ms)
- [x] Lifecycle: INSTALLED → STARTING → RUNNING → STOPPING → STOPPED, ERROR, DISABLED
- [x] `GET/POST /api/v1/modules`, `POST :id/start|stop|restart`, `PATCH :id/enabled`, `GET :id/health`, `DELETE :id` (nur ADMIN)
- [x] Duplikat-Schutz: Modul-ID, Slug und Port müssen eindeutig sein (409)
- [x] Frontend: Modulverwaltungs-Seite (ZIP-Upload, Tabelle mit Status-Badges, Lifecycle-Buttons, Health-Anzeige, Remove-Dialog)
- [x] Persistente Volumes für Modul-Dateien und Logs (`modules-data`, `module-logs`)
- [x] Demo-Modul (`modules/demo`) als Referenzimplementierung
- [x] Backend-Tests: 72 bestanden (inkl. ModulesService-Lifecycle, Manifest-Validierung, Installer)
- [x] E2E verifiziert: Installation (201), Start → RUNNING, Healthcheck (healthy, 2 ms), Stop, Restart, Disable (stoppt Prozess), Start-Sperre bei Disable (400), Remove, RBAC (USER → 403)

## Phase 4 – Gateway & dynamisches Routing (abgeschlossen)

Definition of Done: Module sind über `/slug` erreichbar, Zugriff nur mit gültiger Session und Berechtigung.

- [x] Nginx-Routing: `/slug/*` → Backend-Gateway (`/api/v1/gateway/slug/*`) mit Ausschluss-Regex für Plattform-Pfade (api, assets, login, …)
- [x] Modul-Gateway als Middleware: Session-Check (401), Slug-Suche (404), Status-Check (503), Permission-Check (403), Proxy zum internen Port
- [x] Sichere Identitätsübergabe über interne Header (`x-user-id`, `x-user-username`, `x-user-display-name`, `x-user-role`); Session-Cookie wird nie an Module weitergereicht
- [x] Fail-closed: USERs erhalten bis Phase 5 grundsätzlich 403
- [x] Startup-Recovery: Nach Container-Neustarts werden veraltete Status zurückgesetzt und aktivierte Module automatisch neu gestartet
- [x] Backend-Tests: 81 bestanden (inkl. 9 Gateway-Tests)
- [x] E2E verifiziert: `/demo` → 200 (Modul-Inhalt), `/demo/health` → 200, unbekanntes Modul → 404, ohne Login → 401, USER → 403, gestopptes Modul → 503

## Phase 5 – Berechtigungssystem (abgeschlossen)

Definition of Done: User ↔ Module-Zuweisung, Access Control, Permission Middleware, 401/403-Handling.

- [x] `user_module_permissions`-Tabelle (Migration 003, GRANTED/DENIED, UNIQUE user+module, CASCADE)
- [x] Admin-API: `GET/POST/DELETE /api/v1/users/:userId/modules(/:moduleId)` (nur ADMIN, auditiert)
- [x] Gateway-Permission-Check an Tabelle angebunden: ADMIN immer, USER nur mit GRANTED (fail-closed)
- [x] `GET /api/v1/profile/modules`: Dashboard-Module (ADMIN: alle aktivierten, USER: nur freigegebene)
- [x] Frontend: Dashboard-Modul-Kacheln ausschließlich nach tatsächlichen Berechtigungen
- [x] Frontend: Berechtigungs-Modal in der Benutzerverwaltung (Freigeben/Entziehen pro Modul)
- [x] Backend-Tests: 90 bestanden (inkl. ModulePermissionsService, Gateway GRANTED-Fall)
- [x] Testszenarien aus Arbeitsplan abgedeckt: Admin → alle Module; User ohne Berechtigung → 403; User mit GRANTED → Proxy weitergeleitet

## Phase 6 – Modul-API (abgeschlossen)

Definition of Done: `GET /health`, `GET /api/manifest`, `GET /api/me` plus zentrale Authentifizierung zwischen Plattform und Modul.

- [x] Verbindlicher Modul-API-Vertrag definiert (health, manifest, me)
- [x] `platform-module-sdk` (CommonJS): `extractIdentity` (Gateway-Header, case-insensitive, Rollen-Validierung), `healthResponse`, `meResponse`
- [x] Identitätsübergabe über interne Header (`x-user-id`, `x-user-username`, `x-user-display-name`, `x-user-role`); Session-Cookie wird nie an Module weitergereicht
- [x] Demo-Modul als Referenzimplementierung des Vertrags
- [x] Backend-Tests: 98 bestanden (inkl. 8 SDK-Tests)
- [x] E2E verifiziert: `/demo/health` → vertragskonform, `/demo/api/manifest` → Manifest, `/demo/api/me` → Identität vom Gateway (admin/ADMIN, Permissions); direkter Aufruf ohne Identität → 401; ohne Login → 401 vom Gateway

## Phase 7 – Referenzmodul Kalender (übersprungen)

Entscheidung: Das Kalender-Modul wird zugunsten der Einbindung bestehender Projekte übersprungen. Das Demo-Modul dient als Referenzimplementierung des Modul-Vertrags.

## Phase 8 – Modul-SDK (abgeschlossen)

Definition of Done: `platform-module-sdk` mit Authentication, Current User, Permissions, API Client, Module Config, Logging, Healthcheck.

- [x] SDK-Paket `packages/platform-module-sdk` (CommonJS, vendor-fähig als Einzeldatei)
- [x] `createModuleServer`: verdrahtet den vollständigen Vertrag (health, manifest, me) + fachliche Routen mit Identitäts-Context
- [x] `extractIdentity`: Gateway-Header (case-insensitive, Rollen-Validierung, 401-Verhalten)
- [x] `loadManifest`: Manifest-Validierung (Pflichtfelder, Runtime, apiVersion)
- [x] `loadModuleConfig`: PORT, NODE_ENV, PLATFORM_INTERNAL_URL, MODULE_SERVICE_TOKEN
- [x] `createLogger`: strukturierte JSON-Logs mit automatischem Schwärzen sensibler Schlüssel
- [x] `createPlatformClient`: interner HTTP-Client zur Plattform (Service-Token vorbereitet)
- [x] Demo-Modul vollständig auf das SDK umgestellt (Vendor-Pattern)
- [x] Backend-Tests: 116 bestanden (inkl. 26 SDK-Tests: Vertrag, Manifest, Config, Logger-Schwärzung, Server-Verhalten)
- [x] E2E verifiziert: SDK-Vertrag über Gateway (health/manifest/me), fachliche Route, 404, 401 ohne Identität

## Phase 9 – Administration (abgeschlossen)

Definition of Done: Modulübersicht, Benutzerverwaltung, Rechteverwaltung, Systemstatus, Audit Log, Einstellungen.

- [x] `system_settings`-Tabelle (Migration 004) mit Whitelist-Schlüsseln
- [x] Settings-API: `GET /api/v1/settings`, `PATCH /api/v1/settings/:key` (nur ADMIN, auditiert SETTINGS_CHANGED)
- [x] Audit-Abfragen: `GET /api/v1/audit` mit Filtern (action, username) und Paginierung (nur ADMIN)
- [x] Erweiterter Systemstatus: `GET /api/v1/system/status` mit Gesamtstatus (HEALTHY/DEGRADED/UNHEALTHY) und allen Modul-Healths
- [x] Frontend: Audit-Log-Seite (Filter, Paginierung), Einstellungen-Seite (Inline-Bearbeitung), Systemstatus-Seite (Gesamtstatus + Komponentenliste)
- [x] Navigation erweitert: Audit-Log, Einstellungen
- [x] E2E verifiziert: Migration 004, Settings setzen/lesen, Audit-Log (92 Einträge, Filter), Systemstatus inkl. Modul-Health, RBAC (USER → 403 auf audit/settings/system)

## Nächste Schritte

- Einbindung bestehender Projekte als Module (ersetzt Phase 7; Infrastruktur steht seit Phase 3–8)
- Phase 10 – Security Hardening: Dependency/Container-Scans, HSTS, Backup/Restore, Pen-Tests