Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-LEADS.md
T

32 KiB

R-LEADS · Native Plattform-Leads + Ablösung lead-inbox

♻️ Recut vom 2026-07-16: Dieses Dokument ersetzt J-QA; der Plane-Key bleibt HIVEGRID-73. Der frühere Website-QA-Anteil liegt jetzt in J-LIVE. HIVEGRID-73 übernimmt den vorgezogenen M040a-Slice: nativer Plattform-Lead-Eingang, Admin-Inbox, Quellenumstellung, Datenmigration und kontrollierte Stilllegung des separaten lead-inbox-Dienstes. Deal-Kanban, ARR/Forecast und „Promote to Tenant" bleiben als M040b in VA-P28b.

Plane HIVEGRID-73
Typ Dev (Code + Cross-Repo-Cutover)
Owner Raffael
Phase P28 / M040a — vorgezogener Plattform-Lead-Unterbau
Cycle/Fenster Start 2026-07-16 · Ziel 2026-07-31 · Abschluss in v2-W3
Status in Arbeit

🎨 design-nachzug: offen — die erste Version wird nach AD-28 als Interim-UI aus ~/ui gebaut. VD-P28 liefert später die finale Subframe-Optik; das blockiert die Dev-DoD nicht.

Zielbild und Architekturentscheidung

HiveGrid-eigene Vertriebsleads werden nativ in HiveGrid verwaltet. Es gibt keinen „internen Mandanten" und keine Wiederverwendung der tenantgebundenen InboxLead-Welt aus R-P7. Die Plattform-Leads leben in der operatorweiten Admin-Welt auf admin.hivegrid.de und tragen kein tenant_id.

Alle Eingangswege verwenden einen transportneutralen AdminLeadIngestionService. Websites und spätere Partner senden serverseitig an den kanonischen Endpoint POST https://api.hivegrid.de/v1/platform/leads. Manuelle Anlage und Backfill nutzen denselben Domain-Service über getrennte Ports. Das bisherige Subsystem Lead/LeadEvent, die Route /api/leads/capture, das Embed-SDK und der externe lead-inbox-Dienst werden nach Migration und Drain aus dem aktiven Schreibpfad entfernt.

Die bindende Architekturentscheidung steht in docs/ARCHITECTURE-DECISIONS.md als AD-31.

Ist-Zustand, den dieses Ticket ablöst

  • leads.hivegrid.de ist ein separater Node/Postgres-Dienst mit POST /v1/leads, source-spezifischem Bearer-Key und best-effort Mailjet-Versand nach bereits bestätigtem 201.
  • Der Dienst hat keine fachliche Admin-Inbox, keinen Owner-/Status-Workflow, keine belastbare Idempotenz, keinen transaktionalen Notification-Retry und keinen dokumentierten Datenbank-Backup-/Restore-Nachweis.
  • Die Produktions-Website kann bei fehlender LEAD_INBOX_*-Konfiguration in eine lokale SQLite-Datei im Container schreiben und trotzdem Erfolg melden. Diese Datei muss vor jedem Website-Deploy gesichert werden.
  • HiveGrid-Cloud besitzt parallel das operatorweite Legacy-Modell Lead/LeadEvent, die Browserroute /api/leads/capture, public/embed/marketing.js und die Admin-Routen /marketing-leads sowie /incoming-leads-board.
  • R-P7 ist die bereits fertige Mandanten-Lead-Inbox für Kunden von HiveGrid und bleibt unverändert. Plattform-Leads dürfen dort nicht abgelegt werden.

Scope

In Scope

  1. Native Plattformmodelle AdminLead, AdminLeadActivity, AdminLeadSource und source-spezifische, rotierbare Credentials in einer eigenen prisma/schema/adminLeads.prisma.
  2. Ein zentraler Ingestion-Service für S2S-Eingang, manuelle Anlage und Import.
  3. Authentifizierter, versionierter und idempotenter S2S-Endpoint für beliebige freigeschaltete Quellen.
  4. Admin-Inbox auf admin.hivegrid.de/leads mit Liste, Detail, Suche/Filter, manueller Anlage, Status, Zuweisung, Notizen/Aktivitäten und Archivierung.
  5. Operator-Permissions, RLS/SECURITY-DEFINER-Grenze, Audit, Activity und transaktionales Outbox-Event.
  6. M011-konforme Plattform-Benachrichtigung ohne Aufweichung des tenantgebundenen notify()-Vertrags. Haris wird für die aktuelle Website-Quelle konfigurierter Default-Assignee und Empfänger, nicht als Code-Konstante eingebaut.
  7. Umstellung der HiveGrid-Website auf den nativen Endpoint.
  8. Idempotenter Backfill aller bekannten Legacy-Speicher mit manifestiertem Zähl-/Hash-Nachweis.
  9. Staging-/Produktions-Cutover, mindestens sieben Tage Drain/Beobachtung und kontrollierte Stilllegung von App, DNS und Secrets des separaten Dienstes.
  10. Ablösung der aktiven Legacy-Schreib- und Leserouten in HiveGrid-Cloud, sodass genau ein aktives Plattform-Lead-System übrig bleibt.

