Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,589 @@
# 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:
```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.