# Plattform-Lead-Eingang und historischer Marketing-Funnel Seit R-LEADS (`HIVEGRID-73`, AD-31) ist der native Plattform-Lead-Eingang die einzige aktive Zielarchitektur für HiveGrid-eigene Vertriebsanfragen. Diese Datei dokumentiert den aktuellen Vertrag und die während des Cutovers bewusst noch vorhandenen Legacy-Kompatibilitätspfade. ## Aktive Architektur | Ebene | Aktiver Vertrag | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | Datenmodell | `AdminLead`, `AdminLeadActivity`, `AdminLeadSource` und gehashte Source-Credentials in `prisma/schema/adminLeads.prisma` | | Eingang | `POST /v1/platform/leads` auf dem API-Host | | Producer | ausschließlich serverseitig; ein Source-Credential pro freigeschalteter Website/Partnerquelle | | Admin-Inbox | `/leads`, `/leads/new`, `/leads/:id` und `/leads/sources` auf dem Admin-Host | | Benachrichtigung | tenantlose, PII-minimierte M011-Outbox mit Worker-Retry und aktueller Empfänger-Revalidierung | Das Source-Credential bestimmt die Quelle. Ein Request darf die Source nicht selbst autoritativ wählen. `Idempotency-Key` ist Pflicht und muss von einem Producer für dieselbe Submission bis zur bestätigten Antwort stabil wiederverwendet werden. Kontakt-, Nachrichten- und Attributionsfelder werden schema- und größenvalidiert; Logs, Outbox und Queue enthalten keine Lead-PII. Der API-Eingang kann im Notfall mit `PLATFORM_LEADS_INGRESS_ENABLED=false` neutral als 404 abgeschaltet werden. Die Admin-Oberfläche ist davon unabhängig standardmäßig aktiv und wird über AdminUser, Permissions und Own-/All-RLS geschützt. Details zu Source-Bootstrap, Backfill, Canary, Rollback und Decommission stehen in `docs/ops/platform-leads-cutover.md`. Der vollständige Bauvertrag steht in `.planning/ticket-docs/R-LEADS.md`. ## Aktiver API-Vertrag `POST /v1/platform/leads` erwartet: - `Authorization: Bearer ` - `Idempotency-Key: ` - JSON mit mindestens einem nutzbaren Kontakt- oder Inhaltsfeld - optionale, begrenzte UTM-, Referrer-, Landing-Page- und Metadatenfelder Relevante Antworten sind `201` für Create und identischen Replay, `400` für Validierung, `401` für ein ungültiges oder revoktes Credential, `409` für einen Idempotency-Hash-Konflikt, `413` für einen zu großen Body und `429` für das Source-/Ingress-Limit. OpenAPI ist die kanonische Feldreferenz. Browser und statische Marketing-Sites erhalten niemals das Source-Credential. Die HiveGrid-Website besitzt deshalb einen serverseitigen Proxy/Action-Handler. Ein fehlgeschlagener API-Request darf dort nicht als erfolgreicher Lead angezeigt oder in eine Container-SQLite-Datei zurückgefallen werden. ## Retired: Browser-Capture und Embed-SDK Die folgenden Komponenten sind kein aktiver Lead-Eingang mehr: - `POST /api/leads/capture` liefert während des Drain-Fensters bewusst `410 Gone` und verweist auf `/v1/platform/leads`; `OPTIONS` bleibt nur für eine saubere CORS-Fehlermeldung verfügbar. - `apps/web/public/embed/marketing.js` ist entfernt. Es gibt kein öffentliches `window.hivegridMarketing`-SDK und keinen `data-hivegrid-lead`-Hook mehr. - `/marketing-leads`, `/incoming-leads-board` und `/marketing-funnels` leiten auf die native `/leads`-Inbox um. - Die Legacy-Tabellen `Lead`/`LeadEvent` sind bis zum Ende des Rollback-/Drain- Fensters read-only. Verbleibende CLI-Reads dienen ausschließlich Export und Rollback; sie sind kein zweites aktives Produkt-Frontend und werden nach dem bestätigten Sieben-Tage-Drain entfernt. `MARKETING_ALLOWED_ORIGINS` beeinflusst nur noch die CORS-Header der `410 Gone`-Antwort. `MARKETING_RATE_LIMIT_PER_MIN` ist für den retired Endpoint wirkungslos und bleibt vorübergehend nur als kompatibler, deprecated Env-Key im Konfigurationskatalog. ## Historische Conversion-Kompatibilität Die signierte Self-Service-Conversion bestehender Legacy-Leads bleibt während des Rollback-Fensters bewusst separat erhalten. Sie darf keine neuen `Lead`/`LeadEvent`-Captures erzeugen. Die SECURITY-DEFINER-Funktion `hivegrid_convert_self_service_lead` ist nur für den signierten Registrierungsweg freigegeben; direkte Runtime-Schreibrechte auf Legacy-Tabellen bleiben entzogen. `LEAD_CONVERSION_SECRET` und `LEAD_CONVERSION_ENABLED` gehören zu diesem Kompatibilitätspfad. Eine Überführung dieser Conversion in die spätere `AdminDeal`-/M040b-Welt ist nicht Teil von R-LEADS. ## Outbound- und E-Mail-Marketing-Abgrenzung Die vorhandenen Marketing-Webhook-Adapter und die E-Mail-Sequenz-Engine sind eigenständige Foundations. Sie machen den retired Browser-Capture nicht wieder aktiv und dürfen nicht automatisch von einem AdminLead-Import ausgelöst werden. Die jeweiligen Runtime-Schalter und Betriebsgrenzen stehen in `docs/features/email-sequences.md` und den zugehörigen Worker-Dokumenten. This page also keeps the marketing-outbound boundary explicit: the `packages/marketing-outbound` adapters and `apps/worker/src/jobs/marketing-outbound.ts` handler are a shipped general handler foundation, but the general subscriber is not bootstrapped from `apps/worker/src/index.ts`. That foundation is separate from the tenant Email Marketing scope in `.planning/ticket-docs/AK-P14a.md` and proves neither an active subscriber nor production delivery. ## Rollback Während des dokumentierten Drain-Fensters können Producer auf den gesicherten externen Legacy-Dienst zurückgestellt werden. Der HiveGrid-Cloud-Browserendpoint bleibt auch im Rollback `410`; eine Reaktivierung wäre eine neue Architektur- und Security-Entscheidung. Native Importe sind idempotent und löschen keine Quellbestände. Das letzte verschlüsselte, restore-geprüfte Backup wird bis zu einem separaten Retention-Entscheid behalten.