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
- 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/KbCategoryDtoals Zielform wiederverwendbar).
- 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_slugnicht existiert (harte Validierung — existiert in BP nicht).
- Build-Step erzeugt Volltext-Index (FlexSearch ~50KB) oder Postgres-FTS-Helper-Tabelle, Kategorien-Manifest,
- Frontmatter-spezifische Felder ohne DB-Pendant:
last_updated(BP nutztupdatedAt),keywords,deprecated+ Deprecated-Banner,redirect_to/Redirect-Handling. Neu zu bauen (Spec A.2, Block D, Block H). - Inhaltsverzeichnis (TOC) aus H2-Headings, klickbar/scroll-spy. In
KbArticleContent/KbDocsLayoutnicht vorhanden (kein toc/heading-Generator gefunden). Neu zu bauen (Spec Block D). /help/sitemap.xml-Route. Keine Sitemap-/robots-Route in der Boilerplate (grep sitemap/robots→ leer). Neu (Spec Block B, A.4).- URL-Schema-Umstellung. Boilerplate-Routen sind
/help/$slug/($lang)/...(KB-Slug zuerst, Sprache optional/hinten). HiveGrid verlangt/help/$lang/$category/$slugmit/help/→/help/de/-Redirect und 404 für nicht-DE (Spec Block B, INTEGRATION-CONTRACTS §3). Routen-Files müssen neu strukturiert werden. - Public-Mounting / Auth-Vorlagerung.
help/**steht aktuell indefaultDisabledPluginRouteFilePatterns(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. - 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). - Anonymes Feedback ohne Cookies. BP-Feedback nutzt
getAnalyticsInfo(userAnalyticsId, i.d.R. Cookie-gestützt). Spec fordert „anonym ohne Cookies“ — Mechanik prüfen/ersetzen. - 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). - „Sprache nicht verfügbar“-Klartext-Banner / Redirect (
/help/en/...→/help/de/mit Hinweis, Spec Block H). BP wirft stattdessen hartes 404 bei unsupported lang. - 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. - Initial-Artikel-Inventar (~10-20 DE-Artikel). Inhalt, nicht Code — neu zu schreiben (Spec A.5, M172). BP hat
DefaultKbsTemplate.tsals Demo-Content, aber inhaltlich irrelevant.
Empfohlenes Vorgehen
Phase A — Daten-/Build-Fundament zuerst neu bauen (die Kern-Lücke):
- Verzeichnis-Layout
content/help/de/<kategorie>/<slug>.md+_category.jsonfestlegen. - Frontmatter-Parser + File-Loader bauen; Ausgabe direkt auf die vorhandenen DTOs (
KbArticleDto/KbCategoryDto/KbSearchResultDtoals Zielform) mappen — so bleibt die UI-Schicht wiederverwendbar. - 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 inapps/web/app/routes.tsstandardmäß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.