--- module: 37 title: Plattform-Admin phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-1, LP-6, LP-9, LP-10, LP-13] spec_style: requirements-pur --- # Modul 37 — Plattform-Admin > **Detail-Spec gemäß LP-9.** Eigene Welt für uns als Software-Betreiber. **Hardgrenze:** läuft auf Sub-Domain `admin.hivegrid.de`, ist **nicht** unter `/{tenant}/...` erreichbar, hat eine **eigene User-Klasse** (`AdminUser`) parallel zu `User`/`TenantUser`, eigene Auth-Schicht, eigenes Permission-System. Kein Cross-Routing zwischen App-Welt und Admin-Welt. ## Themenblöcke ``` A. Architektur-Trennung (Sub-Domain, eigene Codebase-Routes, AdminUser-Klasse) B. Datenmodell (AdminUser, AdminRole, AdminPermission, AdminSession, AdminAuditLog, AdminLead, AdminDeal, AdminSupportTicket, AdminTenantNote) C. Auth (Login, 2FA, Session) D. Permission-System (eigenes Bundle-Modell) E. Bereiche / Routes F. Dashboard G. Tenant-Verwaltung H. User-Verwaltung I. Subscription-Management J. Feature-Flag-Verwaltung (siehe Modul 32) K. Health/Metrics-Dashboard L. Cross-Tenant-Audit-Trails M. Lead-Management (eigenes CRM-Lite für UNSERE Sales) N. Manuelle Tenant-Anlage und Trial-Verlängerung O. Support-Bereich P. Subprozessoren- und AVV-Verwaltung (Querschnitt zu Modul 35) Q. Klartext-Hinweise R. Phase 2 Erweiterungen ``` --- ## Block A — Architektur-Trennung ### Sub-Domain ``` hivegrid.de → Marketing-Site (extern, Next.js) app.hivegrid.de → SaaS-Anwendung (Tenant-Welt) admin.hivegrid.de → Plattform-Admin (uns, dieser Modul-Scope) ``` ### Hard-Trennungs-Vorschriften - **Code-Routes** in `admin.hivegrid.de` sind **nicht** unter `/{tenant}/...` erreichbar — separate Routen-Struktur - **AdminUser** ist eigene Entität, **nicht** TenantUser, **nicht** User. Kein Login-Pfad zwischen Welten. - **Cookies/Sessions** sind Domain-getrennt (`admin.hivegrid.de` setzt nicht das gleiche Cookie wie `app.hivegrid.de`) - **DB-Zugriff:** AdminUser hat **kein** Tenant-Membership, RLS gilt nicht für admin-eigene Tabellen. Tenant-Daten werden über App-Role mit gesetztem Tenant-Context gelesen (gleicher Pattern wie App-Code, aber Admin kann Tenant-Context wählen). Admin-Code hat **kein** `BYPASSRLS`-Privileg — Admin liest Tenant-Daten bewusst durch RLS, mit explizit gesetztem `app.tenant_id`. - **Audit-Trennung:** Admin-Aktionen werden in `AdminAuditLog` geloggt (eigene Tabelle), nicht in tenant-internem Audit-Log - **Permissions:** eigene Tabellen (`AdminRole`, `AdminPermission`), unabhängig von Tenant-Rollen ### Zugriff-Pattern - AdminUser kann auf `admin.hivegrid.de/tenants/:tenantId/...` Tenant-Daten **lesen** (mit Audit) - Schreib-Aktionen auf Tenant-Daten sind explizit limitiert (siehe Block G — z.B. Status-Wechsel, Trial-Verlängerung, Support-Notes anlegen) — kein freies CRUD auf Tenant-Daten durch Admin - Direkte Datenbearbeitung im Tenant-Kontext bleibt dem Tenant-User vorbehalten ### Begründung Maximale Sicherheit (Compromise-Radius eingegrenzt), klare DSGVO-Verantwortlichkeit (Admin-Aktionen separat dokumentiert), klare Permission-Hygiene (Plattform-Rolle nicht versehentlich in Tenant-Welt kopiert). --- ## Block B — Datenmodell ### AdminUser Plattform-globale Tabelle, **kein** RLS, App-Code-gegated. - `id`, `created_at`, `updated_at` - `email` (unique, Pflicht — wird zum Login-Identifier) - `first_name`, `last_name` - `password_hash` (Bcrypt, Cost 12) - `totp_secret` (verschlüsselt; NULL wenn 2FA nicht eingerichtet) - `totp_enabled` (Boolean — Pflicht für AdminUsers, siehe Block C) - `totp_backup_codes_hash` (Array, gehashed) - `last_login_at`, `last_login_ip` - `status` (Enum: `active | disabled | locked`) - `disabled_reason` (optional) - `created_by_admin_user_id` (Bootstrap-Sonderfall: erster Admin via CLI/Seeding) **Constraints:** `totp_enabled` muss `true` sein bevor `status='active'` möglich ist. ### AdminRole / AdminPermission / AdminUserRole Eigene RBAC parallel zur Tenant-RBAC. **AdminRole:** - `id`, `name` (z.B. *„Super-Admin", „Support", „Sales"*), `description`, `is_template_origin` **AdminPermission:** - `id`, `permission_id` (Enum-String, z.B. `admin.tenants.read`) **AdminRolePermission:** - `admin_role_id`, `admin_permission_id` **AdminUserRole:** - `admin_user_id`, `admin_role_id` ### AdminSession Server-Side, Postgres. - `id`, `admin_user_id`, `created_at`, `expires_at`, `last_seen_at` - `ip`, `user_agent` - `revoked_at` (für globalen Logout) ### AdminAuditLog Plattform-globale Audit-Tabelle. Cross-Tenant — auch Aktionen die Tenant-Daten verändern werden hier geloggt. - `id`, `created_at` - `admin_user_id` (Akteur, NULL bei System-Cron) - `actor_kind` (Enum: `admin_user | system | api`) - `action_type` (z.B. `tenant.status_changed`, `feature_flag.tenant_override.created`, `subscription.manual_override`) - `target_kind` (Enum: `tenant | tenant_user | admin_user | feature_flag | subscription | subprocessor | avv_version | system`) - `target_id` - `summary_text` (Klartext-Pflicht in DE) - `metadata` (JSONB — Diff, Vorher/Nachher, Reason-Text, etc.) - `ip`, `user_agent` **Indizes:** `(admin_user_id, created_at DESC)`, `(target_kind, target_id, created_at DESC)`, `(action_type, created_at DESC)`. ### AdminTenantNote Frei-Text-Notizen pro Tenant durch Admin (Sales/Support). - `id`, `tenant_id`, `created_at`, `created_by_admin_user_id` - `note_text` (Markdown) - `category` (Enum: `sales | support | technical | billing | other`) - `pinned` (Boolean — wichtige Notes oben) - `archived_at` **Indizes:** `(tenant_id, pinned DESC, created_at DESC)`. ### Lead-Management-Datenmodell (für UNSERE eigenen HiveGrid-Sales) > **Wichtig:** Bewusst getrennt von Tenant-CRM. Wir verkaufen HiveGrid an Handwerksbetriebe und brauchen ein eigenes Lead-Tool. Variante (a) aus Brainstorming gewählt: separates Lead-Tool im Admin, kein Master-Tenant-Dogfooding. **AdminLead:** - `id`, `created_at`, `updated_at` - `first_name`, `last_name`, `email`, `phone`, `company_name` (alle nullable — Form-Submissions sind dünn) - `industry` (Enum: `shk | other`) - `company_size` (Enum: `1-10 | 11-25 | 26-50 | 51-100 | 100+`) - `source` (Enum: `marketing_form | demo_booking | referral | manual | inbound_email | partner | other`) - `source_detail` (Freitext, z.B. *„LinkedIn-Kampagne Mai 2026"*) - `status` (Enum: `new | qualified | contacted | demo_scheduled | proposal_sent | won | lost | spam`) - `assigned_to_admin_user_id` - `lost_reason` (optional Enum + Freitext bei `lost`) - `notes` (Markdown) - `converted_to_tenant_id` (FK auf Tenant bei `won` + nach Tenant-Anlage) - `archived_at` **AdminDeal** (sehr leichtgewichtig, eigene Sales-Pipeline): - `id`, `created_at`, `updated_at` - `admin_lead_id` (FK) - `expected_arr_eur` (geschätzter Jahresumsatz) - `seats_office_estimated`, `seats_field_estimated` - `stage` (Enum: `discovery | demo | proposal | negotiation | won | lost`) - `expected_close_date` - `assigned_to_admin_user_id` - `notes` **AdminLeadActivity** (eigener Activity-Stream für Lead-Management): - `id`, `admin_lead_id`, `created_at`, `actor_admin_user_id` - `activity_type` (Enum: `email_sent | email_received | call_made | demo_held | proposal_sent | note_added | stage_changed | assigned_changed`) - `summary_text` (Pflicht, DE) - `metadata` (JSONB) ### AdminSupportTicket Inbound-Feedback aus Tenants und In-App-Feedback-Widget-Submissions. - `id`, `created_at`, `updated_at` - `source_kind` (Enum: `in_app_feedback_widget | inbound_email | manual`) - `tenant_id` (NULL wenn nicht zuordenbar) - `tenant_user_id` (NULL wenn anonym) - `subject`, `body` (Markdown) - `status` (Enum: `open | in_progress | waiting_user | resolved | closed`) - `priority` (Enum: `low | normal | high | urgent`) - `assigned_to_admin_user_id` - `tags[]` (frei: `bug`, `feature_request`, `billing`, `onboarding`, etc.) - `resolved_at` **AdminSupportTicketMessage** (Konversation): - `id`, `ticket_id`, `created_at`, `actor_kind` (Enum: `admin_user | tenant_user | system`), `actor_user_id`, `body`, `attachments[]` --- ## Block C — Auth ### Login - Email + Passwort (NIST-konform analog Tenant-User: ≥12 Zeichen, HIBP-Check, Bcrypt Cost 12) - **2FA Pflicht** für jeden AdminUser (kein Opt-Out — Plattform-Sicherheit) - TOTP-only, gleicher Flow wie Tenant-User-2FA - Magic-Link **nicht** verfügbar für AdminUser (zu hohes Risiko bei Email-Account-Compromise) ### Login-Schutz - Rate-Limit: 5 Fehlversuche / 15 Min → 15 Min Lockout - Captcha ab 3. Fehlversuch - Bei 10 Fehlversuchen in 24h: AdminUser-Status auf `locked`, manuelle Reaktivierung durch anderen Super-Admin ### Session - Server-Side, Postgres - Default-Lebenszeit: **8 Stunden** (kürzer als Tenant-User wegen höherem Risiko) - Inaktivitäts-Timeout: 1h ohne Aktivität → Re-Login - IP-Bindung: bei IP-Wechsel mitten in Session → Re-Login - Cookie: HTTP-only, Secure, SameSite=Strict ### Session-Übersicht - Eigene Settings-Seite `admin.hivegrid.de/settings/security/` - Liste aktiver Sessions, individueller Revoke - Trust-Device **nicht** verfügbar (jeder Login mit 2FA) ### Initial-AdminUser - Bootstrap via CLI-Seed-Script (kein Public-Signup) - Erste AdminUser-Rolle: `super_admin` (alle Permissions) - Weitere AdminUsers werden durch `super_admin` über UI angelegt --- ## Block D — Permission-System ### Bundle-Stufen pro Bereich (analog Variante 2 in Modul 27) ``` admin.tenants.none / read / write / admin admin.users.none / read / write / admin admin.subscriptions.none / read / write / admin admin.feature_flags.none / viewer / operator / owner (siehe Modul 32) admin.metrics.none / read admin.audit.none / read admin.leads.none / read_own / read_all / write / admin admin.support.none / read / write / admin admin.legal.none / read / write (Subprozessoren, AVV-Versionen) admin.admin_users.none / read / write / admin (AdminUser-Verwaltung) admin.system.none / read / admin (Infra-Aktionen, Worker-Steuerung) ``` ### Default-Rollen (Seeding) | Rolle | Bundles | |---|---| | `super_admin` | alle Permissions, alle Bundles auf höchster Stufe | | `support` | `tenants.read`, `users.read`, `subscriptions.read`, `metrics.read`, `audit.read`, `support.admin`, `feature_flags.viewer`, `legal.read` | | `sales` | `leads.admin`, `tenants.read`, `subscriptions.read`, `metrics.read`, `support.read` | | `engineering` | `metrics.read`, `audit.read`, `feature_flags.owner`, `system.admin`, `tenants.read`, `users.read` | | `viewer` (read-only) | `tenants.read`, `users.read`, `subscriptions.read`, `metrics.read`, `audit.read`, `feature_flags.viewer`, `support.read`, `leads.read_all`, `legal.read` | **Anpassbarkeit:** alle Rollen editierbar wie in Tenant-RBAC. Rollen sind Pre-Sets, atomare Permissions kombinierbar. ### Self-Permission-Schutz - Letzter `super_admin` kann sich nicht selbst entziehen - AdminUser kann sich nicht selbst deaktivieren --- ## Block E — Bereiche / Routes ``` admin.hivegrid.de/ → Login admin.hivegrid.de/login → Login-Form admin.hivegrid.de/2fa → 2FA-Eingabe admin.hivegrid.de/dashboard → Plattform-Dashboard (siehe Block F) admin.hivegrid.de/tenants → Tenant-Liste admin.hivegrid.de/tenants/new → Manuelle Tenant-Anlage (siehe Block N) admin.hivegrid.de/tenants/:tenantId → Tenant-Detail (siehe Block G) admin.hivegrid.de/tenants/:tenantId/... → Tenant-Sub-Bereiche admin.hivegrid.de/users → User-Verwaltung (siehe Block H) admin.hivegrid.de/users/:userId → User-Detail admin.hivegrid.de/admin-users → AdminUser-Verwaltung admin.hivegrid.de/admin-users/:id → AdminUser-Detail (Rollen, Audit, Sessions) admin.hivegrid.de/admin-users/roles → AdminRole-Editor admin.hivegrid.de/subscriptions → Subscription-Management (siehe Block I) admin.hivegrid.de/subscriptions/:id → Subscription-Detail admin.hivegrid.de/feature-flags/ → siehe Modul 32 admin.hivegrid.de/health → Health/Metrics-Dashboard (siehe Block K) admin.hivegrid.de/health/workers → Worker-Queue-Detail admin.hivegrid.de/health/kwp-sync → KWP-Sync-Status pro Tenant admin.hivegrid.de/audit → Cross-Tenant-Audit-Trails (siehe Block L) admin.hivegrid.de/leads → Lead-Inbox (siehe Block M) admin.hivegrid.de/leads/:id → Lead-Detail admin.hivegrid.de/leads/deals → Deal-Pipeline (Sales) admin.hivegrid.de/leads/deals/:id → Deal-Detail admin.hivegrid.de/support → Support-Inbox (siehe Block O) admin.hivegrid.de/support/:ticketId → Ticket-Detail admin.hivegrid.de/legal/subprocessors → Subprozessoren-Verwaltung (siehe Block P) admin.hivegrid.de/legal/avv → AVV-Versions-Verwaltung admin.hivegrid.de/settings/account → Eigenes Profil admin.hivegrid.de/settings/security → 2FA, Sessions ``` **Sidebar-Hauptpunkte:** Dashboard, Tenants, Users, Subscriptions, Feature-Flags, Health, Audit, Leads, Support, Legal, AdminUsers, Settings. --- ## Block F — Dashboard ### Zu zeigende Daten - **Tenants-Übersicht:** - Gesamt-Tenant-Zahl mit Trend (vs. Vormonat) - Aktive Tenants nach Status (`trial`, `active`, `past_due`, `frozen`, `suspended`, `deletion_pending`) - Neue Tenants letzte 7/30 Tage - **MRR / Wachstum:** - Monthly Recurring Revenue aktuell - MRR-Trend (Chart letzte 12 Monate) - Neue MRR / Churned MRR / Expansion MRR letzten Monat - ARPU (Average Revenue per Tenant) - **Health:** - System-Status-Indikator (grün/gelb/rot mit Klartext bei Auffälligkeit) - Worker-Queue-Backlog (Anzahl Jobs, oldest pending) - Error-Rate letzte 24h - KWP-Sync-Health (Anzahl Tenants mit aktivem Heartbeat / fehlerhaft) - **Aktivität:** - Anzahl aktiver Tenant-User letzte 24h / 7d - Top 5 Tenants nach Activity - **Sales-Pipeline (UNSERE):** - Anzahl Leads in jedem Status - Pipeline-Volumen (Summe `expected_arr_eur` pro Stage) - **Support:** - Offene Tickets, ältester offener - Durchschnittliche Lösungs-Zeit ### Benötigte UI-Elemente - Widget-basierte Anzeige (Kacheln pro Bereich) - Klick auf jede Kachel → Drill-Down auf zugehörigen Bereich - Zeitraum-Wechsler (24h / 7d / 30d / 12 Monate) - Refresh-Funktion ### Performance - Daten werden gecacht (Redis, TTL 5 Min) - Live-Werte (System-Status, Queue-Backlog) sind direkter DB-/Redis-Read - Aggregat-Berechnung als Background-Job (Hourly), Dashboard liest Snapshot --- ## Block G — Tenant-Verwaltung ### Tenant-Liste (`admin.hivegrid.de/tenants`) **Zu zeigende Daten pro Eintrag:** - Tenant-Name + Slug - Status mit Klartext-Farbe - Subscription-Plan + MRR - Erstellt-Datum - Anzahl Tenant-User - Letzte User-Aktivität - Branche, Größe - Verantwortlicher AdminUser (für Sales-Zuordnung) **Benötigte UI-Elemente:** - Tabellarische Liste - Filter: Status, Plan, Branche, Größe, Erstellt zwischen, mit/ohne aktive Subscription - Suche über Name + Slug + Email der Tenant-Admins - Sortierung pro Spalte - Spalten-Konfiguration - Bulk-Actions: Tag setzen, an AdminUser zuweisen, Email-Versand (Marketing-Newsletter, Pflicht-Hinweise) **Operationen:** - Klick auf Tenant → Detail - Schnelle Status-Aktion: Suspend / Reaktivieren (mit Bestätigung) - Manuelle Tenant-Anlage über Add-Funktion (siehe Block N) ### Tenant-Detail (`admin.hivegrid.de/tenants/:tenantId`) **Zu zeigende Daten:** - Stammdaten: Slug, Name, Branche, Größe, Erstellt-Datum, Status, Subscription, primärer Tenant-Admin - Kontakt-Info (Email, Telefon, Adresse aus Signup) - Tenant-Admins-Liste (welche User haben `tenant.admin`) - Activity-Indikatoren: letzte 7/30 Tage, MAU, Speicher-Nutzung, KWP-Sync-Status - Subscription-Detail: Plan, Seats, MRR, nächste Rechnung, Legacy-Provider-Customer-ID (mit Link zu Legacy-Provider-Dashboard) - Trial-Info (falls Trial): Restdauer, manuelle Verlängerung möglich - Feature-Flag-Auswertungen für diesen Tenant (siehe Modul 32) - Subprozessoren-Status (welche AVV-Version akzeptiert) - Notizen (Liste der `AdminTenantNote` mit Pin-Funktion) - Activity-Log (Cross-Modul: Logins, Status-Wechsel, Plan-Wechsel, Support-Interaktionen — Quelle: AdminAuditLog gefiltert auf `target_kind=tenant, target_id=tenantId` + Tenant-eigenes Audit für Lese-Sicht) **Benötigte UI-Elemente:** - Sektionierte Anzeige: Stammdaten, Subscription, Users, Activity, Notes, Audit, Feature-Flags, Health - Tab- oder Sektionen-Navigation - Notes-Editor (Markdown, Kategorie, Pin-Toggle) - Status-Wechsler mit Bestätigungs-Dialog und Reason-Text-Pflicht - Trial-Verlängerungs-Funktion: Datum-Picker + Reason-Text - Subscription-Override-Funktion (siehe Block I) - Impersonate-Funktion: *„Als Tenant-Admin einloggen"* — siehe unten **Operationen:** - Status ändern: → `suspended`, → `active`, → `frozen` mit Klartext-Reason - Trial verlängern (Datum-Eingabe + Reason) - Subscription manuell überschreiben (Plan, Seats, Sonderpreis) - Tenant-Notiz anlegen/editieren/pinnen - Feature-Flag-Override für diesen Tenant setzen - Email an Tenant-Admin(s) senden (Template-basiert oder freier Text) - Tenant-Daten-Export anstoßen (für Support-Fall, vermittelt Tenant-Admin den Download — siehe Modul 35) - Tenant-Lösch-Workflow im Auftrag des Tenant-Admins anstoßen (`admin_initiated`-Reason, siehe Modul 35) - KWP-Sync-Status detailliert ansehen mit Re-Trigger-Funktion ### Impersonate-Funktion - AdminUser kann *„Als Tenant-User einloggen"* klicken - Reason-Text-Pflicht (z.B. *„Bug-Reproduktion Ticket #123"*) - Generiert temporäre Session als gewählter Tenant-User (max. 30 Min) - Sichtbar im Tenant für andere Tenant-User: Klartext-Banner *„Plattform-Support hat sich gerade als [Name] eingeloggt — Ticket #123"* - Audit-Log mit voller Reason-Spur - Permission: `admin.tenants.admin` + spezielles `admin.tenants.impersonate` Bundle ### Permissions - Liste/Detail: `admin.tenants.read` - Notes anlegen/bearbeiten: `admin.tenants.write` - Status-Wechsel, Trial-Verlängerung, Subscription-Override, Lösch-Workflow: `admin.tenants.admin` - Impersonate: `admin.tenants.impersonate` - Klartext-Reason-Text bei sensitiven Aktionen Pflicht --- ## Block H — User-Verwaltung ### User-Liste (`admin.hivegrid.de/users`) **Zu zeigende Daten pro Eintrag:** - Email, Name - Anzahl Tenant-Memberships - Letzte Aktivität - 2FA-Status - Erstellt-Datum - Status (aktiv / disabled / gelöscht) **Benötigte UI-Elemente:** - Tabellarische Liste mit Filter (Status, 2FA, mit/ohne Memberships) - Suche über Email + Name - Klick → Detail **Operationen:** - Detail öffnen - Bulk-Email an User-Auswahl (z.B. Pflicht-Mitteilungen) ### User-Detail (`admin.hivegrid.de/users/:userId`) **Zu zeigende Daten:** - Stammdaten (Email, Name, Sprache, 2FA-Status, OAuth-Verknüpfungen) - Liste aller Tenant-Memberships mit Rolle pro Tenant - Aktive Sessions - Letzte Logins (Datum, IP, Geo, User-Agent) - 2FA-Trust-Devices-Liste - Audit-Spur (User-bezogen) - Account-Lösch-Status (falls in Bearbeitung) **Operationen:** - 2FA zurücksetzen (mit Reason-Text-Pflicht) - Sessions revoken - Email ändern (mit Audit + Verifikations-Email) - User deaktivieren / reaktivieren - Account-Lösch-Funktion im Auftrag (für Support-Fälle; siehe Modul 35) - Wiederherstellung innerhalb 24h-Reverse-Window (siehe Modul 27 D.3) **Permissions:** `admin.users.read` für Lese, `admin.users.write` für Stamm, `admin.users.admin` für Lösch-/2FA-Reset. ### AdminUser-Verwaltung (`admin.hivegrid.de/admin-users`) **Zu zeigende Daten pro Eintrag:** - Email, Name, Rollen, Status, 2FA-Status, letzter Login, Anzahl aktiver Sessions **Benötigte UI-Elemente:** - Liste mit Filter / Suche - AdminUser-Anlegen (Email, Name, Initial-Rolle → Magic-Link-Setup-Email mit 2FA-Setup-Pflicht beim ersten Login) - AdminRole-Editor (analog Tenant-RBAC) **Operationen:** - AdminUser anlegen / deaktivieren / Rolle ändern - 2FA zurücksetzen (durch anderen Super-Admin) - Sessions revoken - AdminRoles editieren **Permissions:** `admin.admin_users.admin`. Self-Permission-Schutz für letzten `super_admin`. --- ## Block I — Subscription-Management ### Liste (`admin.hivegrid.de/subscriptions`) **Zu zeigende Daten pro Eintrag:** - Tenant-Name, Plan, MRR, Status (active, trialing, past_due, canceled), Renewal-Datum, Legacy-Provider-Sync-Status **Benötigte UI-Elemente:** - Tabellarische Liste mit Filter (Plan, Status, MRR-Range) - Suche über Tenant-Name - Klick → Detail ### Detail (`admin.hivegrid.de/subscriptions/:id`) **Zu zeigende Daten:** - Legacy-Provider-Customer-ID, Subscription-ID (mit Link zu Legacy-Provider-Dashboard) - Aktueller Plan, Seats (Office + Field), MRR - Trial-Status, Trial-Ende - Rechnungs-History - Override-Vermerke (manueller Plan / Sonderpreis) **Operationen:** - **Legacy-Provider-Sync forcieren** (zieht aktuellen Legacy-Provider-Stand und gleicht ab) - **Manuelle Override** für Enterprise-Kunden: - Plan überschreiben - Seats-Limit überschreiben - Sonderpreis (Custom-MRR) - Reason-Text-Pflicht - Override-Eintrag im Audit - Klartext-Hinweis im Tenant-Detail: *„Manuelle Konditionen aktiv — siehe Override-Vermerk"* - **Trial verlängern** (analog Block G) - **Manuelle Rechnung anstoßen** (für Setup-Fees, Custom-Onboarding) - **Abo kündigen** (Legacy-Provider-Cancel + Tenant-Lösch-Workflow-Trigger) - **Refund anstoßen** (mit Reason-Text + Legacy-Provider-Sync) **Permissions:** Lese `admin.subscriptions.read`, Schreib-Aktionen `admin.subscriptions.admin`. ### Legacy-Provider-Webhook-Sync - Events von Legacy-Provider (Subscription-Update, Payment-Failed, Invoice-Paid) werden automatisch in Tenant-Daten gespiegelt (Modul 28) - Manuelle Re-Sync-Funktion in diesem Bereich, falls Webhook ausgefallen war --- ## Block J — Feature-Flag-Verwaltung **Komplette Spec siehe Modul 32.** Nur Querverweise hier: - Routes leben unter `admin.hivegrid.de/feature-flags/` - Permission-Bundles `admin.feature_flags.viewer | operator | owner` - Audit fließt in `AdminAuditLog` --- ## Block K — Health/Metrics-Dashboard ### System-Status **Zu zeigende Daten:** - Web-Service: Uptime, P50/P95-Latency, Error-Rate - API-Service: gleiches - Worker-Service: Backlog, oldest-pending, Error-Rate - Scheduler-Service: letzter Run pro Cron-Job - DB: Connection-Pool-Status, slow-Query-Count - Redis: Memory, Connection-Count - Storage (Scaleway): aktuelle Nutzung pro Bucket-Pfad **Benötigte UI-Elemente:** - Real-Time-Updates (Polling oder Websocket) - Klick auf Service → Detail mit Metriken-Charts (letzte 24h / 7d) - Alert-Indikator bei Auffälligkeiten ### Worker-Queues (`admin.hivegrid.de/health/workers`) - Liste aller BullMQ-Queues (Automation, Email-Sending, KWP-Sync, GdprExport, etc.) - Pro Queue: Active, Waiting, Delayed, Failed, Completed - Klick auf Queue → Job-Liste mit Detail (Payload, Error-Stack) - Funktionen: Retry failed Jobs (Bulk + einzeln), Pause/Resume Queue, Job manuell aus Queue entfernen ### KWP-Sync-Status (`admin.hivegrid.de/health/kwp-sync`) - Liste aller Tenants mit aktiver KWP-Integration - Pro Tenant: Heartbeat-Status (grün/gelb/rot, letzter Heartbeat-Zeitstempel), Queue-Backlog, letzter erfolgreicher Sync, Error-Count letzte 24h - Klick auf Tenant → Detail mit kwpsync.exe-Logs, Versions-Info, Schema-Drift-Sentinel-Hits ### Error-Rate - Sentry-Integration (oder direkter Read aus DB) - Top 10 Errors letzten 24h mit Count und Klick-Drill auf Stack-Trace **Permissions:** `admin.metrics.read` für Lese, `admin.system.admin` für Worker-Steuerung. --- ## Block L — Cross-Tenant-Audit-Trails ### Audit-Log (`admin.hivegrid.de/audit`) **Zu zeigende Daten:** - Cross-Tenant-Liste aus `AdminAuditLog` + aggregierter Read-Zugriff auf alle Tenant-internen Audit-Logs - Pro Eintrag: Datum, Akteur (AdminUser oder Tenant-User), Tenant-Kontext, Action-Type, Summary-Text, Diff (in Detail-Drawer) **Benötigte UI-Elemente:** - Tabellarische Liste mit Filter: - Akteur (AdminUser, Tenant-User, System) - Tenant (Auto-Complete) - Action-Type (Multi-Select aus bekannten Typen) - Zeitraum (Date-Range) - Target-Kind - Volltext-Suche in `summary_text` - Detail-Drawer mit voller Diff - Export (CSV/JSON) für Compliance-Anfragen **Operationen:** - Audit-Einträge sind **read-only** — keine Edit-/Delete-Funktion - Retention: 24 Monate Default für AdminAuditLog (AV-aligned mit Modul 21) **Permissions:** `admin.audit.read` für alle Lese-Zugriffe. Compliance-relevante Exports erfordern `admin.audit.admin`. --- ## Block M — Lead-Management (UNSERE Sales) ### Lead-Inbox (`admin.hivegrid.de/leads`) **Zu zeigende Daten pro Eintrag:** - Name, Email, Firma, Branche, Größe - Source mit Detail - Status mit Farbe - Verantwortlicher AdminUser - Letzte Activity-Datum - Erstellt-Datum **Benötigte UI-Elemente:** - Tabellarische Liste - Filter: Status, Source, Branche, Größe, Verantwortlicher, Erstellt zwischen - Suche über Name + Email + Firma - Sortierung pro Spalte - Bulk-Actions: Status setzen, Verantwortlichen zuweisen, Tag setzen, exportieren **Operationen:** - Add-Funktion (manuell anlegen) - Detail öffnen ### Lead-Detail (`admin.hivegrid.de/leads/:id`) **Zu zeigende Daten:** - Stammdaten (alle Lead-Felder) - Activity-Stream (`AdminLeadActivity`) - Verknüpfter Deal falls vorhanden (`AdminDeal`) - Verknüpfter Tenant falls `won` und nach Tenant-Anlage - Notes (Markdown, kommen aus den `note_added`-Activities) **Benötigte UI-Elemente:** - Sektionen: Stamm, Activities, Deal, Notes - Inline-Edit für Stammdaten - Activity-Add-Funktionen: Note, Email-Log, Anruf-Log, Demo-Log - Status-Wechsler - Promote-to-Tenant-Funktion bei `won`: triggert manuelle Tenant-Anlage (siehe Block N) und setzt `converted_to_tenant_id` **Operationen:** - Stammdaten editieren - Status wechseln - Verantwortlichen ändern - Notes/Activities anlegen - Deal anlegen / verknüpfen (öffnet Modal mit Deal-Stammdaten) - Promote zu Tenant - Hard-Delete (nur als `spam` markiert; sonst archivieren) ### Deal-Pipeline (`admin.hivegrid.de/leads/deals`) **Zu zeigende Daten:** - Kanban-View mit Stage-Spalten (`discovery | demo | proposal | negotiation | won | lost`) - Pro Karte: Lead-Name, Firma, ARR, Verantwortlicher, Expected-Close-Date **Benötigte UI-Elemente:** - Kanban-Layout (Stages als Spalten) - Drag&Drop zwischen Stages - Filter: Verantwortlicher, ARR-Range, Expected-Close-Date - Detail-Drawer beim Klick **Operationen:** - Drag&Drop zum Stage-Wechsel - Klick → Deal-Detail mit Verknüpfung zu `AdminLead` ### Permissions - `admin.leads.read_own` (Sales sieht seine eigenen Leads) - `admin.leads.read_all` (Sales-Leitung) - `admin.leads.write` (anlegen, editieren) - `admin.leads.admin` (Bulk-Operations, Hard-Delete) --- ## Block N — Manuelle Tenant-Anlage und Trial-Verlängerung ### Manuelle Tenant-Anlage (`admin.hivegrid.de/tenants/new`) **Use-Cases:** - Demo-Termin: Sales legt Tenant für Demo-Vorbereitung an - Enterprise-Onboarding: nach Vertrag wird Tenant manuell angelegt mit Sonder-Konditionen - Lead-Promotion: aus `AdminLead` nach `won` **Benötigte UI-Elemente:** - Form mit Feldern: - Tenant-Name + Slug (Live-Validation analog Modul 27 A.2) - Branche, Größe - Initial-Tenant-Admin: Email, Vor-/Nachname (kann existierender User sein, dann Membership; sonst neue Account-Erstellung mit Magic-Link-Setup-Email) - Initial-Subscription: Plan auswählen (inkl. Custom-Override-Felder für Enterprise) - Trial-Dauer (Default 7 Tage, anpassbar) - Optional: Demo-Daten provisionieren (Häkchen pro Demo-Set: SHK-Demo, leer) - Reason-Text (Pflicht — was ist der Grund für die manuelle Anlage) **Operationen:** - Validierung aller Felder - Bestätigungs-Klick → Tenant wird angelegt, Initial-Tenant-Admin bekommt Email mit Magic-Link - AdminAuditLog-Eintrag mit Reason - Optional: Verknüpfung zu `AdminLead` (`converted_to_tenant_id` setzen) ### Trial-Verlängerung - Aus Tenant-Detail-View aufrufbar (siehe Block G) - Form: neues Trial-Ende-Datum + Reason-Text - Bestätigungs-Klick → Tenant-Status bleibt `trial`, `trial_ends_at` wird aktualisiert - Audit-Eintrag mit Vorher/Nachher-Datum + Reason - Klartext-Hinweis: *„Trial wurde bis [Datum] verlängert von [AdminUser] mit Reason: [Reason]"* **Permissions:** `admin.tenants.write` für Verlängerung, `admin.tenants.admin` für manuelle Anlage und Subscription-Override beim Anlegen. --- ## Block O — Support-Bereich ### Inbound-Quellen - **In-App-Feedback-Widget-Submissions:** Tenant-User klickt im Workspace auf Feedback-Button (siehe Modul 39) → erzeugt `AdminSupportTicket` mit `source_kind=in_app_feedback_widget` - **Inbound-Email:** Email an `support@hivegrid.de` wird parsed, erzeugt Ticket mit `source_kind=inbound_email`. Tenant-Zuordnung via Sender-Email-Match auf User-Tabelle. - **Manuelle Anlage:** AdminUser legt Ticket im Auftrag eines Anrufs/Chats an (`source_kind=manual`) ### Support-Inbox (`admin.hivegrid.de/support`) **Zu zeigende Daten pro Eintrag:** - Subject, Tenant-Name (falls zuordenbar), Tenant-User, Source, Status, Priority, Tags, Assigned, Erstellt-Datum, letzte Activity **Benötigte UI-Elemente:** - Tabellarische Liste - Filter: Status, Priority, Tags, Assigned, Source, Tenant - Suche über Subject + Body - Sortierung - Bulk-Actions: Status setzen, zuweisen, taggen, schließen **Operationen:** - Klick → Detail - Quick-Assign ### Ticket-Detail (`admin.hivegrid.de/support/:ticketId`) **Zu zeigende Daten:** - Stammdaten - Konversation (alle `AdminSupportTicketMessage`s) - Verlinkung auf Tenant + User (Klick öffnet Tenant/User-Detail) - Activity-Log (Status-Änderungen, Zuweisungen) **Benötigte UI-Elemente:** - Konversations-Anzeige chronologisch - Reply-Editor (Markdown + Anhänge) - Status-Wechsler, Priority-Wechsler, Tag-Editor, Assignee-Wechsler - Reaktions-Templates (vorgefertigte Antworten) - Internal-Note-Funktion (Notiz nur für AdminUsers, nicht zum Tenant gesendet) **Operationen:** - Antwort senden (Reply geht als Email an Tenant-User-Email-Adresse + erscheint im Tenant ggf. als In-App-Notification) - Status wechseln - Ticket schließen mit Resolution-Note - Re-Open **Permissions:** `admin.support.read` für Lese, `admin.support.write` für Antworten, `admin.support.admin` für Bulk + Lösch. --- ## Block P — Subprozessoren- und AVV-Verwaltung **Querschnitt zu Modul 35.** ### Subprozessoren-Verwaltung (`admin.hivegrid.de/legal/subprocessors`) **Zu zeigende Daten:** - Liste aller `Subprocessor`-Einträge (siehe Modul 35 Block A) - Pro Eintrag: alle Felder + Klartext über Aktivitäts-Datum **Benötigte UI-Elemente:** - Tabellarische Liste mit Filter (EU/Drittland, Datenkategorie) - Add/Edit-Funktionen - Archivieren **Operationen:** - Subprozessor anlegen / editieren / archivieren - Bei Anlage / Änderung: Notification-Trigger (siehe Modul 35 Block H) — Email an alle Tenant-Admins mit 14-Tage-Widerspruchs-Frist - Audit-Eintrag ### AVV-Versions-Verwaltung (`admin.hivegrid.de/legal/avv`) **Zu zeigende Daten:** - Liste aller AVV-Versionen mit Aktiv-ab-Datum - Pro Version: Anzahl akzeptierender Tenants, Anzahl ausstehender Re-Akzeptanzen - PDF-Vorlage-Editor **Operationen:** - Neue AVV-Version anlegen (PDF-Vorlage hochladen, Aktiv-ab-Datum wählen, Klartext-Beschreibung der Änderungen) - Re-Akzeptanz-Trigger für alle Tenants - Klartext über betroffene Tenants - Audit-Eintrag **Permissions:** `admin.legal.read` und `admin.legal.write`. --- ## Block Q — Klartext-Hinweise / -Fehler - Tenant-Status-Wechsel ohne Reason-Text: Block mit Klartext *„Bitte Reason-Text angeben — wird im Audit-Log dauerhaft gespeichert."* - Impersonate ohne Reason: Block analog - Subscription-Override ohne Bestätigung: Modal *„Diese Konditionen weichen vom Standard-Plan ab. Legacy-Provider wird nicht angepasst — manuelle Rechnungs-Erstellung erforderlich. [Verstanden, fortfahren]"* - AdminUser-Anlegen mit existierender Email: Klartext *„Diese Email gehört bereits zu einem AdminUser ‚X' — bitte direkt diesen verwalten."* - Self-Permission-Schutz: *„Du bist der einzige Super-Admin. Permission-Entzug nicht möglich. Bitte zuerst weiteren Super-Admin anlegen."* - AdminUser-Lockout durch zu viele Fehlversuche: Klartext *„Account gesperrt nach 10 Fehlversuchen. Bitte anderen Super-Admin um Reaktivierung bitten."* - Tenant-Lösch-Anstoß im Auftrag: *„Du startest die Kündigung für Tenant ‚X' im Auftrag. Bestätigung-Email geht an alle Tenant-Admins mit Cancel-Link."* - Legacy-Provider-Sync-Konflikt: *„Legacy-Provider-Stand und HiveGrid-Stand weichen ab. Bitte manuell prüfen: [Legacy-Provider-Wert] vs. [HiveGrid-Wert]."* - Worker-Queue-Pause: *„Queue ‚X' pausiert. Neue Jobs werden eingereiht aber nicht verarbeitet. Vergiss nicht zu reaktivieren!"* - Cross-Tenant-Email-Bulk: *„Diese Email geht an X Tenant-Admins. Bitte nochmal Subject + Body prüfen. [Senden]"* - Lead-Promote-to-Tenant: *„Tenant wird angelegt mit Initial-Admin [Email]. Bitte Subscription + Trial-Dauer wählen vor Anlage."* --- ## Block R — Phase 2 / spätere Features - **AI-Generations-Logs sichtbar** — alle KI-Aufrufe pro Tenant (Token-Verbrauch, Modell, Kosten) für Cost-Analyse + Fehler-Debug - **KB-Verwaltung global** — zentrale Help-Center-Artikel-Pflege (siehe Modul 38) - **Help-Desk-Backend mit Tickets** — voller Helpdesk-Workflow (SLA, Eskalations-Stufen, Customer-Satisfaction-Surveys) - **Marketing-Tools** — Tenant-Segmentierung für Marketing-Newsletter aus Admin heraus, Marketing-Automations für Trial-Conversion - **Custom-Domain-Verwaltung** — Enterprise-Tenants mit eigenen Domains (siehe Modul 27 A.3 Phase 2) - **Cohort-Analyse** — Retention, Churn-Predictoren, Feature-Adoption pro Cohort - **Plattform-API** — programmatischer Zugriff auf Admin-Funktionen (für interne Automation, z.B. Lead → Tenant via Make/n8n) - **Cross-Tenant-Bulk-Migration** — bei Schema-Änderung Migration über alle Tenants koordinieren - **Tenant-zu-Tenant-Daten-Move** — Edge-Case für Firmen-Restrukturierung (Konzern-Aufteilung) - **Erweiterte AdminUser-2FA-Optionen** — Hardware-Keys (WebAuthn/FIDO2) - **Drittland-Audit-Log und DSFA-Generator** (siehe Modul 35 Phase 2) - **Marketing-Site-CMS** (falls Marketing-Site auf eigene Plattform migriert wird) --- ## Block S — Architektur-Vorschriften (Querschnitt) - **LP-1 — Eine Handwerksfirma = ein Tenant:** Hardgrenze Admin-Welt vs. App-Welt (Block A) - **LP-6 — Anti-Agentur-Positionierung:** Plattform-Admin ist UNSER Werkzeug, kein Tenant-Tool. Klare Trennung wahrt Selbst-Wartbarkeits-Anspruch der Tenants - **LP-9 — Spec-Tiefe:** keine UI-Layouts - **LP-10 — Klartext-Diagnostik:** alle sensitiven Aktionen mit Reason-Text + Klartext-Bestätigung (Block Q) - **AV #6 — Audit-Trail-Default:** AdminAuditLog erfasst alle Admin-Aktionen - **AV #20 — Action-Boundary:** keine KI-getriebenen schreibenden Aktionen ohne explizite AdminUser-Bestätigung --- ## Detail-Spec-Status: DRAFT Erste vollständige Detail-Spec für Modul 37. Bewusst breit, da Modul ein Hub für mehrere Querschnitts-Themen (Feature-Flags M32, DSGVO M35, Subscriptions M28) ist. **Offene Detail-Punkte (nicht-blockierend):** - Konkrete AdminPermission-IDs final mit Modulen 32 und 35 abstimmen - Impersonate-Mechanik technisch ausarbeiten (Cookie-Scope, Banner-Anzeige im App-Workspace) - Inbound-Email-Parser für Support-Tickets (Provider-Wahl) - Legacy-Provider-Webhook-Sync-Detail in Modul 28 - Worker-Queue-Steuerungs-API (BullMQ-spezifisch) - AVV-PDF-Templating (Template-Engine-Wahl) - Subframe-UI-Designs separat - Initial-AdminUser-Bootstrap-Skript (Implementierungs-Detail)