Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M38-help-center.md
T

17 KiB

Boilerplate-Mapping: M38 — Help-Center (öffentlich)

Modul-ID M38
Name Help-Center (öffentlich)
Milestones M172 (Markdown-Artikel-Mgmt / Git-PRs), M173 (Routes + Suche + SEO + Kontextuelle Hilfe)
Block Block 7
LPs LP-9, LP-10, LP-12, LP-13
Reuse-Level medium

TL;DR — Verdict

Die Boilerplate enthält ein vollständiges, produktionsreifes Help-Center / Knowledge-Base-System (SaaSRock-Stil) unter apps/web/app/modules/knowledgeBase/ mit öffentlichen Routen /help/..., Kategorien, Artikeln, Suche (Meilisearch + SQL-Fallback), anonymem Daumen-hoch/runter-Feedback, View-Tracking, SEO-Metatags (OG/Twitter/Canonical), Markdown-Rendering mit Sanitizer, verwandten Artikeln, Featured-Artikeln und kompletter Admin-Editor-UI — sogar mit RAG-Service für KI-Suche.

Der entscheidende Bruch: Die Boilerplate ist DB-getrieben (Prisma KnowledgeBase*-Modelle + Editor-UI in admin/knowledge-base). Die HiveGrid-M38-Phase-1-Spec verlangt aber explizit das Gegenteil: file-basierte Markdown-Artikel im Repo, Pflege via Git-PRs, kein Editor-UI, mit Build-Time-Index + Sitemap + Frontmatter-/Verlinkungs-Validierung als Build-Step (Spec Block A.1, A.4; M172-Erfolgskriterium). Dieser file-/build-basierte Daten- und Validierungslayer existiert in der Boilerplate nicht.

