Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,58 @@
# VA-P29 · P29 Help-Center + Help-Desk
> ⚠️ **KI→MCP-Pivot ([[AD-26]]):** Der **RAG-Korpus-Andock entfällt** (kein RAG/Embedding mehr — VR-P25 zurückgestellt, HiveGrid wird MCP-Server, [[VR-MCP]]). Das **Help-Center bleibt** voll funktional (Artikel + Suche). Optional können Help-Artikel später als **MCP-Resource** exponiert werden. RAG-Stellen unten durchgestrichen.
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Akeshan |
| **Phase** | P29 — Help-Center & Help-Desk · v2-P9 |
| **Cycle/Fenster** | v2-W3 — Admin/Help/Dashboard/v2-Launch · fällig 2026-07-30 |
| **Status** | geplant |
## Abhängigkeiten & Parallelität
- **Blocked by:** `AK-P21` (v1-Feedback-Widget → Support-Inbox als generische Quelle/Andockpunkt), `AK-P19` (Plattform-Admin — Admin-Permissions + AdminAuditLog)
- **Blocks:** `VJ-2` (Website — Help-Center-Verlinkung/SEO) ~~, `VR-P25` (KI-Tiefe — Help-Artikel als RAG-Korpus, retro)~~ → **entfällt ([[AD-26]]: RAG-Korpus gestrichen; optional als MCP-Resource via [[VR-MCP]])**
- **Läuft parallel zu:** `VA-P28b` / `VA-P30a/b` (Akeshans W3-Tickets) — disjunkte Domänen. `Feedback` liegt im **Plattform-Admin-Datenraum** (kein Tenant-RLS, App-Code permission-gegated).
- **Konflikt-Risiko:** gering — öffentliche Help-Routen vor der Auth-Middleware, additiv; Feedback erweitert den v1-Support-Ticket-Andockpunkt.
## Was wir bauen
Ein **öffentliches, file-basiertes Help-Center** (Markdown-Artikel im Repo via Git-PRs, **kein Editor-UI**) mit SEO-Routen `/help/{lang}/{category}/{slug}` (ohne Auth, **vor der Auth-Middleware**), Volltext-Suche und **Build-Time-Index** (Build-Fail bei kaputten Referenzen). Aus jeder App-Route führt ein **Hilfe-Icon per Deep-Link** zum passenden Artikel. Ein überall erreichbares **Feedback-Widget** erzeugt `Feedback`-Einträge mit Auto-Kontext; die Plattform-Admin-Seite verwaltet Feedback als Liste + Detail mit Status-Lifecycle/Assignee/Notes/Attachments und Audit. **Bewusst klein (Phase 1)** — kein Live-Chat, kein User-facing-Status-Tracking.
## Benötigte Screens (Backend bedient — Design liefert `D-P29`)
| Screen [Route] | Kern-Inhalt |
|---|---|
| Help-Home [`/help/{lang}/`] | Hero, Such-Eingang, Kategorien-Übersicht, **öffentlich (kein Tenant-Context)** |
| Kategorie-Seite [`/help/{lang}/{category}/`] | Artikel einer Kategorie + Kategorie-Metadaten |
| Artikel-Detail [`/help/{lang}/{category}/{slug}`] | Markdown-Inhalt, TOC, verwandte Artikel, „War das hilfreich?"-Vote, **SEO-Meta/Canonical** |
| Such-Ergebnisse [`/help/{lang}/search?q=`] | Volltext-Treffer mit Snippets, Kategorie-Zuordnung |
| Feedback-Widget [Modal, überall] | „Problem melden"-Trigger (global), Freitext, Screenshot-One-Click-Anhang, Erfolgs-/Rate-Limit-Hinweis |
| Admin-Feedback-Liste [`admin.hivegrid.de/support`] | Feedback-Liste (Status/Assignee/Quelle/Datum/Filter) |
| Admin-Feedback-Detail [`admin.hivegrid.de/support/:ticketId`] | Status-Lifecycle, Assignee, interne Notes, Auto-Kontext (route/browser/app-version), Attachments, **Audit** |
## Definition of Done
- [ ] **Markdown mit Frontmatter** + **Build-Time-Index** (Volltext + Kategorien + Sitemap); **Build-Fail bei kaputten Referenzen/`related_slug`**
- [ ] Öffentliche Routen `/help/{lang}/{category}/{slug}` **ohne Auth (vor Auth-Middleware)** + SEO-Defaults (title/description/canonical) + Suche
- [ ] **Deep-Link Route→Artikel** (Hilfe-Icon pro App-Route, Fallback Help-Home)
- [ ] **Feedback-Widget überall** → `Feedback` mit Auto-Kontext (tenant/user/route/browser/app-version), Screenshot-Option, **Rate-Limit 10/h**
- [ ] **Plattform-Admin:** Feedback-Liste + Detail (Status-Lifecycle/Assignee/Notes/Attachments) mit **Audit**
- [ ] ~~Help-Artikel als **RAG-Korpus** an `VR-P25`/v2-P4 registrierbar (Embedding-Quelle)~~ → **entfällt ([[AD-26]]); optional später als MCP-Resource ([[VR-MCP]])**
## Technische Bausteine
- **Help-Center (file-basiert, keine eigene .prisma):** Markdown + Frontmatter im Repo; **Build-Time-Index** (Volltext/Kategorien/Sitemap) mit Build-Fail bei kaputten `related_slug`-Referenzen. Öffentliche Routen vor der Auth-Middleware + **IP-Rate-Limiting**.
- **Feedback (Plattform-Admin-Datenraum, KEIN Tenant-RLS):** `AdminSupportTicket` (+ Message) mit `source_kind` (`in_app_feedback_widget`/`inbound_email`), tenant_id, status, priority — speist sich aus dem Feedback-Widget; Attachments → v1-Files. App-Code permission-gegated über Admin-Permissions (AK-P19) + AdminAuditLog.
- **Feedback-Widget:** global erreichbarer Trigger → erzeugt Ticket mit Auto-Kontext (tenant/user/route/browser/app-version) + optionalem Screenshot; Rate-Limit 10/h.
- **Deep-Link:** Hilfe-Icon pro App-Route mappt Route→Artikel-Slug (Fallback Help-Home).
- ~~**RAG-Andockpunkt:** Help-Artikel als Embedding-Quelle für P25 registrierbar (retro, kein harter Forward-Dep).~~ → **entfällt ([[AD-26]]); Help-Artikel optional als MCP-Resource ([[VR-MCP]]).**
## Quellen (granular)
- `ROADMAP-V2.md` → **§v2-P9 Help-Center & Help-Desk** (Routen/Index/Feedback = Hauptquelle; Recut „bewusst klein")
- `ENTITY-MODEL.md` → **Domäne 11** `AdminSupportTicket (+ Message)` (source_kind in_app_feedback_widget/inbound_email, speist sich aus Feedback-Widget) + AdminAuditLog
- `ROADMAP.md` → Phase 29 · `PHASE-SOURCES.md` → Phase 29 (M172 Markdown-Artikel Git-PRs, M173 Routes/Suche/SEO/kontextuelle Hilfe, M174 Email-Ticket-System, M175 In-App-Feedback-Widget)
- `designer-briefs/P29-help-center-help-desk.md` (öffentliche Help-Routen, Feedback-Widget, Admin-Feedback-Liste/Detail, Phase-1-Grenze)
- `_bmad-output/specs/M38-help-center.md`, `M39-help-desk.md`
## Dev-Nachzug (nach Davids `D-P29`-Delta)
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
- [ ] Plane-Ticket `VA-P29` aktualisiert