Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/designer-briefs/P03-querschnitts-oberflaechen.md

56 lines
6.7 KiB
Markdown

# Designer-Brief · P3 — Querschnitts-Oberflächen
**Phase:** 3/21 · **Module:** M21 (Audit-Viewer/Export) · M22 (Notification-Center/Settings) · M30 (Sprach-Settings DE) · **Owner-Dev:** Akeshan (AK-P3) · **Designer:** David (D-P3)
**Quellen:** `ROADMAP.md` §Phase 3 · `SCREEN-MAP.md` §2-Anhang (Audit-Viewer / Notification-Center / Notification-Settings) · `REQUIREMENTS.md` Modul 21/22/30 (REQ-audit-retention-export, -permissions, -notification-versand-pipeline, -i18n-outbound) · `ENTITY-MODEL.md` Domäne 2 (AuditEntry, Notification, NotificationPreference, NotificationDevice; i18n = Felder, keine Tabelle) · `_bmad-output/specs/M21-audit-log.md`, `M22-notifications.md`, `M30-i18n.md` (Oberflächen-Teile; Service-Kerne liegen in P1)
**Subframe:** Pflicht je Route. Archetypen aus D0 (A2 Liste + Drawer, A6 Settings).
> ⚙️ **Scope-Hinweis (Scope-Schnitte 11./12.06.):** v1 ist bewusst gedünnt. Audit: **kein Retention-Editor / Legal-Hold / Saved-Views** (→ v2; fixe Default-Retention). Notifications: **kein Quiet-Hours / keine Bündelung / kein Push-Kanal** (→ v2 mit M117; Push-Kanal = Stub). i18n: **v1 DE-only — kein Sprach-Wechsler, keine EN-Templates** (→ v2); die Sprach-UX beschränkt sich auf den fest-DE-Hinweis im Profil + `Contact.language`-Feld als Outbound-Steuerung (ab v2 aktiv). Die Service-Kerne (Hash-Kette, notify(), i18n-Engine) liegen schon in P1 — P3 liefert nur die Bedien-Oberflächen.
## Was dieses Modul tut (Kurzfassung)
Stellt die Bedien-Oberflächen der in P1 gebauten Plattformdienste bereit. Audit-Viewer: gefilterter, permission-gegateter Trail mit Vorher-/Nachher-Diff-Drawer und Compliance-Export (NDJSON/CSV ins Hetzner-Object-Storage, fixe Default-Retention). Notification-Center: In-App-Liste (SSE) mit Read-Status, Deeplink, Bulk; plus Pro-User-Präferenzen (Event-Typen je Modul, In-App/Email-Toggle, Master „alle Emails aus"). Sprach-Settings: v1 DE-only-Hinweis; `Contact.language` als Feld vorhanden, alle Strings laufen durch `t()` mit vollständiger `de`-Locale (`verify:i18n`-Gate grün).
## Benötigte Screens
| Screen [Route] | Kern-Inhalt | Archetyp |
|---|---|---|
| Audit-Viewer [`/admin/audit`] | Zeit, Actor (+Kind-Marker User/Automation/KI/Admin), Aktion, Subjekt, **deutscher Summary-Text** · Filter: Zeitraum (Default 30 Tage, max 24 Monate ohne Export), Actor, Kategorie, Subjekt-Typ · Quick-Filter (Klick auf Actor/Subject/Action) · **Detail-Drawer mit Diff-Ansicht** (Feld-für-Feld Vorher/Nachher, sensible Diffs nur „Wert geändert") · Export-Button (CSV/NDJSON, Zweck-Pflichtfeld) | A2+Drawer |
| Audit-Export-Jobs [`/admin/audit/exports` + `/new` + `/:id`] | Export-Job-Liste · Anlage (Filter-Kriterien wie Listen-View, Format, Zweck) · Job-Status + Download (signed-URL) | A2 |
| Notification-Center [Topbar-Drawer + `/notifications`] | Einträge: Titel, Body, Actor, Zeit, Read-Status, Priorität · Tabs Alle/Ungelesen · Mark-read/unread, Klick→Deeplink · Bulk-Clear · Klartext bei pausierten Emails (Bounce) | A2 |
| Notification-Settings [`/settings/notifications`] | Event-Typen nach Modul gruppiert, je **In-App/Email-Toggle** + Priority-Selektor · Master-Toggle „alle Emails aus" (mit Klartext: betrifft auch zukünftige Event-Typen) | A6 |
**Eingebettete Oberflächen (kein eigener Screen, aber zu designen):**
- Per-Subject-Audit-Drawer in jeder Detail-View (filtert auf `subject_type+subject_id`, Permission `audit.read`)
- Per-User-Audit-Drawer in `/admin/users/:id` (Aktionen dieses Users)
- Sprach-Hinweis „fest DE" im Profil-Screen (P2) — kein eigener Screen
*(Quiet-Hours/Bündelung/Push-Devices-Liste/Retention-Editor/Legal-Hold/Saved-Views/Sprach-Wechsler → v2.)*
## Geplante Features (muss abgedeckt sein)
- [ ] Audit-Viewer permission-gegated (audit.read), server-side-Filter zwingend (Tabellen werden groß), deutscher Summary-Text je Eintrag, Actor-Kind-Marker
- [ ] Diff-Detail-Drawer (Feld-für-Feld Vorher/Nachher; Datenschutz-Maskierung bei sensiblen Inhalten) + „Verlauf dieses Objekts"/„Ähnliche Einträge"
- [ ] Compliance-Export als NDJSON/CSV ins S3-kompatible Hetzner-Object-Storage mit Zweck-Pflichtfeld + Export-Job-Status/Download; fixe Default-Retention + Cron-Auto-Löschung; jeder Export selbst auditiert (`audit.exported`)
- [ ] Notification-Versand-Pipeline-Oberfläche: In-App-Center via SSE (sofort, ohne Bündelung), Email-Kanal; Push-Kanal als Stub bis v2
- [ ] Notification-Center mit Read-Status, Deeplink, Tabs Alle/Ungelesen, Bulk-Clear; Bounce-Klartext „Emails an dich kommen aktuell nicht an"
- [ ] Notification-Präferenzen pro User (Event-Typen je Modul, In-App/Email-Toggle, Priority-Threshold, Master „alle Emails aus")
- [ ] i18n: alle Oberflächen-Strings durch `t()` mit vollständiger `de`-Locale (`verify:i18n`-Gate grün); `Contact.language`-Feld vorhanden (Outbound-Steuerung ab v2); v1 fest DE — Wechsler/EN-Templates ausdrücklich → v2
- [ ] *(→ v2)* ~~Quiet-Hours, Bündelung, Push-Limits, Retention-Policy/Legal-Hold/Saved-Views, Sprach-Wechsler~~
## Benötigte UI-Elemente (Liste, KEIN Layout — Anordnung = Davids freie Hand)
Audit-Daten-Tabelle (server-paginiert) mit Actor-Kind-Marker (visuell unterscheidbar: User/Automation/KI/Admin), deutschem Summary-Text, Subjekt-Verlinkung; Filter-Bar (Datum-Range-Selektor mit Presets, Actor-, Kategorie-, Subjekt-Typ-Filter) mit Quick-Filter-Klick auf Tabellenwerte; Detail-Drawer mit Feld-für-Feld-Diff-Visualisierung (Hinzufügung/Löschung/Änderung farblich, JSON-Strukturdiff, Maskierungs-Hinweis bei sensiblen Werten) + „Verlauf dieses Objekts"-/„Ähnliche Einträge"-Aktionen; Export-Button der zum Export-Job-Anlage-Dialog führt (Format-Auswahl CSV/NDJSON + Zweck-Pflichtfeld); Export-Job-Liste mit Status-Badge + Download-Link; eingebetteter Per-Subject- und Per-User-Audit-Drawer (wiederverwendbar in Detail-Views); Notification-Liste/-Drawer mit Titel/Body/Actor/Zeit/Read-Status/Prioritäts-Marker, Alle-/Ungelesen-Tabs, Mark-read/unread-Aktion, Deeplink-Klick, Bulk-Clear, Bounce-Klartext-Hinweis; Notification-Bell-Anbindung (Badge liegt in P1-Topbar); Notification-Präferenzen-Editor mit nach Modul gruppierten Event-Typen, je Zeile In-App-/Email-Toggle + Priority-Selektor, Master-„alle-Emails-aus"-Toggle mit Klartext; DE-Sprach-Hinweis-Element; Empty-/Loading-/Permission-Denied-/Fehler-States (Klartext, z. B. leerer Center „Keine Benachrichtigungen — sobald etwas Wichtiges passiert, erscheint es hier").
## Davids Delta (David füllt aus)
- [ ] Überschriebene/geänderte Spec-Punkte:
- [ ] Neue UI/UX-Entscheidungen:
- [ ] Subframe-Screen-Link(s):
- [ ] Offene Fragen an Dev:
## Dev-Nachzug (wir nach Davids Delta)
- [ ] Spec/ENTITY-MODEL an Davids Entscheidungen angepasst:
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen:
- [ ] Plane-Ticket (AK-P3) aktualisiert: