Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M38-help-center.md
T
2026-07-08 16:15:37 +02:00

11 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
38 Help-Center (öffentlich) 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-9
LP-10
LP-12
LP-13
requirements-pur

Modul 38 — Help-Center (öffentlich)

Detail-Spec gemäß LP-9. HiveGrids eigene öffentliche Hilfeseite für Tenant-User (Erste Schritte, Setup-Anleitungen, FAQ). Nicht zu verwechseln mit M16 Knowledge-Base (= tenant-internes Wiki, Phase 2). Phase 1 minimal: Markdown-Files im Repo, ~10-20 Artikel, nur Deutsch.

Themenblöcke

A. Datenmodell (file-basiert, nicht DB)
B. Routen + URL-Struktur
C. Listen-View / Kategorien-Übersicht
D. Detail-View / Artikel-Seite
E. Suche
F. Verlinkung aus der App (Deep-Links)
G. Permissions
H. Phase 2

Block A — Datenmodell

A.1 — File-basierter Ansatz (Phase 1)

Help-Center-Inhalte werden nicht in der DB gepflegt, sondern als Markdown-Files im Repository abgelegt. Pflege erfolgt über Git-PRs durch das Plattform-Team. Keine Editor-UI in Phase 1.

Verzeichnis-Struktur (Vorgabe):

content/help/
  de/
    erste-schritte/
      _category.json           → Kategorie-Metadaten
      willkommen.md
      tenant-einrichten.md
    vertrieb/
      _category.json
      crm-kontakt-anlegen.md
      ...
    ...

A.2 — Markdown-File-Format

Jede .md-Datei beginnt mit YAML-Frontmatter:

---
slug: kwp-setup
title: KWP-Integration einrichten
category: integrationen
order: 10
description: Schritt-für-Schritt-Anleitung zur Verbindung von HiveGrid mit deiner KWP-Anlage.
last_updated: 2026-05-08
related_slugs: [kwp-troubleshooting, sandra-rechnungs-flow]
keywords: [kwp, erp, integration, anlage, setup]
---

Pflicht-Frontmatter-Felder: slug, title, category, order, description, last_updated. Optional: related_slugs, keywords, deprecated (Boolean), redirect_to.

Body: Standard-Markdown. Erlaubt: Headings (h2-h4), Bold/Italic, Listen, Code-Blocks, Tabellen, Bilder, Links, Callout-Blocks (> [!info] / > [!warning]).

A.3 — Kategorie-Metadaten (_category.json)

{
  "slug": "integrationen",
  "label": "Integrationen",
  "description": "Anbindung externer Systeme (KWP, Google, AirCall, ...)",
  "icon": "plug",
  "order": 50
}

A.4 — Build-Time-Index

Build-Schritt erzeugt:

  • Volltext-Index (Lunr.js / FlexSearch oder Postgres-FTS in einer Helper-Tabelle, falls Server-Side-Suche bevorzugt)
  • Kategorien-Manifest (alle Kategorien + Artikel pro Kategorie, sortiert)
  • Sitemap (/help/sitemap.xml)

Index wird im Build geprüft (jede Kategorie-Referenz aus Frontmatter muss existieren, jeder related_slug muss existieren, sonst Build-Fail).

A.5 — Phase-1-Artikel-Inventar (initial ~10-20)

Erste Schritte: Willkommen, Tenant einrichten, Erste Mitarbeiter einladen, Magic-Link-Login-FAQ Vertrieb: Kontakte und Firmen, Lead-Inbox-Workflow, Sales-Pipeline-Grundlagen Aufträge: Projekt anlegen, Plantafel nutzen, Acceptance-Protokoll-Anleitung Mitarbeiter: HR-Hub-Übersicht, Krankmeldung/Urlaubsantrag stellen Integrationen: KWP-Setup, Google-Kalender verbinden, AirCall-Setup, Email-Integration (Gmail/Outlook) Mobile: Mobile-App-Setup, Offline-Modus auf Baustelle Abrechnung: Legacy-Provider-Setup, Plan wechseln, Rechnungen einsehen Tutorials: Form-Builder-Tutorial, Automation-Builder-Tutorial

(Konkrete Liste wird mit Plattform-Team beim Bau finalisiert.)


Block B — Routen

Sidebar-Hauptpunkt: (keiner — Help-Center ist außerhalb des Tenant-Sidebar-Kontexts erreichbar).

Routen:

