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 inJ-LIVE. HIVEGRID-73 übernimmt den vorgezogenen M040a-Slice: nativer Plattform-Lead-Eingang, Admin-Inbox, Quellenumstellung, Datenmigration und kontrollierte Stilllegung des separatenlead-inbox-Dienstes. Deal-Kanban, ARR/Forecast und „Promote to Tenant" bleiben als M040b inVA-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.deist ein separater Node/Postgres-Dienst mitPOST /v1/leads, source-spezifischem Bearer-Key und best-effort Mailjet-Versand nach bereits bestätigtem201.- 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.jsund die Admin-Routen/marketing-leadssowie/incoming-leads-board. R-P7ist 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
- Native Plattformmodelle
AdminLead,AdminLeadActivity,AdminLeadSourceund source-spezifische, rotierbare Credentials in einer eigenenprisma/schema/adminLeads.prisma. - Ein zentraler Ingestion-Service für S2S-Eingang, manuelle Anlage und Import.
- Authentifizierter, versionierter und idempotenter S2S-Endpoint für beliebige freigeschaltete Quellen.
- Admin-Inbox auf
admin.hivegrid.de/leadsmit Liste, Detail, Suche/Filter, manueller Anlage, Status, Zuweisung, Notizen/Aktivitäten und Archivierung. - Operator-Permissions, RLS/SECURITY-DEFINER-Grenze, Audit, Activity und transaktionales Outbox-Event.
- 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. - Umstellung der HiveGrid-Website auf den nativen Endpoint.
- Idempotenter Backfill aller bekannten Legacy-Speicher mit manifestiertem Zähl-/Hash-Nachweis.
- Staging-/Produktions-Cutover, mindestens sieben Tage Drain/Beobachtung und kontrollierte Stilllegung von App, DNS und Secrets des separaten Dienstes.
- 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 inVA-P28b.- Tenant-Lead-Routing aus M048 und Änderungen am
InboxLead-Contract ausR-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-P28amuss 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 undrecordAdminAction()/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 vonVA-P28b. - Design:
VD-P28bedient R-LEADS als getrackten Nachzug; nach AD-28 keinblocked-by. - Späterer Identitäts-Nachzug:
VR-P28amuss bestehendeassignedToAdminUserId-/Quellen-Zuweisungen beim Wechsel auf die getrennte AdminUser-Welt erhalten. R-LEADS blockiertVR-P28anicht. - Delivery-Owner-Nachzug 2026-07-24:
VA-P28bwechselt von Akeshan zu Raffael. Der nativeAdminLead-/Activity-/Source-Vertrag und der separate operative 7-Tage-Cutover bleiben unverändert. - Website-Launch-Kette: HIVEGRID-73 blockiert
J-LIVEnicht mehr. Responsive QA und Formular-Smoke liegen inJ-LIVE;J-CONTENTundJ-LAWbleiben 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-Keyist Pflicht. Partition des bestehendenIdempotencyKey-Modells:platform-leads:<sourceId>. Gleicher Key + gleicher Request liefert Status/Body der ersten Antwort; gleicher Key + anderer Request-Hash liefert409.- 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
BYPASSRLSund 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:
201mit{ id, status, createdAt }bei neuer Anlage- identische gespeicherte Antwort bei Replay, zusätzlich Replay-Header
400Validierung,401ungültiges/revoktes Credential,409Idempotency- Konflikt,413zu großer Body,429Rate-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_ownadmin.leads.read_alladmin.leads.writeadmin.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,AdminLeadActivityund Outbox in derselben Transaktion. - Operatoraktionen:
recordAdminAction()/gemeinsamerAuditEventplus fachlicheAdminLeadActivity; kein parallelesAdminAuditLog-Subsystem. notify()bleibt tenantpflichtig. Das Ticket ergänzt einen eng getrenntennotifyPlatform()-Vertrag mit zwingendemuserId,tenantId=null, PII-minimierter Metadata und deduplizierendemsourceKey.- Für Plattform-Deliveries wird die NULL-Eindeutigkeit in Postgres explizit per
partieller Unique-Constraint/Index abgesichert; ein gewöhnlicher Composite-Unique
mit
tenantId=NULLreicht 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:
lead-inboxPostgres- HiveGrid-Website Produktions-SQLite aus dem laufenden Container
- HiveGrid-Website Staging-SQLite
- 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.prismaprisma/tenant-policy-contract.mjspackages/db/src/platform-leads.server.tspackages/db/src/pretenant-security.server.tsbzw. 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.tsapps/api/src/app.ts,apps/api/src/app-dependencies.tsapps/api/src/openapi.tsbzw. Public-API-OpenAPI-Builderapps/api/src/route-access-inventory.tsdocs/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.tspackages/db/src/notifications.server.tsprisma/schema/notifications.prismaplus Merge-Migration für Partial-Uniqueapps/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
~/uibauen. - SQL-Suche nur in der Admin-Welt; kein tenantweiter Meili-Eintrag.
Voraussichtliche Dateien:
packages/view-models/src/admin-leads/*.vm.tsapps/web/app/services/admin/platform-leads.server.tsapps/web/app/routes/admin/leads.tsxapps/web/app/routes/admin/leads/index.tsxapps/web/app/routes/admin/leads/$id.tsxapps/web/app/routes/admin/leads/new.tsxapps/web/app/routes/admin/leads/sources.tsxapps/web/app/components/screens/admin/leads/*Page.tsxapps/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=0liefern. - Legacy-Admin-Routen und
/api/leads/captureauf die native Welt umstellen bzw. entfernen;public/embed/marketing.jsmigrieren/entfernen. Lead/LeadEventbleiben bis Ende des Rollbacks read-only; abhängigeTenantAcquisition-/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-inboxin Coolify stoppen, Source-Secrets/Mailjet-Zugang revoken,leads.hivegrid.deaus 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-P28und 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-Websitec81aca1. - 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ürlead-inboxPostgres (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-livemit 14/14 Tests grün, einschließlich Atomicity, Rollback und Notification-Eligibility. - Echter Redis-/BullMQ-Retry:
pnpm run verify:platform-notification-redis-livemit 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 lintundpnpm testgrü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
bf3133a97ergänzt den Regressionstest;pnpm test:packagesist 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
/readyzgrün. Producer-Commit: HiveGrid-Websitec81aca1. 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 mitpnpm run verify:migrations-parityaus leerer Datenbank sowie mitprisma validategrü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-P28aundVD-P28wurden 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-P28bergänzt den bestehendenAdminLeadadditiv 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 28docs/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.mdprisma/schema/marketingLeads.prisma,prisma/schema/core.prisma,prisma/schema/admin.prismaapps/web/app/routes/api.leads.capture.tsx,apps/web/app/routes/admin/marketing-leads/**,apps/web/public/embed/marketing.jspackages/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.