# 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 - [x] **Host-Routing `admin.hivegrid.de`** (NICHT `/admin`-Pfad!) + **Cookie-Domain-Trennung** App↔Admin - [x] **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)* - [x] **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* - [x] **`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 - [x] 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 ` (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.