109 lines
6.0 KiB
Markdown
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.
|