diff --git a/docs/PLAN.md b/docs/PLAN.md new file mode 100644 index 00000000..d579d295 --- /dev/null +++ b/docs/PLAN.md @@ -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// Mitgelieferte Plugins (News, Seiten, Verzeichnis, …) – + Teil des Repos, kommen per Self-Updater +plugins// 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)? diff --git a/docs/specs/feedback.md b/docs/specs/feedback.md new file mode 100644 index 00000000..646bf7fc --- /dev/null +++ b/docs/specs/feedback.md @@ -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: + Authorization: Bearer + X-Device-Id: + +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": "", + "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: + +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. diff --git a/docs/specs/self-updater.md b/docs/specs/self-updater.md new file mode 100644 index 00000000..b1522916 --- /dev/null +++ b/docs/specs/self-updater.md @@ -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": "", + "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= + Client ist aktuell: + -> { "has_update": false, + "latest_sha": "", "version": …, "released_at": … } + Es gibt Neues: + -> { "has_update": true, + "latest_sha": "", + "version": "1.12.0"|null, + "released_at": "…"|null, + "versions_behind": , + "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= + -> Binäres ZIP des Projektstands. GitHub-Stil: EIN gemeinsamer + Top-Level-Ordner ("repo-/"), 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= + -> { "files": [ { "name", "path", "type": "file"|"dir", "size" }, … ] } + + GET https://update.loheide.cloud/mitarbeiterportal/download/ + -> 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: + Authorization: Bearer + X-Device-Id: + X-Device-Token: + +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= 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 + "## "-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.