14 KiB
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
FeedbackundSupportTicket(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-Felderid/created_at/tenant_id/tenant_user_id/body/route_pathab. 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 alsFeedback. 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 dediziertesFeedbackAttachment-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_idan Feedback ergänzen.browser_info(JSON: UA, Viewport, Screen, Sprache, Timezone),app_version,route_pathals eigenes Feld.FeedbackAttachment-Relation aufFileObject+ Storage-Pfad-Konventiontenants/{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 inapps/web/app/components+modules/helpDesk/components. - Permission-Keys
platform_admin.feedback.read/write/delete(M004) stattrequireAuth({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).
- 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:SupportTicketals separates (Mailbox-)Modell behalten oder Feedback-Modell konsolidieren. - Service-Layer übernehmen + härten (M174):
Feedback.server.ts+feedback.db.server.ts+FeedbackRedaction.tsaus BP übernehmen; Rate-Limit aufrate-limit-sliding(10/User/h) umstellen; Status-Lifecycle-Übergänge, Assignee-Set, Internal-Notes-Edit ergänzen; Notification auf M011notify(), Audit/Activity über M001/M045 verdrahten. - Plattform-Admin-Liste (M174): Routen
admin/help-desk.tsx+feedback.tsx+FeedbackTable.tsxals 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-Gateplatform_admin.feedback.read. - Plattform-Admin-Detail-View neu (M174):
/feedback/:idmit allen Spec-D.3-Blöcken + Activity-Log + Hard-Delete; Mailbox-Direktlink-Tab (/feedback/mailbox) + Klartext-Hinweis (Spec C). - In-App-Widget (M175):
AddFeedbackButton.tsxals Vorlage nachpackages/ui-hivegridportieren; Route-Anzeige, DSGVO-Hinweis, 10-Zeichen-Validierung, Browser-Info-Util, App-Version, Attachment-Upload (M052/M23-FileObject),html2canvas-pro-Screenshot ergänzen; Submit-Action (BPapp.$tenant.tsx-Pattern) anpassen; mailto-Trigger in Public-/help/-Routen. - 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.