# Spezifikation: Rückmeldungen an den Hersteller (Fehlerbericht / Funktionswunsch) > Vorgabe des Herstellers, unverändert übernommen (Stand 2026-09-25). > Umsetzungsnotizen für dieses Projekt stehen in `docs/PLAN.md`, Abschnitt 6. Baue in dieses Projekt einen Meldeweg ein, mit dem Anwender direkt aus der laufenden Software heraus Rückmeldungen an den Hersteller senden – mit Zuordnung zur hinterlegten Lizenz. Der empfangende Dienst steht bereits und muss NICHT gebaut werden. Übertrage das Konzept auf den Stack DIESES Projekts (HTTP-Client, Dialoge, Einstellungen, Hintergrundaufgaben). Deutsche Oberflächentexte mit echten Umlauten, technische Schlüssel bleiben ASCII. ## Die Endpunkte Für „mitarbeiterportal" stehen bereit: POST https://api.loheide.cloud/v1/software/mitarbeiterportal/bugreport Fehlerbericht POST https://api.loheide.cloud/v1/software/mitarbeiterportal/featurerequest Funktionswunsch Nicht freigeschaltet und daher hier bewusst ausgelassen: Beta-Anmeldung. Sollen sie dazukommen, zuerst in der Verwaltung freischalten (Software → das Programm → API-Endpunkte). ## Anmeldung: Lizenzdaten mitsenden Sende bei jeder Meldung die Lizenzdaten mit, damit die Einsendung dem Kunden zugeordnet wird: X-License-Email: Authorization: Bearer X-Device-Id: Ersatzweise als Felder im JSON-Körper: email, key, device_id. DREI DINGE, die du dabei richtig machen musst: 1. Die Lizenz-E-Mail ist NICHT die E-Mail des Anwenders. Sie gehört zur Lizenz und kann davon abweichen. Nimm den Wert aus deinem Lizenzspeicher, nicht aus einem Benutzerprofil. 2. Eine ungültige oder abgelaufene Lizenz verhindert die Meldung NICHT. Der Server nimmt sie trotzdem an – dann eben ohne Kundenzuordnung, und der Grund wird intern vermerkt. Das ist Absicht: Ein Kunde mit abgelaufener Lizenz ist genau derjenige, dessen Fehlerbericht man hören will. Baue also KEINE Vorabprüfung ein, die das Absenden sperrt. 3. Hat der Anwender gar keine Lizenz hinterlegt, sende die Kopfzeilen einfach nicht mit. Die Meldung geht dann anonym raus. Sende niemals leere oder erfundene Werte – daraus entsteht nur ein Fehlerprotokoll ohne Nutzen. Das Feld "email" im Körper ist davon unabhängig: Es ist die Adresse für die RÜCKMELDUNG an den Anwender. Ohne Angabe verwendet der Server die Lizenz-Adresse. ## Anfrage und Antwort Anfragekörper (application/json): { "title": "Export bricht bei großen Listen ab", // Pflicht, max. 255 Zeichen "body": "Ab etwa 5000 Zeilen …", // Pflicht, mind. 10 Zeichen "email": "anwender@example.com", // freiwillig, für Rückfragen "name": "Vorname Nachname", // freiwillig "app_version": "3.4.1", // aus deiner Anwendung "current_sha": "9f2c1ab…", // installierter Stand "os": "Windows 11 24H2", // Betriebssystem "severity": "high", // low | normal | high | critical "metadata": { "zeilen": 5231, "speicher_mb": 812 } // frei, höchstens 50 Felder } Antwort bei Erfolg (HTTP 201): { "ok": true, "reference": "BUG-8F3K2Q", "id": "", "message": "Der Fehlerbericht ist eingegangen." } Die "reference" ist die Nummer für Rückfragen. ZEIGE SIE DEM ANWENDER an und lege sie in deinem Protokoll ab – sie ist der einzige Faden, an dem er sich später auf seine Meldung beziehen kann. Fülle app_version, current_sha und os IMMER selbst aus deiner Anwendung. Diese drei Angaben entscheiden bei der Fehlersuche fast alles, und kein Anwender tippt sie freiwillig korrekt ab. ## Fehlerbehandlung Fehler kommen als JSON mit einem stabilen `code`. Prüfe auf `code`, NICHT auf den Meldungstext. 404 Dieser Meldeweg ist für dieses Programm nicht freigeschaltet. Blende die Schaltfläche dann dauerhaft aus, statt es erneut zu versuchen. Am besten einmalig beim Programmstart über GET https://api.loheide.cloud/v1/software ermitteln, welche Wege offen sind (Feld "endpoints" je Programm) und die Oberfläche danach aufbauen. 409 Dieselbe Meldung wird gerade schon verarbeitet (siehe Idempotency-Key weiter unten). Kurz warten, dann erneut - NICHT als Fehler anzeigen. 422 Eingabe unvollständig – Feld und Grund stehen in der Antwort. Zeige das direkt am betroffenen Formularfeld. 429 Zu viele Meldungen: 10 pro Stunde und Absender. Beachte Retry-After, versuche es NICHT sofort erneut und sage dem Anwender, dass er es später noch einmal probieren soll. 503 Der Server wird gerade aktualisiert. Meldung zwischenspeichern und später senden (siehe unten). ### Doppelte Meldungen vermeiden (wichtig) Erzeuge je Meldung EINMAL einen zufälligen Schlüssel (16 Zufallsbytes als Hex) und schicke ihn als Kopfzeile mit: Idempotency-Key: Denselben Wert bei JEDEM Wiederholungsversuch derselben Meldung mitschicken, auch nach einem Neustart des Programms - also zusammen mit der Meldung in der Warteschlange speichern, nicht daneben. Der Server merkt sich die Antwort und liefert bei einer Wiederholung dieselbe Ticketnummer zurück, statt ein zweites Ticket anzulegen. Ohne das entsteht der klassische Fehler: Die Antwort geht unterwegs verloren, dein Programm versucht es erneut - und die Meldung steht doppelt im System. Für eine NEUE Meldung immer einen NEUEN Schlüssel erzeugen; einen alten wiederzuverwenden beantwortet der Server mit 422. ## Oberfläche in der Anwendung Ein Menüpunkt „Hilfe → Rückmeldung geben" (oder gleichwertig, gut auffindbar) öffnet einen Dialog mit: - Auswahl der Meldungsart, aber NUR die freigeschalteten Wege anzeigen - Betreff und Beschreibung - freiwillige Rückmeldeadresse, als freiwillig gekennzeichnet - bei Fehlerberichten: Auswahl der Dringlichkeit - eine aufklappbare Anzeige „Diese technischen Angaben werden mitgesendet" mit dem tatsächlichen Inhalt von app_version, current_sha, os und metadata Der letzte Punkt ist nicht Verzierung, sondern Voraussetzung: Wer nicht sehen kann, was er verschickt, verschickt im Zweifel nichts. ### Datenschutz Sende in metadata keine personenbezogenen Daten, keine Dateipfade mit Benutzernamen und keine Inhalte aus Kundendokumenten. Willst du einen Logauszug mitschicken, zeige ihn vorher an und lass den Anwender zustimmen. Im Zweifel lieber weglassen – ein Fehlerbericht ohne Log ist immer noch nützlich, ein versehentlich übertragener Datensatz ist ein Vorfall. ### Wenn gerade kein Netz da ist Lege die Meldung in eine kleine lokale Warteschlange und versuche es beim nächsten Programmstart erneut. Höchstens fünf Versuche, dann verwerfen und den Anwender darüber informieren. Wichtig: Der Dialog darf NICHT hängen bleiben, während gesendet wird – bestätige sofort, sende im Hintergrund. ### Was der Dialog niemals tun darf - den Programmstart blockieren - bei einem Fehler die Eingabe des Anwenders verwerfen - ungefragt Dateien anhängen ## Datenschutzhinweis – Pflichtteil, nicht optional Eine Meldung überträgt personenbezogene Daten an einen Server, den der Anwender nicht betreibt – und zwar mehr, als ihm bewusst ist: Was in einem Bildschirmfoto oder Protokollauszug steht, sieht er im Moment des Anhängens nicht durch. Der Hinweis gehört deshalb sichtbar ÜBER den Absendeknopf, nicht hinter einen Verweis. Mit dem Absenden werden Daten an api.loheide.cloud übertragen. Übermittelt werden: • Ihr Text: Betreff und Beschreibung • Name und E-Mail-Adresse, soweit Sie sie angeben – für Rückfragen • Ihre Lizenzdaten, damit die Meldung Ihrem Konto zugeordnet werden kann • Programmversion, installierter Stand und Betriebssystem • die von Ihnen angehängten Dateien • technisch bedingt: Ihre IP-Adresse, Datum und Uhrzeit Bitte beachten: Was Sie in die Beschreibung schreiben und was in einem Bildschirmfoto oder Protokollauszug zu sehen ist, wird mit übertragen. Enthält es Namen, Adressen oder Vorgänge anderer Personen, entfernen Sie diese bitte vorher. Zweck: Bearbeitung Ihrer Meldung und Rückfragen dazu. Das Senden ist freiwillig; es geschieht nur, wenn Sie es hier auslösen. Regeln für die Umsetzung: - Text sichtbar anzeigen, nicht hinter „Mehr erfahren" verstecken. - Den Wortlaut übernehmen, nicht umschreiben. Er ist an dem ausgerichtet, was die Endpunkte tatsächlich entgegennehmen. - Sendet dein Client ein Feld NICHT – etwa keinen Rechnernamen –, streiche die entsprechende Zeile. Ein Hinweis, der mehr aufzählt als geschieht, ist genauso falsch wie einer, der etwas verschweigt. - Ist in der Anwendung eine eigene Datenschutzerklärung hinterlegt, verweise zusätzlich dorthin. - KEINEN zusätzlichen Zustimmungshaken. Das Absenden ist die Handlung des Anwenders; ein Haken davor ist eine Hürde ohne Zugewinn. - Zeige vor dem Absenden, WAS angehängt wird – Dateiname und Größe. Ein Anhang, den man nicht mehr sieht, wird nicht mehr geprüft. ## Abnahmekriterien - Der Dialog ist aus der Anwendung heraus in höchstens zwei Klicks erreichbar. - Nur freigeschaltete Meldewege erscheinen; 404 führt zum dauerhaften Ausblenden. - app_version, current_sha und os werden automatisch befüllt und sind vor dem Absenden einsehbar. - Nach erfolgreichem Absenden sieht der Anwender die Referenznummer. - 422 zeigt den Fehler am betroffenen Feld, 429 nennt die Wartezeit. - Ohne Netz wird die Meldung zwischengespeichert und später gesendet. - Ein Fehler beim Senden verwirft die eingegebene Beschreibung nicht. - eine abgelaufene oder falsche Lizenz verhindert das Absenden NICHT - ohne hinterlegte Lizenz werden gar keine Lizenz-Kopfzeilen gesendet Automatisierte Tests für: Aufbau des Anfragekörpers, Behandlung von 201, 404, 422, 429 und 503, sowie die Warteschlange (einreihen, erneut senden, aufgeben). Erkläre am Ende kurz, welche Dateien du angelegt hast und wo der Menüpunkt sitzt.