Konsequenz: Die UI-, Routing-, Such-, SEO- und Feedback-Schicht ist als Vorlage exzellent (high reuse), aber der Daten-Layer muss komplett ersetzt werden (DB → File/Frontmatter + Build-Index). Was die Boilerplate liefert, entspricht eher der HiveGrid-Phase-2 (DB-getriebene Pflege durch Plattform-Admin, Spec Block I). Daher gesamt medium.


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
apps/web/app/routes/help/$slug.($lang).tsx Public Help-Home-Route (Kategorien + Suche), Sprach-Segment optional, Meta-Tags aus Loader als-vorlage (URL-Schema von /help/$slug/($lang) → HiveGrid /help/$lang/$category/$slug umstellen)
apps/web/app/routes/help/$slug.($lang).categories.$category.tsx Public Kategorie-Seite als-vorlage
apps/web/app/routes/help/$slug.($lang).articles.$article.tsx Public Artikel-Detail + action (Feedback) als-vorlage
apps/web/app/routes/help/help-routes.test.tsx Route-Smoke-/Render-Tests der Public-Help-Routen als-vorlage (Test-Pattern für DoD-Smoke-Tests)
apps/web/app/modules/knowledgeBase/routes/api/KbRoutes.Index.Api.tsx Loader-VM-Builder: metatags/kb/search/categories/featured/isAdmin; 404 bei unsupported lang als-vorlage (Loader→VM-Konvention 1:1, Datenquelle tauschen)
apps/web/app/modules/knowledgeBase/routes/api/KbRoutes.Category.Api.tsx Kategorie-Loader-VM als-vorlage
apps/web/app/modules/knowledgeBase/routes/api/KbRoutes.Article.Api.tsx Artikel-Loader-VM + anonymes voteArticle (thumbsUp/Down via userAnalyticsId, ohne PII) als-vorlage (Feedback-Mechanik 1:1, Artikel-Quelle tauschen)
apps/web/app/modules/knowledgeBase/routes/views/KbRoutes.{Index,Category,Article}.View.tsx Reine View-Komponenten (empfangen Loader-Data), Layer-getrennt anpassen
apps/web/app/modules/knowledgeBase/components/KbSearch.tsx Such-Eingabe mit useDebounce (500ms) + q-Query-Param + Ergebnis-Liste anpassen (Spec verlangt 300ms-Debounce; Ranking Title>Desc>Keyword>Body ergänzen)
apps/web/app/modules/knowledgeBase/components/KbHeader.tsx, KbFeaturedArticles.tsx, KbSkeletons.tsx Header, Featured-Artikel-Block, Loading-Skeletons anpassen
apps/web/app/modules/knowledgeBase/components/categories/Kb{Categories,CategoriesGrid,CategoriesList,Category,CategoriesTopArticles}.tsx Kategorien-Übersicht (Grid/List/„Top-Artikel“) anpassen (deckt Spec Block C: Kategorie-Karten + „Beliebteste Artikel“)
apps/web/app/modules/knowledgeBase/components/articles/Kb{Article,ArticleContent,Articles,ArticlesBySection}.tsx Artikel-Detail: Title/Description/Autor/Datum, Markdown-Body, verwandte Artikel, Daumen-Feedback anpassen (deckt Spec Block D weitgehend; TOC fehlt — siehe Lücken)
apps/web/app/modules/knowledgeBase/components/KbArticleContent.tsx renderSanitizedMarkdown(content) + prose-Styling + Related-Sidebar + Feedback-Buttons anpassen
apps/web/app/utils/html-sanitizer.ts renderSanitizedMarkdown() über marked (Renderer), Raw-HTML-Escaping, JS-URL-/rel-Hardening 1:1 (sichere Markdown→HTML-Pipeline; Spec-Renderer-Frage „unified/remark“ damit faktisch schon gelöst)
apps/web/app/modules/knowledgeBase/components/layouts/KbDocsLayout.tsx, KbDocsHeader.tsx „docs“-Layout-Variante (Sidebar-Navigation Kategorie→Artikel) als-vorlage (passt zum Help-Layout; TOC-Spalte ergänzen)
apps/web/app/components/ui/breadcrumbs/BreadcrumbSimple.tsx (via KbArticle.tsx) Breadcrumb Kategorie > Artikel 1:1 (Spec Block C/D Breadcrumb)
apps/web/app/modules/knowledgeBase/dtos/{KbArticleDto,KbCategoryDto,KbCategorySectionDto,KbNavLinkDto,KbSearchResultDto,KnowledgeBaseDto}.ts Vollständige DTO-/VM-Typen für KB/Kategorie/Artikel/Suche inkl. metatags als-vorlage (Zielform für den neuen File-Index-Loader; Frontmatter→DTO mappen)
apps/web/app/modules/knowledgeBase/service/KnowledgeBaseService.server.ts kbToDto/categoryToDto/articleToDto mit kompletten SEO-Metatags (title/description/OG/Twitter/Canonical), search(), getFeaturedArticles(), getypte Error-Codes → i18n-Keys als-vorlage (Metatag-/DTO-Mapping 1:1 übernehmbar, DB-Reads durch File-Index-Reads ersetzen; nutzt cachified 24h-TTL — passt zu Spec „langer Cache-Header / SSG“)
apps/web/app/modules/knowledgeBase/services/kbArticleSearch.server.ts Such-Service mit Meilisearch-Pfad + transparentem SQL-LIKE-Fallback, gleiche Rückgabeform als-vorlage (Server-Side-Suche; für file-basiert: SQL-Pfad raus, FlexSearch-Index oder Postgres-FTS-Helper-Tabelle einsetzen)
packages/search/src/{client,query,index-helper,sanitize}.ts + schemas/kb-articles.ts @toolctrl/search Meilisearch-Wrapper, tenant-scoped Query, Index-Schema kbArticlesIndex, Outbox-Publisher anpassen (Spec bevorzugt Phase-1 client-side FlexSearch ODER Postgres-FTS; Meili ist „nice-to-have“ — als Server-Side-Option direkt verfügbar)
apps/web/app/modules/knowledgeBase/services/kbArticleRag.server.ts RAG-Service für KB-Artikel (Embeddings-Suche) als-vorlage (HiveGrid-Phase-2 „KI-gestützte Artikel-Suche/RAG“, Spec Block I)
packages/ai/src/embeddings/* (@toolctrl/ai/embeddings) Komplette Embeddings-/RAG-Pipeline (embed-and-upsert, retrieve, chunking, Outbox-Reindex) als-vorlage (Phase-2 RAG)
apps/web/app/modules/knowledgeBase/db/kbAnalytics.db.server.ts createKnowledgeBaseView, voteArticle, getArticleStateByUserAnalyticsId (anonym via userAnalyticsId) als-vorlage (Spec: „helpful?“-Daumen anonym ohne PII; View-Counts = Phase-2)
apps/web/app/utils/analyticsCookie.server.ts (getAnalyticsInfo) Anonyme Analytics-ID-Quelle für Feedback/Views ohne Login anpassen (Spec verlangt anonym ohne Cookies — prüfen/anpassen)
apps/web/app/components/ui/errors/ServerError.tsx + Route-ErrorBoundary Fehlerseiten-Pattern für Public-Routen 1:1
apps/web/react-router.config.ts + apps/web/app/routes.ts (Flat-Folder-Convention) RR7-Routing-Setup inkl. „Plugin-Routen deaktivierbar“-Liste (help/** ist dort enthalten = Feature-Flag-fähig per Datei-Pattern) 1:1 (Routing-Fundament; help/** aus defaultDisabledPluginRouteFilePatterns aktivierbar machen → Feature-Flag-Anforderung DoD erfüllt)
packages/i18n/src/index.ts (@toolctrl/i18n) + apps/web/app/locale/* i18n-Setup (defaultLocale="de", supportedLocales, SSR-Integration); Help-Center-Komponenten nutzen durchgängig t(...) 1:1 (deckt LP-12 „alle UI-Strings aus Locale-Files, Phase 1 nur DE“)
packages/view-models/src/index.ts (VMState, assertI18nLabel, ShellRegistries) View-Model-Statusmodell + i18n-Key-Zwang 1:1 (Loader→VM-Konvention, DoD „Unit-Test VM-Builder mit Zod/Schema“)
packages/ui-mock/* + apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.tsx Hot-Swap-/Visual-Regression-Fundament als-vorlage (DoD: Hot-Swap-Drill + Visual-Snapshot)

Vorhandene Daten-Modelle

Quelle: /Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/knowledgeBase.prisma

Prisma-Modell Relevanz für M38
KnowledgeBase KB-Container (slug, title, description, defaultLanguage, layout list/articles/grid/docs, color, enabled, languages, links, logo, seoImage, basePath, optional tenantId) — entspricht inhaltlich dem Help-Center-Root. DB-getrieben — Phase-2-Modell, nicht Phase-1.
KnowledgeBaseCategory Kategorie (slug, order, title, description, icon, language, seoImage) — deckt Spec-_category.json (slug/label/description/icon/order) inhaltlich vollständig ab, aber als DB-Zeile statt File.
KnowledgeBaseCategorySection Unter-Sektionen je Kategorie (order/title/description) — über Spec hinaus (optional).
KnowledgeBaseArticle Artikel (slug, title, description, order, contentDraft/contentPublished/contentPublishedAsText, contentType wysiwyg/markdown, language, featuredOrder, seoImage, publishedAt, relatedInArticleId, createdByUserId) — deckt Frontmatter-Felder slug/title/order/description + Body inhaltlich ab. Kein Frontmatter-deprecated/redirect_to/keywords/last_updated-Äquivalent (siehe Lücken).
KnowledgeBaseRelatedArticle Verwandte-Artikel-Relation (Spec: related_slugs).
KnowledgeBaseViews / KnowledgeBaseArticleViews View-Tracking pro userAnalyticsId (Spec Block I Phase-2 „View-Counts“).
KnowledgeBaseArticleUpvotes / KnowledgeBaseArticleDownvotes Anonymes Daumen-Feedback pro userAnalyticsId (Spec Block D „War hilfreich?“, ohne PII).

Wichtig: Diese Modelle modellieren die DB-getriebene Variante. M38-Phase-1 ist bewusst file-basiert (Spec A.1, M172). Sie sind nur als Strukturreferenz / Phase-2-Fundament relevant, nicht als Phase-1-Datenquelle.

Such-Index-Schema vorhanden: packages/search/src/schemas/kb-articles.ts (kbArticlesIndex). Vektor/RAG-Speicher (Phase-2): @toolctrl/vector-store (pgvector/Qdrant), prisma/migrations/...enable_pgvector.


Lücken / komplett neu zu bauen

  1. File-basierter Daten-Layer (Kern-Lücke). Es gibt keine Boilerplate-Mechanik für content/help/de/<kategorie>/<slug>.md + _category.json. Komplett neu zu bauen:
    • Markdown-File-Loader mit YAML-Frontmatter-Parser (Pflicht: slug/title/category/order/description/last_updated; optional related_slugs/keywords/deprecated/redirect_to).
    • _category.json-Loader (slug/label/description/icon/order).
    • Mapping Frontmatter/File → bestehende DTO-Form (KbArticleDto/KbCategoryDto als Zielform wiederverwendbar).
  2. Build-Time-Index + Validierung (M172-Erfolgskriterium). Nicht vorhanden. Neu:
    • Build-Step erzeugt Volltext-Index (FlexSearch ~50KB) oder Postgres-FTS-Helper-Tabelle, Kategorien-Manifest, sitemap.xml.
    • Build-Fail, wenn eine Kategorie-Referenz oder ein related_slug nicht existiert (harte Validierung — existiert in BP nicht).
  3. Frontmatter-spezifische Felder ohne DB-Pendant: last_updated (BP nutzt updatedAt), keywords, deprecated + Deprecated-Banner, redirect_to/Redirect-Handling. Neu zu bauen (Spec A.2, Block D, Block H).
  4. Inhaltsverzeichnis (TOC) aus H2-Headings, klickbar/scroll-spy. In KbArticleContent/KbDocsLayout nicht vorhanden (kein toc/heading-Generator gefunden). Neu zu bauen (Spec Block D).
  5. /help/sitemap.xml-Route. Keine Sitemap-/robots-Route in der Boilerplate (grep sitemap/robots → leer). Neu (Spec Block B, A.4).
  6. URL-Schema-Umstellung. Boilerplate-Routen sind /help/$slug/($lang)/... (KB-Slug zuerst, Sprache optional/hinten). HiveGrid verlangt /help/$lang/$category/$slug mit /help/ → /help/de/-Redirect und 404 für nicht-DE (Spec Block B, INTEGRATION-CONTRACTS §3). Routen-Files müssen neu strukturiert werden.
  7. Public-Mounting / Auth-Vorlagerung. help/** steht aktuell in defaultDisabledPluginRouteFilePatterns (apps/web/app/routes.ts), also standardmäßig deaktiviert. Muss aktiviert und als vor-Auth, kein Tenant-Context, kein RLS gemountet werden (Spec Block G). IP-Rate-Limiting (1000 Req/Min/IP) ist neu zu ergänzen.
  8. Deep-Link-Mapping Route→Slug aus der App (Block F). Hilfe-Icon-Pattern + Mapping-Konfiguration (/{tenant}/... → kategorie/slug) mit Fallback auf /help/de/. Komplett neu (kein Pendant in BP).
  9. Anonymes Feedback ohne Cookies. BP-Feedback nutzt getAnalyticsInfo (userAnalyticsId, i.d.R. Cookie-gestützt). Spec fordert „anonym ohne Cookies“ — Mechanik prüfen/ersetzen.
  10. Such-Ranking & Highlight. BP-SQL-Fallback ist einfaches LIKE ohne explizites Ranking; Spec verlangt Title>Description>Keyword>Body + Snippet-Highlight + Empty-State-Text mit support@hivegrid.de. Ranking/Highlight neu (Meili liefert Ranking, aber Phase-1 ist client-side FlexSearch vorgesehen).
  11. „Sprache nicht verfügbar“-Klartext-Banner / Redirect (/help/en/... → /help/de/ mit Hinweis, Spec Block H). BP wirft stattdessen hartes 404 bei unsupported lang.
  12. HiveGrid-Querschnitt-Pakete. @hivegrid/* (activity/audit/notifications/entitlements/i18n) sind HiveGrid-eigene Pakete (INTEGRATION-CONTRACTS) und in der Boilerplate nicht vorhanden (dort @toolctrl/*). Für M38 großteils irrelevant (öffentlich, keine Permissions, keine schreibende Domain-Aktion außer anonymem Vote) — aber Feature-Flag-Schaltbarkeit (M006) und ggf. Audit für externe Effekte müssen HiveGrid-konform verdrahtet werden.
  13. Initial-Artikel-Inventar (~10-20 DE-Artikel). Inhalt, nicht Code — neu zu schreiben (Spec A.5, M172). BP hat DefaultKbsTemplate.ts als Demo-Content, aber inhaltlich irrelevant.

Empfohlenes Vorgehen

Phase A — Daten-/Build-Fundament zuerst neu bauen (die Kern-Lücke):

  1. Verzeichnis-Layout content/help/de/<kategorie>/<slug>.md + _category.json festlegen.
  2. Frontmatter-Parser + File-Loader bauen; Ausgabe direkt auf die vorhandenen DTOs (KbArticleDto/KbCategoryDto/KbSearchResultDto als Zielform) mappen — so bleibt die UI-Schicht wiederverwendbar.
  3. Build-Step: Kategorien-Manifest + Volltext-Index (FlexSearch oder Postgres-FTS) + sitemap.xml; harte Validierung (Kategorie-Refs, related_slugs) → Build-Fail. (M172-Erfolgskriterium.)

Phase B — UI/Routing aus Boilerplate übernehmen und umbauen: 4. renderSanitizedMarkdown aus apps/web/app/utils/html-sanitizer.ts 1:1 übernehmen (löst die Renderer-Wahl der Spec). 5. View-Komponenten + DTO-Mapping aus modules/knowledgeBase/{components,routes/views,service} als Vorlage übernehmen; Daten-Reads von DB auf den File-Index umstellen. 6. SEO-Metatag-Builder (kbToDto/categoryToDto/articleToDto) als-vorlage übernehmen — OG/Twitter/Canonical sind fertig. 7. Routen neu nach HiveGrid-Schema /help/$lang/$category/$slug strukturieren (Vorlage: routes/help/*); /help/→/help/de/-Redirect, nicht-DE-Klartext-Banner, sitemap.xml-Route; help/** aus der Disabled-Liste aktivieren und public/vor-Auth mounten + IP-Rate-Limiting.

Phase C — Ergänzungen, die der Boilerplate fehlen: 8. TOC-aus-H2-Generator (klickbar/scroll-spy) in die Artikel-View ergänzen. 9. Deep-Link-Mapping Route→Slug (Block F) inkl. Hilfe-Icon-Pattern + Fallback /help/de/. 10. Such-Ranking (Title>Desc>Keyword>Body) + Snippet-Highlight + Empty-State-Klartext; Debounce auf 300ms. 11. Deprecated-Banner + redirect_to-Handling + Artikel-404-Klartextseite (Block D/H). 12. Anonymes Feedback (Daumen) aus kbAnalytics.db.server.ts übernehmen, aber cookieless umbauen.

Phase D — DoD-Querschnitt (HiveGrid): 13. Feature-Flag-Schaltbarkeit (M006), i18n-Keys (DE-Locale, LP-12), Smoke-Test (routes/help/help-routes.test.tsx als Vorlage), Hot-Swap-Drill + Visual-Snapshot. Sidebar-Eintrag entfällt (Help ist außerhalb Tenant-Sidebar, Spec Block B) — als „nur Inline-Verlinkung“ dokumentieren (DoD-Erreichbarkeit erlaubt das explizit).

Phase-2 (später, BP liefert das Fundament fertig): DB-getriebene Pflege + Editor-UI (admin/knowledge-base/* + KnowledgeBase*-Prisma-Modelle), Mehrsprachigkeit, RAG-Suche (kbArticleRag.server.ts + @toolctrl/ai/embeddings + @toolctrl/vector-store), View-Counts/Helpful-Statistik.


Anti-Erfindung / Vorbehalte

  • Die Boilerplate-Help-Center-Implementierung ist DB-getrieben; die file-/Git-PR-basierte Phase-1-Architektur der M38-Spec ist nicht vorhanden und muss neu gebaut werden.
  • help/**-Routen sind in apps/web/app/routes.ts standardmäßig deaktiviert (defaultDisabledPluginRouteFilePatterns).
  • Kein TOC-/H2-Generator, keine sitemap.xml-/robots-Route, kein Deep-Link-Route→Slug-Mapping in der Boilerplate gefunden.
  • Such-SQL-Fallback ist LIKE-basiert ohne explizites Title>Desc>Keyword>Body-Ranking; Highlight fehlt.
  • HiveGrid-Querschnitt-Pakete (@hivegrid/*, packages/ui-hivegrid, packages/db/src/search/indexed-entities.ts) sind HiveGrid-eigen und in der Boilerplate (@toolctrl/*) nicht enthalten.