Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/designer-briefs/P29-help-center-help-desk.md
T

4.1 KiB
Raw Blame History

Designer-Brief · P29 — Help-Center & Help-Desk

Phase: 29/34 · Module: M38/M39 (M172–M175) · Owner-Dev: Akeshan (VA-P29) · Designer: David (D-Help) Quellen: ROADMAP-V2.md §v2-P9 · ROADMAP.md §Phase 29 · _bmad-output/specs/M38-help-center.md · _bmad-output/specs/M39-help-desk.md Subframe: Pflicht je Route. Öffentliche Help-Routen + In-App-Widget + interne Admin-Flächen.

🔵 Bewusst klein (Phase 1): Help-Center = Markdown-Artikel im Repo via Git-PRs (kein Editor-UI), Build-Time-Index, ~10–20 Artikel, primär Deutsch. Help-Desk = Email-Ticket-System basic + In-App-Feedback-Widget → landet im Plattform-Admin (kein User-facing-Status-Tracking, kein Live-Chat in Phase 1). Feedback liegt im Plattform-Admin-Datenraum (kein Tenant-RLS, App-Code permission-gegated). Help-Artikel werden rückwirkend RAG-Korpus für P25/v2-P4.

Was dieses Modul tut (Kurzfassung)

Öffentliches, file-basiertes Help-Center mit SEO-Routen (/help/{lang}/{category}/{slug}, ohne Auth, vor der Auth-Middleware), Volltext-Suche und Build-Time-Index (Build-Fail bei kaputten Referenzen). Aus jeder App-Route führt ein Hilfe-Icon per Deep-Link zum passenden Artikel (Fallback Help-Home). Ein überall erreichbares Feedback-Widget („Problem melden") erzeugt Feedback-Einträge mit Auto-Kontext (tenant/user/route/browser/app-version) und optionalem Screenshot; die Plattform-Admin-Seite verwaltet Feedback als Liste + Detail mit Status-Lifecycle/Assignee/Notes/Attachments und Audit.

Benötigte Screens

Screen [Route] Kern-Inhalt Archetyp
Help-Home [/help/{lang}/] Hero, Such-Eingang, Kategorien-Übersicht, öffentlich (kein Tenant-Context) A-Public
Kategorie-Seite [/help/{lang}/{category}/] Liste der Artikel einer Kategorie, Kategorie-Metadaten A2-Public
Artikel-Detail [/help/{lang}/{category}/{slug}] Markdown-Inhalt, TOC, verwandte Artikel, Vote (hilfreich?), SEO-Meta/Canonical A3-Public
Such-Ergebnisse [/help/{lang}/search?q=] Volltext-Treffer mit Snippets, Kategorie-Zuordnung A2-Public
Feedback-Widget [Modal, überall] „Problem melden"-Trigger (global erreichbar), Freitext, Screenshot-One-Click-Anhang, Erfolgs-Hinweis A5
Admin-Feedback-Liste [admin.hivegrid.de/support] Feedback-Liste mit Status, Assignee, Quelle, Datum, Filter A2
Admin-Feedback-Detail [admin.hivegrid.de/support/:ticketId] Status-Lifecycle, Assignee, interne Notes, Auto-Kontext (route/browser/app-version), Attachments, Audit A3

Geplante Features (muss abgedeckt sein)

  • Markdown mit Frontmatter, Build-Time-Index (Volltext + Kategorien + Sitemap), Build-Fail bei kaputten Referenzen/related_slug
  • Öffentliche Routen /help/{lang}/{category}/{slug} ohne Auth (vor Auth-Middleware), SEO-Defaults (title/description/canonical), Suche
  • Deep-Link Route→Artikel (Hilfe-Icon pro App-Route, Fallback Help-Home)
  • Feedback-Widget überall → Feedback mit Auto-Kontext (tenant/user/route/browser/app-version), Screenshot-Option, Rate-Limit 10/h
  • Plattform-Admin: Feedback-Liste + Detail (Status-Lifecycle/Assignee/Notes/Attachments) mit Audit
  • Help-Artikel als RAG-Korpus an P25/v2-P4 registrierbar (Embedding-Quelle)

Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)

Such-Eingabe mit Auto-Suggest, Kategorie-Kacheln/-Liste, Artikel-Renderer (Markdown) mit Inhaltsverzeichnis, „War das hilfreich?"-Vote, Breadcrumb, Hilfe-Icon (in-App, deep-link-fähig), Feedback-Trigger (Button/FAB, global), Feedback-Formular (Freitext + Screenshot-One-Click), Erfolgs-/Rate-Limit-Hinweis (Klartext), Admin-Daten-Tabelle (Status-Filter), Status-Lifecycle-Badge, Assignee-Auswahl, Notiz-Liste, Attachment-Vorschau, Empty-/Loading-/Permission-Denied-States (Klartext).

Davids Delta (David füllt aus)

  • Überschriebene/geänderte Spec-Punkte:
  • Neue UI/UX-Entscheidungen:
  • Subframe-Screen-Link(s):
  • Offene Fragen an Dev:

Dev-Nachzug (wir nach Davids Delta)

  • Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
  • REQUIREMENTS/PHASE-SOURCES nachgezogen:
  • Plane-Ticket (VA-P29) aktualisiert: