Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M39-help-desk.md
T

14 KiB
Raw Blame History

Boilerplate-Abgleich — M39 Help-Desk / Support

Feld Wert
Modul-ID M39
Name Help-Desk / Support
Milestones M174 (Email-/Feedback-Ticket-Eingang + Plattform-Admin-Bearbeitung), M175 (In-App-Feedback-Widget „Problem melden")
Block Block 7 — Plattform-Außenseite (Betrieb, Compliance, Zugang)
Reuse-Level HIGH
Spec-Quellen _bmad-output/specs/M39-help-desk.md, _bmad-output/pflichtenheft/blocks/block7.md §39

Kurzfazit

Die Boilerplate enthält ein fast vollständiges Phase-1-Help-Desk-Modul unter apps/web/app/modules/helpDesk + prisma/schema/helpDesk.prisma. Es deckt im Kern:

  • In-App-Feedback-Widget (AddFeedbackButton.tsx) mit Trigger + Modal + Submit-Action,
  • Submit-Action verdrahtet in app.$tenant.tsx (add-feedback + create-support-ticket),
  • Service- und DB-Layer für Feedback und SupportTicket (inkl. Inbound-E-Mail-Dedup),
  • PII-/Secret-Redaction beim Submit (DSGVO-relevant, spec-konform),
  • Plattform-Admin-Bereich admin/help-desk (Overview + Tickets-Liste + Feedback-Liste) mit Filter/Suche/Bulk-Delete,
  • Admin-Sidebar-Eintrag bereits registriert,
  • Notification an Admin-Rolle bei neuem Feedback/Ticket,
  • Sliding-Window-Rate-Limiter als Package vorhanden.

Was fehlt, sind die HiveGrid-spezifischen Spec-Erweiterungen (reicheres Status-/Assignee-/ Internal-Notes-Datenmodell, Attachments, Browser-Info/App-Version-Capture, Screenshot, Detail-View, 10/h-Rate-Limit) und die HiveGrid-Layer-Disziplin (View-Model-Layer, ui-hivegrid-Adapter, Permission-Keys statt adminOnly-Bool). Es ist eine Anpass- und Erweiterungsaufgabe, kein Neubau.


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
prisma/schema/helpDesk.prisma → model Feedback Tenant/User-scoped Feedback (message, fromUrl, tenantId?, userId?, createdAt) als-vorlage — Felder fehlen (status, assignee, internal_notes, route_path, browser_info, app_version, attachments, resolved_*) → erweitern
prisma/schema/helpDesk.prisma → model SupportTicket Ticket mit source/status(default open)/priority, subject, message, fromEmail, fromUrl, inboundMessageId @unique, Indizes [tenantId,status,createdAt] + [source,createdAt] anpassen — näher an Spec-Lifecycle als Feedback; entweder konsolidieren oder als Mailbox-Ticket-Modell weiterführen
prisma/schema/core.prisma → model FileObject (Z.213) S3-Storage-Objekt (provider/bucket/key/contentType/byteSize/checksum/publicUrl) + FileUploadProgress/FileChunk anpassen — Basis für Attachments (Spec A.3); Join Feedback↔FileObject + Storage-Pfad-Konvention tenants/{id}/feedback/{id}/... ergänzen
apps/web/app/modules/helpDesk/services/Feedback.server.ts Submit-Service: Redaction, Rate-Limit-Count, Notification-Call, createFeedback anpassen — Rate-Limit ist count-basiert ohne Zeitfenster (Spec: 10/User/h) → auf Sliding-Window umstellen; Browser-Info/App-Version/route_path ergänzen
apps/web/app/modules/helpDesk/services/SupportTickets.server.ts createInline + createFromInboundEmail (E-Mail-Dedup via inboundMessageId), Subject-Normalisierung, Redaction anpassen — createFromInboundEmail ist Phase-2-Vorgriff; createInline-Pattern 1:1 nutzbar
apps/web/app/modules/helpDesk/services/FeedbackRedaction.ts (+ .server.ts) redactFeedbackText — entfernt E-Mails, Bearer-Tokens, API-Keys, Hex/Base64-Secrets aus Body+URL 1:1 — deckt DSGVO-Transparenz/Query-Param-Stripping (Spec B.3) zum großen Teil ab
apps/web/app/modules/helpDesk/db/feedback.db.server.ts getAllFeedback (Filter/Suche/Pagination, include tenant+user), createFeedback anpassen — Volltextsuche nur über message; Spec will Body+Tenant-Name+User-Name; Cursor- statt Offset-Pagination
apps/web/app/modules/helpDesk/db/supportTickets.db.server.ts getAllSupportTickets, createSupportTicket, updateSupportTicketStatus anpassen — Status-Update-Funktion vorhanden; Assignee/Notes/Bulk-Status fehlen
apps/web/app/components/layouts/buttons/AddFeedbackButton.tsx In-App-Trigger (Top-Bar-Button) + Feedback-Modal + Fetcher-Submit + Toast bei Erfolg/Fehler, autoerfasst fromUrl+tenantId als-vorlage — UI-Grundgerüst da; nach packages/ui-hivegrid portieren (Layer-Disziplin), Attachments/Screenshot/Route-Anzeige/DSGVO-Hinweis/10-Zeichen-Validierung ergänzen
apps/web/app/routes/admin/help-desk.tsx Plattform-Admin-Shell (SidebarIconsLayout: Overview/Tickets/Feedback) + Outlet anpassen — Reihenfolge/Labels an HiveGrid; „Mailbox"-Direktlink-Tab (Spec D.1 /feedback/mailbox) ergänzen
apps/web/app/routes/admin/help-desk/feedback.tsx Listen-Route: Loader baut Filterable-Props (tenant/user), Pagination, Action mit Bulk-delete + CSRF anpassen — Status/Assignee/Zeitraum-Filter + CSV-Export + Bulk-Status/Bulk-Assign fehlen
apps/web/app/routes/admin/help-desk/tickets.tsx Tickets-Listen-Route mit TableSimple (createdAt/subject/status/source/message) als-vorlage — Listen-Pattern für die Feedback-Tabelle
apps/web/app/modules/helpDesk/components/FeedbackTable.tsx Tabelle: Suche, Filter, Bulk-Select+Delete, Spalten (createdAt/tenant/user/message), Redaction in Anzeige anpassen — Spalten Body-Preview(100), #Attachments, Route, Status-Badge, Assignee ergänzen; nach ui-hivegrid portieren
apps/web/app/application/sidebar/AdminSidebar.tsx (Z.287-294) Admin-Sidebar-Eintrag „Help-Desk" + Sub „Feedback" via enabledAdminRouteItem / UI_NAV_IDS.adminHelpDesk anpassen — Reachability-Anker vorhanden; auf HiveGrid-Permission-Gate (platform_admin.feedback.read) statt reinem Route-Enable umstellen
packages/shared-store/src/helpers/rate-limit-sliding.ts Sliding-Window-Rate-Limiter (consume/reset, windowSeconds, max, Redis-Lua) 1:1 — exakt für Spec B.5 „10 Submissions/User/h"
apps/web/app/modules/notifications/services/.server/NotificationService.ts → sendToRoles Notify-Channel admin-users bei neuem Feedback/Ticket anpassen — in HiveGrid über M011 notify({...}) statt Direkt-Aufruf (AGENTS.md Querschnitt)
apps/web/app/routes/help/$slug.($lang).tsx (+ Geschwister) Öffentliche Help-Center-Routen (Modul 38) als-vorlage — Andock-Punkt für den mailto:support@hivegrid.de-Trigger (Spec B.1, Public-Kontext)
apps/web/app/routes/admin/help-desk.auth.test.ts Auth-Test-Gerüst (Loader/Action gemockt, adminOnly) als-vorlage — Test-Pattern für die HiveGrid-Smoke/Unit-Tests

Vorhandene Daten-Modelle

Alle in /Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/:

  • helpDesk.prisma → Feedback — id, createdAt, tenantId?, tenant, userId?, user, message, fromUrl. Minimal: deckt Spec-Felder id/created_at/tenant_id/tenant_user_id/body/route_path ab. Fehlt: updated_at, status, assignee_admin_user_id, internal_notes, resolved_at/_by, browser_info, app_version, attachments[], Spec-Indizes.
  • helpDesk.prisma → SupportTicket — id, createdAt, updatedAt, tenantId?, userId?, source, status(@default open), priority, subject, message, fromEmail?, fromUrl?, inboundMessageId? @unique; Indizes [tenantId,status,createdAt], [source,createdAt]. Näher am Spec-Status-Lifecycle als Feedback. Fehlt: Assignee, internal_notes, resolved-Felder, browser_info, app_version, Attachments-Relation.
  • core.prisma → FileObject (Z.213) + FileUploadProgress/FileChunk (Z.195-211) — S3-Storage-Fundament für Attachments (Spec A.3). Es gibt kein dediziertes FeedbackAttachment-Join-Modell → neu.

Permission/Plan-Hinweis: packages/entitlements/src/features.ts definiert supportTickets+prioritySupport als Feature-Keys, plans.ts weist Quotas zu. Das ist Tenant-Entitlement-Logik, nicht die in Spec E.2 geforderten Plattform-Admin-Permissions (platform_admin.feedback.read/write/delete) — die fehlen komplett.


Lücken / komplett neu zu bauen

Datenmodell (Erweiterung, kein Neubau):

  • status-Enum (open|in_progress|resolved|wontfix), assignee_admin_user_id, internal_notes (Markdown), resolved_at, resolved_by_admin_user_id an Feedback ergänzen.
  • browser_info (JSON: UA, Viewport, Screen, Sprache, Timezone), app_version, route_path als eigenes Feld.
  • FeedbackAttachment-Relation auf FileObject + Storage-Pfad-Konvention tenants/{tenantId}/feedback/{feedbackId}/..., Typ-/Größen-Limits (5×10 MB, PNG/JPG/WEBP/PDF).
  • Spec-Indizes (status, created_at DESC), (tenant_id, created_at DESC), (assignee_admin_user_id, status).

Widget (Spec B):

  • Browser-Info-Sammler-Util (UA/Viewport/Sprache/Timezone) — nicht vorhanden.
  • App-Version-Einbettung zur Build-Zeit (Build-Hash) — nicht vorhanden.
  • Screenshot-Funktion (html2canvas-pro, One-Click, mit Consent) — nicht vorhanden.
  • Attachment-Upload-Komponente (Drag&Drop, max 5) im Modal — nicht vorhanden.
  • Aktuelle-Route-Anzeige (read-only) + DSGVO-Hinweis + 10-Zeichen-Min-Validierung (Send disabled) im Modal — nur Basis-Modal da.
  • Query-Param-Stripping bei route_path (Redaction deckt Secrets ab, aber nicht generelles Query-Strip).
  • mailto:support@hivegrid.de-Trigger in Public-/help/-Routen — nicht vorhanden.

Plattform-Admin-Detail-View (Spec D.3) — fehlt komplett:

  • Route admin.hivegrid.de/feedback/:id, Body-Anzeige mit URL-Link-Detection, Attachment-Preview (Image/PDF), Tenant-Block + User-Block mit Direktlinks ins Tenant-Admin (Impersonation M37), Browser-/Tech-Kontext ausklappbar, Inline-Edit Status/Assignee/Internal-Notes, Hard-Delete mit Warnung.
  • Activity-Log pro Feedback (Status-/Assignee-/Notes-Wechsel mit Actor+Timestamp) — kein Audit/Activity-Wiring im BP-Modul; via M001/M045 neu verdrahten.
  • Mailbox-Direktlink-Tab (Spec C/D.1 /feedback/mailbox) — nicht vorhanden.

Liste (Spec D.2) — Teil-Lücken:

  • Status-/Assignee-/Zeitraum-Filter, Volltextsuche über Body+Tenant+User, Cursor-Pagination (50), Bulk-Status-Wechsel, Bulk-Assign, CSV-Export. Nur Tenant/User-Filter + Body-Suche + Offset-Pagination + Bulk-Delete vorhanden.

Querschnitt / Layer-Disziplin (AGENTS.md DoD) — durchgehend neu:

  • View-Model-Layer (packages/view-models) — BP-Routen geben rohe DB-DTOs direkt aus.
  • UI nach packages/ui-hivegrid (Widget+Tabelle), Subframe-Adapter — BP-UI liegt in apps/web/app/components + modules/helpDesk/components.
  • Permission-Keys platform_admin.feedback.read/write/delete (M004) statt requireAuth({adminOnly})-Bool; Permission-Denied → 404 (Spec E.2).
  • Audit auto (M001) + Activity (M045) + Notification via M011 notify() statt Direkt-sendToRoles.
  • i18n-Keys (M003): BP nutzt feedback.*/helpDesk.*-Keys, aber HiveGrid-Klartexte (Spec B.4/F/39.Y) neu pflegen.
  • Feature-Flag (M006), Smoke-Test/Hot-Swap (M017), Visual-Regression (M016) — neu pro DoD.

Bewusst NICHT bauen (Phase 2 / Anti-Liste, Spec F + 39.X): Live-Chat, voll-Ticket-System mit User-Notifications, User-facing-Status-Page, NPS/CSAT, Mailbox-Sync in der App, KI-Auto-Triage, Feedback-Voting, Bug-Tracker-/Slack-Integration. → SupportTickets.createFromInboundEmail (Inbound-Mail→Ticket) ist ein Phase-2-Vorgriff und in M174 nicht zu aktivieren (Spec C.1/C.2: Mailbox extern lesen, nur Direktlink).


Empfohlenes Vorgehen

M174 zuerst (Backend + Plattform-Admin), dann M175 (Widget) — entspricht der Milestone-Abhängigkeit (M175 setzt M174 voraus).

  1. Daten-Layer erweitern (M174): Feedback-Modell der Boilerplate als Vorlage nehmen und um Spec-Felder (status-Enum, assignee_admin_user_id, internal_notes, resolved_*, browser_info, app_version, route_path) + Spec-Indizes + FeedbackAttachment→FileObject-Relation erweitern. Forward-Only-Migration mit Inverse-SQL-Kommentar. Entscheiden: SupportTicket als separates (Mailbox-)Modell behalten oder Feedback-Modell konsolidieren.
  2. Service-Layer übernehmen + härten (M174): Feedback.server.ts + feedback.db.server.ts + FeedbackRedaction.ts aus BP übernehmen; Rate-Limit auf rate-limit-sliding (10/User/h) umstellen; Status-Lifecycle-Übergänge, Assignee-Set, Internal-Notes-Edit ergänzen; Notification auf M011 notify(), Audit/Activity über M001/M045 verdrahten.
  3. Plattform-Admin-Liste (M174): Routen admin/help-desk.tsx + feedback.tsx + FeedbackTable.tsx als Vorlage nach View-Model + ui-hivegrid portieren; Status/Assignee/Zeitraum-Filter, Volltextsuche (Body+Tenant+User), Cursor-Pagination, Bulk-Status/Bulk-Assign, CSV-Export ergänzen; Permission-Gate platform_admin.feedback.read.
  4. Plattform-Admin-Detail-View neu (M174): /feedback/:id mit allen Spec-D.3-Blöcken + Activity-Log + Hard-Delete; Mailbox-Direktlink-Tab (/feedback/mailbox) + Klartext-Hinweis (Spec C).
  5. In-App-Widget (M175): AddFeedbackButton.tsx als Vorlage nach packages/ui-hivegrid portieren; Route-Anzeige, DSGVO-Hinweis, 10-Zeichen-Validierung, Browser-Info-Util, App-Version, Attachment-Upload (M052/M23-FileObject), html2canvas-pro-Screenshot ergänzen; Submit-Action (BP app.$tenant.tsx-Pattern) anpassen; mailto-Trigger in Public-/help/-Routen.
  6. Querschnitt + Tests + Reachability (beide): Sidebar-Permission-Gate, i18n-Keys (HiveGrid-Klartexte), Feature-Flag, Smoke-/Unit-/Hot-Swap-/Visual-Regression-Tests, Empty-/Loading-/Permission-Denied(404)-States pro DoD.

Erstellt durch Boilerplate-Abgleich-Agent. Geprüft direkt gegen /Users/raffaelsheikh/Documents/GitHub/boilerplate (nicht nur Inventur). Es wurde nichts in der Boilerplate oder im HiveGrid-Code geändert.