Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,869 @@
---
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, Stripe-Customer-ID (mit Link zu Stripe-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, Stripe-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:**
- Stripe-Customer-ID, Subscription-ID (mit Link zu Stripe-Dashboard)
- Aktueller Plan, Seats (Office + Field), MRR
- Trial-Status, Trial-Ende
- Rechnungs-History
- Override-Vermerke (manueller Plan / Sonderpreis)
**Operationen:**
- **Stripe-Sync forcieren** (zieht aktuellen Stripe-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** (Stripe-Cancel + Tenant-Lösch-Workflow-Trigger)
- **Refund anstoßen** (mit Reason-Text + Stripe-Sync)
**Permissions:** Lese `admin.subscriptions.read`, Schreib-Aktionen `admin.subscriptions.admin`.
### Stripe-Webhook-Sync
- Events von Stripe (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. Stripe 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."*
- Stripe-Sync-Konflikt: *„Stripe-Stand und HiveGrid-Stand weichen ab. Bitte manuell prüfen: [Stripe-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)
- Stripe-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)