327 lines
15 KiB
Markdown
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
|