app.hivegrid.de/help/                              → Redirect auf /help/de/
app.hivegrid.de/help/{lang}/                       → Help-Home (Kategorien-Übersicht + Suche)
app.hivegrid.de/help/{lang}/{category}/            → Kategorie-Übersicht (Liste der Artikel)
app.hivegrid.de/help/{lang}/{category}/{slug}      → Artikel-Detail
app.hivegrid.de/help/{lang}/search?q=...           → Such-Ergebnisse
app.hivegrid.de/help/sitemap.xml                   → SEO-Sitemap

Phase 1 nur lang = de. Andere Sprachen würfeln 404 mit Klartext-Hinweis.

Öffentlich: keine Auth nötig, Routen sind public, kein Tenant-Context.

SEO-Defaults:

  • Statisches Rendering (SSG oder SSR mit langem Cache-Header)
  • Pro Artikel: <title> aus Frontmatter, <meta name="description"> aus Frontmatter
  • Open-Graph-Tags
  • Canonical-URL pro Artikel

Block C — Kategorien-Übersicht (Help-Home + Kategorie-Seite)

Help-Home (/help/de/)

Zu zeigende Daten:

  • Hero-Bereich mit Such-Funktion
  • Kategorien-Liste mit Label, Description, Icon, Anzahl Artikel
  • Optional: „Beliebteste Artikel"-Block (Phase 1: manuell-kuratierte Liste, Phase 2: View-Counts)

Benötigte UI-Elemente:

  • Such-Eingabefeld (zentral platziert)
  • Kategorie-Karten/-Liste (klickbar)
  • Footer mit Link zu „Support kontaktieren" → triggert In-App-Feedback-Widget oder mailto:support@hivegrid.de

Kategorie-Seite (/help/de/{category}/)

Zu zeigende Daten:

  • Kategorie-Label + Description
  • Liste aller Artikel in dieser Kategorie, sortiert nach order
  • Pro Artikel: Title, Description, ggf. last_updated-Datum

Benötigte UI-Elemente:

  • Such-Eingabefeld
  • Artikel-Liste (klickbar)
  • Breadcrumb (Help / Kategorie)

Block D — Artikel-Detail (/help/de/{category}/{slug})

Zu zeigende Daten:

  • Title, Description, last_updated-Datum
  • Markdown-Body (gerendert als HTML)
  • Verwandte Artikel (related_slugs) als Liste
  • „War dieser Artikel hilfreich?"-Feedback (optional, sehr einfach: Daumen hoch/runter, anonym tracked als Klicks ohne PII)

Benötigte UI-Elemente:

  • Markdown-Renderer mit Support für: Headings, Listen, Bold/Italic, Code-Blocks (mit Syntax-Highlighting für Bash/JSON/YAML), Tabellen, Bilder (responsive), Links (External-Link-Indicator), Callout-Blocks (Info/Warning/Tip)
  • Inhaltsverzeichnis (TOC) aus h2-Headings, klickbar/scrollbar
  • Breadcrumb (Help / Kategorie / Artikel)
  • Such-Eingabefeld (im Header)
  • „Verwandte Artikel"-Sektion am Ende
  • Optional: Edit-on-GitHub-Link (führt zur Markdown-Quelle für Plattform-Team)

Operationen:

  • Lesen (read-only — kein Login, keine Edit-Funktion in Phase 1)
  • Drucken (Browser-nativ)
  • Link kopieren

Klartext-Hinweise:

  • Artikel mit deprecated: true: Banner „Dieser Artikel ist veraltet — siehe stattdessen [neuer Link]"
  • 404 (Slug existiert nicht): Klartext-Page „Diesen Artikel gibt's nicht mehr. Vielleicht hilft die Suche?" + Such-Eingabefeld

Block E — Suche

Such-Funktion

Verhalten:

  • Eingabe → Such-Ergebnis-Page mit Treffern, ranked nach Relevanz
  • Ranking: Title-Match > Description-Match > Keyword-Match > Body-Match
  • Highlight des Such-Treffers im Snippet
  • Empty-State bei keinen Treffern: „Nichts gefunden zu '{query}'. Schreib uns: support@hivegrid.de"

Benötigte UI-Elemente:

  • Such-Eingabefeld (auf allen Help-Routen verfügbar)
  • Ergebnis-Liste mit: Title, Kategorie-Label, Snippet (mit Highlight), Link
  • Pagination (selten benötigt bei Phase-1-Volumen, aber sauber vorbereitet)

Performance:

  • Index wird beim Build erzeugt
  • Phase 1: Client-side-Suche via FlexSearch (~50KB Index für 20 Artikel) ODER Server-side über Postgres-FTS-View (nice-to-have)
  • Debounce auf Eingabe (300ms)

