IMVS (MintyPHP)

IMVS ist eine mandantenfaehige Admin-Anwendung auf Basis von MintyPHP. Der Fokus liegt auf klarer Rollen-/Rechtestruktur, Tenant-Scope und einer konsistenten Admin-UI.

Funktionsumfang

• Mandantenverwaltung (inkl. Branding/Farbe/Favicon)
• Abteilungen pro Mandant
• Benutzerverwaltung mit Rollen, Sichtbarkeit und Stammdaten
• Rollen- und Berechtigungsverwaltung
• Adressbuch (tenant-scoped, read-only Profilansicht)
• Globale Suche (Admin + Address Book)
• Mail-Versand (SMTP/PHPMailer) inkl. Mail-Log
• Onboarding-PDF fuer Zugangsdaten (Single inline, Bulk als ZIP)
• Passwort-Reset und Remember-Login-Tokens

Tech Stack

• PHP 8.5 (Runtime im Docker-Container)
• MintyPHP Core
• MariaDB 11
• Memcached
• Nginx
• Grid.js (Tabellen)
• PHPMailer
• Dompdf (PDF Rendering)
• endroid/qr-code (QR-Code Rendering)

Schnellstart (Docker)

1. Umgebungsdatei anlegen

cp .env.example .env

2. Container starten

docker compose up --build -d

3. App oeffnen

• App: http://localhost:8080
• phpMyAdmin: http://localhost:8081

4. Container stoppen

docker compose down

Produktion (Docker)

Es gibt eine getrennte Produktions-Compose:

• Dev: /docker-compose.yml
• Prod: /docker-compose.prod.yml

Grundschritte:

1. .env auf Produktionswerte setzen (siehe /.env.prod.example)
2. Domain und TLS in /docker/nginx/prod.conf anpassen
3. Zertifikate unter /docker/nginx/certs/ bereitstellen
4. Starten:

docker compose -f docker-compose.prod.yml up --build -d

Details stehen in:

• /docs/docker-lokal.md
• /docs/docker-produktiv.md
• /docs/docker-betrieb.md (Übersicht)

Seed-Daten

Die Initialisierung liegt in /db/init/init.sql.

Standard-Demo-User:

• E-Mail: demo@user.com
• Passwort: Demo123
• Tenant: Cronus
• Abteilung: IT
• Rolle: Admin

Projektstruktur

• /config Konfiguration (Routen, Settings, Themes, Assets)
• /db/init Datenbankschema + Seeds
• /lib Backend-Code (Repository, Service, Http, Support)
• /pages Action-Layer + Views pro Route
• /templates Layouts + wiederverwendbare Partials
• /web oeffentliche Assets (CSS/JS/Vendor)
• /i18n Uebersetzungen
• /tests PHPUnit-Tests
• /docs Projekt-Dokumentation

Architektur-Kurzregeln