Nicht in Scope

  • AdminDeal, Deal-Kanban, Drag-and-drop, Stage-Forecast, ARR-/Abschlussprognosen und „Gewonnen → Promote to Tenant"; das ist M040b in VA-P28b.
  • Tenant-Lead-Routing aus M048 und Änderungen am InboxLead-Contract aus R-P7.
  • Marketing-Automation, Lead-Scoring-Automatik oder E-Mail-Kampagnen.
  • Die endgültige getrennte AdminUser-Identität aus VR-P28a; R-LEADS nutzt einen klar dokumentierten Kompatibilitätsadapter zur bereits laufenden AdminUser/User- Brücke. VR-P28a muss die IDs/Assignments verlustfrei übernehmen.
  • Löschen des letzten verschlüsselten Backups oder irreversible Datenvernichtung. Nach Drain wird der Dienst abgeschaltet; die endgültige DB-Löschung braucht einen separat bestätigten Retention-/Löschentscheid.

Abhängigkeiten und Auswirkungen

  • Blocked by: keine offene Ticket-DoD. Verwendet werden nur bereits ausgelieferte Teile aus AK-P19: Admin-Host, Admin-Shell/Auth und recordAdminAction()/ AuditEvent. Die dort noch offenen Billing-/Support-/Queue-Punkte sind kein Blocker.
  • Blocks: H-INBOUND (operative Abnahme: Haris erhält und bearbeitet Leads in unter 24 Stunden) und den M040b-Anteil von VA-P28b.
  • Design: VD-P28 bedient R-LEADS als getrackten Nachzug; nach AD-28 kein blocked-by.
  • Späterer Identitäts-Nachzug: VR-P28a muss bestehende assignedToAdminUserId-/Quellen-Zuweisungen beim Wechsel auf die getrennte AdminUser-Welt erhalten. R-LEADS blockiert VR-P28a nicht.
  • Delivery-Owner-Nachzug 2026-07-24: VA-P28b wechselt von Akeshan zu Raffael. Der native AdminLead-/Activity-/Source-Vertrag und der separate operative 7-Tage-Cutover bleiben unverändert.
  • Website-Launch-Kette: HIVEGRID-73 blockiert J-LIVE nicht mehr. Responsive QA und Formular-Smoke liegen in J-LIVE; J-CONTENT und J-LAW bleiben dessen fachliche Abhängigkeiten.

Fachlicher Datenvertrag

AdminLead

Mindestens folgende Felder:

  • Identität/Zeit: id, createdAt, updatedAt, capturedAt, archivedAt?
  • Quelle: sourceId, sourceDetail?, externalId?, idempotencyKey?
  • Kontakt/Inhalt: firstName?, lastName?, email?, phone?, company?, message?
  • Attribution: utmSource?, utmMedium?, utmCampaign?, utmTerm?, utmContent?, referrer?, landingPage?
  • Bearbeitung: status (new|contacted|qualified|disqualified), assignedToAdminUserId?, duplicateHintOfLeadId?
  • begrenzte Zusatzdaten: metadata? mit Größen-/Key-Allowlist; keine beliebigen ungeprüften Payload-Dumps

@@unique([sourceId, externalId]) gilt für gesetzte externe IDs. E-Mail oder Telefon werden nicht als Unique-Key und nicht für stilles Zusammenführen verwendet. Ähnliche normalisierte Kontakte dürfen nur einen sichtbaren Duplicate-Hinweis erzeugen. Damit werden Haushalte/Sammeladressen nicht versehentlich verschmolzen.

AdminLeadActivity

Append-only Verlauf mit leadId, type, actorAdminUserId?, payload, createdAt. Mindestens unterstützt:

captured, imported, manually_created, status_changed, assigned, note_added, archived, restored, duplicate_hint_recorded.

Freitextnotizen liegen im Activity-Verlauf, nicht als überschreibbarer Sammel-Blob auf dem Lead. Payloads werden schema-validiert und PII-minimiert.

AdminLeadSource und Credentials

Quellen sind konfiguriert, nicht vom Request frei wählbar. Sie enthalten mindestens: key, displayName, enabled, defaultAssigneeAdminUserId?, notifyAdminUserIds, Rate-Limit und optionale Metadaten. Credentials liegen als eigene rotierbare Child-Records ausschließlich gehasht mit Prefix, Erstell-/Ablauf- und Revoke-Zeit vor. Klartext wird nur einmal bei Erstellung gezeigt.

Die initialen Quellen sind hivegrid-website, hivegrid-legacy-cloud und lead-inbox-legacy; Haris wird für die aktuelle Website-Quelle per Konfiguration zugewiesen. Weitere Websites und Partner können über die allgemeine Quellenverwaltung mit eigenem Credential ergänzt werden.

