# 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 `; eigener Plattform-Source-Key, weder globaler Service-Bearer noch tenantgebundener API-Key. - `Idempotency-Key` ist Pflicht. Partition des bestehenden `IdempotencyKey`-Modells: `platform-leads:`. 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: ```bash 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.