• Keine DB-Zugriffe in .phtml-Views.
• SQL bleibt in Repositories.
• Geschaeftslogik bleibt in Services.
• pages/.../*.php fungiert als Action-/Controller-Schicht.
• Permissions + Tenant-Scope werden in Actions/Services erzwungen.
• Wiederkehrende UI-Bloecke als Partials zentralisieren.

UI-Konventionen

Edit-Seiten verwenden einheitliche Tab-Struktur:

• erster Tab: Master data
• letzter Tab: Visibility
• optional letzter Tab: Danger zone

User-Organisation:

• Departments werden tenantweise angezeigt (ein Multi-Select je ausgewaehltem Tenant).
• Nach Tenant-Aenderungen im selben Formular werden Department-Optionen nach Speichern/Reload aktualisiert (kein Live-Update).

Zentrale Partials:

• /templates/partials/app-details-titlebar.phtml
• /templates/partials/app-visibility-status-field.phtml
• /templates/partials/app-danger-zone-delete-field.phtml
• /templates/partials/app-details-aside-audit.phtml
• /templates/partials/app-details-aside-ids.phtml

Onboarding-PDF (User)

• Permission: users.access_pdf
• Single: admin/users/access-pdf/{uuid} (inline im neuen Tab)
• Bulk: admin/users/access-pdf-bulk (POST, ZIP mit einer PDF pro User)
• Hard limit: maximal 100 User pro Bulk-Request
• Benoetigte Extensions: ext-zip, ext-dom, ext-mbstring
• Bestehende Installationen: Schema-/Permission-Updates als idempotentes SQL-Update ausfuehren

Microsoft SSO (Tenant, Entra ID)

• Zentraler Einstieg: login (optional mit Tenant-Hint login?tenant={tenant-slug})
• OIDC-Endpunkte: auth/microsoft/start und auth/microsoft/callback
• Tenant-Config liegt in tenant_auth_microsoft
• Externe User-Linkung liegt in user_external_identities
• Optionaler Profil-Sync pro Tenant:
  • sync_profile_on_login aktiviert Sync bei jedem Microsoft-Login
  • sync_profile_fields: first_name, last_name, phone, mobile, avatar
  • Default-Felder bei aktivem Sync ohne Auswahl: first_name,last_name
  • phone/mobile/avatar nutzen Microsoft Graph (User.Read)
• Shared App Credentials werden in Settings gepflegt (optional Tenant-Overrides)
• Permission fuer Tenant-SSO-Konfiguration: tenants.sso_manage
• Bestandsinstallationen: Schema-/Permission-Updates als idempotentes SQL-Update ausfuehren
• Wichtig: APP_CRYPTO_KEY in .env setzen, sonst koennen SSO-Secrets nicht gespeichert/verwendet werden

Asset- und Frontend-System

• CSS-Layer-Entrypoint: /web/css/app-layers.css
• Vendor-Overrides: /web/css/vendor-overrides
• Asset-Gruppen: /config/assets.php
• Template-Styles: renderTemplateStyles('default'|'login')
• Seiten-Styles per Action: Buffer::set('style_groups', ...)
• JS-Bootstrap:
  • /web/js/app-boot.js (frueh, ohne Module)
  • /web/js/app-init.js (Standardseiten)
  • /web/js/app-login-init.js (Loginseiten)

Qualitaetschecks

Alle Befehle aus dem Projekt-Root ausfuehren.

PHPUnit

docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php

Gezielt:

docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php tests/I18n/TranslationKeysTest.php
docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php tests/Repository/RepoQueryTest.php

PHPStan

docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress

ESLint (Frontend-JS)

npx eslint web/js

Dokumentation

• /docs/index.md Einstieg und Dokumentationsindex
• /docs/architektur.md Request-Flow und Layering
• /docs/konventionen.md Coding- und UI-Konventionen
• /docs/sicherheitsmodell.md Auth/Permission/Tenant-Scope
• /docs/entwickler-checkliste.md konkrete Checkliste fuer Aenderungen
• /docs/benutzerdefinierte-felder.md Quick Reference fuer Tenant/User-Zusatzfelder
• /docs/api.md API v1 Referenz (inkl. Self-Service Token-Endpunkte)
• /docs/einstellungen-speicherung.md Globale Settings: DB als Quelle, config/settings.php als Teil-Cache
• /docs/frontend-javascript.md Frontend-JS-Struktur
• /docs/frontend-css.md Frontend-CSS-Struktur
• /docs/docker-lokal.md Docker lokal (Entwicklung)
• /docs/docker-produktiv.md Docker produktiv (Serverbetrieb)
• /docs/docker-betrieb.md Dev/Prod Docker-Betrieb

Troubleshooting

• Verhalten wirkt stale nach groesseren Refactors:

docker compose restart php nginx

• Uebersetzungs-Keys fehlen:

docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php tests/I18n/TranslationKeysTest.php

• Favicon/Logo aus Storage fehlt:
  • Symlink und Tenant-Kontext pruefen (web/favicon/tenants -> storage/tenants).

Lizenz

MIT (siehe /LICENSE.md)