Loheide-eu-mitarbeiterplatt.../docs/PLAN.md
Friederich Loheide f11a3e24b3
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 3m54s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 4m0s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 4m54s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 4m50s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 7m48s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 7m38s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 6m56s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 7m5s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m17s
Phase 8 Mobil: REST-API, Web-Push, installierbare App (0.25.0)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 08:20:07 +00:00

503 lines
28 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 v1 mit persönlichen Zugangs-Tokens (Sanctum; Login per Passwort oder Token aus dem Profil, auch für SSO-Konten), Endpunkte für Profil, Benachrichtigungen, Personen, Suche, Neuigkeiten, Termine, Plugin-Endpunkte über `routes/api.php` (docs/API.md); ✅ Web-Push ohne Zusatzpakete (VAPID, je Gerät, dieselben Hinweise wie die Glocke); ✅ installierbare Web-App mit Service Worker und Offline-Seite. Offen: native Store-Apps (brauchen Apple-/Google-Entwicklerkonten und eigene Push-Anbindung) |
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?)