Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M39-help-desk.md
T

15 KiB

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
39 Help-Desk / Support 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-6
LP-9
LP-10
requirements-pur

Modul 39 — Help-Desk / Support

Detail-Spec gemäß LP-9. Phase 1 basic: Support-Email-Mailbox sichtbar im Plattform-Admin (Modul 37) und ein einfaches In-App-Feedback-Widget („Problem melden"), dessen Submissions im Plattform-Admin landen. Kein Ticket-System, kein Live-Chat, kein User-facing-Status-Tracking in Phase 1.

Themenblöcke

A. Datenmodell (Feedback)
B. In-App-Feedback-Widget (Tenant-Seite)
C. Support-Mailbox (Plattform-Admin-Seite)
D. Plattform-Admin-Feedback-Liste
E. Permissions
F. Phase 2

Block A — Datenmodell

A.1 — Feedback (zentrale Tabelle)

Tabelle: Feedback. Liegt im Plattform-Admin-Datenraum (kein RLS auf Tenant-Ebene; siehe Modul 27 A.4 — Sonderfall „kein Tenant-RLS, App-Code permission-gegated"). tenant_id und user_id sind referenziell vorhanden, aber Lese-Zugriff über Plattform-Admin-Permissions, nicht über Tenant-Permissions.

Felder:

  • id, created_at, updated_at
  • tenant_id (FK Tenant — von welchem Tenant kam das Feedback)
  • tenant_user_id (FK TenantUser — welcher User; nullable falls Feedback in nicht-eingeloggtem Kontext, in Phase 1 aber Pflicht da Widget nur eingeloggt funktioniert)
  • body (Pflicht, Freitext-Beschreibung des Problems)
  • route_path (Pflicht, der App-Pfad auf dem das Widget ausgelöst wurde, z.B. /{tenant}/projects/abc-123)
  • browser_info (JSON: User-Agent, Viewport-Size, Screen-Size, Browser-Sprache, Timezone — automatisch befüllt)
  • app_version (semver/Build-Hash der App-Version zum Zeitpunkt der Meldung)
  • attachments[] (FK auf File-Records, siehe A.3)
  • status (Enum: open | in_progress | resolved | wontfix)
  • assignee_admin_user_id (FK auf AdminUser, nullable — Plattform-Admin der das Feedback bearbeitet)
  • internal_notes (Markdown-Freitext, nur Plattform-Admin sichtbar)
  • resolved_at, resolved_by_admin_user_id

Indizes:

  • (status, created_at DESC) für Default-Liste
  • (tenant_id, created_at DESC) für Filter pro Tenant
  • (assignee_admin_user_id, status) für „meine offenen Tickets"

A.2 — Status-Lifecycle

open          → neu eingegangen, ungesehen oder gesehen aber unbearbeitet
in_progress   → Plattform-Admin hat sich zugewiesen, arbeitet dran
resolved      → behoben (Bug-Fix, Erklärung an User, etc.)
wontfix       → bewusst nicht behoben (Duplikat, kein Bug, falscher Kontext, etc.)

Übergänge:

  • open → in_progress: Plattform-Admin ordnet sich zu
  • open/in_progress → resolved: Plattform-Admin markiert als gelöst
  • open/in_progress → wontfix: Plattform-Admin verwirft
  • resolved/wontfix → open: Plattform-Admin re-opens

In Phase 1 keine Notifications zurück an den Tenant-User über Status-Änderungen.

A.3 — Attachments

  • Wiederverwendet die File-Infrastruktur aus Modul 23 (Files / Dokumente)
  • Storage-Pfad: tenants/{tenantId}/feedback/{feedbackId}/...
  • Erlaubte Typen: PNG, JPG, WEBP, PDF (Phase 1)
  • Max. 5 Attachments pro Feedback, max. 10 MB pro File
  • Auto-Screenshot der aktuellen Page wird angeboten (Browser-API, optional, mit User-Bestätigung)

Block B — In-App-Feedback-Widget (Tenant-Seite)

B.1 — Auslöse-Funktion

Zu zeigende UI-Element-Anforderungen (Designer-Entscheidung wo platziert):

  • Feedback-Trigger-Funktion („Problem melden"-Button/Icon) überall in der App verfügbar — von jeder Tenant-Route aus erreichbar (z.B. global in Top-Bar oder als Floating-Action-Button, Designer entscheidet)
  • Gleiche Trigger-Funktion in /help/-Routen (öffentlich) — aber dort verlinkt auf mailto:support@hivegrid.de (kein Login → kein Tenant-Context)

B.2 — Eingabe-Modal

Zu zeigende Daten:

  • Hinweis-Text „Was hakt? Wir lesen jedes Feedback persönlich."
  • Aktuelle Route-Path-Anzeige (read-only, zeigt User wo er gerade ist — Transparenz, dass wir das mit-erfassen)
  • Hinweis-Text dass Browser-Info + App-Version mitgeschickt werden (DSGVO-Transparenz)

Benötigte UI-Elemente:

  • Multi-line-Text-Input für Beschreibung (Pflicht, min. 10 Zeichen)
  • Attachment-Upload-Komponente (Drag&Drop + Klassischer-Datei-Wähler, max. 5 Files)
  • „Screenshot der aktuellen Seite anhängen"-Funktion (One-Click, fügt automatisch generierten Screenshot als Attachment hinzu)
  • Send-Button (disabled bis Beschreibung ≥ 10 Zeichen)
  • Cancel-Button
  • Klartext-Hinweis bei Send-Erfolg: „Danke. Wir haben dein Feedback bekommen und melden uns falls nötig."
  • Klartext-Hinweis bei Fehler: „Senden hat nicht geklappt — du kannst uns auch direkt schreiben: support@hivegrid.de"

Operationen:

  • Senden → POST an internen API-Endpoint → Feedback-Record erstellt → Plattform-Admin sieht in Liste
  • Cancel → Modal schließt, kein Datenverlust-Warning (Phase 1 sehr basic)

B.3 — Auto-Befüllung (Code-internal)

Bei Submit wird automatisch erfasst:

  • tenant_id aus aktuellem Tenant-Context
  • tenant_user_id aus Session
  • route_path aus aktuellem URL-Path (ohne Query-Params um keine Tokens/IDs durchzuleaken — Plattform-Admin entscheidet pro Fall ob Query-Param-Sample relevant ist; Phase 2 erweiterbar)
  • browser_info aus User-Agent + Viewport (Standard-Browser-API)
  • app_version aus Build-Hash (eingebettet zur Build-Zeit)
  • created_at server-side

B.4 — Klartext-Hinweise

  • Beschreibung zu kurz: „Bitte mindestens 10 Zeichen — je mehr Details, desto schneller können wir helfen."
  • Attachment zu groß: „Datei zu groß (max. 10 MB). Beschneide sie oder lass sie weg — wir können trotzdem helfen."
  • Senden fehlgeschlagen: „Senden hat nicht geklappt — Internet-Verbindung prüfen oder direkt an support@hivegrid.de mailen."
  • Rate-Limit erreicht (max. 10 Submissions/User/h): „Du hast schon einige Meldungen in kurzer Zeit gesendet. Bitte warte kurz oder schreib uns direkt."

B.5 — Performance / Limit

  • Rate-Limit pro tenant_user_id: max. 10 Submissions/h, hard-block sonst
  • Body-Größenlimit: 10.000 Zeichen
  • Submit ist async, Modal-Close direkt nach API-OK (keine Blockade im UI)

Block C — Support-Mailbox

C.1 — Adresse + Anbindung

  • Inbound-Mailbox: support@hivegrid.de
  • Routing: ankommende Mails landen in einer dedizierten Mail-Postbox (z.B. Google Workspace oder Scaleway-Mail-Service)
  • Phase 1: Mailbox wird außerhalb der App (z.B. via Gmail-Web) gelesen — keine eigene Mail-UI in HiveGrid für Phase 1
  • Plattform-Admin-Bereich (Modul 37) zeigt nur einen Direkt-Link auf die externe Mailbox + Klartext-Hinweis „Externe Support-Mailbox via Google Workspace / [...]"

Konsequenz: keine eigene Mail-Sync-Implementierung für Support-Mailbox in Phase 1 (Aufwand-Begrenzung).

C.2 — Verknüpfung Mail ↔ Feedback

In Phase 1 keine automatische Verknüpfung. Support-Email-Antworten sind manuell zu führen.

Phase 2: Mail-Sync via Email-Integration (Modul 9) — Mails landen direkt in Feedback-System mit Status-Tracking und Reply-Funktion.


Block D — Plattform-Admin-Feedback-Liste

D.1 — Routes

Sidebar-Hauptpunkt im Plattform-Admin (Modul 37): Feedback / Support.

admin.hivegrid.de/feedback/                   → Liste aller Feedback-Submissions
admin.hivegrid.de/feedback/:id                → Detail-View einer Submission
admin.hivegrid.de/feedback/mailbox            → Direkt-Link auf externe Support-Mailbox (Phase 1)

D.2 — Liste (/feedback/)

Zu zeigende Daten pro Eintrag:

  • Eingangs-Datum/-Uhrzeit
  • Tenant-Name
  • User-Name + Email
  • Erste 100 Zeichen des Body
  • Anzahl Attachments
  • Route-Path (verkürzt)
  • Status (visuell unterscheidbar)
  • Assignee (falls zugewiesen)

Benötigte UI-Elemente:

  • Tabellarische Liste, sortierbar nach Datum (Default: neueste zuerst)
  • Filter:
    • Status (Multi-Select: open / in_progress / resolved / wontfix)
    • Tenant (Auto-Complete aus Tenant-Liste)
    • Assignee (Multi-Select)
    • Zeitraum (Date-Range-Picker)
  • Volltext-Suche über body + Tenant-Name + User-Name
  • Pagination (50 pro Page, Cursor-basiert)
  • Bulk-Auswahl + Bulk-Status-Wechsel + Bulk-Assign

Operationen:

  • Klick auf Zeile → Detail-View
  • Bulk-Status-Update
  • Bulk-Assign zu Plattform-Admin
  • Export als CSV (gefilterte Auswahl)

Performance:

  • Default-Liste indexiert über (status, created_at DESC)
  • Bei vielen offenen Tickets: separate „Meine offenen"-View mit Index (assignee_admin_user_id, status, created_at DESC)

D.3 — Detail-View (/feedback/:id)

Zu zeigende Daten:

  • Vollständiger Body
  • Attachments mit Vorschau (Bild-Inline-Anzeige, PDF-Download-Link)
  • Tenant-Block: Name, Plan, Status, Direktlink ins Tenant-Admin (Modul 37)
  • User-Block: Name, Email, Rolle im Tenant, Direktlink ins Tenant-Admin
  • Route-Path mit klickbarem Direktlink (für Plattform-Admin der Impersonation hat — Modul 37)
  • Browser-Info (User-Agent, Viewport, etc.) ausklappbar
  • App-Version
  • Status + Assignee (editierbar)
  • Internal-Notes (Markdown-Freitext, nur Plattform-Admin)
  • Activity-Log: alle Status-Wechsel, Assignee-Wechsel, Notes-Änderungen mit Timestamp + Actor

Benötigte UI-Elemente:

  • Body-Anzeige (mit URL-Link-Detection, kein Markdown-Rendering — User-Eingaben sind plain text)
  • Attachment-Preview-Komponente (Image/PDF)
  • Inline-Edit für Status + Assignee + Internal-Notes
  • Sektion „Tenant-Kontext" mit Direktlinks
  • Sektion „Browser-/Tech-Kontext" (ausklappbar)
  • Sektion „Aktivitäten" (Activity-Stream-Komponente analog Modul 1 Block E, scope: nur dieses Feedback)

Operationen:

  • Status setzen (open / in_progress / resolved / wontfix)
  • Assignee zuordnen (Plattform-Admin)
  • Internal-Notes editieren (Markdown)
  • Attachment downloaden
  • Direktlink ins Tenant öffnen (Modul 37 Impersonation)
  • Hard-Delete (mit Klartext-Warnung — nur in Ausnahmefällen, z.B. PII-Verstoß)

Klartext-Hinweise:

  • Tenant inzwischen gelöscht: „Dieser Tenant wurde inzwischen gelöscht — Daten zu User/Tenant nur noch eingeschränkt verfügbar."
  • User inzwischen entfernt: „Dieser User ist nicht mehr Mitglied dieses Tenants."

Block E — Permissions-Anwendung

E.1 — Tenant-Seite (Feedback senden)

Permission Erlaubt
(keine spezielle Permission) Jeder eingeloggte Tenant-User kann Feedback senden

Begründung: „Problem melden" ist eine basale Funktion, kein Premium-Feature, keine Berechtigung nötig. Rate-Limit greift technisch.

E.2 — Plattform-Admin-Seite (Feedback lesen + bearbeiten)

Permission Erlaubt
platform_admin.feedback.read Liste + Detail-View aller Feedbacks
platform_admin.feedback.write Status setzen, Assignee zuordnen, Internal-Notes editieren
platform_admin.feedback.delete Feedback hard-löschen

Bundle-Mapping:

Bundle Atomare Permissions
platform_admin.support.full platform_admin.feedback.read + platform_admin.feedback.write
platform_admin.super alle

Anwendung in Routes:

  • admin.hivegrid.de/feedback/* → platform_admin.feedback.read minimum

Klartext-Fehler:

  • Plattform-Admin ohne Permission greift auf /feedback/: 404 (nicht 403)
  • Tenant-User ohne Login greift auf Submit-API: 401 mit Klartext „Bitte einloggen, um Feedback zu senden."

Block F — Klartext-Hinweise / Fehler-Cases

  • Submit-API-Fehler 5xx: „Senden hat nicht geklappt — bitte direkt an support@hivegrid.de schreiben."
  • Rate-Limit-Hit (Tenant-User): „Du hast schon einige Meldungen in kurzer Zeit gesendet. Bitte warte kurz oder schreib uns direkt."
  • Attachment-Upload-Fehler: „Datei konnte nicht hochgeladen werden ({reason}). Probier ein anderes Format."
  • Tenant inaktiv (frozen/suspended): Submit blockiert mit Klartext „Dein Workspace ist derzeit pausiert. Schreib uns direkt: support@hivegrid.de"

Block G — Activity-Stream-Integration

Phase 1: keine Tenant-seitige Activity (Feedback ist privater Vorgang Tenant↔Plattform). Kein Eintrag im Tenant-Activity-Stream.

Plattform-Admin-Audit-Log (Modul 21 Plattform-Variante) loggt:

  • feedback.received (System-Event bei Submit)
  • feedback.status_changed (mit Diff)
  • feedback.assigned (mit User-Diff)
  • feedback.deleted

Block H — Phase 2 / spätere Features

  • In-App-Live-Chat mit Support (Intercom-/Crisp-Style; entweder Eigen-Implementierung oder eingebettetes Drittprodukt)
  • Vollständiges Ticket-System mit Status-Tracking + Notifications zurück an User (Email + In-App-Notification)
  • User-facing-Status-Page im Tenant: Liste seiner eigenen Feedbacks mit Status, kann antworten
  • NPS-Surveys (1x/Quartal, in-App-Pop-up, anonymisiert ans Plattform-Team)
  • CSAT-Tracking pro Resolved-Feedback (1-5-Sterne nach Resolution)
  • Support-Mailbox-Sync in der App über Modul 9 (Email-Integration) — Mails landen direkt in Feedback-Liste
  • Auto-Triage durch KI: beim Submit klassifiziert KI das Feedback (Bug / Feature-Request / Frage / Beschwerde) und schlägt Zuordnung vor
  • Feedback-Voting: ähnliche Feedbacks werden zusammengefasst, andere Tenants können „+1" geben (Public-Roadmap-Feel)
  • Integration mit Bug-Tracker (Linear / Jira / GitHub-Issues): Feedback → Issue mit Backlink
  • Slack-Notification an Plattform-Team-Channel bei neuem Feedback (Phase 1 evtl. schon manuell via Webhook anbindbar)

Block I — Architektur-Vorschriften (Querschnitt)

  • LP-6: Anti-Agentur-Positionierung — niedrige Hürde Feedback zu senden ist Teil von „Selbst-Wartbarkeit". User soll spüren: wir hören zu.
  • LP-9: Spec-Tiefe — Datenmodell + Permissions explizit festgelegt
  • LP-10: Klartext-Diagnostik — alle Fehler-Cases mit menschenlesbarem Text
  • AV #6 (Audit-Trail-Default): alle Status-/Assignee-/Notes-Änderungen geloggt
  • DSGVO-Transparenz: User wird im Modal informiert was mitgeschickt wird (Browser-Info, App-Version, Route-Path)

Detail-Spec-Status: DRAFT

Phase-1-Modul bewusst klein. Vor Bau:

  • Submit-API-Endpoint definieren (POST /api/internal/feedback)
  • Auto-Screenshot-Implementierung wählen (z.B. html2canvas clientseitig, mit User-Consent)
  • Verknüpfung mit File-Infrastruktur aus Modul 23 für Attachments
  • Plattform-Admin-Permissions konkretisieren (im Rahmen Modul 37)

Offene Detail-Punkte (nicht-blockierend):

  • Externe Support-Mailbox-Provider entscheiden (Google Workspace empfohlen, da konsistent mit Geerkens-Setup)
  • Rate-Limit-Werte ggf. nach erstem Live-Feedback-Volumen anpassen
  • Attachment-Storage-Pfad-Konvention bestätigen (sollte mit Modul 23 konsistent sein)
  • Ob Submit auch ohne Login möglich sein soll (z.B. von /help/-Public-Routes) — Phase 1 Empfehlung: nein, Public verweist auf mailto-Link