# 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//.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//.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.