--- module: 38 title: Help-Center (öffentlich) phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-9, LP-10, LP-12, LP-13] spec_style: 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: ```yaml --- 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`) ```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:** Stripe-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: `` 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) --- ## Block F — Verlinkung aus der App (Deep-Links) ### 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)