Projektplan und Hersteller-Spezifikationen

- docs/PLAN.md: Architektur, Plugin-System, Self-Updater & Lizenz,
  Rückmeldungen, Berechtigungen, Entra-ID-Gruppen-Mapping, Performance,
  Pagebuilder, Branding & Theming, Phasen
- docs/specs/: Vorgaben für Self-Updater und Rückmeldungen (unverändert)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Friederich Loheide 2026-09-25 20:04:34 +00:00
parent e4d767737f
commit 45b4e46ee9
3 changed files with 1131 additions and 0 deletions

490
docs/PLAN.md Normal file
View file

@ -0,0 +1,490 @@
# 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 + Vuetify (Material 3 Blueprint)**, vorkompiliert ausgeliefert |
| 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/Vuetify, Material 3): Mitarbeitende und Redakteure.
- **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: später über eine `update_url` im Manifest; für
eigene, lizenzpflichtige Plugins kann dasselbe Proxy-Modell wie beim Core
genutzt werden.
### 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.
### 4.4 Frontend von Plugins
- Portal stellt **Vue, Vuetify und ein Portal-UI-Kit per Import Map** bereit.
- 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`.
- Optional Signaturprüfung, Warnung bei unsignierten Plugins.
- 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:** `stable` → Branch `main`, `development` → Branch `develop`
(Proxy-Konfiguration beim Hersteller).
- **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, Frontend-Build + `composer install --no-dev` → Assets und
`vendor/` mitcommitten
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 – später, technisch als Plugins
### 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.
- 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**
- **Primärfarbe** (Pflicht) → daraus erzeugt Material 3 automatisch die
komplette Palette für hell und dunkel
- optional Sekundär- und Tertiärfarbe überschreiben
- **Farbtreue-Schalter:** M3 verschiebt die Seed-Farbe leicht. Für Kunden mit
strengem Corporate Design wird die exakte Markenfarbe als Primärfarbe
gesetzt, nur die Abstufungen werden berechnet
- 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
- 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 mit `material-color-utilities` im Browser (Vorschau) und
identisch beim Speichern (Ergebnis wird mitgespeichert, damit Server und
Client dieselben Werte nutzen)
- Vuetify-Theme, 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, Verzeichnis &
Organigramm, Dokumente, 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: Pest, 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, MD3-Layout mit Design-Tokens, **Basis-Branding (Portalname, Logo, Primärfarbe)**, Filament-Grundgerüst |
| **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, Delta-Sync |
| **4 – CMS** | Seitenbaum, Pagebuilder, Versionen; News mit Kategorien & Freigabe |
| **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** | Verzeichnis/Organigramm, Dokumente, Events …; OIDC generisch, LDAP, SAML; Lasttests 5.000 User |
| **7 – Plugin-SDK öffentlich** | Doku, Generator, Beispiel-Plugins, Signierung, ggf. 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
- Branch-Zuordnung der Kanäle (`main`/`develop`) mit Proxy abstimmen
- Plugin-Verzeichnis/Store: öffentlich, nur für Kunden, oder gar nicht?
- Update-Weg für lizenzpflichtige Hersteller-Plugins (eigene Proxy-Einträge?)
- White-Label: Darf der Kunde „Inhaus“ komplett ausblenden, oder bleibt ein
dezentes „Powered by Inhaus“ (ggf. abhängig von der Lizenz)?

208
docs/specs/feedback.md Normal file
View file

@ -0,0 +1,208 @@
# Spezifikation: Rückmeldungen an den Hersteller (Fehlerbericht / Funktionswunsch)
> Vorgabe des Herstellers, unverändert übernommen (Stand 2026-09-25).
> Umsetzungsnotizen für dieses Projekt stehen in `docs/PLAN.md`, Abschnitt 6.
Baue in dieses Projekt einen Meldeweg ein, mit dem Anwender direkt aus der
laufenden Software heraus Rückmeldungen an den Hersteller senden – mit
Zuordnung zur hinterlegten Lizenz.
Der empfangende Dienst steht bereits und muss NICHT gebaut werden. Übertrage das
Konzept auf den Stack DIESES Projekts (HTTP-Client, Dialoge, Einstellungen,
Hintergrundaufgaben). Deutsche Oberflächentexte mit echten Umlauten, technische
Schlüssel bleiben ASCII.
## Die Endpunkte
Für „mitarbeiterportal" stehen bereit:
POST https://api.loheide.cloud/v1/software/mitarbeiterportal/bugreport
Fehlerbericht
POST https://api.loheide.cloud/v1/software/mitarbeiterportal/featurerequest
Funktionswunsch
Nicht freigeschaltet und daher hier bewusst ausgelassen: Beta-Anmeldung.
Sollen sie dazukommen, zuerst in der Verwaltung freischalten (Software → das Programm → API-Endpunkte).
## Anmeldung: Lizenzdaten mitsenden
Sende bei jeder Meldung die Lizenzdaten mit, damit die Einsendung dem Kunden
zugeordnet wird:
X-License-Email: <die auf der Lizenz hinterlegte Adresse>
Authorization: Bearer <Lizenzschlüssel>
X-Device-Id: <dauerhafte Gerätekennung, falls vorhanden>
Ersatzweise als Felder im JSON-Körper: email, key, device_id.
DREI DINGE, die du dabei richtig machen musst:
1. Die Lizenz-E-Mail ist NICHT die E-Mail des Anwenders. Sie gehört zur Lizenz
und kann davon abweichen. Nimm den Wert aus deinem Lizenzspeicher, nicht aus
einem Benutzerprofil.
2. Eine ungültige oder abgelaufene Lizenz verhindert die Meldung NICHT.
Der Server nimmt sie trotzdem an – dann eben ohne Kundenzuordnung, und der
Grund wird intern vermerkt. Das ist Absicht: Ein Kunde mit abgelaufener
Lizenz ist genau derjenige, dessen Fehlerbericht man hören will. Baue also
KEINE Vorabprüfung ein, die das Absenden sperrt.
3. Hat der Anwender gar keine Lizenz hinterlegt, sende die Kopfzeilen einfach
nicht mit. Die Meldung geht dann anonym raus. Sende niemals leere oder
erfundene Werte – daraus entsteht nur ein Fehlerprotokoll ohne Nutzen.
Das Feld "email" im Körper ist davon unabhängig: Es ist die Adresse für die
RÜCKMELDUNG an den Anwender. Ohne Angabe verwendet der Server die Lizenz-Adresse.
## Anfrage und Antwort
Anfragekörper (application/json):
{
"title": "Export bricht bei großen Listen ab", // Pflicht, max. 255 Zeichen
"body": "Ab etwa 5000 Zeilen …", // Pflicht, mind. 10 Zeichen
"email": "anwender@example.com", // freiwillig, für Rückfragen
"name": "Vorname Nachname", // freiwillig
"app_version": "3.4.1", // aus deiner Anwendung
"current_sha": "9f2c1ab…", // installierter Stand
"os": "Windows 11 24H2", // Betriebssystem
"severity": "high", // low | normal | high | critical
"metadata": { "zeilen": 5231, "speicher_mb": 812 } // frei, höchstens 50 Felder
}
Antwort bei Erfolg (HTTP 201):
{ "ok": true,
"reference": "BUG-8F3K2Q",
"id": "<uuid>",
"message": "Der Fehlerbericht ist eingegangen." }
Die "reference" ist die Nummer für Rückfragen. ZEIGE SIE DEM ANWENDER an und
lege sie in deinem Protokoll ab – sie ist der einzige Faden, an dem er sich
später auf seine Meldung beziehen kann.
Fülle app_version, current_sha und os IMMER selbst aus deiner Anwendung. Diese
drei Angaben entscheiden bei der Fehlersuche fast alles, und kein Anwender tippt
sie freiwillig korrekt ab.
## Fehlerbehandlung
Fehler kommen als JSON mit einem stabilen `code`. Prüfe auf `code`, NICHT auf
den Meldungstext.
404 Dieser Meldeweg ist für dieses Programm nicht freigeschaltet.
Blende die Schaltfläche dann dauerhaft aus, statt es erneut zu
versuchen. Am besten einmalig beim Programmstart über
GET https://api.loheide.cloud/v1/software ermitteln, welche Wege offen sind
(Feld "endpoints" je Programm) und die Oberfläche danach aufbauen.
409 Dieselbe Meldung wird gerade schon verarbeitet (siehe
Idempotency-Key weiter unten). Kurz warten, dann erneut - NICHT als
Fehler anzeigen.
422 Eingabe unvollständig – Feld und Grund stehen in der Antwort.
Zeige das direkt am betroffenen Formularfeld.
429 Zu viele Meldungen: 10 pro Stunde und Absender. Beachte Retry-After,
versuche es NICHT sofort erneut und sage dem Anwender, dass er es
später noch einmal probieren soll.
503 Der Server wird gerade aktualisiert. Meldung zwischenspeichern und
später senden (siehe unten).
### Doppelte Meldungen vermeiden (wichtig)
Erzeuge je Meldung EINMAL einen zufälligen Schlüssel (16 Zufallsbytes als Hex)
und schicke ihn als Kopfzeile mit:
Idempotency-Key: <dein zufälliger Wert>
Denselben Wert bei JEDEM Wiederholungsversuch derselben Meldung mitschicken,
auch nach einem Neustart des Programms - also zusammen mit der Meldung in der
Warteschlange speichern, nicht daneben. Der Server merkt sich die Antwort und
liefert bei einer Wiederholung dieselbe Ticketnummer zurück, statt ein zweites
Ticket anzulegen.
Ohne das entsteht der klassische Fehler: Die Antwort geht unterwegs verloren,
dein Programm versucht es erneut - und die Meldung steht doppelt im System.
Für eine NEUE Meldung immer einen NEUEN Schlüssel erzeugen; einen alten
wiederzuverwenden beantwortet der Server mit 422.
## Oberfläche in der Anwendung
Ein Menüpunkt „Hilfe → Rückmeldung geben" (oder gleichwertig, gut auffindbar)
öffnet einen Dialog mit:
- Auswahl der Meldungsart, aber NUR die freigeschalteten Wege anzeigen
- Betreff und Beschreibung
- freiwillige Rückmeldeadresse, als freiwillig gekennzeichnet
- bei Fehlerberichten: Auswahl der Dringlichkeit
- eine aufklappbare Anzeige „Diese technischen Angaben werden mitgesendet"
mit dem tatsächlichen Inhalt von app_version, current_sha, os und metadata
Der letzte Punkt ist nicht Verzierung, sondern Voraussetzung: Wer nicht sehen
kann, was er verschickt, verschickt im Zweifel nichts.
### Datenschutz
Sende in metadata keine personenbezogenen Daten, keine Dateipfade mit
Benutzernamen und keine Inhalte aus Kundendokumenten. Willst du einen Logauszug
mitschicken, zeige ihn vorher an und lass den Anwender zustimmen. Im Zweifel
lieber weglassen – ein Fehlerbericht ohne Log ist immer noch nützlich, ein
versehentlich übertragener Datensatz ist ein Vorfall.
### Wenn gerade kein Netz da ist
Lege die Meldung in eine kleine lokale Warteschlange und versuche es beim
nächsten Programmstart erneut. Höchstens fünf Versuche, dann verwerfen und den
Anwender darüber informieren. Wichtig: Der Dialog darf NICHT hängen bleiben,
während gesendet wird – bestätige sofort, sende im Hintergrund.
### Was der Dialog niemals tun darf
- den Programmstart blockieren
- bei einem Fehler die Eingabe des Anwenders verwerfen
- ungefragt Dateien anhängen
## Datenschutzhinweis – Pflichtteil, nicht optional
Eine Meldung überträgt personenbezogene Daten an einen Server, den der
Anwender nicht betreibt – und zwar mehr, als ihm bewusst ist: Was in
einem Bildschirmfoto oder Protokollauszug steht, sieht er im Moment des
Anhängens nicht durch. Der Hinweis gehört deshalb sichtbar ÜBER den
Absendeknopf, nicht hinter einen Verweis.
Mit dem Absenden werden Daten an api.loheide.cloud übertragen. Übermittelt werden:
• Ihr Text: Betreff und Beschreibung
• Name und E-Mail-Adresse, soweit Sie sie angeben – für Rückfragen
• Ihre Lizenzdaten, damit die Meldung Ihrem Konto zugeordnet werden kann
• Programmversion, installierter Stand und Betriebssystem
• die von Ihnen angehängten Dateien
• technisch bedingt: Ihre IP-Adresse, Datum und Uhrzeit
Bitte beachten: Was Sie in die Beschreibung schreiben und was in einem
Bildschirmfoto oder Protokollauszug zu sehen ist, wird mit übertragen.
Enthält es Namen, Adressen oder Vorgänge anderer Personen, entfernen Sie
diese bitte vorher.
Zweck: Bearbeitung Ihrer Meldung und Rückfragen dazu. Das Senden ist
freiwillig; es geschieht nur, wenn Sie es hier auslösen.
Regeln für die Umsetzung:
- Text sichtbar anzeigen, nicht hinter „Mehr erfahren" verstecken.
- Den Wortlaut übernehmen, nicht umschreiben. Er ist an dem ausgerichtet,
was die Endpunkte tatsächlich entgegennehmen.
- Sendet dein Client ein Feld NICHT – etwa keinen Rechnernamen –, streiche
die entsprechende Zeile. Ein Hinweis, der mehr aufzählt als geschieht, ist
genauso falsch wie einer, der etwas verschweigt.
- Ist in der Anwendung eine eigene Datenschutzerklärung hinterlegt, verweise zusätzlich dorthin.
- KEINEN zusätzlichen Zustimmungshaken. Das Absenden ist die Handlung des
Anwenders; ein Haken davor ist eine Hürde ohne Zugewinn.
- Zeige vor dem Absenden, WAS angehängt wird – Dateiname und Größe. Ein
Anhang, den man nicht mehr sieht, wird nicht mehr geprüft.
## Abnahmekriterien
- Der Dialog ist aus der Anwendung heraus in höchstens zwei Klicks erreichbar.
- Nur freigeschaltete Meldewege erscheinen; 404 führt zum dauerhaften Ausblenden.
- app_version, current_sha und os werden automatisch befüllt und sind vor dem
Absenden einsehbar.
- Nach erfolgreichem Absenden sieht der Anwender die Referenznummer.
- 422 zeigt den Fehler am betroffenen Feld, 429 nennt die Wartezeit.
- Ohne Netz wird die Meldung zwischengespeichert und später gesendet.
- Ein Fehler beim Senden verwirft die eingegebene Beschreibung nicht.
- eine abgelaufene oder falsche Lizenz verhindert das Absenden NICHT
- ohne hinterlegte Lizenz werden gar keine Lizenz-Kopfzeilen gesendet
Automatisierte Tests für: Aufbau des Anfragekörpers, Behandlung von 201, 404,
422, 429 und 503, sowie die Warteschlange (einreihen, erneut senden, aufgeben).
Erkläre am Ende kurz, welche Dateien du angelegt hast und wo der Menüpunkt sitzt.

433
docs/specs/self-updater.md Normal file
View file

@ -0,0 +1,433 @@
# Spezifikation: Self-Updater & Lizenzprüfung
> Vorgabe des Herstellers, unverändert übernommen (Stand 2026-09-25).
> Umsetzungsnotizen für dieses Projekt stehen in `docs/PLAN.md`, Abschnitt 5.
Baue in dieses Projekt einen selbstständigen In-App-Updater ein („Self-Updater"),
mit dem eine laufende Installation sich per Klick im Admin-Bereich auf den neuesten
Stand aktualisiert – OHNE SSH-Zugriff auf dem Zielserver. Übertrage das folgende
Konzept auf den Stack DIESES Projekts: passe Framework-spezifische Teile an
(Routing, Middleware, HTTP-Client, CLI-Aufrufe, Markdown-Renderer, Admin-Auth),
behalte Architektur, Ablauf und ALLE Sicherheitseigenschaften bei.
Deutsche UI-Texte mit echten Umlauten, technische Schlüssel und Routen bleiben ASCII.
## Gesamtidee
Die App kennt ihre installierte Version als Git-Commit-SHA (in einer DATEI, nicht in
der Datenbank – der Updater muss sie auch lesen können, wenn die DB gerade hängt) und
eine semantische Release-Version aus dem Code. Ein bereits laufender Update-Proxy
stellt den neuesten Stand eines Branches als ZIP bereit. Der Updater lädt das ZIP,
entpackt es kontrolliert über die Produktion (mit geschützten Pfaden), führt
ausstehende DB-Migrationen aus, leert Caches und schreibt die neue SHA. Während des
Updates zeigt die App eine Wartungsseite; der Fortschritt wird über eine Status-Datei
gepollt.
## Der Update-Proxy steht bereits – das ist sein Vertrag
Du musst KEINEN Proxy bauen. Er läuft unter:
https://update.loheide.cloud/mitarbeiterportal
Verfügbare Endpunkte (alle GET, Antworten JSON sofern nicht anders vermerkt):
GET https://update.loheide.cloud/mitarbeiterportal/version
-> { "sha": "<voller Commit-SHA>",
"version": "1.12.0"|null, aus dem Änderungsprotokoll
"released_at": "…"|null,
"release_note": "…" } NUR falls hinterlegt
GET https://update.loheide.cloud/mitarbeiterportal/check?current_sha=<sha>
Client ist aktuell:
-> { "has_update": false,
"latest_sha": "<sha>", "version": …, "released_at": … }
Es gibt Neues:
-> { "has_update": true,
"latest_sha": "<sha>",
"version": "1.12.0"|null,
"released_at": "…"|null,
"versions_behind": <int>,
"changelog_preview": {
"entries": [ { "version", "heading", "text" }, … ],
"complete": true|false } }
Ohne current_sha antwortet der Proxy wie „aktuell" – die erste Prüfung
einer frischen Installation liefert also latest_sha zum Merken.
Kanalwechsel (nur bei Software mit mehreren Kanälen):
-> { …, "channel_switch": { "from_channel", "to_channel",
"direction": "forward"|"back" } }
Steht das Feld da, stammt der gemeldete Stand aus einem anderen Kanal.
Dann ist "versions_behind" 1. Bei "direction": "back" ist der
Zielstand ÄLTER als der laufende; das ist beim Zurückschalten auf
den Hauptkanal der Normalfall. Ein Updater darf hier nicht abbrechen,
weil der Zeitstempel rückwärts geht: Er soll schlicht latest_sha
ziehen und einspielen.
GET https://update.loheide.cloud/mitarbeiterportal/zip?ref=<sha>
-> Binäres ZIP des Projektstands. GitHub-Stil: EIN gemeinsamer
Top-Level-Ordner ("repo-<sha>/"), der beim Entpacken entfernt wird.
Antwort beginnt mit "PK". Kopfzeilen X-Commit-Sha und
X-Content-Sha256 benennen den gelieferten Stand.
GET https://update.loheide.cloud/mitarbeiterportal/changelog?format=raw
-> Die CHANGELOG.md des aktuellen Stands als Markdown (text/markdown).
Mit format=json stattdessen { tool, file, latest_sha, content }.
GET https://update.loheide.cloud/mitarbeiterportal/files?path=<unterverzeichnis>
-> { "files": [ { "name", "path", "type": "file"|"dir", "size" }, … ] }
GET https://update.loheide.cloud/mitarbeiterportal/download/<pfad-im-repo>
-> Einzelne Datei. Nützlich, um vor dem Update z. B. nur die
CHANGELOG.md oder eine Versionsdatei zu ziehen.
Fehlerfälle, die kein Fehler des Clients sind:
503 mirror_pending Der Stand wird gerade gespiegelt. Später erneut.
503 not_released Es liegt etwas bereit, aber noch nichts ist
freigegeben. Ebenfalls später erneut – der Client
kann nichts richtig machen. Beide tragen retry_after.
WICHTIG zum Modell: Es gibt KEINE Tags und KEINE Releases. Es zählt der Stand des
Branches, und die Identität eines Stands ist sein Commit-SHA. „versions_behind"
zählt Commits, nicht Versionsnummern. Baue nichts, was Tags erwartet.
WICHTIG zur Anzeige: Es gibt KEINE Commit-Titel und KEINE Commit-Texte in diesen
Antworten, und es wird auch keine geben. Commit-Nachrichten sind für Entwickler
geschrieben ("Merge pull request #229 from …") und dürfen einem Anwender nie
unter die Augen kommen. Zeige deshalb genau zwei Dinge:
1. dass eine neue Version da ist – aus has_update, version, released_at,
2. was daran neu ist – aus changelog_preview.entries.
changelog_preview enthält die Abschnitte des Änderungsprotokolls, die seit dem
gemeldeten Stand dazugekommen sind, neueste zuerst; "text" ist Markdown. Das
FELD KANN FEHLEN – dann gibt es nichts zu berichten, und die Anzeige beschränkt
sich auf „neue Version verfügbar". Baue keinen leeren Kasten und erfinde keinen
Ersatztext. Bei "complete": false wurde gekürzt; dann ist ein Verweis auf
https://update.loheide.cloud/mitarbeiterportal/changelog richtig.
## Lizenzprüfung – dieser Teil ist der Unterschied
Dieses Programm ist lizenzpflichtig. Jede Anfrage an die Update-Endpunkte muss
sich ausweisen, sonst antwortet der Proxy mit 401 oder 403.
### Kopfzeilen
X-License-Email: <die auf der Lizenz hinterlegte Adresse>
Authorization: Bearer <Lizenzschlüssel>
X-Device-Id: <dauerhafte, einmalig erzeugte Gerätekennung>
X-Device-Token: <zuletzt erhaltenes Token, falls vorhanden>
Alles geht ersatzweise auch als Query-Parameter (email, key, device_id,
device_token). Bevorzuge die Kopfzeilen: Parameter landen in Server-Protokollen.
Die Lizenz-E-Mail ist NICHT zwingend die E-Mail des Kunden – sie gehört zur
Lizenz. Nimm sie als eigenständigen Wert entgegen und leite sie nicht aus
irgendeinem Benutzerkonto ab.
### Das rotierende Gerätetoken – bitte genau so umsetzen
JEDE Antwort auf eine Anfrage mit Lizenzdaten kann ein neues Token liefern: als
Kopfzeile `X-Device-Token` und, bei JSON-Antworten, im Feld `device_token`. Das
gilt auch für Dateidownloads und für die Meldungs-Endpunkte (Fehlerbericht,
Funktionswunsch, Beta-Anmeldung) – nicht nur für die Lizenzprüfung.
Speichere es SOFORT und sende es bei der nächsten Anfrage zurück –
auch dann, wenn die Antwort selbst ein Fehler war.
Hintergrund: Wird ein Installationsordner kopiert, halten beide Kopien zunächst
dasselbe Token. Sobald eine rotiert, legt die andere ein veraltetes vor – genau
daran erkennt der Server die Mehrfachnutzung.
Gültig bleibt nicht nur das jüngste Token, sondern die zuletzt ausgegebenen.
Eine verlorene Antwort, ein abgebrochener Download oder mehrere gleichzeitige
Anfragen sind deshalb unkritisch. Ein Client, der das Token gar nicht speichert,
meldet sich dagegen bei jedem Aufruf selbst als Verdachtsfall.
Verliert der Client das Token (Neuinstallation, gelöschte Einstellungen), sendet
er einfach keines. Ein einzelner Verlust ist unkritisch.
Schickst du mehrere Anfragen gleichzeitig los – etwa vier gesammelte Meldungen
auf einen Klick –, ist das erlaubt. Wenn es sich einfach machen lässt, ist es
trotzdem sauberer, sie nacheinander zu senden und das Token dazwischen
nachzuführen.
### Neuer Endpunkt: Lizenzauskunft
GET https://update.loheide.cloud/mitarbeiterportal/license
-> {
"licensing_required": true,
"license": { "status", "valid_until"|null, "unlimited": bool,
"days_remaining"|null, "expired": bool },
"registered_to": { "license_email", "company", "contact_name" },
"devices": { "used", "max", "policy" },
"updates": { "last_seen_sha", "last_download_sha", "last_download_at" }
}
"valid_until": null zusammen mit "unlimited": true bedeutet UNBEFRISTET.
Behandle das ausdrücklich – nicht als „abgelaufen" und nicht als Fehler.
Gut geeignet für einen „Über dieses Programm"-Dialog: auf wen die Lizenz läuft,
wie lange noch, wie viele Geräteplätze belegt sind.
### Fehlerbehandlung
Fehler kommen als JSON mit einem stabilen `code`. Prüfe auf `code`, NICHT auf
den Meldungstext – der Text kann sich ändern.
license_required 401 keine Lizenzdaten gesendet → Eingabemaske
invalid_key 403 Schlüssel unbekannt → Eingabemaske
email_mismatch 403 E-Mail passt nicht zum Schlüssel
license_expired 403 abgelaufen → Hinweis auf Verlängerung
license_revoked 403 gesperrt → Support-Hinweis
device_limit_reached 403 alle Plätze belegt; Antwort enthält
devices_used und devices_max
device_cloned 403 Mehrfachnutzung erkannt → Support-Hinweis
device_id_required 403 Lizenz ist gerätegebunden, Client sendet keine ID
rate_limited 429 Retry-After beachten
maintenance 503 Server aktualisiert sich gerade → später erneut
upstream_unavailable 503 vorübergehend → alten Stand behalten
GRUNDREGEL, die du strikt einhalten musst:
Ein Lizenzfehler darf das Programm NIE unbenutzbar machen. Er verhindert
ausschließlich den Update-Bezug. Alles andere führt zu Anrufen an Feiertagen.
Zeige einen Hinweis, protokolliere den Code – und lass das Programm laufen.
### Optional: Gerät selbst abmelden
POST https://api.loheide.cloud/v1/license/release-device?software=mitarbeiterportal
(mit denselben Kopfzeilen)
Gibt den Geräteplatz wieder frei. Baue das in einen Deinstallations- oder
„Diesen Rechner abmelden"-Ablauf ein, dann kann der Kunde ohne Rückfrage auf
einen neuen Rechner wechseln.
## Komponenten (Namen an die Konventionen des Projekts anpassen)
1) Version-Helper
- current(): volle SHA aus `storage/.version`, oder null bei Erstinstallation
- save(sha): schreibt sie zurück (vorher auf 40 Hex-Zeichen prüfen)
- short() (7 Zeichen), release() (SemVer aus dem Code), full() → "1.4.2 (a1b2c3d)"
Die Datei liegt bewusst in storage/ – das ist ein geschützter Pfad, ein Update
überschreibt sie also nie mit dem Stand aus dem Archiv.
2) Fortschritts-Datei
- schreibt bei jedem Schritt JSON nach `storage/.update-progress`:
{ pct: int, step: string, text: string, ts: int }
- get() liefert Default { pct: 0, step: "idle" }, wenn nichts da ist
- Fehler: pct = -1, step = "error" – dadurch eindeutig von "0 % erledigt"
unterscheidbar
- isRunning(): läuft nur als aktiv, wenn das letzte Lebenszeichen jünger als
~10 Minuten ist. Sonst blockiert ein abgestürzter Lauf dauerhaft den nächsten.
3) Wartungsmodus
- Flag-Datei `storage/.maintenance` mit { since, until }
- isActive() ist SELBSTHEILEND: ein abgelaufenes `until` wird beim Prüfen
automatisch entfernt. Ohne das legt ein Absturz mitten im Update die
Installation dauerhaft lahm – und niemand käme mehr an die Oberfläche,
um den Modus abzuschalten.
- activate(maxSeconds = 600), deactivate()
4) Updater (Kern), Methode installUpdate() mit Fortschritts-Meldungen:
(0 %) Wartungsmodus aktivieren
(5 %) GET /version → Ziel-SHA
(20 %) GET /zip?ref=<sha> in eine Datei streamen, NICHT in den Speicher.
Danach prüfen: beginnt die Datei mit "PK"? Wenn nicht, hat in
Wahrheit eine Fehlerseite geantwortet – mit klarer Meldung abbrechen.
(50 %) nach `storage/.update-staging` entpacken:
- gemeinsamen Top-Level-Ordner ermitteln und strippen
- ZIP-SLIP-SCHUTZ, zweistufig:
a) Eintragsnamen vorab ablehnen: absolute Pfade, Laufwerks-
buchstaben (C:\), ".."-Segmente, Null-Bytes
b) NACH dem Schreiben den aufgelösten Pfad prüfen – liegt er
wirklich im Staging? Sonst Datei sofort wieder löschen.
Die zweite Prüfung fängt ab, was die erste übersieht (Symlinks,
ungewöhnliche Kodierungen). Beides einbauen, nicht nur eins.
(65 %) Staging über die Produktion legen, geschützte Pfade auslassen.
Je Datei erst daneben schreiben, dann umbenennen – ein Abbruch
mittendrin hinterlässt sonst eine halbe Datei, die den nächsten
Aufruf mit einem Parse-Fehler abwürgt.
NUR überschreiben und ergänzen, NICHT löschen: eine im neuen Stand
fehlende Datei bleibt liegen. Etwas unaufgeräumter, aber ein Fehler
in der Pfadberechnung nimmt so keine Nutzdaten mit.
(80 %) ausstehende Migrationen ausführen, Anzahl zurückgeben
(90 %) Caches leeren (App-, View-, Config-, Route-Cache) und den
Bytecode-Cache verwerfen (opcache_reset o. ä.) – sonst läuft nach
dem Update noch eine Weile der alte Code
(100 %) neue SHA speichern, Audit-Eintrag schreiben, ZIP und Staging löschen
Fehlerbehandlung: bei einer Ausnahme step = "error", pct = -1, Meldung setzen,
Fehler ins Audit-Log. Im finally IMMER den Wartungsmodus deaktivieren.
Timeouts: maßvoll für die JSON-Aufrufe, großzügig für den ZIP-Download
(z. B. 180 s), Weiterleitungen begrenzen, nur HTTPS zulassen.
5) Geschützte Pfade (konfigurierbar, werden beim Übernehmen NIE überschrieben).
Mindestens: `.env`, `.git/`, `storage/`, `vendor/`, `node_modules/`,
`composer.lock`, `package-lock.json`, lokale Konfiguration, lokale DB-Datei.
Verzeichnisse per Schrägstrich am Ende matchen, Dateien exakt.
6) Auto-Migration beim ersten Seitenaufruf nach dem Update
Ohne SSH ist das der einzige verlässliche Zeitpunkt, zu dem neue Migrationen
laufen können.
- überspringen, wenn nicht installiert oder in Tests
- Fingerabdruck (Hash) über die Liste der Migrationsdateien bilden; nur wenn
der sich geändert hat, überhaupt migrieren. Sonst läuft der Migrator bei
JEDEM Request – das ist der Fehler, den man hier am häufigsten sieht.
- Sperre über Requests hinweg gegen Parallellauf (DB-Lock oder Lock-Datei)
- Fehler protokollieren, NICHT werfen: eine fehlgeschlagene Nachführung darf
nicht jede Seite unbenutzbar machen
7) Wartungs-Middleware
Solange der Wartungsmodus aktiv ist: 503 mit Retry-After und einer
verständlichen Wartungsseite – AUSSER für die Update-Endpunkte selbst, die
Anmeldeseite und den Health-Check. Sonst kann niemand mehr sehen, wie weit
das laufende Update ist.
8) Lizenz-Speicher
- hält Lizenz-E-Mail, Lizenzschlüssel, device_id und device_token
- device_id: EINMALIG erzeugen (16 Zufallsbytes als Hex genügen) und
dauerhaft neben der Konfiguration ablegen. Eine Hardware-Kennung tut es
auch, wechselt aber beim Tausch von Bauteilen und ist datenschutzrechtlich
heikler – eine gespeicherte Zufallszahl ist der ruhigere Weg.
- Zusätzlich bei JEDER Anfrage mitschicken: hostname (Rechnername) und
device_label (Rechnername + Installationspfad, z. B.
"web01:/var/www/kunde"). Beides ist optional, aber ohne das sieht der
Kunde im Portal nur namenlose Zeilen und kann nicht erkennen, welchen
Geräteplatz er freigeben darf. Ein „Gerät“ ist hier ein
Installationsverzeichnis: zwei Vhosts auf demselben Server zählen als
zwei, ein mitkopiertes Verzeichnis als eines.
- device_token: NACH JEDER ANTWORT sofort speichern, bevor irgendetwas
anderes passiert (siehe unten – das ist der Punkt, an dem die meisten
Implementierungen scheitern)
- Eingabemaske im Admin-Bereich für E-Mail und Schlüssel, mit
„Lizenz prüfen"-Knopf gegen https://update.loheide.cloud/mitarbeiterportal/license
## Admin-Oberfläche (nur für Administratoren)
Eine Seite „Aktualisierung" mit:
- aktueller Version (SemVer + Kurz-SHA) und aktivem Kanal
- Kanal-Auswahl, persistiert in den App-Einstellungen
- „Nach Updates suchen" → ruft /check und zeigt: Update ja/nein, Zielversion
und Ziel-SHA, „X Version(en) zurück" und die Abschnitte aus
changelog_preview. Fehlt das Feld, steht dort nur „neue Version verfügbar" –
ohne Ersatztext und ohne leeren Kasten
- „Jetzt aktualisieren" → startet die Installation und pollt den Fortschritt
alle ~2 s; Fortschrittsbalken + Statustext, im Fehlerfall die Meldung
- „Migrationen ausführen" (manuell) + Liste aller Migrationsdateien mit Status
angewendet/offen
- Changelog-Historie: liest die mitgelieferte CHANGELOG.md, zerlegt sie an
"## <version>"-Abschnitten, rendert je Abschnitt Markdown → HTML
(unsichere Links strippen) und zeigt sie chronologisch
- Lizenzbereich: hinterlegte Lizenz-E-Mail und Schlüssel (Schlüssel maskiert),
Laufzeit, verbleibende Tage, belegte von erlaubten Geräten, Knopf
„Lizenz prüfen". Bei einer bald ablaufenden Lizenz (< 30 Tage) ein Hinweis,
der NICHT blockiert.
Backend-Endpunkte, nur für Admins und CSRF-geschützt:
POST /admin/update/check
POST /admin/update/install
GET /admin/update/progress
POST /admin/update/channel
POST /admin/update/migrations
/install muss das Zeitlimit anheben (set_time_limit(0) o. ä.) und einen
Client-Abbruch ignorieren (ignore_user_abort(true)) – der Ablauf läuft
serverseitig weiter, das Frontend pollt nur den Fortschritt.
## Kanäle
Mehrere Kanäle über Konfiguration, jeweils eigene Proxy-Basis-URL, z. B.:
stable -> https://update.loheide.cloud/mitarbeiterportal
development -> https://update.loheide.cloud/mitarbeiterportal-development
Der aktive Kanal wird persistiert (Standard: stable). Eine Factory erzeugt die
Updater-Instanz für den aktiven oder einen übergebenen Kanal und lehnt
unbekannte Kanäle ab.
## Versionierung und Changelog (im Repo, nicht in der App)
Lege eine `CHANGELOG.md` an (neueste Version oben, Abschnitte
"## MAJOR.MINOR.PATCH", kurze deutsche Stichpunkte) und eine Konstante `VERSION`
(SemVer) im Code. Dokumentiere diesen Ablauf für JEDE Änderung:
1. CHANGELOG.md: neuen Versionsabschnitt ergänzen
2. VERSION anheben (Patch = Fehlerbehebung, Minor = Funktion)
3. Tests grün, ggf. Frontend-Build – kompilierte Assets werden MITVERSIONIERT,
weil beim Kunden kein Build läuft
4. Commit und Merge in den Branch, den der Proxy ausliefert
Damit ist die neue Fassung sofort über den Self-Updater verfügbar. Die
installierte SHA pflegt der Updater selbst.
## Datenschutzhinweis – Pflichtteil, nicht optional
Die Update-Prüfung überträgt personenbezogene Daten an einen Server, den
der Anwender nicht betreibt. Der Hinweis darauf gehört an die Stelle, an
der es passiert, und zwar VORHER: auf die Seite „Aktualisierung",
dauerhaft sichtbar unter oder neben dem Knopf „Nach Updates suchen" –
nicht in einen Dialog, den man einmal wegklickt.
Bei der Suche nach Updates und beim Herunterladen einer neuen Fassung
werden Daten an update.loheide.cloud übertragen. Übermittelt werden:
• die auf Ihrer Lizenz hinterlegte E-Mail-Adresse und der Lizenzschlüssel
• eine Gerätekennung, die dieses Programm einmalig als Zufallszahl erzeugt
hat (keine Hardwarekennung, keine Seriennummer) – damit wird gezählt,
auf wie vielen Geräten die Lizenz genutzt wird
• Rechnername, Betriebssystem und Programmversion, damit Sie Ihre Geräte
im Kundenportal auseinanderhalten können
• der bei Ihnen installierte Stand, damit die Gegenstelle weiß, was neu ist
• technisch bedingt: Ihre IP-Adresse, Datum und Uhrzeit des Abrufs
Zweck: Bereitstellung der Aktualisierung und Prüfung der Lizenz.
Nicht übertragen werden Inhalte aus diesem Programm: keine Dokumente,
keine Datenbank, keine Eingaben. Die Verbindung ist verschlüsselt.
Regeln für die Umsetzung:
- Text sichtbar anzeigen, nicht hinter „Mehr erfahren" verstecken.
- Den Wortlaut übernehmen, nicht umschreiben. Er ist an dem ausgerichtet,
was die Endpunkte tatsächlich entgegennehmen.
- Sendet dein Client ein Feld NICHT – etwa keinen Rechnernamen –, streiche
die entsprechende Zeile. Ein Hinweis, der mehr aufzählt als geschieht, ist
genauso falsch wie einer, der etwas verschweigt.
- Ist in der Anwendung eine eigene Datenschutzerklärung hinterlegt, verweise zusätzlich dorthin.
- KEINEN Zustimmungshaken vor die Update-Prüfung setzen. Die Prüfung ist
zur Vertragserfüllung nötig; ein Haken suggeriert eine Freiwilligkeit,
die es nicht gibt, und blockiert im Zweifel die Auslieferung von
Sicherheitskorrekturen.
- Zugriffe auf die Update-Endpunkte werden serverseitig 400 Tage
aufbewahrt, danach gelöscht. Nenne die Zahl, wenn du eine ausführliche
Fassung baust.
## Sicherheits- und Robustheitsanforderungen (MÜSSEN erfüllt sein)
- Nur Administratoren dürfen prüfen, aktualisieren und den Kanal wechseln.
- ZIP-Slip-Schutz beim Entpacken, beide Stufen (s. o.).
- Geschützte Pfade werden nie überschrieben – kein Verlust von .env, Datenbank,
storage, hochgeladenen Dateien.
- Der Wartungsmodus ist selbstheilend und läuft nach maxSeconds von allein aus.
- Auto-Migration nur bei geändertem Fingerabdruck, mit Sperre gegen Parallellauf.
- Jeder Lauf, Erfolg wie Fehler, erzeugt einen Audit-Eintrag: Kanal, Ziel-SHA,
Anzahl Migrationen, auslösender Benutzer.
- Fehlermeldungen benennen die Ursache verständlich: Proxy nicht erreichbar,
Antwort ist kein ZIP, Datei nicht schreibbar (dann Schreibrechte nennen).
## Abnahmekriterien
Automatisierte Tests für:
- SHA lesen und schreiben, inklusive Ablehnung ungültiger Werte
- Wartungsmodus inklusive Selbstheilung nach Ablauf
- Fortschritts-Datei, inklusive Fehlerzustand
- ZIP-Slip: ein Archiv mit "../evil" darf NICHTS außerhalb des Staging anlegen
- geschützte Pfade werden beim Übernehmen übersprungen
- Migrationszähler
- Changelog-Parsing
- Lizenzfehler führen zu verständlichen Meldungen und blockieren NICHT die
Benutzung des Programms
- ein neu erhaltenes device_token wird gespeichert, auch wenn die Antwort
gleichzeitig einen Fehler meldet
Manueller Durchlauf: Kanal wählen → suchen → aktualisieren → Fortschritt bis
100 % → Version und Changelog aktualisiert → Wartungsseite verschwindet wieder.
Erkläre am Ende kurz, welche Dateien du angelegt hast und welche
Framework-Details du angepasst hast.
## Reihenfolge beim Einführen
Falls dieses Programm bisher ohne Lizenzprüfung aktualisiert hat, ist die
Reihenfolge wichtig – sonst stehen Kunden ohne Updates da:
1. Diese Client-Fassung ausliefern. Sie KANN Lizenzdaten senden, auch wenn
noch keine hinterlegt sind. Verteilen und abwarten.
2. Lizenzen im Hub anlegen und verteilen.
3. Die Lizenzen zunächst auf „nur protokollieren" stellen und ein paar Tage
beobachten, wer sich meldet.
4. Erst dann die Software auf „lizenzpflichtig" und die Lizenzen auf
„durchsetzen" umstellen.
Schritt 3 ist die Versicherung: Du siehst vorher, welche Installationen noch
nicht umgestellt sind – statt es hinterher am Telefon zu erfahren.