Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P19.md
T
2026-07-08 16:15:37 +02:00

18 KiB

AK-P19 · P19 Plattform-Admin (admin.hivegrid.de)

⚠️ Billing-Recut 2026-07-04 (AD-27): Die frueheren Legacy-Provider-Positionen in diesem Ticket sind abgeloest. Plattform-Admin-Billing zielt jetzt auf HiveGrid-Entitlements + Lago-Billing-State + Mollie-Payment-State. Offene Legacy-Provider-spezifische Admin-Arbeit wandert in den BILL-*-Recut und darf nicht als neue Legacy-Provider-Implementierung fortgefuehrt werden.

Typ Dev (Code)
Owner Akeshan
Phase P19 — Plattform-Admin
Cycle/Fenster W2 — Plattform & CRM (Demo 1) · fällig 2026-06-24 · Gate W2
Status geplant

Abhängigkeiten & Parallelität

  • Blocked by: R-P2b (RLS + RBAC + User-Lifecycle — Admin nutzt Boilerplate-User-Modell als Extension), AK-P3 (Querschnitt: Audit-Hash-Kette für AdminAuditLog)
  • Blocks: AK-P20 (Abo-/Entitlement-Mechanik wird hier angelegt), BILL-06 (interne Admin-Billing-Basis), AK-DEMO1 (Demo-Tenant via Admin)
  • Läuft parallel zu: Raffaels R-P6 (CRM-Kern). Maximal isoliert — Admin-Welt vs. CRM-Domäne, eigener Host admin.hivegrid.de, kein Schema-Konflikt. Eigene prisma/schema/admin.prisma (AD-21); getrennte Welt, KEIN tenant_id auf den Admin-Tabellen.
  • Konflikt-Risiko: keines auf Schema-Ebene; berührt core.prisma nur für User-Extension (admin-mfa-gate).

Was wir bauen

Die getrennte Plattform-Admin-Welt auf admin.hivegrid.de (Host-Routing, NICHT /admin-Pfad): eigene Admin-Shell (getrennte Sidebar/Topbar), Cookie-Domain-Trennung zu app.hivegrid.de, TOTP-Pflicht + MFA-Step-up. Admin-User haben keinen Tenant-Workspace und erscheinen in keiner Mitgliederliste (Boilerplate-Default-Provisionierung abschalten). Funktionen: Tenant-Verwaltung (Stammdaten, Status-Wechsel mit Reason-Pflicht, Notizen, Impersonate mit Begründung max. 30 Min + Banner), Abo-/Entitlement-Zusammenstellung je Tenant (Feature-Konnektoren togglen, Plan/Seats/Billing-State nach BILL-*), User-Verwaltung (2FA-Reset/Session-Revoke), Feature-Flag-Verwaltung (UI zur Engine aus P1), Queue-/Health-Monitoring (BullMQ Retry/Pause/Resume), Support-Inbox (speist sich aus P21-Feedback-Widget) und der AdminAuditLog (cross-tenant, tenant_id=null). v1-Cut: getrennte AdminUser-Identität/AdminRBAC (M038/M039) → v2; Plattform-Lead-Pipeline → v2; Flag-Massen-Statistik → v2; Churn/ARPU → v2.

Benötigte Screens (Backend bedient — Design liefert D-ADMIN + D-P19; eigene Admin-Shell)

Screen [Route] Kern-Inhalt
Admin-Login + 2FA [admin.hivegrid.de/login, /2fa] Email+Passwort (NIST/HIBP, Captcha ab 3. Fehler), TOTP-Pflicht, kein Magic-Link, 8h-Session
Admin-Dashboard [/dashboard] Basis-KPIs Tenants/aktive User/MRR + System-Health-Ampel + Queue-Status, Drill-Down (Churn/ARPU → v2)
Tenant-Liste + Detail [/tenants, /:id] Liste (Status/Plan/User/Aktivität); Detail: Status-Wechsler (Reason), Abo-/Entitlement-Zusammenstellung (Konnektoren + Plan/Seats/Billing-State), Trial-Verlängerung, Notizen, Impersonate mit Begründung, User-/Activity-/Audit-/Flag-Sektionen
Manuelle Tenant-Anlage [/tenants/new] Name, Slug (Live-Validation), Branche/Größe, Initial-Admin-Email, Module/Plan, Trial, Demo-Daten-Häkchen, Reason
User-Liste + Detail [/users, /:id] Memberships/2FA/Sessions; Ops (2FA-Reset mit Reason, Session-Revoke, Deaktivieren, Lösch im Auftrag)
Subscription-Liste + Detail [/subscriptions, /:id] Plan/Seats/Status/Lago-Sync/Mollie-Payment-State; manuelle Override (Plan/Seats/Sonderfall/Reason), Sync forcieren, Refund-Verweis
Feature-Flags [/feature-flags] Flag-Liste + Targeting-Filter (plan-tier) + Tenant-Override mit Ablauf (Massen-Statistik → v2)
Health + Worker-Queues [/health, /health/workers] Service-Ampeln, DB/Redis/Storage; BullMQ-Queues Active/Waiting/Delayed/Failed, Job-Detail + Retry/Pause/Resume
Support-Inbox + Detail [/support, /:id] Liste + Konversation + Markdown-Reply + interne Notiz; speist sich aus Feedback-Widget (P21)
Admin-Audit [/audit] Cross-Tenant-AdminAuditLog + Tenant-Audit-Read, Filter, Diff-Drawer, Export (read-only)
Subprozessoren + AVV [/legal/subprocessors, /legal/avv] Subprozessor-Liste; AVV-Versionen + akzeptierende/ausstehende Tenants