API-Vertrag: POST /v1/platform/leads

Sicherheit

  • Authorization: Bearer <source credential>; eigener Plattform-Source-Key, weder globaler Service-Bearer noch tenantgebundener API-Key.
  • Idempotency-Key ist Pflicht. Partition des bestehenden IdempotencyKey-Modells: platform-leads:<sourceId>. Gleicher Key + gleicher Request liefert Status/Body der ersten Antwort; gleicher Key + anderer Request-Hash liefert 409.
  • Die authentifizierte Quelle stammt ausschließlich aus dem Credential. Ein source-Feld im Body wird abgelehnt bzw. niemals als Autorität verwendet.
  • Body-Limit, schema-validierte Stringlängen, source-spezifisches Rate-Limit und strukturierte Klartextfehler. Keys und Lead-PII erscheinen nie in Logs.
  • Runtime-Schreibzugriff erfolgt über eine enge, versionierte SECURITY-DEFINER-/Pre-Tenant-Capability; kein BYPASSRLS und kein freier Tabellenzugriff für den API-Role.

Payload und Semantik

Erlaubte Kernfelder sind Kontakt/Inhalt, externalId, sourceDetail, Attribution und begrenzte metadata. Mindestens eines der Felder email, phone, company, firstName, lastName oder message muss nach Normalisierung nutzbar sein; E-Mail allein ist ausdrücklich nicht Pflicht.

Antworten:

  • 201 mit { id, status, createdAt } bei neuer Anlage
  • identische gespeicherte Antwort bei Replay, zusätzlich Replay-Header
  • 400 Validierung, 401 ungültiges/revoktes Credential, 409 Idempotency- Konflikt, 413 zu großer Body, 429 Rate-Limit

Lead, erste Activity, Idempotency-Antwort und PII-minimiertes platform.admin_lead.captured.v1-Outbox-Event committen atomar. Der Outbox-Payload enthält nur Lead-ID, Source-ID, Event-Zeit und Routing-IDs, nicht Nachricht, E-Mail oder Telefon.

Admin-Oberfläche und Permissions

Kanonische Host-Pfade (kein /admin im öffentlichen URL-Pfad):

Screen Inhalt
admin.hivegrid.de/leads Liste, Suche, Filter nach Status/Quelle/Assignee/Archiv, Empty-/Loading-/Fehlerzustände
/leads/new manuelle Anlage über denselben Domain-Service
/leads/:id Kontaktdaten, Quelle, Attribution, Zuweisung, Status, Activity/Notizen, Archivieren/Wiederherstellen
/leads/sources Quellenstatus, Default-Assignee/Empfänger, Credential erstellen/rotieren/revoken; kein Klartext-Key nach Erstellung

Permissions:

  • admin.leads.read_own
  • admin.leads.read_all
  • admin.leads.write
  • admin.leads.admin

Fehlende Leseberechtigung ergibt 404. Jeder Screen wird als VM im Loader gebaut; UI erhält ausschließlich VM + Actions. Die Interim-UI nutzt ~/ui, enthält keinen zweiten App-Chrome und bekommt Sidebar, Breadcrumbs und i18n. Die Inbox-Suche ist operatorintern und DB-seitig; Plattform-PII wird nicht in tenantweite Meili- Indizes aufgenommen.

Audit, Activity und Benachrichtigung

  • Automatischer Eingang: systemischer AuditEvent, AdminLeadActivity und Outbox in derselben Transaktion.
  • Operatoraktionen: recordAdminAction()/gemeinsamer AuditEvent plus fachliche AdminLeadActivity; kein paralleles AdminAuditLog-Subsystem.
  • notify() bleibt tenantpflichtig. Das Ticket ergänzt einen eng getrennten notifyPlatform()-Vertrag mit zwingendem userId, tenantId=null, PII-minimierter Metadata und deduplizierendem sourceKey.
  • Für Plattform-Deliveries wird die NULL-Eindeutigkeit in Postgres explizit per partieller Unique-Constraint/Index abgesichert; ein gewöhnlicher Composite-Unique mit tenantId=NULL reicht nicht.
  • Der bestehende Notification-Worker verarbeitet Plattform-E-Mail/In-App-Zustellung dauerhaft mit Retry. Kein direkter Mailjet-Aufruf aus Lead-Code. Eine erfolgreiche Lead-Antwort hängt nicht vom synchronen E-Mail-Versand ab, wohl aber vom atomar angelegten Delivery-/Outbox-Auftrag.

Betroffene Repositories und Systeme

