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

109 lines
6.0 KiB
Markdown

# 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.