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 Hostadmin.hivegrid.de, kein Schema-Konflikt. Eigeneprisma/schema/admin.prisma(AD-21); getrennte Welt, KEINtenant_idauf den Admin-Tabellen. - Konflikt-Risiko: keines auf Schema-Ebene; berührt
core.prismanur 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 ausBILL-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/auditcross-tenant + Gate- Eigene getrennte Admin-Shell (kein Reuse der App-Sidebar)
Technische Bausteine
- Entities (eigene
prisma/schema/admin.prisma— KEINtenant_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 nachBILL-02bisBILL-06ueber 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-featuresROADMAP.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-P19aktualisiert
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-gateStep-up. - DoD #7
AdminAuditLogwird 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.prismaenthaelt 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 bestehendesSupportTicketstatt Duplikat). Minimale Back-Relations.prisma validate+generategruen.db pushsteht 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) uebercreateAuditEvent. 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.tstoggelt Feature-Konnektoren je Tenant ueberTenantFeatureOverride(enabled/disabled/inherit), invalidiert dentenantHasModule-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:TypedQueueist 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 demSupportTicketMessage-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/listAdminTenantNotemit 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.tslegt nurUser+AdminUseran, keinen Tenant, keineTenantUser-Mitgliedschaft, keindefaultTenantId. Damit hat ein Admin keinen Workspace und taucht in keiner Mitgliederliste auf. TOTP/MFA laeuft ueber Authentik +admin-mfa-gateStep-up (bestehend). Verifiziert per Code-Read + bestehendejit-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 ohnetenantId-Param alle AuditEvent-Zeilen inkl. dertenantId=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_MSwar 60 Min -> auf 30 Min gesetzt;validateImpersonationSessionStateliefert danachstale_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 pusherfolgreich gegen eine frische pgvector-Postgres (Docker, da compose kein Postgres mitbringt): das gesamte Schema inkl.admin.prismasynct sauber. Verifiziert perpsql: TabellenAdminTenantNote,SupportTicketMessage+ SpalteSupportTicket.assignedToUserIdvorhanden. Damit AD-21 (Feature-Branch =db push, Migration erst beim Merge) erfuellt. Befehl:prisma db push --url <direct-url>(Prisma 7 kennt kein--skip-generatemehr).- 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 ohneADMIN_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.