Hilfe-Icon-Pattern

Jede App-Route kann ein optionales Hilfe-Icon zeigen (Plazierung Designer-Entscheidung). Klick öffnet:

  • Deep-Link in neuem Tab: app.hivegrid.de/help/de/{category}/{slug}
  • Deep-Link wird pro Route in einer Mapping-Konfiguration gepflegt

Konfigurations-Beispiel (Code-internal):

{
  "/{tenant}/automation/builder": "automatisierungen/automation-builder-tutorial",
  "/{tenant}/integrations/kwp": "integrationen/kwp-setup",
  "/{tenant}/forms/builder": "tutorials/form-builder-tutorial",
  ...
}

Klartext-Fallback: Falls für eine Route kein Mapping existiert, führt das Hilfe-Icon zu /help/de/ (Help-Home).


Block G — Permissions-Anwendung

Keine Permissions — Help-Center ist öffentlich erreichbar ohne Login.

Konsequenz für Routing:

  • /help/* ist vor dem Auth-Middleware-Layer gemounted
  • Kein Tenant-Context, kein RLS-Setting
  • Standard-Rate-Limiting per IP (Schutz gegen Crawler-Missbrauch, z.B. 1.000 Req/Min/IP)

Block H — Klartext-Hinweise

  • Sprache nicht verfügbar (/help/en/... in Phase 1): Redirect auf /help/de/ mit Klartext-Banner „Englischsprachige Hilfe ist in Vorbereitung. Hier ist die deutsche Version."
  • Such-Empty-State: „Nichts gefunden zu '{query}'. Probier andere Begriffe — oder schreib uns direkt an support@hivegrid.de."
  • Artikel-404: „Diese Hilfe-Seite gibt's nicht mehr. [Zur Übersicht] oder [Suche starten]."

Block I — Phase 2 / spätere Features

  • DB-getriebene Pflege durch Plattform-Admin (Editor-UI in admin.hivegrid.de/help/)
  • Mehrsprachigkeit: EN/TR/PL via DeepL-Pipeline (LP-12). Aus DE-Quelltext werden Übersetzungen generiert, manuell verifiziert, dann publiziert. Frontmatter-Feld translations: [en, tr, pl].
  • KI-gestützte Artikel-Suche (RAG): Help-Center-Inhalte als Embeddings-Korpus für KI-Assistent in der App; User kann „Wie geht X?" fragen und bekommt Antwort mit Artikel-Zitat
  • View-Counts + Helpful-Votes-Statistik für Plattform-Team (welche Artikel werden gelesen, welche helfen)
  • Versionierung: alte Artikel-Versionen sichtbar bei Deprecation
  • Kontextuelle Inline-Hilfe: statt Deep-Link in neuem Tab → Side-Panel mit Artikel direkt in der App
  • Video-Tutorials einbettbar (YouTube/Loom-Embeds)
  • „Was ist neu?"-Changelog-Feed auf Help-Home

Block J — Architektur-Vorschriften (Querschnitt)

  • LP-9: Spec-Tiefe — Mapping-Tabelle Route→Slug ist explizit definiert, nicht „mal so anlegen"
  • LP-10: Klartext-Diagnostik — auch im Help-Center selbst (404-/Empty-State-Texte)
  • LP-12: i18n-sauber — alle UI-Strings aus Locale-Files; Phase 1 nur DE-Locale, Library bereits mehrsprachig vorbereitet
  • LP-13: EU-Stack — Help-Content auf Scaleway-Hosting, kein US-CDN für Pflege-Content

Detail-Spec-Status: DRAFT

Phase-1-Modul bewusst minimal. Vor Bau:

  • Konkretes Verzeichnis-Layout im Code-Setup (content/help/de/...) festlegen
  • Initial-Artikel-Inventar mit Plattform-Team finalisieren (welche 15-20 Artikel zum Launch nötig)
  • Markdown-Renderer-Library wählen (z.B. unified + remark-gfm + rehype-shiki)
  • Such-Strategie entscheiden: client-side (FlexSearch) vs. server-side (Postgres-FTS)
  • Mapping-Konfiguration Route→Slug als File im Repo oder als Konstante im Code

Offene Detail-Punkte (nicht-blockierend):

  • Konkretes Auswahl der Initial-Artikel
  • Routing-Setup für Public-Route außerhalb Auth-Middleware
  • SEO-Optimierung-Details (sitemap.xml, robots.txt)
  • Optionales Helpful-Voting-Tracking (anonym ohne Cookies)