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

121 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.*