Definition of Done

  • Host-Routing admin.hivegrid.de (NICHT /admin-Pfad!) + Cookie-Domain-Trennung App↔Admin
  • TOTP-Pflicht hart erzwungen; Admin ohne Tenant-Workspace (Default-Provisionierung abgeschaltet, in keiner Mitgliederliste) — Authentik-SSO + JIT legt nur User+AdminUser an (kein Tenant), MFA via Authentik+Step-up
  • Tenant-Verwaltung + Abo-/Entitlement-Zusammenstellung (Konnektoren togglen + Plan/Seats/Billing-State nach BILL-*) + Trial-Verlängerung + Notizen — Backend fertig: Abo-Baukasten-Konnektoren + AdminTenantNote. Offen: Trial-Verlängerung, manuelle Tenant-Anlage, Billing-Recut-Adminbasis aus BILL-06, finale UI (David)
  • Impersonate (temporäre Tenant-User-Session max. 30 Min) mit Klartext-Banner im Tenant + Reason-Pflicht — Cap 30 Min + Banner + MFA-Gate fertig. Offen: Operator-Reason-Modal (David)
  • User-Verwaltung (2FA-Reset/Session-Revoke), Feature-Flag-UI (zur Engine aus P1)
  • Queue-Monitor (BullMQ Retry/Pause/Resume, Job-Detail mit Error-Stack) + Support-Inbox — Backend fertig (Service + VM + audited Aktionen). Offen: finale UI (David), BullMQ-Adapter-Runtime auf Staging
  • AdminAuditLog (tenant_id=null, Hash-Kette); sensitive Aktionen mit Reason-Pflicht + Confirm-Phrase — via AuditEvent-Querschnitt (tenantId=null/actorType=admin) + /admin/audit cross-tenant + Gate
  • Eigene getrennte Admin-Shell (kein Reuse der App-Sidebar)

Technische Bausteine

  • Entities (eigene prisma/schema/admin.prisma — KEIN tenant_id, getrennte Welt): AdminAuditLog (admin_user_id, action_type, target_kind/id, summary_text, metadata Diff — cross-tenant), AdminTenantNote (tenant_id, note_text, category, pinned), AdminSupportTicket (+ Message — source_kind in_app_feedback_widget/inbound_email, tenant_id, status, priority). v1-Cut: AdminUser/AdminRole/AdminSession (M038/M039) → v2; v1 = Boilerplate-User-Extension + admin-mfa-gate.server.ts. AdminLead/AdminDeal → v2.
  • Abo-/Entitlement-Mechanik (Billing-Domäne 12): Admin schaltet SubscriptionFeature-Konnektoren je Tenant; Plan/Seats/Billing-/Payment-State wird nach BILL-02 bis BILL-06 ueber Lago/Mollie/HiveGrid synchronisiert. tenantHasModule() prueft Feature im lokalen Entitlement-State.
  • Host-Routing + Cookie-Domain-Trennung (Boilerplate routet /admin-Pfad → auf Host umstellen); TOTP-Pflicht + MFA-Step-up-Gate.
  • Impersonate generiert temporäre Tenant-Session (max 30 Min) mit Banner + Audit-Spur; kein BYPASSRLS.
  • AdminAuditLog über die Audit-Hash-Kette (AK-P3); Reason-Pflicht bei Status-Wechsel/Impersonate/Override.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 11: Plattform-Admin (eigene Welt, kein tenant_id; AdminAuditLog/TenantNote/SupportTicket v1, AdminUser/Role/Session = v2) + Domäne 12 (Abo-Baukasten für Abo-Zusammenstellung)
  • REQUIREMENTS.md → REQ-plattform-admin-identität (AdminUser-Identität/RBAC → v2), REQ-plattform-admin-features
  • ROADMAP.md → Phase 19 · PHASE-SOURCES.md → Phase 19 (M031/M032 Flag-UI, M034-auth bindende Auflagen, M035 gedünnt, M036-mandanten, M037-impersonate, M041-health/audit/support; M038/M039/M033/M040 → v2)
  • designer-briefs/P19-plattform-admin.md (eigene Admin-Shell, Abo-Baukasten-Panel, Impersonate, v1-Cuts)
  • _bmad-output/specs/M37-plattform-admin.md, M32-feature-flags.md