Bereich Erwartete Änderung
HiveGrid-Cloud Modelle, Service, API, Admin-UI, Importer, Tests, Legacy-Cutover
../HiveGrid-Website serverseitiger Producer, stabiler Submission-Key, kein Erfolgs-Fallback auf Container-SQLite
../lead-inbox Read-only-Export/Drain, anschließend App stilllegen und Repo archivieren
../infra Backup-/Restore-Runbook, Coolify/Cloudflare/Secrets/DNS-Cleanup, ADR-Nachzug
Extern Coolify Staging/Prod, Cloudflare, Mailjet, Gitea

Bekannte Importquellen:

  1. lead-inbox Postgres
  2. HiveGrid-Website Produktions-SQLite aus dem laufenden Container
  3. HiveGrid-Website Staging-SQLite
  4. HiveGrid-Cloud Lead/LeadEvent

Der Importer verwendet source + legacy_store + legacy_id als deterministischen externen Schlüssel, übernimmt Original-Zeitstempel und Activities, löst keine Benachrichtigungen/Automationen aus und erzeugt ein Manifest mit Input-Hash, Quellzählung, created/replayed/rejected und Zeitbereich — ohne PII.

Implementierungs-Slices

Slice 0 — Safety-Inventar und Backups

  • Live-Konfiguration und tatsächlich beschriebene Stores read-only inventarisieren.
  • Vor jedem HiveGrid-Website-Deploy die Produktions-SQLite aus dem laufenden Container sichern.
  • lead-inbox-Postgres per konsistentem Dump sichern, verschlüsselt offsite ablegen und Restore in eine leere DB beweisen.
  • Quellenzählungen/-Hashes als nicht-PII Manifest festhalten.

Rollback: keine Mutation. Bei fehlendem Backup/Restore-Proof stoppt der Cutover.

Slice 1 — Datenmodell, Domain-Service und Sicherheitsgrenze

  • prisma/schema/adminLeads.prisma, Status-/Activity-Typen und Policies anlegen.
  • Operator-RLS sowie enge S2S-SECURITY-DEFINER-Capability bauen.
  • Transportneutralen Ingestion-/Admin-Service mit Repository-Ports implementieren.
  • Legacy-Lead/LeadEvent-Mapping und Idempotency-Partition festlegen.

Voraussichtliche Dateien:

  • prisma/schema/adminLeads.prisma
  • prisma/tenant-policy-contract.mjs
  • packages/db/src/platform-leads.server.ts
  • packages/db/src/pretenant-security.server.ts bzw. dedizierte Capability
  • Service-/RLS-/DB-Integrationstests

Rollback: Feature-Flag aus, neue Tabellen ungenutzt lassen; auf Feature-Branch nur prisma db push. Merge-Migration forward-only mit Inverse-SQL-Kommentar.

Slice 2 — S2S-API, Source-Keys und OpenAPI

  • Route, Authenticator, Idempotency, Rate-Limit und Klartextfehler umsetzen.
  • Source-Credential Create/Rotate/Revoke serverseitig verfügbar machen.
  • OpenAPI, Route-Access-Inventar und Security-Tests ergänzen.

Voraussichtliche Dateien:

  • apps/api/src/routes/platform-lead-routes.ts
  • apps/api/src/app.ts, apps/api/src/app-dependencies.ts
  • apps/api/src/openapi.ts bzw. Public-API-OpenAPI-Builder
  • apps/api/src/route-access-inventory.ts
  • docs/security/route-access-inventory.md

Rollback: Source-Keys revoken und Endpoint per Feature-Flag deaktivieren; alte Producer bleiben bis zum jeweiligen Cutover unangetastet.

Slice 3 — Activity, Audit, Outbox und M011-Plattform-Notification

  • System-/Operator-Audit und Activity atomar verdrahten.
  • notifyPlatform() ergänzen, Haris über Source-Konfiguration routen und Worker- Retry/Dedupe beweisen.
  • Notification-/Outbox-Payloads auf PII-Minimierung testen.

