Loheide-eu-mitarbeiterplatt.../docs/specs/feedback.md
Friederich Loheide 45b4e46ee9 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>
2026-09-25 20:04:34 +00:00

208 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

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

# 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.