35 KiB
module, title, phase, status, last_updated, session_source, related_lps, spec_style
| module | title | phase | status | last_updated | session_source | related_lps | spec_style | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 37 | Plattform-Admin | 1 | detail-spec-draft | 2026-05-08 | brainstorming-session-2026-05-07-2206.md |
|
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 zuUser/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.desind 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.desetzt nicht das gleiche Cookie wieapp.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 gesetztemapp.tenant_id. - Audit-Trennung: Admin-Aktionen werden in
AdminAuditLoggeloggt (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_atemail(unique, Pflicht — wird zum Login-Identifier)first_name,last_namepassword_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_ipstatus(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_atip,user_agentrevoked_at(für globalen Logout)
AdminAuditLog
Plattform-globale Audit-Tabelle. Cross-Tenant — auch Aktionen die Tenant-Daten verändern werden hier geloggt.
id,created_atadmin_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_idsummary_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_idnote_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_atfirst_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_idlost_reason(optional Enum + Freitext beilost)notes(Markdown)converted_to_tenant_id(FK auf Tenant beiwon+ nach Tenant-Anlage)archived_at
AdminDeal (sehr leichtgewichtig, eigene Sales-Pipeline):
id,created_at,updated_atadmin_lead_id(FK)expected_arr_eur(geschätzter Jahresumsatz)seats_office_estimated,seats_field_estimatedstage(Enum:discovery | demo | proposal | negotiation | won | lost)expected_close_dateassigned_to_admin_user_idnotes
AdminLeadActivity (eigener Activity-Stream für Lead-Management):
id,admin_lead_id,created_at,actor_admin_user_idactivity_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_atsource_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_idtags[](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_adminkann 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_eurpro 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
AdminTenantNotemit 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, →frozenmit 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+ speziellesadmin.tenants.impersonateBundle
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
wonund 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 setztconverted_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
spammarkiert; 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
AdminLeadnachwon
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_idsetzen)
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_atwird 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
AdminSupportTicketmitsource_kind=in_app_feedback_widget - Inbound-Email: Email an
support@hivegrid.dewird parsed, erzeugt Ticket mitsource_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
AdminSupportTicketMessages) - 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)