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

327 lines
15 KiB
Markdown

---
module: 39
title: Help-Desk / Support
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-6, LP-9, LP-10]
spec_style: 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