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 |
|
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_attenant_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 zuopen/in_progress → resolved: Plattform-Admin markiert als gelöstopen/in_progress → wontfix: Plattform-Admin verwirftresolved/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_idaus aktuellem Tenant-Contexttenant_user_idaus Sessionroute_pathaus 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_infoaus User-Agent + Viewport (Standard-Browser-API)app_versionaus Build-Hash (eingebettet zur Build-Zeit)created_atserver-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.readminimum
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.
html2canvasclientseitig, 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