lxe/mpm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
tst-version.20
mpm/docs/PHASES.md

9.6 KiB
Raw Permalink Blame History

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:

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

Phase 2 – Benutzerverwaltung (abgeschlossen)

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

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

  • modules-Tabelle (Migration 002) mit Lifecycle-Status und eindeutigen Ports/Slugs
  • Manifest-Vertrag module.json (Zod: ID, Name, Version, Slug, Runtime, Entrypoint, Port 41000–41999, Healthcheck, apiVersion)
  • ZIP-Installer mit Manifest-Validierung, Größenlimit (10 MB) und Zip-Slip-Schutz
  • Modul-Lifecycle: Compose-Containerstacks pro Modul, Datenbanken als separate Services und persistente Named Volumes
  • Healthcheck-Service mit Startup-Grace (10 Retries × 500 ms)
  • Lifecycle: INSTALLED → STARTING → RUNNING → STOPPING → STOPPED, ERROR, DISABLED
  • GET/POST /api/v1/modules, POST :id/start|stop|restart, PATCH :id/enabled, GET :id/health, DELETE :id (nur ADMIN)
  • Duplikat-Schutz: Modul-ID, Slug und Port müssen eindeutig sein (409)
  • Frontend: Modulverwaltungs-Seite (ZIP-Upload, Tabelle mit Status-Badges, Lifecycle-Buttons, Health-Anzeige, Remove-Dialog)
  • Persistente Volumes für Modul-Dateien und Logs (modules-data, module-logs)
  • Demo-Modul (modules/demo) als Referenzimplementierung
  • Backend-Tests: 72 bestanden (inkl. ModulesService-Lifecycle, Manifest-Validierung, Installer)
  • 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.

  • Nginx-Routing: /slug/* → Backend-Gateway (/api/v1/gateway/slug/*) mit Ausschluss-Regex für Plattform-Pfade (api, assets, login, …)
  • Modul-Gateway als Middleware: Session-Check (401), Slug-Suche (404), Status-Check (503), Permission-Check (403), Proxy zum internen Port
  • 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
  • Fail-closed: USERs erhalten bis Phase 5 grundsätzlich 403
  • Startup-Recovery: Nach Container-Neustarts werden veraltete Status zurückgesetzt und aktivierte Module automatisch neu gestartet
  • Backend-Tests: 81 bestanden (inkl. 9 Gateway-Tests)
  • 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.

  • user_module_permissions-Tabelle (Migration 003, GRANTED/DENIED, UNIQUE user+module, CASCADE)
  • Admin-API: GET/POST/DELETE /api/v1/users/:userId/modules(/:moduleId) (nur ADMIN, auditiert)
  • Gateway-Permission-Check an Tabelle angebunden: ADMIN immer, USER nur mit GRANTED (fail-closed)
  • GET /api/v1/profile/modules: Dashboard-Module (ADMIN: alle aktivierten, USER: nur freigegebene)
  • Frontend: Dashboard-Modul-Kacheln ausschließlich nach tatsächlichen Berechtigungen
  • Frontend: Berechtigungs-Modal in der Benutzerverwaltung (Freigeben/Entziehen pro Modul)
  • Backend-Tests: 90 bestanden (inkl. ModulePermissionsService, Gateway GRANTED-Fall)
  • 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.

  • Verbindlicher Modul-API-Vertrag definiert (health, manifest, me)
  • platform-module-sdk (CommonJS): extractIdentity (Gateway-Header, case-insensitive, Rollen-Validierung), healthResponse, meResponse
  • 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
  • Demo-Modul als Referenzimplementierung des Vertrags
  • Backend-Tests: 98 bestanden (inkl. 8 SDK-Tests)
  • 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.

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

  • system_settings-Tabelle (Migration 004) mit Whitelist-Schlüsseln
  • Settings-API: GET /api/v1/settings, PATCH /api/v1/settings/:key (nur ADMIN, auditiert SETTINGS_CHANGED)
  • Audit-Abfragen: GET /api/v1/audit mit Filtern (action, username) und Paginierung (nur ADMIN)
  • Erweiterter Systemstatus: GET /api/v1/system/status mit Gesamtstatus (HEALTHY/DEGRADED/UNHEALTHY) und allen Modul-Healths
  • Frontend: Audit-Log-Seite (Filter, Paginierung), Einstellungen-Seite (Inline-Bearbeitung), Systemstatus-Seite (Gesamtstatus + Komponentenliste)
  • Navigation erweitert: Audit-Log, Einstellungen
  • 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