- 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>
208 lines
10 KiB
Markdown
208 lines
10 KiB
Markdown
# 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.
|