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

10 KiB
Raw Permalink Blame History

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.