Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 3m47s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 3m50s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 4m4s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 4m13s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 5m43s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 5m44s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 4m55s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m14s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 5m1s
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
503 lines
28 KiB
Markdown
503 lines
28 KiB
Markdown
# Inhaus – Projektplan
|
||
|
||
Stand: 2026-09-25 · Status: Entwurf · Produktname: **Inhaus** (Arbeitstitel)
|
||
(technischer Schlüssel beim Hersteller: `mitarbeiterportal`)
|
||
|
||
Ein modulares Mitarbeiterportal (Intranet/CMS) mit an- und abschaltbaren
|
||
Plugins nach WordPress-Prinzip, Anbindung an Identity Provider (Schwerpunkt
|
||
Microsoft Entra ID), feingranularem Berechtigungskonzept, Pagebuilder und
|
||
anpassbarem Design. Kunden hosten selbst – auch auf Shared Webhosting.
|
||
Lizenzpflichtig, mit Self-Updater und Rückmeldeweg zum Hersteller.
|
||
|
||
Mitgeltende Spezifikationen (verbindlich, wörtlich umzusetzen):
|
||
- [`docs/specs/self-updater.md`](specs/self-updater.md) – Self-Updater & Lizenzprüfung
|
||
- [`docs/specs/feedback.md`](specs/feedback.md) – Fehlerbericht & Funktionswunsch
|
||
|
||
---
|
||
|
||
## 1. Rahmenbedingungen & Entscheidungen
|
||
|
||
| Thema | Entscheidung |
|
||
|---|---|
|
||
| Betriebsmodell | **Eigene Installation pro Kunde**, vom Kunden selbst gehostet |
|
||
| Hosting-Ziel | **Muss auf Shared Webhosting laufen** (Apache, PHP, MySQL – ohne Shell, Node, Docker, Redis) |
|
||
| Größe | **10 bis 5.000 Mitarbeitende** pro Instanz → Performance ist Kernanforderung |
|
||
| Sprache/Framework | **PHP ≥ 8.3 + Laravel** |
|
||
| Datenbank | **MySQL ≥ 8.0 und MariaDB ≥ 10.6** |
|
||
| Webserver | **Apache** (mod_rewrite, `.htaccess`), PHP-FPM oder mod_php |
|
||
| Lizenz | **Lizenzpflichtig** – Lizenz-E-Mail + Schlüssel + Gerätekennung; Lizenzfehler blockieren **nur** Updates |
|
||
| Updates | **Self-Updater** gegen `update.loheide.cloud` (Branch-Stand per Commit-SHA, Kanäle stable/development) |
|
||
| Rückmeldungen | Fehlerbericht & Funktionswunsch an `api.loheide.cloud`, mit Lizenzzuordnung |
|
||
| Plugins | **WordPress-Prinzip**: ZIP hochladen, aktivieren, Hooks/Filter |
|
||
| Wichtigster IdP | **Microsoft Entra ID** |
|
||
| Admin-Backend | **Filament** – nur für Administratoren |
|
||
| Portal-Frontend | **Inertia + Vue 3 + Tailwind CSS + shadcn-vue (reka-ui) + Lucide-Icons**, vorkompiliert ausgeliefert |
|
||
| Design | Nüchtern-professionell (Vorbild: moderne Intranets wie MeinMagenta/Viva Connections): neutrale Flächen, Markenfarbe nur als Akzent, Schrift Inter (lokal) – **kein Material 3** (entschieden 2026-09-25, wirkte verspielt) |
|
||
| Redaktion | Direkt im Portal (Inline-Bearbeitung/Pagebuilder) |
|
||
| Später | Push-Benachrichtigungen, native App (Architektur jetzt schon API-fähig halten) |
|
||
|
||
---
|
||
|
||
## 2. Hosting & Auslieferung (Shared-Hosting-tauglich)
|
||
|
||
Grundsatz: **Auf dem Server des Kunden wird nichts gebaut und nichts per Shell
|
||
ausgeführt.**
|
||
|
||
- **Das Repo ist das Release.** Der Update-Proxy liefert den Branch-Stand als
|
||
ZIP – deshalb werden **kompilierte Frontend-Assets und PHP-Abhängigkeiten
|
||
mitversioniert** (siehe 5.2 zu `vendor/`).
|
||
- **Erstinstallation:** ZIP (vom Kundenportal/Proxy) hochladen → **Web-Installer**
|
||
(Systemprüfung, DB-Zugang, Admin-Konto, Lizenzdaten, Basis-Branding).
|
||
- **Document Root:** Wenn der Hoster kein Umbiegen auf `public/` erlaubt,
|
||
leitet eine Root-`.htaccess` auf `public/` um und sperrt alle anderen
|
||
Verzeichnisse.
|
||
- **Hintergrundjobs ohne Worker:**
|
||
- bevorzugt Cron `* * * * *` → `schedule:run` + Queue mit Zeitlimit
|
||
(`queue:work --stop-when-empty --max-time=50`),
|
||
- Fallback **Web-Cron** (URL mit Token für externen Cron-Dienst),
|
||
- letzter Fallback **Pseudo-Cron** (wie WP-Cron) nach Auslieferung der Antwort.
|
||
- Jobs in kleinen, wiederaufnehmbaren Häppchen.
|
||
- **Treiber mit Fallbacks:** Cache/Session/Queue über Datenbank oder Dateien;
|
||
APCu/Redis wenn vorhanden. Bilder über GD, Imagick optional. Dateien lokal,
|
||
optional S3-kompatibel.
|
||
- Für Kunden mit eigenem Server zusätzlich: Docker-Image und Anleitung.
|
||
- **Site Health** im Admin: PHP-Version/Extensions, OPcache, Schreibrechte,
|
||
Cron-Status, ausstehende Migrationen, Lizenzstatus.
|
||
|
||
---
|
||
|
||
## 3. Architektur
|
||
|
||
```
|
||
app/ (Core) Auth, User, Profil, Rollen & Rechte, Einstellungen,
|
||
Theming, Plugin-Loader, Hooks, Erweiterungspunkte,
|
||
Audit-Log, Self-Updater, Lizenz, Rückmeldungen, Site Health
|
||
plugins-core/<slug>/ Mitgelieferte Plugins (News, Seiten, Verzeichnis, …) –
|
||
Teil des Repos, kommen per Self-Updater
|
||
plugins/<slug>/ Vom Kunden installierte Plugins – **geschützter Pfad**,
|
||
wird vom Self-Updater nie angefasst
|
||
```
|
||
|
||
- **Eigene Module sind Plugins** und nutzen dieselbe API wie Kunden-Plugins.
|
||
- Fachlogik in Actions/Services, nicht in Controllern → später wiederverwendbar
|
||
für REST-API und native App.
|
||
|
||
Oberflächen:
|
||
- **Portal** (Vue, Tailwind/shadcn-vue): Mitarbeitende und Redakteure.
|
||
Zweizeiliger Header (Logo, Suche, Avatar-Menü; darunter Hauptnavigation),
|
||
Startseite als Raster aus Kacheln (Schnellzugriffe, Begrüßung, News …).
|
||
- **Admin** (Filament): Plugins, Rollen & Rechte, Identity Provider,
|
||
Gruppen-Mapping, Theme, Benutzer, Audit-Log, **Aktualisierung & Lizenz**,
|
||
**Rückmeldung geben**, Site Health.
|
||
|
||
---
|
||
|
||
## 4. Plugin-System (WordPress-Prinzip)
|
||
|
||
### 4.1 Aus Sicht des Admins
|
||
|
||
- Plugin-ZIP im Admin **hochladen**, **aktivieren / deaktivieren / löschen**.
|
||
- **Wiederherstellungsmodus:** Fatal Error beim Laden → Plugin wird automatisch
|
||
deaktiviert, Admin wird informiert, Portal bleibt erreichbar.
|
||
- Datei-Änderungen über den Admin per Konfiguration abschaltbar
|
||
(analog `DISALLOW_FILE_MODS`).
|
||
- Updates von Kunden-Plugins: ✅ über `update_url` im Manifest (Forgejo/Gitea/GitHub-Releases
|
||
oder eigenes JSON, siehe docs/PLUGINS.md); für eigene, lizenzpflichtige Plugins kann
|
||
dasselbe Proxy-Modell wie beim Core genutzt werden (offen).
|
||
|
||
### 4.2 Aufbau eines Plugins
|
||
|
||
```
|
||
plugins/mav-kalender/
|
||
plugin.json Name, Slug, Version, Autor, Beschreibung,
|
||
requires.core, requires.php, requires.plugins,
|
||
update_url, Einstiegsklasse
|
||
src/ PHP-Code (PSR-4, Autoload registriert der Core)
|
||
src/Plugin.php extends BasePlugin:
|
||
register(), boot(), activate(), deactivate(), uninstall()
|
||
vendor/ eigene Abhängigkeiten – gescoped (Strauss/PHP-Scoper)
|
||
database/migrations/ laufen bei Aktivierung/Update
|
||
resources/lang/ Übersetzungen
|
||
dist/ vorkompilierte JS/CSS-Module (kein Build beim Kunden)
|
||
```
|
||
|
||
### 4.3 Hooks & Erweiterungspunkte
|
||
|
||
- **Actions:** `Hooks::on('post.published', fn($post) => …)`
|
||
- **Filter:** `Hooks::filter('navigation.items', fn($items) => …)`
|
||
- Prioritäten wie bei WordPress, intern auf Laravel-Events aufgebaut.
|
||
- **Typisierte Registries:** Navigation, Dashboard-Widgets, Profil-Tabs,
|
||
Profilfelder, Pagebuilder-Blöcke, Objekttypen & Abilities,
|
||
Einstellungsseiten, Admin-Ressourcen, Routen, Suche, Benachrichtigungen,
|
||
geplante Jobs.
|
||
- Stabile, versionierte Plugin-API (SemVer); Deprecations mit Vorlauf.
|
||
- Entwickleranleitung: [`docs/PLUGINS.md`](PLUGINS.md).
|
||
|
||
### 4.4 Frontend von Plugins
|
||
|
||
- Portal stellt **Vue, reka-ui und das Portal-UI-Kit (shadcn-vue-Komponenten) per Import Map** bereit;
|
||
Plugin-Styles nutzen die Design-Tokens (CSS-Variablen) des Portals.
|
||
- Plugins werden beim Entwickler mit `@portal/plugin-sdk` (Vite-Preset) gebaut;
|
||
Vue & Co. sind „external“.
|
||
- Der Core lädt die ES-Module aktiver Plugins lazy zur Laufzeit.
|
||
|
||
### 4.5 Sicherheit & Tooling
|
||
|
||
- Plugins laufen mit vollen Rechten; Installation nur mit `plugins.manage`.
|
||
- **Kein Plugin-Verzeichnis/Store** (entschieden 2026-09-25): Plugins werden
|
||
ausschließlich per ZIP-Upload installiert. Warnhinweis vor der Installation,
|
||
dass Plugins vollen Zugriff auf das System haben.
|
||
- Später „Remote Apps“ (Webhooks + API + iFrame-Widgets).
|
||
- Plugin-Generator, Doku, Beispiel-Plugins, lokale Dev-Umgebung.
|
||
|
||
---
|
||
|
||
## 5. Self-Updater & Lizenz
|
||
|
||
Verbindlich: [`docs/specs/self-updater.md`](specs/self-updater.md).
|
||
Hier nur die Übertragung auf Laravel und projektspezifische Entscheidungen.
|
||
|
||
### 5.1 Komponenten (Laravel)
|
||
|
||
| Spezifikation | Umsetzung |
|
||
|---|---|
|
||
| Version-Helper | `App\Support\Update\InstalledVersion` – SHA in `storage/.version`, `App\Version::VERSION` (SemVer-Konstante) |
|
||
| Fortschritts-Datei | `App\Support\Update\UpdateProgress` → `storage/.update-progress` |
|
||
| Wartungsmodus | `App\Support\Update\MaintenanceFlag` → `storage/.maintenance` (selbstheilend) – **eigener** Mechanismus, nicht `php artisan down`, damit ohne Shell und DB funktionsfähig |
|
||
| Updater-Kern | `App\Support\Update\Updater::installUpdate()` – Laravel HTTP-Client (Guzzle) mit `sink` für den ZIP-Stream, nur HTTPS, begrenzte Redirects, 180 s für ZIP |
|
||
| Entpacken | `ZipArchive`, zweistufiger ZIP-Slip-Schutz, Staging in `storage/.update-staging` |
|
||
| Übernehmen | Datei für Datei: temporär daneben schreiben → `rename()`; nur überschreiben/ergänzen, nie löschen |
|
||
| Migrationen | `Artisan::call('migrate', ['--force' => true])` im Prozess, Zähler über Migrator-Repository |
|
||
| Caches | `optimize:clear` + `opcache_reset()` (falls verfügbar), danach `config:cache`/`route:cache` neu |
|
||
| Kanal-Factory | `UpdaterFactory::for(?string $channel)` – Kanäle in `config/updater.php`, aktiver Kanal in App-Einstellungen (DB, Fallback Datei) |
|
||
| Auto-Migration | Middleware `RunPendingMigrations` – Fingerabdruck über Migrationsdateien (Core + aktive Plugins), `Cache::lock()` bzw. Lock-Datei, Fehler nur loggen |
|
||
| Wartungs-Middleware | `EnsureNotInMaintenance` – 503 + `Retry-After`, Ausnahmen: `/admin/update/*`, Login, `/up` (Health) |
|
||
| Lizenz-Speicher | `App\Support\License\LicenseStore` – E-Mail & Schlüssel (verschlüsselt), `device_id`, `device_token` in `storage/app/license.json` (außerhalb der DB, überlebt DB-Probleme) |
|
||
| Lizenz-Client | Guzzle-Middleware, die **jede** Antwort (auch Fehler, auch Downloads) sofort auf `X-Device-Token`/`device_token` prüft und speichert, bevor irgendetwas anderes passiert |
|
||
| Admin-UI | Filament-Seite „Aktualisierung“ (Version, Kanal, Suche, Changelog-Vorschau, Fortschritt per Polling, Migrationen, Changelog-Historie, Lizenzbereich, Datenschutzhinweis) |
|
||
| Endpunkte | `POST /admin/update/check`, `POST /admin/update/install`, `GET /admin/update/progress`, `POST /admin/update/channel`, `POST /admin/update/migrations` – Admin-only, CSRF |
|
||
| Markdown | `league/commonmark` mit `html_input: strip`, `allow_unsafe_links: false` |
|
||
| Audit | Audit-Log-Eintrag je Lauf: Kanal, Ziel-SHA, Anzahl Migrationen, Benutzer, Ergebnis |
|
||
|
||
- `hostname` = `gethostname()`, `device_label` = `hostname:base_path()`.
|
||
- Gerät abmelden: Button „Diese Installation abmelden“ im Lizenzbereich
|
||
(`POST …/license/release-device`).
|
||
- **Grundregel:** Lizenzfehler erzeugen nur Hinweise im Admin und Log-Einträge.
|
||
Keine Middleware, kein Feature hängt vom Lizenzstatus ab.
|
||
- Datenschutzhinweis **wörtlich** unter „Nach Updates suchen“; Zeilen für nicht
|
||
gesendete Felder streichen (z. B. Betriebssystem/Programmversion, falls
|
||
nicht übertragen – bei Umsetzung abgleichen). Verweis auf die im Portal
|
||
hinterlegte Datenschutzerklärung, falls gesetzt.
|
||
|
||
### 5.2 Projektspezifische Entscheidungen
|
||
|
||
- **`vendor/` – bewusste Abweichung (entschieden 2026-09-25):** Die
|
||
Spezifikation führt `vendor/` als geschützten Pfad. Auf Shared Hosting ohne
|
||
Shell kann aber kein `composer install` laufen – neue PHP-Abhängigkeiten kämen
|
||
dann nie beim Kunden an. Daher wird `vendor/` **mitversioniert** (nur
|
||
`--no-dev`) und **nicht** geschützt, analog zu den kompilierten Assets.
|
||
`composer.lock` bleibt geschützt.
|
||
Da nur überschrieben, nie gelöscht wird, bleiben alte Pakete liegen –
|
||
unschön, aber harmlos (Autoloader kennt sie nicht mehr).
|
||
- **Geschützte Pfade** (Erweiterung der Mindestliste): `.env`, `.git/`,
|
||
`storage/`, `node_modules/`, `composer.lock`, `package-lock.json`,
|
||
`plugins/` (Kunden-Plugins), `public/storage`, `public/uploads/`,
|
||
`config/local.php`, `.htaccess` im Root (falls vom Kunden angepasst →
|
||
als `.htaccess.dist` ausliefern).
|
||
- **Kanäle** (bestätigt): `stable` → Branch `main`, `development` → Branch
|
||
`develop`.
|
||
- **Rollout Lizenzpflicht:** Da es noch keine Installationen gibt, kann die
|
||
erste Version direkt mit Lizenzdaten ausgeliefert werden; die Stufen
|
||
„nur protokollieren“ → „durchsetzen“ trotzdem wie beschrieben nutzen.
|
||
|
||
### 5.3 Versionierung & Changelog
|
||
|
||
- `CHANGELOG.md` im Repo-Root, neueste Version oben, Abschnitte
|
||
`## MAJOR.MINOR.PATCH`, kurze deutsche Stichpunkte.
|
||
- `App\Version::VERSION` (SemVer).
|
||
- Ablauf für **jede** Änderung (in `CONTRIBUTING.md` dokumentiert):
|
||
1. `CHANGELOG.md` ergänzen
|
||
2. `VERSION` anheben (Patch = Fix, Minor = Funktion)
|
||
3. Tests grün, `bin/build` (Frontend-Build + `composer install --no-dev`) →
|
||
Assets und `vendor/` mitcommitten. Entwicklungspakete liegen getrennt in
|
||
`vendor-dev/` (siehe `CONTRIBUTING.md`)
|
||
4. Merge in den ausgelieferten Branch
|
||
- CI prüft: CHANGELOG-Abschnitt passt zu `VERSION`, Build-Artefakte sind aktuell.
|
||
|
||
---
|
||
|
||
## 6. Rückmeldungen an den Hersteller
|
||
|
||
Verbindlich: [`docs/specs/feedback.md`](specs/feedback.md).
|
||
|
||
- **Ort:** Im Admin-Backend (Filament) ein Menüpunkt **„Hilfe → Rückmeldung
|
||
geben“** in der Navigation und im Benutzermenü → Dialog (≤ 2 Klicks).
|
||
Optional später auch für Redakteure im Portal.
|
||
- **Freigeschaltete Wege** via `GET https://api.loheide.cloud/v1/software`
|
||
(Feld `endpoints`), gecacht; 404 auf einen Weg → dauerhaft ausblenden
|
||
(in App-Einstellungen gemerkt). Aktuell: Fehlerbericht, Funktionswunsch.
|
||
- **Automatisch befüllt & im Dialog aufklappbar sichtbar:**
|
||
`app_version` (= `App\Version::VERSION`), `current_sha`,
|
||
`os` (Server-Betriebssystem, z. B. „Linux 6.8 (Debian 12)“),
|
||
`metadata`: PHP-Version, DB-Typ/-Version, Webserver, aktiver Update-Kanal,
|
||
Anzahl aktiver Plugins + deren Slugs/Versionen, Cache-/Queue-Treiber.
|
||
**Keine** personenbezogenen Daten, keine Pfade mit Benutzernamen, keine Inhalte.
|
||
- **Lizenz-Kopfzeilen** aus dem `LicenseStore` – nur wenn Lizenz hinterlegt,
|
||
nie leere Werte; keine Vorabprüfung der Lizenz. Rückmeldeadresse ist ein
|
||
eigenes, freiwilliges Feld (vorbelegt mit der E-Mail des Admins, änderbar).
|
||
- **Warteschlange:** Tabelle `vendor_feedback_outbox` (Payload, Art,
|
||
`idempotency_key`, Versuche, nächster Versuch, Status, Referenz). Absenden
|
||
bestätigt sofort, der Versand läuft als Queue-Job (Cron/Pseudo-Cron).
|
||
Max. 5 Versuche, dann verwerfen + Admin-Benachrichtigung. 409 → kurz warten,
|
||
erneut; 429 → `Retry-After`; 503/Netzfehler → später erneut; 422 → zurück an
|
||
das Formular (Eingabe bleibt erhalten).
|
||
- **Referenznummer** wird angezeigt und in einer Liste „Meine Rückmeldungen“
|
||
gespeichert.
|
||
- **Rotierendes Gerätetoken** auch hier über denselben Lizenz-Client
|
||
speichern; mehrere Meldungen nacheinander senden.
|
||
- **Datenschutzhinweis wörtlich über dem Absendeknopf.** Anhänge sind zunächst
|
||
nicht vorgesehen → Zeile „die von Ihnen angehängten Dateien“ entfällt; der
|
||
„Bitte beachten“-Absatz wird bei der Umsetzung entsprechend auf die
|
||
tatsächlich gesendeten Inhalte abgeglichen.
|
||
|
||
---
|
||
|
||
## 7. Berechtigungskonzept
|
||
|
||
### 7.1 Drei Ebenen
|
||
|
||
| Ebene | Beispiel |
|
||
|---|---|
|
||
| **Globale Rechte** | „Plugins verwalten“, „Benutzer verwalten“, „Aktualisieren“ |
|
||
| **Objekt-Rechte (Grants)** | „Rolle MAV darf Seite /mav inkl. Unterseiten bearbeiten“ |
|
||
| **Sichtbarkeit (Zielgruppen)** | „Seite nur für Standort Hamburg sichtbar“ |
|
||
|
||
### 7.2 Datenmodell (vereinfacht)
|
||
|
||
```
|
||
roles id, name, description, is_system
|
||
role_user user_id, role_id, source, source_ref, created_at
|
||
source = manual | idp
|
||
source_ref = z. B. identity_provider_id + Gruppen-Objekt-ID
|
||
grants role_id, ability, resource_type, resource_id (NULL = alle),
|
||
include_children
|
||
audiences resource_type, resource_id, rule (Rolle / Abteilung / Standort / …)
|
||
```
|
||
|
||
- Abilities je Objekttyp: `view`, `create`, `edit`, `publish`, `delete`,
|
||
`manage_permissions`. Plugins registrieren eigene Objekttypen und Abilities.
|
||
- Prüfung zentral über Laravel Policies + Grant-Resolver.
|
||
- **Rollen sind additiv** (manuell + IdP), keine „Verbots“-Rechte.
|
||
|
||
### 7.3 Beispiel MAV
|
||
|
||
- Rolle **MAV** – Mitglieder manuell oder über Entra-Gruppe.
|
||
- `page.edit`, `page.publish` auf Seite „MAV“ inkl. Unterseiten.
|
||
- `post.create`, `post.publish` in Kategorie „MAV-Info“.
|
||
|
||
### 7.4 Admin-UI
|
||
|
||
- Rollen-Editor, Tab „Berechtigungen“ an Seite/Kategorie, **Rechte-Prüfer**,
|
||
optionaler Freigabe-Workflow, Audit-Log.
|
||
|
||
---
|
||
|
||
## 8. Identity Provider & Gruppen-Mapping
|
||
|
||
### 8.1 Anbieter
|
||
|
||
1. **Microsoft Entra ID** (OIDC) – Priorität 1
|
||
2. Lokaler Login mit 2FA (TOTP) – immer verfügbar für Notfall-Admin
|
||
3. Generisch OIDC, LDAP/AD, SAML 2 – als Plugins (`plugins-core/oidc|ldap|saml`) auf
|
||
`App\Identity\IdentityDriver` ✅
|
||
|
||
### 8.2 Gruppen → Rollen
|
||
|
||
- Je IdP Mapping-Tabelle: **IdP-Gruppe → eine oder mehrere Rollen**;
|
||
optionale Standardrolle.
|
||
- **Additiv**; Sync gleicht **nur IdP-Zuweisungen** ab, **manuelle
|
||
Zuweisungen werden nie verändert**.
|
||
|
||
### 8.3 Entra-spezifisch
|
||
|
||
- Sicherheitsgruppen (`groups`) und App-Rollen (`roles`) mappbar, über
|
||
**Objekt-ID**; Gruppensuche per Graph.
|
||
- Group-Overage → Graph `/me/transitiveMemberOf` (inkl. verschachtelter Gruppen).
|
||
- Profil-Sync inkl. **Profilfoto** → Avatar im Header; jedes Graph-Attribut (auch
|
||
`employeeOrgData.*`, `onPremisesExtensionAttributes.*`, `extension_…`) frei
|
||
einem Kern- oder eigenen Profilfeld zuordenbar.
|
||
- Hintergrund-Sync mit **Delta-Abfragen**, Offboarding deaktivierter Konten.
|
||
- JIT-Provisioning, „Mapping testen“.
|
||
|
||
### 8.4 Datenmodell
|
||
|
||
```
|
||
identity_providers id, type, name, config (verschlüsselt), enabled
|
||
user_identities user_id, identity_provider_id, subject (oid), last_login_at
|
||
idp_group_mappings identity_provider_id, external_group_id,
|
||
external_group_name, role_id
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Performance (10 – 5.000 Mitarbeitende, Shared Hosting)
|
||
|
||
Ziel: Portal-Seiten **< 200 ms Serverzeit** bei 5.000 Usern.
|
||
|
||
- Effektive Rechte pro User **vorberechnet und gecacht**; Zielgruppen als
|
||
indizierte SQL-Bedingungen.
|
||
- Pagebuilder-JSON beim Veröffentlichen in vorbereitete Render-Struktur
|
||
übersetzt und gecacht; dynamische Blöcke mit kurzem Cache.
|
||
- Cursor-Pagination, Indizes, `preventLazyLoading()` in Dev/CI.
|
||
- Gehashte Assets mit langen Cache-Headern; Bilder beim Upload in feste
|
||
Größen + WebP.
|
||
- OPcache voraussetzen; Config/Route/View-Cache nach jedem Update.
|
||
- **Auto-Migration prüft nur den Fingerabdruck** – kein Migrator pro Request.
|
||
- Seed-Datensatz (5.000 MA, 2.000 Seiten, 20.000 Beiträge), k6-Lasttests in CI.
|
||
|
||
---
|
||
|
||
## 10. Profil & Portal-Frontend
|
||
|
||
- Header: Logo, Navigation, Suche, Benachrichtigungen, **Avatar** mit Menü.
|
||
- Avatar aus Entra oder Upload; Fallback Initialen.
|
||
- Profil mit frei definierbaren Feldern und Sichtbarkeit pro Feld.
|
||
- Organisationsstruktur als Basis für Zielgruppen. Mobile-first, PWA-fähig.
|
||
|
||
---
|
||
|
||
## 11. Pagebuilder
|
||
|
||
- Seite = **Baum aus Blöcken** (versioniertes JSON), registrierte Blöcke,
|
||
gleicher Renderer für Editor und Frontend.
|
||
- **Layout:** Abschnitt, **Spalten (1–4, Verhältnisse, Umbruchpunkt)**,
|
||
**Tabs**, **Akkordeon**, **Boxen** (Info/Hinweis/Warnung/Erfolg/neutral/
|
||
hervorgehoben), Raster – beliebig verschachtelbar.
|
||
- **Inhalt:** Rich Text (TipTap), Überschrift, Zitat, Liste, Tabelle, Bild,
|
||
Galerie, Video, Embed, Buttons, Trenner, Abstand, Icon-Liste, Hero,
|
||
Downloads.
|
||
- **Dynamisch:** Ansprechpartner, News-Liste, Events, App-Kacheln, Geburtstage.
|
||
- **Editor:** Drag & Drop, Vorschau Desktop/Tablet/Mobil, Entwürfe, Versionen,
|
||
Zeitsteuerung, Vorlagen, wiederverwendbare Blöcke, Sichtbarkeit pro Block,
|
||
Bearbeitungssperre.
|
||
|
||
---
|
||
|
||
## 12. Branding & Theming
|
||
|
||
Jede Installation soll wie das **eigene Portal des Kunden** aussehen – ohne
|
||
Entwickler, ohne Build, direkt im Admin unter „Erscheinungsbild“.
|
||
|
||
### 12.1 Was der Kunde anpassen kann
|
||
|
||
**Identität**
|
||
- Portalname (z. B. „Caritas-Netz“ statt „Inhaus“) – erscheint in Header,
|
||
Browser-Tab, E-Mails, PWA
|
||
- **Logo** – getrennt für hellen und dunklen Hintergrund, optional
|
||
quadratisches Signet für kleine Bildschirme
|
||
- Favicon und **App-Icon** (PWA/Homescreen), automatisch in alle Größen
|
||
umgerechnet
|
||
- Login-Seite: Hintergrundbild, Begrüßungstext, Logo-Position
|
||
|
||
**Farben**
|
||
- **Markenfarbe** (Pflicht) → wird **exakt** übernommen (Buttons, aktive
|
||
Navigation, Links, Begrüßungskarte); daraus werden die Abstufungen 50–950
|
||
im OKLCH-Farbraum berechnet (serverseitig, `App\Support\ColorPalette`)
|
||
- Flächen bleiben neutral (weiß/grau) – die Markenfarbe ist Akzent, kein Anstrich
|
||
- optional eine zweite Akzentfarbe
|
||
- Header-Stil: farbig (Primärfarbe), hell oder dunkel
|
||
- **Kontrastprüfung (WCAG AA):** Warnung, wenn Text auf Farben schlecht lesbar
|
||
wird – blockiert nicht, schlägt aber eine Korrektur vor
|
||
|
||
**Typografie & Form**
|
||
- Schriftart: Auswahl gängiger Schriften oder **eigene Schrift hochladen**
|
||
(WOFF2) – immer lokal ausgeliefert, **nie von Google Fonts o. ä. geladen**
|
||
(DSGVO)
|
||
- Eckenradius (eckig ↔ rund), Dichte (kompakt ↔ luftig)
|
||
- Dark Mode: erlaubt / Standard hell / Standard dunkel / Systemeinstellung
|
||
|
||
**Weiteres**
|
||
- E-Mail-Vorlagen im gleichen Branding (Logo, Farbe, Fußzeile)
|
||
- **Admin-Backend** übernimmt Logo und Primärfarbe (Filament unterstützt das)
|
||
- Fußzeile: Links zu Impressum, Datenschutz, eigenen Seiten
|
||
- **White-Label** (entschieden 2026-09-25): „Inhaus“ lässt sich vollständig
|
||
ausblenden – Portal, Login, E-Mails, Admin-Backend, PWA, Browser-Tab. Kein
|
||
Pflicht-„Powered by“. Hersteller-Bezüge bleiben nur dort, wo sie sachlich
|
||
nötig sind (Seite „Aktualisierung“, Lizenz, Rückmeldungen, Datenschutzhinweise).
|
||
- Für Fortgeschrittene: **eigenes CSS** (mit Warnhinweis, pro Update
|
||
unverändert übernommen, weil in der DB gespeichert)
|
||
|
||
### 12.2 Bedienung
|
||
|
||
- **Live-Vorschau** neben den Einstellungen: Portal-Startseite, Login,
|
||
Beispielseite mit Boxen/Tabs/Akkordeon, hell und dunkel
|
||
- **Entwurf → Veröffentlichen**: Änderungen erst ansehen, dann für alle
|
||
freischalten; „Auf Standard zurücksetzen“
|
||
- Export/Import des Themes als Datei (z. B. von Test- auf Produktivsystem)
|
||
|
||
### 12.3 Technik
|
||
|
||
- Einstellungen in der DB, Logos/Schriften in `storage/` (geschützter Pfad –
|
||
überleben jedes Update)
|
||
- Beim Veröffentlichen wird **eine statische CSS-Datei mit CSS-Variablen**
|
||
erzeugt (Hash im Dateinamen, lange Cache-Header) – kein Build, keine
|
||
Laufzeitkosten pro Request
|
||
- Farbberechnung in PHP (`App\Support\ColorPalette`); die Werte werden als
|
||
CSS-Variablen (`--brand`, `--brand-50` … `--brand-950`) in die Seite geschrieben –
|
||
keine Farbberechnung im Browser
|
||
- Portal-Tokens (Tailwind), Filament-Farben, E-Mail-Vorlagen und Pagebuilder-Boxen lesen
|
||
alle **dieselben Tokens** → ein Farbwechsel wirkt überall
|
||
- Später: **Theme-Pakete** als Plugins (eigene Layouts, Header-Varianten)
|
||
|
||
---
|
||
|
||
## 13. Mitgelieferte Plugins
|
||
|
||
**Start:** Dashboard, News/Feed mit Kategorien, CMS-Seiten, Formulare,
|
||
WordPress-Import, Verzeichnis & Organigramm, Downloads, QM-Dokumente (eigenes Modul), App-Launcher.
|
||
|
||
**Später:** Events, Umfragen, Geburtstage/Jubiläen, Onboarding, Raumbuchung,
|
||
Kantinenplan, Ideenbox, Urlaubsanträge.
|
||
|
||
---
|
||
|
||
## 14. Querschnitt
|
||
|
||
- **DSGVO & Mitbestimmung:** keine personenbezogene Nutzungsauswertung,
|
||
Audit-Log für Admin-Aktionen, Löschkonzept, Datenexport; Datenschutzhinweise
|
||
für Update-Prüfung und Rückmeldungen gemäß Spezifikationen.
|
||
- Mehrsprachigkeit DE/EN; UI-Texte mit echten Umlauten, Schlüssel/Routen ASCII.
|
||
- Tests: PHPUnit (Pest scheidet aus, weil es fest `vendor/autoload.php` lädt –
|
||
dort liegen nur die Produktionspakete), Vitest, Playwright, k6.
|
||
- CI-Matrix: PHP 8.3/8.4 × MySQL 8.0/8.4 × MariaDB 10.6/11.
|
||
|
||
---
|
||
|
||
## 15. Phasen
|
||
|
||
| Phase | Inhalt |
|
||
|---|---|
|
||
| **0 – Fundament** ✅ | Laravel-Skeleton, Docker-Dev, CI-Matrix, `VERSION` + `CHANGELOG.md` + Build-Workflow (Assets/`vendor` mitversioniert), lokaler Login, User & Profil, Header mit Avatar, Design-System (Tailwind/shadcn-vue) mit Design-Tokens, **Basis-Branding (Portalname, Logo, Markenfarbe)**, Personenverzeichnis, Schnellzugriffe, Filament-Grundgerüst |
|
||
| **0b – News & Termine (vorgezogen)** ✅ | Neuigkeiten mit Kategorien, Titelbild, Planung, Hervorhebung (Slider); Termine mit .ics-Export; Startseite nach Intranet-Vorbild. Redaktion vorerst nur im Admin-Backend – Rechte pro Kategorie, Redaktion im Portal und Umzug in Plugins folgen mit Phase 2 |
|
||
| **1 – Betrieb & Lizenz** ✅ | **Self-Updater** (inkl. Wartungsmodus, Auto-Migration, Kanäle), **Lizenz-Speicher & -Client** (rotierendes Token), Seite „Aktualisierung“, **Rückmeldungen**, Web-Installer, Site Health, Cron-Varianten |
|
||
| **2 – Plugin-System & Rechte** ✅ | Plugin-Loader, Hooks/Filter, Registries, Recovery-Modus, Import-Map-Frontend; Rollen, Grants, Zielgruppen, Rechte-Cache, Rechte-Prüfer |
|
||
| **3 – Entra ID** ✅ | OIDC-Login, JIT, Gruppen-/App-Rollen-Mapping (additiv), Graph-Profil- & Foto-Sync mit frei zuordenbaren Attributen (inkl. Erweiterungsattributen) und eigenen Profilfeldern, Delta-Sync |
|
||
| **4 – CMS** ✅ | Seitenbaum, Pagebuilder (Layout-, Inhalts-, Medien- und dynamische Blöcke, Sichtbarkeit je Block), Entwürfe, Versionen, Zeitsteuerung, Bearbeitungssperre, Freigaben; News-Freigabe-Workflow und Redaktion im Portal; Benachrichtigungen; Seitenvorlagen und wiederverwendbare Bausteine mit Verwendungsnachweis |
|
||
| **4b – Formulare & Umstieg** ✅ | Formular-Plugin (visueller Baukasten im Portal, Bedingungen, Uploads, anonyme Formulare, Mail + Backend, Ergebnis-Rechte je Formular und Rolle, CSV, Löschfristen; eingebunden per Pagebuilder-Block und unter Beiträgen, kein eigener Menüpunkt); WordPress-Import (Beiträge, Kategorien, Bilder, Seiten); E-Mail-Versand im Admin; anpassbare Startseite mit eigenen Kacheln; Geburtstage (optionales Plugin) |
|
||
| **5 – Branding & Theming** ✅ | Vollständige Seite „Erscheinungsbild“: Logo-Varianten, Farben inkl. Farbtreue & Kontrastprüfung, Schriften, Form, Login-Seite, E-Mails, Live-Vorschau, Entwurf/Veröffentlichen, Export/Import |
|
||
| **6 – Weitere Plugins & IdPs** ✅ | ✅ Organigramm (aus Vorgesetzten, im Admin pflegbar), ✅ Downloads (Ordner mit vererbten Rechten und Sichtbarkeit, Versionen, Suche, Favoriten, Pagebuilder-Block – früher „Dokumente“); ✅ Qualitätsmanagement (Kategorien, farbige Ordner mit Symbolen, Einführung, Ansprechpartner, Versionen mit Stand und Archiv, Volltextsuche inkl. OCR-Anbindung, PDF-Betrachter, Rollen-Ausschluss, Wiedervorlage mit Erinnerung, Lesebestätigung je Fassung mit Auswertung); ✅ Speiseplan (Wochenbilder, PDF → Bild, A4-Druck); ✅ „Gemeinsam feiern, erinnern und willkommen heißen“ (Personalnachrichten je Monat); ✅ Monatsspruch als erstes separat installierbares Plugin (eigenes Repo); ✅ OIDC generisch, LDAP/AD, SAML 2 (als Plugins auf gemeinsamem Treiber-Unterbau); ✅ IT-Service über OpenNIT; ✅ Mediathek mit Verwendungsnachweis; ✅ globale Suche; ✅ Kommentare unter Neuigkeiten; ✅ Rollen-Ausschluss für Inhalte und Module; ✅ Lasttest 5.000 Personen (docs/LASTTEST.md) |
|
||
| **7 – Plugin-SDK öffentlich** ✅ | Vorkompilierte Oberflächen für Kunden-Plugins (Import Map mit `vue`, `@inertiajs/vue3`, `@inhaus/ui`), Generator `inhaus:make-plugin` mit Build-Voreinstellung und Paketier-Skript, Tailwind mit Design-Tokens und Präfix `ih:`, Doku in docs/PLUGINS.md (kein Plugin-Verzeichnis) |
|
||
| **8 – Mobil** | REST-API (Sanctum), Web-Push, native App |
|
||
|
||
Begründung für Phase 1: Ohne Self-Updater erreicht jede spätere Version
|
||
Shared-Hosting-Kunden nur per manuellem Upload – der Updater muss deshalb in
|
||
der allerersten ausgelieferten Version stecken.
|
||
|
||
---
|
||
|
||
## 16. Offene Punkte
|
||
|
||
- Produktname „Inhaus“: Marken- und Domainprüfung (DPMA, EUIPO, .de/.app);
|
||
technischer Schlüssel `mitarbeiterportal` bleibt, sofern
|
||
der Proxy nicht umkonfiguriert wird
|
||
- Update-Weg für lizenzpflichtige Hersteller-Plugins (eigene Proxy-Einträge?)
|