Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VA-P29.md
T

5.7 KiB

VA-P29 · P29 Help-Center + Help-Desk

⚠️ KI→MCP-Pivot (AD-26): Der RAG-Korpus-Andock entfällt (kein RAG/Embedding mehr — alter VR-P25-Scope zurückgestellt, HiveGrid wird MCP-Server, VR-MCP). Das Help-Center bleibt voll funktional (Artikel + Suche). Optional können Help-Artikel später als MCP-Resource exponiert werden. RAG-Stellen unten durchgestrichen.

Typ Dev (Code)
Owner Akeshan
Phase P29 — Help-Center & Help-Desk · v2-P9
Cycle/Fenster v2-W3 — Admin/Help/Dashboard/v2-Launch · fällig 2026-07-30
Status geplant

Abhängigkeiten & Parallelität

  • Blocked by: AK-P21 (v1-Feedback-Widget → Support-Inbox als generische Quelle/Andockpunkt), AK-P19 (Plattform-Admin — Admin-Permissions + AdminAuditLog)
  • Blocks: VJ-2 (Website — Help-Center-Verlinkung/SEO) , alter VR-P25-Scope (KI-Tiefe — Help-Artikel als RAG-Korpus, retro) → entfällt (AD-26: RAG-Korpus gestrichen; optional als MCP-Resource via VR-MCP)
  • Läuft parallel zu: VA-P28b / VA-P30a/b (Akeshans W3-Tickets) — disjunkte Domänen. Feedback liegt im Plattform-Admin-Datenraum (kein Tenant-RLS, App-Code permission-gegated).
  • Konflikt-Risiko: gering — öffentliche Help-Routen vor der Auth-Middleware, additiv; Feedback erweitert den v1-Support-Ticket-Andockpunkt.

Was wir bauen

Ein öffentliches, file-basiertes Help-Center (Markdown-Artikel im Repo via Git-PRs, kein Editor-UI) 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. Ein überall erreichbares Feedback-Widget erzeugt Feedback-Einträge mit Auto-Kontext; die Plattform-Admin-Seite verwaltet Feedback als Liste + Detail mit Status-Lifecycle/Assignee/Notes/Attachments und Audit. Bewusst klein (Phase 1) — kein Live-Chat, kein User-facing-Status-Tracking.

Benötigte Screens (Backend bedient — Design liefert D-P29)

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

Definition of Done

  • 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 alten v2-P4-KI-Scope registrierbar (Embedding-Quelle) → entfällt (AD-26); optional später als MCP-Resource (VR-MCP)

Technische Bausteine

  • Help-Center (file-basiert, keine eigene .prisma): Markdown + Frontmatter im Repo; Build-Time-Index (Volltext/Kategorien/Sitemap) mit Build-Fail bei kaputten related_slug-Referenzen. Öffentliche Routen vor der Auth-Middleware + IP-Rate-Limiting.
  • Feedback (Plattform-Admin-Datenraum, KEIN Tenant-RLS): AdminSupportTicket (+ Message) mit source_kind (in_app_feedback_widget/inbound_email), tenant_id, status, priority — speist sich aus dem Feedback-Widget; Attachments → v1-Files. App-Code permission-gegated über Admin-Permissions (AK-P19) + AdminAuditLog.
  • Feedback-Widget: global erreichbarer Trigger → erzeugt Ticket mit Auto-Kontext (tenant/user/route/browser/app-version) + optionalem Screenshot; Rate-Limit 10/h.
  • Deep-Link: Hilfe-Icon pro App-Route mappt Route→Artikel-Slug (Fallback Help-Home).
  • RAG-Andockpunkt: Help-Artikel als Embedding-Quelle für P25 registrierbar (retro, kein harter Forward-Dep). → entfällt (AD-26); Help-Artikel optional als MCP-Resource (VR-MCP).

Quellen (granular)

  • ROADMAP-V2.md → §v2-P9 Help-Center & Help-Desk (Routen/Index/Feedback = Hauptquelle; Recut „bewusst klein")
  • ENTITY-MODEL.md → Domäne 11 AdminSupportTicket (+ Message) (source_kind in_app_feedback_widget/inbound_email, speist sich aus Feedback-Widget) + AdminAuditLog
  • ROADMAP.md → Phase 29 · Milestones: (M172 Markdown-Artikel Git-PRs, M173 Routes/Suche/SEO/kontextuelle Hilfe, M174 Email-Ticket-System, M175 In-App-Feedback-Widget)
  • designer-briefs/P29-help-center-help-desk.md (öffentliche Help-Routen, Feedback-Widget, Admin-Feedback-Liste/Detail, Phase-1-Grenze)

Dev-Nachzug (nach Davids D-P29-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket VA-P29 aktualisiert