Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/features/marketing-funnel.md
T

6.0 KiB

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 <source credential>
  • Idempotency-Key: <stabile submission id>
  • 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.