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/captureliefert während des Drain-Fensters bewusst410 Goneund verweist auf/v1/platform/leads;OPTIONSbleibt nur für eine saubere CORS-Fehlermeldung verfügbar.apps/web/public/embed/marketing.jsist entfernt. Es gibt kein öffentlicheswindow.hivegridMarketing-SDK und keinendata-hivegrid-lead-Hook mehr./marketing-leads,/incoming-leads-boardund/marketing-funnelsleiten auf die native/leads-Inbox um.- Die Legacy-Tabellen
Lead/LeadEventsind 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.