121 lines
14 KiB
Markdown
121 lines
14 KiB
Markdown
# 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.*
|