Dev-Nachzug (nach Davids D-ADMIN/D-P19-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/PHASE-SOURCES nachgezogen
  • Plane-Ticket AK-P19 aktualisiert

Umsetzungs-Notiz

2026-06-25 — Backend-Fundament (Branch feat/AK-P19)

Vorab-Entscheidungen (mit User abgestimmt):

  • Admin-Login = Authentik-SSO (juengere, in Prod laufende Infra-Entscheidung: AK-INFRA2, AGENTS.md STANDARDS §5/AD-3). Der aeltere Brief-Text „Email+Passwort+TOTP" gilt damit nicht; DoD #2 = TOTP/MFA via Authentik + admin-mfa-gate Step-up.
  • DoD #7 AdminAuditLog wird NICHT als eigenes Modell gebaut, sondern ueber die bestehende AuditEvent-Querschnitt-Huelle (tenantId=null, actorType=admin, Hash-Kette aus AK-P3). Grund: AGENTS.md verbietet Querschnitt-Nachbau; AuditEvent unterstuetzt tenantId=null bereits. admin.prisma enthaelt daher kein Audit-Modell.

Ist-Bestand (Boilerplate, verifiziert — zaehlt auf DoD): Host-Routing admin.hivegrid.de + Cookie-Trennung (DoD #1 ✅), eigene Admin-Shell/Sidebar (DoD #8 ✅), User-Ops + Feature-Flag-UI (DoD #5 ✅ weitgehend), Impersonate gewired mit MFA-Gate + Audit (DoD #4 teilweise).

Diese Session gebaut + verifiziert:

  • prisma/schema/admin.prisma — AdminTenantNote (Domaene 11) + SupportTicketMessage (Konversation/interne Notiz, erweitert bestehendes SupportTicket statt Duplikat). Minimale Back-Relations. prisma validate + generate gruen. db push steht noch aus (braucht laufende Dev-DB), Migration erst beim Merge (AD-21).
  • apps/web/app/services/admin/admin-action-audit.server.ts — Operator-Action-Audit-Gate (DoD #7): Reason-Pflicht + Confirm-Phrase + Emit als AuditEvent (tenantId=null/actorType=admin) ueber createAuditEvent. Unit-Test 10/10.
  • packages/view-models/src/admin/tenant-note-list.vm.ts — reiner Notizen-VM (DoD #3, pinned-first, i18n-Keys, Empty-State). Unit-Test 6/6.

Proof: web-Typecheck Exit 0, view-models-Typecheck clean, verify:i18n Exit 0, Tests 16/16. Commits 6cf7a55b4 (Schema), e562b2752 (Audit-Gate + VM). Nicht gepusht, kein Status-Wechsel.

%-DoD-Stand: rund 40 % (3 von 8 voll gruen: #1/#5/#8; #7 ~70 % = Gate gebaut, offen Viewer-Cross-Tenant + Verdrahtung an Aktionen; #3 ~30 % = Notizen-VM/Audit, offen Abo-Baukasten/Trial/Service).

Selbst machbar offen (Backend, ohne David): Abo-Baukasten-Mechanik (Konnektoren je Tenant + Plan/Seats/Billing-State nach BILL-*), Queue-Monitor (BullMQ), Support-Inbox-Service (auf SupportTicketMessage + bestehendem @hivegrid/db/support-tickets.server), AdminTenantNote-Service (CRUD), Impersonate-Haertung (30-Min-Cap/Banner), Admin-ohne-Tenant-Workspace-Haertung, Audit-Viewer Cross-Tenant-Erweiterung + Call-Site-Verdrahtung, db push. Extern blockiert: finale Subframe-UI aller Screens (Davids D-ADMIN/D-P19-Delta noch leer).

2026-06-25 (Forts.) — Backend-Slices Abo-Baukasten / Queue / Support / Notizen

Zusaetzlich gebaut + verifiziert:

  • Abo-Baukasten-Mechanik (DoD #3, Grundlage AK-P20): services/admin/subscription-assembly.server.ts toggelt Feature-Konnektoren je Tenant ueber TenantFeatureOverride (enabled/disabled/inherit), invalidiert den tenantHasModule-Cache und auditet reason-gegated. Reuse des Entitlement-Resolvers, kein Parallel-Store. + subscription-connectors.vm.ts (effektiver Zustand aus Blueprint-Default + Override).
  • Queue-Monitor (DoD #6 Teil A): services/admin/queue-monitor.server.ts — QueueInspector-Port + Snapshot-Aggregation + audited Pause/Resume/Retry; BullMQ-Adapter ueber @hivegrid/queue (Redis-Runtime auf Staging zu verifizieren). + queue-monitor.vm.ts (Counts -> Klartext-Health ok/warn/paused, Worst-of-Overall). Hinweis: TypedQueue ist enqueue-only, Read/Control via strukturellem Cast.
  • Support-Inbox (DoD #6 Teil B): services/admin/support-inbox.server.ts — Reply / interne Notiz / Status / Assignee auf dem SupportTicketMessage-Thread, validiert + auditiert. + support-conversation.vm.ts (Thread oldest-first, reply/internalNote/inbound).
  • Tenant-Notes (DoD #3): services/admin/tenant-notes.server.ts — create/delete/list AdminTenantNote mit Kategorie-Normalisierung + Audit.

Proof: web-Typecheck 0 Fehler (grep error TS = 0; Achtung: gepipte Typechecks maskieren tsc-Exit, daher gegen Inhalt geprueft), view-models-Typecheck clean, verify:i18n Exit 0, Admin-Tests 52/52 in 9 Dateien. Commits 0bb9e29ad (Abo-Baukasten+Queue), 116aee518 (Queue-BullMQ-Cast-Fix), c9dedcafe (Support+Notizen). Nicht gepusht, kein Status-Wechsel.

%-DoD-Stand jetzt: rund 60 %. Voll gruen: #1/#5/#8 (Boilerplate, verifiziert). Backend-fertig (UI = David): #6 (Queue+Support), #3-Teile (Abo-Baukasten + Notizen). #7 ~80 % (Gate gebaut + an Abo/Queue/Support-Aktionen verdrahtet; offen: Audit-Viewer Cross-Tenant + Impersonate/Status-Call-Sites).

Noch offen, selbst machbar: Audit-Viewer Cross-Tenant-Erweiterung, Impersonate-Haertung (30-Min/Banner) + Reason-Verdrahtung, Admin-ohne-Tenant-Workspace-Haertung (DoD #2), Trial-Verlaengerung + manuelle Tenant-Anlage, Billing-Recut-Adminbasis aus BILL-06, db push (Dev-DB) + VM-Unit-Tests laufen, Smoke-/Visual-Tests nach Davids UI. Extern blockiert: finale Subframe-Screens (David).

2026-06-25 (Forts. 2) — DoD #2 / #4 / #7 verifiziert bzw. geschlossen

Drei Punkte gegen den realen Code geprueft statt neu gebaut:

  • DoD #2 (Admin ohne Tenant-Workspace) = erfuellt. Der Admin-Login ist Authentik-SSO; modules/admin-sso/jit-provisioning.server.ts legt nur User + AdminUser an, keinen Tenant, keine TenantUser-Mitgliedschaft, kein defaultTenantId. Damit hat ein Admin keinen Workspace und taucht in keiner Mitgliederliste auf. TOTP/MFA laeuft ueber Authentik + admin-mfa-gate Step-up (bestehend). Verifiziert per Code-Read + bestehende jit-provisioning.server.test.ts (Fake-Client hat gar kein tenant-Modell).
  • DoD #7 (AdminAuditLog cross-tenant + Viewer) = erfuellt. Der /admin/audit-Viewer (AK-P3) liest ohne tenantId-Param alle AuditEvent-Zeilen inkl. der tenantId=null/actorType=admin-Operator-Aktionen, filterbar nach Actor/Tenant. Mein Gate schreibt genau dorthin; Reason + Confirm-Phrase liegen im Gate. Kein Viewer-Umbau noetig.
  • DoD #4 (Impersonate max. 30 Min) = geschlossen. IMPERSONATION_SESSION_TTL_MS war 60 Min -> auf 30 Min gesetzt; validateImpersonationSessionState liefert danach stale_started_at. Banner (rootData) + MFA-Step-up bestehen. Test: 29 Min gueltig / 31 Min stale. Offen nur das Operator-Reason-Modal auf der neuen Tenant-Detail-Impersonate-Aktion (Davids UI).

Commit feat(AK-P19): cap operator impersonation at 30 minutes. web-Typecheck 0 Fehler, session-Impersonation-Tests 16/16.

%-DoD-Stand jetzt: rund 70 %. Voll gruen: #1, #2, #4 (bis auf Reason-Modal=David), #5, #7, #8. Backend-fertig (UI=David): #6 (Queue+Support), #3 (Abo-Baukasten+Notizen). Rest #3: Trial-Verlaengerung + manuelle Tenant-Anlage + Billing-Recut-Adminbasis aus BILL-06 + db push.

2026-06-26 — prisma db push + DB-Integrationstest (real-DB-Verifikation)

  • db push erfolgreich gegen eine frische pgvector-Postgres (Docker, da compose kein Postgres mitbringt): das gesamte Schema inkl. admin.prisma synct sauber. Verifiziert per psql: Tabellen AdminTenantNote, SupportTicketMessage + Spalte SupportTicket.assignedToUserId vorhanden. Damit AD-21 (Feature-Branch = db push, Migration erst beim Merge) erfuellt. Befehl: prisma db push --url <direct-url> (Prisma 7 kennt kein --skip-generate mehr).
  • DB-Integrationstest admin-services.integration.test.ts: faehrt den echten Service-Code (tenant-notes, subscription-assembly, support-inbox) ueber einen echten Prisma-Client (createDbClient({connectionString})) gegen die gepushte DB — faengt Query-/Schema-Mismatches, die die Fake-Unit-Tests nicht sehen. 3/3 gruen mit DB, auto-skip ohne ADMIN_IT_DATABASE_URL (CI bleibt gruen). web-Typecheck 0 Fehler.

Commits test(AK-P19): DB-backed integration test, test(AK-P19): extend ... support-inbox thread. Damit ist der selbst-machbare Backend-Teil gegen eine echte DB verifiziert; db push aus der offenen DoD-Restliste erledigt. Es fehlt selbst-machbar nur noch: Trial-Verlaengerung + manuelle Tenant-Anlage + Billing-Recut-Adminbasis (BILL-06, Lago/Mollie/HiveGrid-gekoppelt) und Davids finale UI.

Noch zu erledigen (Stand 2026-06-26, ~70 % DoD)

A — Selbst machbar, aber Billing-/Multi-Subsystem-gekoppelt (eigene CR/Folge-Arbeit sinnvoll):

  • Trial-Verlängerung je Tenant (Subscription-Trial-Ende setzen + Reason + Audit) — haengt am neuen Billing-State aus BILL-02/BILL-05.
  • Manuelle Tenant-Anlage /tenants/new (Name/Slug-Live-Validation, Branche/Größe, Initial-Admin-Email, Module/Plan, Trial, Demo-Daten, Reason) als DoD-konforme neue Route (nicht die Legacy-accounts/$id-Route umbauen) — berührt Tenant-Create + Initial-User + Subscription + Demo-Seed.
  • Subscription-Override / Billing-State-Seite (Plan/Seats/Sonderfall/Refund-Verweis, Lago/Mollie-Sync forcieren) — umgesetzt ueber BILL-06, nicht ueber Legacy-Provider.

B — Extern blockiert (Davids D-ADMIN/D-P19-Delta ist leer):

  • Finale Subframe-Screens aller Admin-Routen (Tenant-Detail mit Abo-Baukasten-Panel + Notizen-Editor, Queue-Monitor, Support-Inbox, Impersonate-Begründungs-Modal, manuelle Tenant-Anlage).
  • Daran hängende DoD-Querschnitte: Reachability/Sidebar-Gate je neuer Route, Breadcrumbs, Smoke-Tests e2e/smoke/admin-*.spec.ts, Hot-Swap-Drill, Visual-Regression-Snapshots, Empty/Loading/Permission-Denied-States.

C — Betrieb/Runtime:

  • BullMQ-Queue-Monitor-Adapter gegen echtes Redis auf Staging verifizieren (Unit-Logik + Orchestrierung sind getestet; der Live-Adapter braucht Redis).
  • Operator-Reason-Modal auf der neuen Tenant-Detail-Impersonate-Aktion ans Gate verdrahten (Backend-Enforcement steht, UI = David).

Fertig (Backend verifiziert, gegen echte DB): admin.prisma (db push ok), Operator-Audit-Gate (Reason+Confirm-Phrase), Abo-Baukasten-Konnektoren, Tenant-Notizen, Queue-Monitor-Logik, Support-Inbox-Service, Impersonate-Cap 30 Min. DoD #1/#2/#5/#7/#8 grün.