Voraussichtliche Dateien:

  • packages/foundation/src/notifications.ts
  • packages/db/src/notifications.server.ts
  • prisma/schema/notifications.prisma plus Merge-Migration für Partial-Unique
  • apps/worker/src/** Notification-/Outbox-Handler

Rollback: Zustellung abschalten, Inbox/Outbox weiter befüllen und nach Fix idempotent drainieren; niemals auf Direktversand ausweichen.

Slice 4 — Admin-Inbox als Interim-UI

  • VM/Zod, Admin-Service, Routen, Sidebar, Breadcrumbs, Permission-Gates und i18n.
  • Liste/Detail/Neu/Quellen mit allen Scope-Aktionen aus ~/ui bauen.
  • SQL-Suche nur in der Admin-Welt; kein tenantweiter Meili-Eintrag.

Voraussichtliche Dateien:

  • packages/view-models/src/admin-leads/*.vm.ts
  • apps/web/app/services/admin/platform-leads.server.ts
  • apps/web/app/routes/admin/leads.tsx
  • apps/web/app/routes/admin/leads/index.tsx
  • apps/web/app/routes/admin/leads/$id.tsx
  • apps/web/app/routes/admin/leads/new.tsx
  • apps/web/app/routes/admin/leads/sources.tsx
  • apps/web/app/components/screens/admin/leads/*Page.tsx
  • apps/web/app/application/sidebar/AdminSidebar.tsx

Rollback: vorheriges Image koordiniert deployen; externer Ingress kann separat über PLATFORM_LEADS_INGRESS_ENABLED=false gestoppt werden. Daten bleiben erhalten.

Slice 5 — Producer umstellen

  • HiveGrid-Website serverseitig auf den nativen Endpoint setzen.
  • Je Formular eine stabile Submission-ID bis zur bestätigten Antwort wiederverwenden.
  • Bearer-Key bleibt ausschließlich im Server-Runtime-Secret.
  • Bei API-Fehler keinen falschen Erfolg anzeigen; retrybare Klartextantwort liefern.

Rollback: den Producer auf den bisherigen Endpoint zurückschalten, solange dessen Drain-Fenster offen ist. Kein Website-Deploy ohne vorher gesicherte Live-SQLite.

Slice 6 — Backfill und Legacy-Cutover

  • Alle vier bekannten Stores mit Dry-Run und anschließendem Apply importieren.
  • Counts/Hashes vor und nach Import abgleichen; Replay muss created=0 liefern.
  • Legacy-Admin-Routen und /api/leads/capture auf die native Welt umstellen bzw. entfernen; public/embed/marketing.js migrieren/entfernen.
  • Lead/LeadEvent bleiben bis Ende des Rollbacks read-only; abhängige TenantAcquisition-/Marketing-Funktionen werden nicht ungeprüft gelöscht.

Rollback: neue Reads deaktivieren und während des Drain-Fensters auf read-only Legacy-Ansicht zurückschalten; Backfill ist wiederholbar und löscht keine Quelle.

Slice 7 — Staging, Produktion, Drain und Decommission

  • Staging-Canary pro Source: create, Replay, Konflikt, Auth-Fehler, Notification, Admin-Bearbeitung.
  • Produktions-Canary mit synthetischem, klar markiertem Lead; Monitoring/Alerts auf 5xx, 401-Spikes, 429, Queue-Failures und Source-Lag.
  • Den Producer umstellen, Backfill-Finaldelta einspielen und mindestens sieben Tage eingehenden Legacy-Traffic beobachten.
  • Danach lead-inbox in Coolify stoppen, Source-Secrets/Mailjet-Zugang revoken, leads.hivegrid.de aus DNS entfernen, Repo archivieren und Infra-ADR/Runbook aktualisieren. Verschlüsseltes Backup gemäß Retention behalten.

Rollback: innerhalb des Drain-Fensters DNS/Producer auf Legacy zurück; nach Abschaltung App aus dem letzten Image und DB aus geprüftem Dump wiederherstellen.

Slice 8 — Abschluss-Audit

  • Alle DoD-Proofs, Deploy-/Restore-Run-IDs und Cutover-Zählungen ohne Secrets/PII in dieser Ticket-Doc dokumentieren.
  • Betroffene Abhängigkeiten erneut lesen, Tests der Konsumenten ausführen und Plane erst bei 10/10 auf Done setzen.

Definition of Done

# DoD Fertigkeitskriterium Proof Zählt nicht als fertig
1 ✅ Native Datenbasis AdminLead, AdminLeadActivity, Quellen/Credentials, Operator-RLS und S2S-Capability stehen; Legacy-Mapping ist idempotent Prisma validate/db-push, Policy-Contract, RLS-Live- und Backfill-Tests Nur Schema ohne scharfe RLS oder nur ein ORM-Mock
2 ✅ Zentraler Domain-Service S2S, manuelle Anlage und Import nutzen denselben validierenden Ingestion-Service Service-Unit-/DB-Integrationstests für alle Ports Drei getrennte Create-Implementierungen
3 ✅ Allgemeiner S2S-Eingang /v1/platform/leads ist source-authentifiziert, idempotent, rate-limited, dokumentiert und liefert definierte Fehler OpenAPI-/Route-Inventar-, Auth-, Replay-, Hash-Konflikt-, 413-/429-Tests Endpoint mit globalem Key, optionaler Idempotenz oder frei wählbarer Source
4 ✅ Admin-Inbox Liste, Detail, Neu, Status, Assignment, Note, Archiv und Source-Admin sind per VM/Actions, Permissions, Sidebar, Breadcrumbs und i18n erreichbar Admin-Smoke, Permission-Tests, Screenshot/Interim-Visual Raw-Prisma-Route, handgeschriebenes Tailwind oder Liste ohne Hauptaktionen
5 ✅ Nachvollziehbarkeit Jede relevante Mutation erzeugt korrekte Activity + AuditEvent; Capture erzeugt PII-minimiertes Outbox-Event atomar Transaktions-/Failure-Injection-Tests Best-effort Logging nach Commit oder PII im Event/Log
6 ⏳ Haris-Routing via M011 Die aktuelle Website-Quelle weist Haris konfiguriert zu; Plattform-Delivery läuft dedupliziert über M011/Worker mit Retry Staging-Proof Inbox + Delivery/Retry, Partial-Unique-Test Hardcodierter Haris, direkter Mailjet-Aufruf oder „201 trotz verlorener Delivery-Aufgabe"
7 ⏳ Producer-Cutover Die HiveGrid-Website nutzt serverseitig den nativen Vertrag mit stabiler Submission-ID und ohne falschen SQLite-Erfolg Repo-Tests + Staging-/Prod-Canary Nur Env gesetzt, Browser enthält Secret oder Fehler wird als Erfolg angezeigt
8 ⏳ Vollständiger Backfill Alle bekannten Stores sind idempotent importiert; Counts/Hashes/Zeitbereiche stimmen, Replay erzeugt 0 neue Leads Dry-run/apply/replay-Manifeste + Restore-/Import-Run Stichprobe, manueller Import ohne Manifest oder Notification-Spam beim Import
9 ⏳ Ein aktives System Legacy-HiveGrid-Routen/SDK sind migriert/retired; externer Dienst hat 7 Tage Nulltraffic, ist gestoppt, DNS/Secrets entfernt, Backup restorable Monitoring-Fenster, Coolify/Cloudflare/Gitea-/Restore-Proof Nur Producer umgestellt, aber Legacy weiter beschreibbar oder DB ungeprüft gelöscht
10 ✅ Qualitätsgates Typecheck, Lint, Tests, relevante verify:*, API/RLS-Live, Admin-Smoke, Hot-Swap und Interim-Visual sind grün; abhängige Tickets bleiben konsistent Befehle/CI-Run-IDs in Umsetzungsnotiz Nur Happy-Path-Unit-Test oder grüne lokale Tests bei RLS-off

Fortschritt: R-LEADS: 6/10 DoD = 60 % done. Der lokal selbst machbare Produktcode und die Qualitätsgates sind abgeschlossen. Offen sind vier operative Cutover-Punkte: Staging-Routing/Delivery, Staging- und Produktions-Canaries, Live-Backfill mit Replay sowie das vorgeschriebene Sieben-Tage-Drain-Fenster mit anschließendem Decommission. VD-P28 ist ein getrackter Design-Nachzug und kein Dev-Blocker.

Verifikation vor Commit/Push

Zusätzlich zur vollständigen docs/AGENT-CHECKLIST.md mindestens:

pnpm typecheck
pnpm lint
pnpm test
pnpm exec prisma validate
pnpm run verify:tenant-policy-contract
pnpm run verify:sidebar-routes
pnpm run verify:i18n
pnpm run test:hot-swap
pnpm run verify:ui-visual

Hinzu kommen gezielte API-, Idempotency-, Source-Key-, Notification-, Import- und RLS-Live-Tests sowie die Cross-Repo-Tests des HiveGrid-Website-Producers. Auf dem Feature-Branch wird nach AD-21 nur prisma db push genutzt; die Phase-Migration wird vor dem Merge gegen eine leere DB verifiziert, ist forward-only und enthält Inverse-SQL als Kommentar.

Umsetzungs-Notiz

2026-07-16 — Implementierung gestartet

  • Eigener Worktree: /Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-r-leads
  • Branch: feat/hivegrid-73-native-platform-leads
  • Arbeitsreihenfolge: Safety-Inventar/Backups → Datenmodell/Domain-Service → API → Audit/Notifications → Admin-UI → Producer/Backfill → Cutover/Decommission.
  • Startstand unverändert: 0/10 DoD = 0 % done.

2026-07-16 — Ticket-Recut und Implementierungsplan

  • HIVEGRID-73 von historischem Website-QA auf M040a umgeschnitten.
  • Abhängigkeiten in beide Richtungen geprüft: J-LIVE, H-INBOUND, AK-P19, VR-P28a, VA-P28b, VD-P28 und M040.
  • Entscheidung dokumentiert: native operatorweite AdminLead-Welt statt internem Tenant oder Ausbau des separaten Dienstes.
  • Cross-Repo-Cutover, Datenquellen, Backups, Rollback, 7-Tage-Drain und Decommission vollständig in Slices zerlegt.
  • Noch kein Produktivcode, Deploy oder Datenbank-Write ausgeführt.

Historischer Startstand: 0/10 = 0 % done. Selbst machbar offen: 10 Punkte. Extern blockiert: 0. Design-Nachzug offen, aber nach AD-28 nicht Done-blockierend.

2026-07-16 — Lokale Implementierung und Sicherheitsgates abgeschlossen

  • Lokaler HiveGrid-Cloud-Implementierungscommit nach Rebase auf ec646f7aa: ebae6ad93; Merge-Readiness/Migration: 5f31fa270; CI-Regressionstest: bf3133a97; Producer-Commit: HiveGrid-Website c81aca1.
  • Native Plattformmodelle, Operator-RLS, enge S2S-/Audit-/Notification- Capabilities, zentraler Ingestion-Service, versionierter S2S-Endpoint, Admin-Inbox, M011-Worker-Retry, Backfill-/Source-Bootstrap-Tooling und Legacy-Retirement sind implementiert.
  • Die HiveGrid-Website sendet serverseitig mit stabiler Submission-ID an den nativen Vertrag. Ihr Deploy-Workflow nutzt immutable Full-SHA-Images, Coolify-Pull-Deploy und einen revisionsgebundenen /readyz-Canary.
  • Safety-Proof vor jeder externen Mutation: verschlüsseltes Offsite-Backup unter backups/platform-leads/20260716T033754Z; Restore-Proof für lead-inbox Postgres (1 Datensatz) und HiveGrid-Staging-SQLite (1). Produktion-Website und Cloud-Legacy waren leer. Ein irrtümlich inventarisiertes fremdes Backup bleibt unverändert erhalten, ist im Evidence-Objekt ausdrücklich vom HiveGrid-Import ausgeschlossen und benötigt einen separaten Retention-/Löschentscheid. PII-freies Manifest: docs/ops/evidence/r-leads-safety-inventory-20260716.json.
  • Live-RLS-Gate gegen frisches PostgreSQL und den eingeschränkten hivegrid_app-Role: pnpm run verify:platform-leads-rls-live mit 14/14 Tests grün, einschließlich Atomicity, Rollback und Notification-Eligibility.
  • Echter Redis-/BullMQ-Retry: pnpm run verify:platform-notification-redis-live mit 1/1 Test grün.
  • Echter Admin-Smoke unter RLS_RUNTIME_MODE=required: Login, temporäre MFA, Lead-Anlage, persistiertes Detail, Notiz, Audit-Outbox und A11y, 1/1 Playwright-Test grün. Kein DB-Owner-/RLS-Bypass.
  • Interim-Pixelsnapshot 1/1, Hot-Swap 2/2 plus Verifier, i18n-Parität 11.902 Keys, Sidebar-/Route-Vertrag 32/32, API-Inventar 20/20 und Backfill-/Bootstrap-Tooling 25/25 grün.
  • Abschluss-Checkliste auf dem rebasierten Merge-Stand: pnpm typecheck, pnpm lint und pnpm test grün; 875 Testdateien / 5.770 Tests bestanden, 10 Dateien/54 environmentbedingt übersprungen. Coverage-, A11y-, Secret-, Permission-, Notification-, DB-Boundary-, Docker-, Runtime-Closure-, OpenAPI- und Deployment-Gates grün. Web/API/Worker/MCP/Hocuspocus bauen erfolgreich.
  • Der erste Remote-CI-Lauf deckte einen fehlenden Metrics-Snapshot-Eintrag für den neuen Plattform-Notification-Job auf. Commit bf3133a97 ergänzt den Regressionstest; pnpm test:packages ist anschließend für alle 36 selektierten Workspace-Pakete grün, darunter 123/123 Queue-Tests.
  • Der TypeScript-SDK wurde aus dem aktuellen OpenAPI-Vertrag neu generiert; beide SDK-Typechecks sowie 132/132 SDK-Tests sind grün. Der nach dem Rebase absichtlich geänderte Legacy-Detail-Redirect und die aktuelle Select-Komponente sind durch Routentest und aktualisierte Interim-Visual-Baseline abgesichert.
  • Producer-Proof: HiveGrid-Website 24/24 Tests, TypeScript, Next-Build, Docker und revisionsgenaues /readyz grün. Producer-Commit: HiveGrid-Website c81aca1. Kein Deploy ausgeführt.
  • Die gemeinsame Forward-only-Migration liegt unter prisma/migrations/20260716120000_r_leads_native_platform_leads/migration.sql, enthält Inverse-SQL und ist mit pnpm run verify:migrations-parity aus leerer Datenbank sowie mit prisma validate grün verifiziert.

%-DoD-Stand: 6/10 = 60 % done. Offen: vier Punkte, davon vier operativ/external-state-gebunden und 0 lokal im Ticket-Code selbst machbar. Kein Staging-/Produktions-Deploy, kein Live-Backfill und kein Decommission wurden vorgetäuscht oder ausgeführt. Ticket bleibt in Arbeit und Plane darf noch nicht auf Done gesetzt werden.

2026-07-16 — Website-Scope korrigiert

  • Eine irrtümlich einbezogene fremde Website wurde aus initialen Quellen, Producer-Cutover, Legacy-Stores, CSV-Backfill und den zugehörigen Tests entfernt.
  • Die generische Multi-Source-API, das Source-/Credential-Schema und die Admin-Quellenverwaltung bleiben unverändert und erlauben weiterhin beliebige explizit freigeschaltete Websites und Partner.
  • H-INBOUND, VA-P28b, VR-P28a und VD-P28 wurden in beide Richtungen erneut geprüft. Sie konsumieren nur den generischen AdminLead-/Website-Vertrag; der Cleanup ändert weder ihre Contracts noch ihre Termine.
  • Das bereits angelegte verschlüsselte Objekt wurde nicht gelöscht. Das Evidence-Inventar markiert es als excluded_from_hivegrid_import: true; Aufbewahrung oder Löschung erfordern eine separate, ausdrücklich autorisierte Entscheidung.
  • Cleanup-Proof: pnpm typecheck, pnpm lint, pnpm test (877 Testdateien / 5.780 Tests grün), fokussierte API-/DB-/VM-/Backfill-/Bootstrap-Tests 72/72 sowie Coverage-, RLS-Policy-, Sidebar-, i18n-, Hot-Swap-, Visual-, CI-Baseline-, Source-Health- und Docs-Link-Gates grün.

%-DoD-Stand unverändert: 6/10 = 60 % done. Offen bleiben die vier operativen Cutover-Punkte; das Ticket bleibt in Arbeit.

2026-07-24 — VA-P28b-Consumer-Vertrag erweitert

  • VA-P28b ergänzt den bestehenden AdminLead additiv um Qualification-, Duplicate- und Conversion-Relationen. Die Inbox-, Ingestion-, Source-, Attribution- und Idempotenzverträge aus R-LEADS bleiben unverändert; es gibt weiterhin genau eine Plattform-Lead-Tabelle.
  • Der bestehende Detail-DTO liefert zusätzlich Score/Enrichment, offene Dubletten und die idempotenten Conversion-IDs. Alte Listen-, Intake- und Source-Konsumenten behalten ihre bisherigen Felder und Semantik.
  • Die neuen Child-Tabellen sind tenant-los, an den aktiven Admin gebunden und vollständig im Plattform-RLS-Vertrag klassifiziert. Der R-LEADS-Visual-Fixture- und Route-Regressionstest wurden auf den additiven DTO-Vertrag nachgezogen.
  • Proof im VA-P28b-Slice: vollständiger Typecheck und Lint, 323/323 RLS-Verträge, 321/321 Modellklassifikationen, dedizierter RLS-Test 3/3, relevante Lead-/Route-/VM-/Visual-Tests grün sowie vollständiger Repository-Testlauf.

%-DoD-Stand unverändert: 6/10 = 60 % done. Die vier offenen Punkte bleiben ausschließlich operative Cutover-Gates; VA-P28b verändert weder Backfill noch Drain oder Decommission.

Dev-Nachzug (nach Davids VD-P28-Delta)

Interim-UI (Vorschau, Stand 2026-07-16): Liste, manuelle Anlage, Detail und Quellenverwaltung sind aus ~/ui unter apps/web/app/components/screens/admin/leads/ gebaut; alle Routen injizieren serverseitig erzeugte View-Models und Actions. Proof: echter Admin-Smoke tests/e2e/platform-leads.smoke.spec.ts, Hot-Swap-Drill grün und als Interim markierte Pixel-Baseline tests/component/__screenshots__/r-leads-platform-lead-inbox.png.

Refactor-Nachzug offen: finale Subframe-Optik aus VD-P28; danach werden die Screen-Internals hinter dem stabilen VM-/Action-Vertrag getauscht, die Visual- Baseline neu gezogen und design-nachzug in dieser Doc sowie in Plane erledigt.

Quellen

  • AGENTS.md
  • .planning/ENTITY-MODEL.md — Domäne 11
  • .planning/ROADMAP.md / .planning/ROADMAP-V2.md — Phase 28
  • docs/ARCHITECTURE-DECISIONS.md — AD-21, AD-28, AD-31
  • .planning/ticket-docs/AK-P19.md, VR-P28a.md, VA-P28b.md, VD-P28.md, H-INBOUND.md, J-LIVE.md, R-P7.md
  • prisma/schema/marketingLeads.prisma, prisma/schema/core.prisma, prisma/schema/admin.prisma
  • apps/web/app/routes/api.leads.capture.tsx, apps/web/app/routes/admin/marketing-leads/**, apps/web/public/embed/marketing.js
  • packages/foundation/src/notifications.ts, packages/db/src/outbox.ts, apps/web/app/services/admin/admin-action-audit.server.ts

Abhängigkeitsnachzug · CR-007 · 2026-07-27

platform_admin_leads wird als Rollout-Gate entfernt. Admin-Inbox und Einstellungen sind standardmäßig aktiv und bleiben durch AdminUser, admin_sales.* und Own-/All-RLS fail-closed. PLATFORM_LEADS_INGRESS_ENABLED bleibt der separate externe Ingress-Schalter.