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:
parent
e4d767737f
commit
45b4e46ee9
3 changed files with 1131 additions and 0 deletions
490
docs/PLAN.md
Normal file
490
docs/PLAN.md
Normal 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
208
docs/specs/feedback.md
Normal 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
433
docs/specs/self-updater.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue