Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,589 @@
|
||||
# R-LEADS · Native Plattform-Leads + Ablösung `lead-inbox`
|
||||
|
||||
> ♻️ **Recut vom 2026-07-16:** Dieses Dokument ersetzt `J-QA`; der Plane-Key bleibt
|
||||
> **HIVEGRID-73**. Der frühere Website-QA-Anteil liegt jetzt in `J-LIVE`. HIVEGRID-73
|
||||
> übernimmt den vorgezogenen **M040a-Slice**: nativer Plattform-Lead-Eingang,
|
||||
> Admin-Inbox, Quellenumstellung, Datenmigration und kontrollierte Stilllegung des
|
||||
> separaten `lead-inbox`-Dienstes. Deal-Kanban, ARR/Forecast und
|
||||
> „Promote to Tenant" bleiben als **M040b** in `VA-P28b`.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Plane** | `HIVEGRID-73` |
|
||||
| **Typ** | Dev (Code + Cross-Repo-Cutover) |
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | P28 / M040a — vorgezogener Plattform-Lead-Unterbau |
|
||||
| **Cycle/Fenster** | Start 2026-07-16 · Ziel 2026-07-31 · Abschluss in v2-W3 |
|
||||
| **Status** | in Arbeit |
|
||||
|
||||
**🎨 design-nachzug: offen** — die erste Version wird nach AD-28 als Interim-UI aus
|
||||
`~/ui` gebaut. `VD-P28` liefert später die finale Subframe-Optik; das blockiert die
|
||||
Dev-DoD nicht.
|
||||
|
||||
## Zielbild und Architekturentscheidung
|
||||
|
||||
HiveGrid-eigene Vertriebsleads werden **nativ in HiveGrid** verwaltet. Es gibt keinen
|
||||
„internen Mandanten" und keine Wiederverwendung der tenantgebundenen `InboxLead`-Welt
|
||||
aus `R-P7`. Die Plattform-Leads leben in der operatorweiten Admin-Welt auf
|
||||
`admin.hivegrid.de` und tragen **kein `tenant_id`**.
|
||||
|
||||
Alle Eingangswege verwenden einen transportneutralen `AdminLeadIngestionService`.
|
||||
Websites und spätere Partner senden serverseitig an den kanonischen Endpoint
|
||||
`POST https://api.hivegrid.de/v1/platform/leads`. Manuelle Anlage und Backfill nutzen
|
||||
denselben Domain-Service über getrennte Ports. Das bisherige Subsystem
|
||||
`Lead`/`LeadEvent`, die Route `/api/leads/capture`, das Embed-SDK und der externe
|
||||
`lead-inbox`-Dienst werden nach Migration und Drain aus dem aktiven Schreibpfad
|
||||
entfernt.
|
||||
|
||||
Die bindende Architekturentscheidung steht in `docs/ARCHITECTURE-DECISIONS.md` als
|
||||
**AD-31**.
|
||||
|
||||
## Ist-Zustand, den dieses Ticket ablöst
|
||||
|
||||
- `leads.hivegrid.de` ist ein separater Node/Postgres-Dienst mit `POST /v1/leads`,
|
||||
source-spezifischem Bearer-Key und best-effort Mailjet-Versand nach bereits
|
||||
bestätigtem `201`.
|
||||
- Der Dienst hat keine fachliche Admin-Inbox, keinen Owner-/Status-Workflow, keine
|
||||
belastbare Idempotenz, keinen transaktionalen Notification-Retry und keinen
|
||||
dokumentierten Datenbank-Backup-/Restore-Nachweis.
|
||||
- Die Produktions-Website kann bei fehlender `LEAD_INBOX_*`-Konfiguration in eine
|
||||
lokale SQLite-Datei im Container schreiben und trotzdem Erfolg melden. Diese Datei
|
||||
muss **vor jedem Website-Deploy** gesichert werden.
|
||||
- HiveGrid-Cloud besitzt parallel das operatorweite Legacy-Modell `Lead`/`LeadEvent`,
|
||||
die Browserroute `/api/leads/capture`, `public/embed/marketing.js` und die
|
||||
Admin-Routen `/marketing-leads` sowie `/incoming-leads-board`.
|
||||
- `R-P7` ist die bereits fertige **Mandanten-Lead-Inbox** für Kunden von HiveGrid und
|
||||
bleibt unverändert. Plattform-Leads dürfen dort nicht abgelegt werden.
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
|
||||
1. Native Plattformmodelle `AdminLead`, `AdminLeadActivity`, `AdminLeadSource` und
|
||||
source-spezifische, rotierbare Credentials in einer eigenen
|
||||
`prisma/schema/adminLeads.prisma`.
|
||||
2. Ein zentraler Ingestion-Service für S2S-Eingang, manuelle Anlage und Import.
|
||||
3. Authentifizierter, versionierter und idempotenter S2S-Endpoint für beliebige
|
||||
freigeschaltete Quellen.
|
||||
4. Admin-Inbox auf `admin.hivegrid.de/leads` mit Liste, Detail, Suche/Filter,
|
||||
manueller Anlage, Status, Zuweisung, Notizen/Aktivitäten und Archivierung.
|
||||
5. Operator-Permissions, RLS/SECURITY-DEFINER-Grenze, Audit, Activity und
|
||||
transaktionales Outbox-Event.
|
||||
6. M011-konforme Plattform-Benachrichtigung ohne Aufweichung des tenantgebundenen
|
||||
`notify()`-Vertrags. Haris wird für die aktuelle Website-Quelle konfigurierter
|
||||
Default-Assignee und Empfänger, nicht als Code-Konstante eingebaut.
|
||||
7. Umstellung der HiveGrid-Website auf den nativen Endpoint.
|
||||
8. Idempotenter Backfill aller bekannten Legacy-Speicher mit manifestiertem
|
||||
Zähl-/Hash-Nachweis.
|
||||
9. Staging-/Produktions-Cutover, mindestens sieben Tage Drain/Beobachtung und
|
||||
kontrollierte Stilllegung von App, DNS und Secrets des separaten Dienstes.
|
||||
10. Ablösung der aktiven Legacy-Schreib- und Leserouten in HiveGrid-Cloud, sodass
|
||||
genau **ein** aktives Plattform-Lead-System übrig bleibt.
|
||||
|
||||
### Nicht in Scope
|
||||
|
||||
- `AdminDeal`, Deal-Kanban, Drag-and-drop, Stage-Forecast, ARR-/Abschlussprognosen
|
||||
und „Gewonnen → Promote to Tenant"; das ist M040b in `VA-P28b`.
|
||||
- Tenant-Lead-Routing aus M048 und Änderungen am `InboxLead`-Contract aus `R-P7`.
|
||||
- Marketing-Automation, Lead-Scoring-Automatik oder E-Mail-Kampagnen.
|
||||
- Die endgültige getrennte AdminUser-Identität aus `VR-P28a`; R-LEADS nutzt einen
|
||||
klar dokumentierten Kompatibilitätsadapter zur bereits laufenden AdminUser/User-
|
||||
Brücke. `VR-P28a` muss die IDs/Assignments verlustfrei übernehmen.
|
||||
- Löschen des letzten verschlüsselten Backups oder irreversible Datenvernichtung.
|
||||
Nach Drain wird der Dienst abgeschaltet; die endgültige DB-Löschung braucht einen
|
||||
separat bestätigten Retention-/Löschentscheid.
|
||||
|
||||
## Abhängigkeiten und Auswirkungen
|
||||
|
||||
- **Blocked by:** keine offene Ticket-DoD. Verwendet werden nur bereits ausgelieferte
|
||||
Teile aus `AK-P19`: Admin-Host, Admin-Shell/Auth und `recordAdminAction()`/
|
||||
`AuditEvent`. Die dort noch offenen Billing-/Support-/Queue-Punkte sind kein Blocker.
|
||||
- **Blocks:** `H-INBOUND` (operative Abnahme: Haris erhält und bearbeitet Leads in
|
||||
unter 24 Stunden) und den M040b-Anteil von `VA-P28b`.
|
||||
- **Design:** `VD-P28` bedient R-LEADS als getrackten Nachzug; nach AD-28 kein
|
||||
`blocked-by`.
|
||||
- **Späterer Identitäts-Nachzug:** `VR-P28a` muss bestehende
|
||||
`assignedToAdminUserId`-/Quellen-Zuweisungen beim Wechsel auf die getrennte
|
||||
AdminUser-Welt erhalten. R-LEADS blockiert `VR-P28a` nicht.
|
||||
- **Delivery-Owner-Nachzug 2026-07-24:** `VA-P28b` wechselt von Akeshan zu Raffael.
|
||||
Der native `AdminLead`-/Activity-/Source-Vertrag und der separate operative
|
||||
7-Tage-Cutover bleiben unverändert.
|
||||
- **Website-Launch-Kette:** HIVEGRID-73 blockiert `J-LIVE` nicht mehr. Responsive
|
||||
QA und Formular-Smoke liegen in `J-LIVE`; `J-CONTENT` und `J-LAW` bleiben dessen
|
||||
fachliche Abhängigkeiten.
|
||||
|
||||
## Fachlicher Datenvertrag
|
||||
|
||||
### `AdminLead`
|
||||
|
||||
Mindestens folgende Felder:
|
||||
|
||||
- Identität/Zeit: `id`, `createdAt`, `updatedAt`, `capturedAt`, `archivedAt?`
|
||||
- Quelle: `sourceId`, `sourceDetail?`, `externalId?`, `idempotencyKey?`
|
||||
- Kontakt/Inhalt: `firstName?`, `lastName?`, `email?`, `phone?`, `company?`,
|
||||
`message?`
|
||||
- Attribution: `utmSource?`, `utmMedium?`, `utmCampaign?`, `utmTerm?`,
|
||||
`utmContent?`, `referrer?`, `landingPage?`
|
||||
- Bearbeitung: `status` (`new|contacted|qualified|disqualified`),
|
||||
`assignedToAdminUserId?`, `duplicateHintOfLeadId?`
|
||||
- begrenzte Zusatzdaten: `metadata?` mit Größen-/Key-Allowlist; keine beliebigen
|
||||
ungeprüften Payload-Dumps
|
||||
|
||||
`@@unique([sourceId, externalId])` gilt für gesetzte externe IDs. E-Mail oder Telefon
|
||||
werden **nicht** als Unique-Key und nicht für stilles Zusammenführen verwendet.
|
||||
Ähnliche normalisierte Kontakte dürfen nur einen sichtbaren Duplicate-Hinweis
|
||||
erzeugen. Damit werden Haushalte/Sammeladressen nicht versehentlich verschmolzen.
|
||||
|
||||
### `AdminLeadActivity`
|
||||
|
||||
Append-only Verlauf mit `leadId`, `type`, `actorAdminUserId?`, `payload`,
|
||||
`createdAt`. Mindestens unterstützt:
|
||||
|
||||
`captured`, `imported`, `manually_created`, `status_changed`, `assigned`,
|
||||
`note_added`, `archived`, `restored`, `duplicate_hint_recorded`.
|
||||
|
||||
Freitextnotizen liegen im Activity-Verlauf, nicht als überschreibbarer Sammel-Blob
|
||||
auf dem Lead. Payloads werden schema-validiert und PII-minimiert.
|
||||
|
||||
### `AdminLeadSource` und Credentials
|
||||
|
||||
Quellen sind konfiguriert, nicht vom Request frei wählbar. Sie enthalten mindestens:
|
||||
`key`, `displayName`, `enabled`, `defaultAssigneeAdminUserId?`,
|
||||
`notifyAdminUserIds`, Rate-Limit und optionale Metadaten. Credentials liegen als
|
||||
eigene rotierbare Child-Records ausschließlich gehasht mit Prefix, Erstell-/Ablauf-
|
||||
und Revoke-Zeit vor. Klartext wird nur einmal bei Erstellung gezeigt.
|
||||
|
||||
Die initialen Quellen sind `hivegrid-website`, `hivegrid-legacy-cloud` und
|
||||
`lead-inbox-legacy`; Haris wird für die aktuelle Website-Quelle per Konfiguration
|
||||
zugewiesen. Weitere Websites und Partner können über die allgemeine
|
||||
Quellenverwaltung mit eigenem Credential ergänzt werden.
|
||||
|
||||
## API-Vertrag: `POST /v1/platform/leads`
|
||||
|
||||
### Sicherheit
|
||||
|
||||
- `Authorization: Bearer <source credential>`; eigener Plattform-Source-Key, weder
|
||||
globaler Service-Bearer noch tenantgebundener API-Key.
|
||||
- `Idempotency-Key` ist Pflicht. Partition des bestehenden `IdempotencyKey`-Modells:
|
||||
`platform-leads:<sourceId>`. Gleicher Key + gleicher Request liefert Status/Body
|
||||
der ersten Antwort; gleicher Key + anderer Request-Hash liefert `409`.
|
||||
- Die authentifizierte Quelle stammt ausschließlich aus dem Credential. Ein
|
||||
`source`-Feld im Body wird abgelehnt bzw. niemals als Autorität verwendet.
|
||||
- Body-Limit, schema-validierte Stringlängen, source-spezifisches Rate-Limit und
|
||||
strukturierte Klartextfehler. Keys und Lead-PII erscheinen nie in Logs.
|
||||
- Runtime-Schreibzugriff erfolgt über eine enge, versionierte
|
||||
SECURITY-DEFINER-/Pre-Tenant-Capability; kein `BYPASSRLS` und kein freier
|
||||
Tabellenzugriff für den API-Role.
|
||||
|
||||
### Payload und Semantik
|
||||
|
||||
Erlaubte Kernfelder sind Kontakt/Inhalt, `externalId`, `sourceDetail`, Attribution
|
||||
und begrenzte `metadata`. Mindestens **eines** der Felder `email`, `phone`, `company`,
|
||||
`firstName`, `lastName` oder `message` muss nach Normalisierung nutzbar sein; E-Mail
|
||||
allein ist ausdrücklich nicht Pflicht.
|
||||
|
||||
Antworten:
|
||||
|
||||
- `201` mit `{ id, status, createdAt }` bei neuer Anlage
|
||||
- identische gespeicherte Antwort bei Replay, zusätzlich Replay-Header
|
||||
- `400` Validierung, `401` ungültiges/revoktes Credential, `409` Idempotency-
|
||||
Konflikt, `413` zu großer Body, `429` Rate-Limit
|
||||
|
||||
Lead, erste Activity, Idempotency-Antwort und PII-minimiertes
|
||||
`platform.admin_lead.captured.v1`-Outbox-Event committen atomar. Der Outbox-Payload
|
||||
enthält nur Lead-ID, Source-ID, Event-Zeit und Routing-IDs, nicht Nachricht,
|
||||
E-Mail oder Telefon.
|
||||
|
||||
## Admin-Oberfläche und Permissions
|
||||
|
||||
Kanonische Host-Pfade (kein `/admin` im öffentlichen URL-Pfad):
|
||||
|
||||
| Screen | Inhalt |
|
||||
|---|---|
|
||||
| `admin.hivegrid.de/leads` | Liste, Suche, Filter nach Status/Quelle/Assignee/Archiv, Empty-/Loading-/Fehlerzustände |
|
||||
| `/leads/new` | manuelle Anlage über denselben Domain-Service |
|
||||
| `/leads/:id` | Kontaktdaten, Quelle, Attribution, Zuweisung, Status, Activity/Notizen, Archivieren/Wiederherstellen |
|
||||
| `/leads/sources` | Quellenstatus, Default-Assignee/Empfänger, Credential erstellen/rotieren/revoken; kein Klartext-Key nach Erstellung |
|
||||
|
||||
Permissions:
|
||||
|
||||
- `admin.leads.read_own`
|
||||
- `admin.leads.read_all`
|
||||
- `admin.leads.write`
|
||||
- `admin.leads.admin`
|
||||
|
||||
Fehlende Leseberechtigung ergibt 404. Jeder Screen wird als VM im Loader gebaut; UI
|
||||
erhält ausschließlich VM + Actions. Die Interim-UI nutzt `~/ui`, enthält keinen
|
||||
zweiten App-Chrome und bekommt Sidebar, Breadcrumbs und i18n. Die Inbox-Suche ist
|
||||
operatorintern und DB-seitig; Plattform-PII wird **nicht** in tenantweite Meili-
|
||||
Indizes aufgenommen.
|
||||
|
||||
## Audit, Activity und Benachrichtigung
|
||||
|
||||
- Automatischer Eingang: systemischer `AuditEvent`, `AdminLeadActivity` und Outbox
|
||||
in derselben Transaktion.
|
||||
- Operatoraktionen: `recordAdminAction()`/gemeinsamer `AuditEvent` plus fachliche
|
||||
`AdminLeadActivity`; kein paralleles `AdminAuditLog`-Subsystem.
|
||||
- `notify()` bleibt tenantpflichtig. Das Ticket ergänzt einen eng getrennten
|
||||
`notifyPlatform()`-Vertrag mit zwingendem `userId`, `tenantId=null`,
|
||||
PII-minimierter Metadata und deduplizierendem `sourceKey`.
|
||||
- Für Plattform-Deliveries wird die NULL-Eindeutigkeit in Postgres explizit per
|
||||
partieller Unique-Constraint/Index abgesichert; ein gewöhnlicher Composite-Unique
|
||||
mit `tenantId=NULL` reicht nicht.
|
||||
- Der bestehende Notification-Worker verarbeitet Plattform-E-Mail/In-App-Zustellung
|
||||
dauerhaft mit Retry. Kein direkter Mailjet-Aufruf aus Lead-Code. Eine erfolgreiche
|
||||
Lead-Antwort hängt nicht vom synchronen E-Mail-Versand ab, wohl aber vom atomar
|
||||
angelegten Delivery-/Outbox-Auftrag.
|
||||
|
||||
## Betroffene Repositories und Systeme
|
||||
|
||||
| Bereich | Erwartete Änderung |
|
||||
|---|---|
|
||||
| `HiveGrid-Cloud` | Modelle, Service, API, Admin-UI, Importer, Tests, Legacy-Cutover |
|
||||
| `../HiveGrid-Website` | serverseitiger Producer, stabiler Submission-Key, kein Erfolgs-Fallback auf Container-SQLite |
|
||||
| `../lead-inbox` | Read-only-Export/Drain, anschließend App stilllegen und Repo archivieren |
|
||||
| `../infra` | Backup-/Restore-Runbook, Coolify/Cloudflare/Secrets/DNS-Cleanup, ADR-Nachzug |
|
||||
| Extern | Coolify Staging/Prod, Cloudflare, Mailjet, Gitea |
|
||||
|
||||
Bekannte Importquellen:
|
||||
|
||||
1. `lead-inbox` Postgres
|
||||
2. HiveGrid-Website Produktions-SQLite aus dem laufenden Container
|
||||
3. HiveGrid-Website Staging-SQLite
|
||||
4. HiveGrid-Cloud `Lead`/`LeadEvent`
|
||||
|
||||
Der Importer verwendet `source + legacy_store + legacy_id` als deterministischen
|
||||
externen Schlüssel, übernimmt Original-Zeitstempel und Activities, löst keine
|
||||
Benachrichtigungen/Automationen aus und erzeugt ein Manifest mit Input-Hash,
|
||||
Quellzählung, `created/replayed/rejected` und Zeitbereich — ohne PII.
|
||||
|
||||
## Implementierungs-Slices
|
||||
|
||||
### Slice 0 — Safety-Inventar und Backups
|
||||
|
||||
- Live-Konfiguration und tatsächlich beschriebene Stores read-only inventarisieren.
|
||||
- Vor **jedem** HiveGrid-Website-Deploy die Produktions-SQLite aus dem laufenden
|
||||
Container sichern.
|
||||
- `lead-inbox`-Postgres per konsistentem Dump sichern, verschlüsselt offsite ablegen
|
||||
und Restore in eine leere DB beweisen.
|
||||
- Quellenzählungen/-Hashes als nicht-PII Manifest festhalten.
|
||||
|
||||
**Rollback:** keine Mutation. Bei fehlendem Backup/Restore-Proof stoppt der Cutover.
|
||||
|
||||
### Slice 1 — Datenmodell, Domain-Service und Sicherheitsgrenze
|
||||
|
||||
- `prisma/schema/adminLeads.prisma`, Status-/Activity-Typen und Policies anlegen.
|
||||
- Operator-RLS sowie enge S2S-SECURITY-DEFINER-Capability bauen.
|
||||
- Transportneutralen Ingestion-/Admin-Service mit Repository-Ports implementieren.
|
||||
- Legacy-`Lead`/`LeadEvent`-Mapping und Idempotency-Partition festlegen.
|
||||
|
||||
**Voraussichtliche Dateien:**
|
||||
|
||||
- `prisma/schema/adminLeads.prisma`
|
||||
- `prisma/tenant-policy-contract.mjs`
|
||||
- `packages/db/src/platform-leads.server.ts`
|
||||
- `packages/db/src/pretenant-security.server.ts` bzw. dedizierte Capability
|
||||
- Service-/RLS-/DB-Integrationstests
|
||||
|
||||
**Rollback:** Feature-Flag aus, neue Tabellen ungenutzt lassen; auf Feature-Branch
|
||||
nur `prisma db push`. Merge-Migration forward-only mit Inverse-SQL-Kommentar.
|
||||
|
||||
### Slice 2 — S2S-API, Source-Keys und OpenAPI
|
||||
|
||||
- Route, Authenticator, Idempotency, Rate-Limit und Klartextfehler umsetzen.
|
||||
- Source-Credential Create/Rotate/Revoke serverseitig verfügbar machen.
|
||||
- OpenAPI, Route-Access-Inventar und Security-Tests ergänzen.
|
||||
|
||||
**Voraussichtliche Dateien:**
|
||||
|
||||
- `apps/api/src/routes/platform-lead-routes.ts`
|
||||
- `apps/api/src/app.ts`, `apps/api/src/app-dependencies.ts`
|
||||
- `apps/api/src/openapi.ts` bzw. Public-API-OpenAPI-Builder
|
||||
- `apps/api/src/route-access-inventory.ts`
|
||||
- `docs/security/route-access-inventory.md`
|
||||
|
||||
**Rollback:** Source-Keys revoken und Endpoint per Feature-Flag deaktivieren; alte
|
||||
Producer bleiben bis zum jeweiligen Cutover unangetastet.
|
||||
|
||||
### Slice 3 — Activity, Audit, Outbox und M011-Plattform-Notification
|
||||
|
||||
- System-/Operator-Audit und Activity atomar verdrahten.
|
||||
- `notifyPlatform()` ergänzen, Haris über Source-Konfiguration routen und Worker-
|
||||
Retry/Dedupe beweisen.
|
||||
- Notification-/Outbox-Payloads auf PII-Minimierung testen.
|
||||
|
||||
**Voraussichtliche Dateien:**
|
||||
|
||||
- `packages/foundation/src/notifications.ts`
|
||||
- `packages/db/src/notifications.server.ts`
|
||||
- `prisma/schema/notifications.prisma` plus Merge-Migration für Partial-Unique
|
||||
- `apps/worker/src/**` Notification-/Outbox-Handler
|
||||
|
||||
**Rollback:** Zustellung abschalten, Inbox/Outbox weiter befüllen und nach Fix
|
||||
idempotent drainieren; niemals auf Direktversand ausweichen.
|
||||
|
||||
### Slice 4 — Admin-Inbox als Interim-UI
|
||||
|
||||
- VM/Zod, Admin-Service, Routen, Sidebar, Breadcrumbs, Permission-Gates und i18n.
|
||||
- Liste/Detail/Neu/Quellen mit allen Scope-Aktionen aus `~/ui` bauen.
|
||||
- SQL-Suche nur in der Admin-Welt; kein tenantweiter Meili-Eintrag.
|
||||
|
||||
**Voraussichtliche Dateien:**
|
||||
|
||||
- `packages/view-models/src/admin-leads/*.vm.ts`
|
||||
- `apps/web/app/services/admin/platform-leads.server.ts`
|
||||
- `apps/web/app/routes/admin/leads.tsx`
|
||||
- `apps/web/app/routes/admin/leads/index.tsx`
|
||||
- `apps/web/app/routes/admin/leads/$id.tsx`
|
||||
- `apps/web/app/routes/admin/leads/new.tsx`
|
||||
- `apps/web/app/routes/admin/leads/sources.tsx`
|
||||
- `apps/web/app/components/screens/admin/leads/*Page.tsx`
|
||||
- `apps/web/app/application/sidebar/AdminSidebar.tsx`
|
||||
|
||||
**Rollback:** vorheriges Image koordiniert deployen; externer Ingress kann separat
|
||||
über `PLATFORM_LEADS_INGRESS_ENABLED=false` gestoppt werden. Daten bleiben erhalten.
|
||||
|
||||
### Slice 5 — Producer umstellen
|
||||
|
||||
- HiveGrid-Website serverseitig auf den nativen Endpoint setzen.
|
||||
- Je Formular eine stabile Submission-ID bis zur bestätigten Antwort wiederverwenden.
|
||||
- Bearer-Key bleibt ausschließlich im Server-Runtime-Secret.
|
||||
- Bei API-Fehler keinen falschen Erfolg anzeigen; retrybare Klartextantwort liefern.
|
||||
|
||||
**Rollback:** den Producer auf den bisherigen Endpoint zurückschalten, solange dessen
|
||||
Drain-Fenster offen ist. Kein Website-Deploy ohne vorher gesicherte Live-SQLite.
|
||||
|
||||
### Slice 6 — Backfill und Legacy-Cutover
|
||||
|
||||
- Alle vier bekannten Stores mit Dry-Run und anschließendem Apply importieren.
|
||||
- Counts/Hashes vor und nach Import abgleichen; Replay muss `created=0` liefern.
|
||||
- Legacy-Admin-Routen und `/api/leads/capture` auf die native Welt umstellen bzw.
|
||||
entfernen; `public/embed/marketing.js` migrieren/entfernen.
|
||||
- `Lead`/`LeadEvent` bleiben bis Ende des Rollbacks read-only; abhängige
|
||||
`TenantAcquisition`-/Marketing-Funktionen werden nicht ungeprüft gelöscht.
|
||||
|
||||
**Rollback:** neue Reads deaktivieren und während des Drain-Fensters auf read-only
|
||||
Legacy-Ansicht zurückschalten; Backfill ist wiederholbar und löscht keine Quelle.
|
||||
|
||||
### Slice 7 — Staging, Produktion, Drain und Decommission
|
||||
|
||||
- Staging-Canary pro Source: create, Replay, Konflikt, Auth-Fehler, Notification,
|
||||
Admin-Bearbeitung.
|
||||
- Produktions-Canary mit synthetischem, klar markiertem Lead; Monitoring/Alerts auf
|
||||
5xx, 401-Spikes, 429, Queue-Failures und Source-Lag.
|
||||
- Den Producer umstellen, Backfill-Finaldelta einspielen und mindestens sieben
|
||||
Tage eingehenden Legacy-Traffic beobachten.
|
||||
- Danach `lead-inbox` in Coolify stoppen, Source-Secrets/Mailjet-Zugang revoken,
|
||||
`leads.hivegrid.de` aus DNS entfernen, Repo archivieren und Infra-ADR/Runbook
|
||||
aktualisieren. Verschlüsseltes Backup gemäß Retention behalten.
|
||||
|
||||
**Rollback:** innerhalb des Drain-Fensters DNS/Producer auf Legacy zurück; nach
|
||||
Abschaltung App aus dem letzten Image und DB aus geprüftem Dump wiederherstellen.
|
||||
|
||||
### Slice 8 — Abschluss-Audit
|
||||
|
||||
- Alle DoD-Proofs, Deploy-/Restore-Run-IDs und Cutover-Zählungen ohne Secrets/PII in
|
||||
dieser Ticket-Doc dokumentieren.
|
||||
- Betroffene Abhängigkeiten erneut lesen, Tests der Konsumenten ausführen und Plane
|
||||
erst bei 10/10 auf Done setzen.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
| # | DoD | Fertigkeitskriterium | Proof | Zählt **nicht** als fertig |
|
||||
|---|---|---|---|---|
|
||||
| 1 | ✅ Native Datenbasis | `AdminLead`, `AdminLeadActivity`, Quellen/Credentials, Operator-RLS und S2S-Capability stehen; Legacy-Mapping ist idempotent | Prisma validate/db-push, Policy-Contract, RLS-Live- und Backfill-Tests | Nur Schema ohne scharfe RLS oder nur ein ORM-Mock |
|
||||
| 2 | ✅ Zentraler Domain-Service | S2S, manuelle Anlage und Import nutzen denselben validierenden Ingestion-Service | Service-Unit-/DB-Integrationstests für alle Ports | Drei getrennte Create-Implementierungen |
|
||||
| 3 | ✅ Allgemeiner S2S-Eingang | `/v1/platform/leads` ist source-authentifiziert, idempotent, rate-limited, dokumentiert und liefert definierte Fehler | OpenAPI-/Route-Inventar-, Auth-, Replay-, Hash-Konflikt-, 413-/429-Tests | Endpoint mit globalem Key, optionaler Idempotenz oder frei wählbarer Source |
|
||||
| 4 | ✅ Admin-Inbox | Liste, Detail, Neu, Status, Assignment, Note, Archiv und Source-Admin sind per VM/Actions, Permissions, Sidebar, Breadcrumbs und i18n erreichbar | Admin-Smoke, Permission-Tests, Screenshot/Interim-Visual | Raw-Prisma-Route, handgeschriebenes Tailwind oder Liste ohne Hauptaktionen |
|
||||
| 5 | ✅ Nachvollziehbarkeit | Jede relevante Mutation erzeugt korrekte Activity + AuditEvent; Capture erzeugt PII-minimiertes Outbox-Event atomar | Transaktions-/Failure-Injection-Tests | Best-effort Logging nach Commit oder PII im Event/Log |
|
||||
| 6 | ⏳ Haris-Routing via M011 | Die aktuelle Website-Quelle weist Haris konfiguriert zu; Plattform-Delivery läuft dedupliziert über M011/Worker mit Retry | Staging-Proof Inbox + Delivery/Retry, Partial-Unique-Test | Hardcodierter Haris, direkter Mailjet-Aufruf oder „201 trotz verlorener Delivery-Aufgabe" |
|
||||
| 7 | ⏳ Producer-Cutover | Die HiveGrid-Website nutzt serverseitig den nativen Vertrag mit stabiler Submission-ID und ohne falschen SQLite-Erfolg | Repo-Tests + Staging-/Prod-Canary | Nur Env gesetzt, Browser enthält Secret oder Fehler wird als Erfolg angezeigt |
|
||||
| 8 | ⏳ Vollständiger Backfill | Alle bekannten Stores sind idempotent importiert; Counts/Hashes/Zeitbereiche stimmen, Replay erzeugt 0 neue Leads | Dry-run/apply/replay-Manifeste + Restore-/Import-Run | Stichprobe, manueller Import ohne Manifest oder Notification-Spam beim Import |
|
||||
| 9 | ⏳ Ein aktives System | Legacy-HiveGrid-Routen/SDK sind migriert/retired; externer Dienst hat 7 Tage Nulltraffic, ist gestoppt, DNS/Secrets entfernt, Backup restorable | Monitoring-Fenster, Coolify/Cloudflare/Gitea-/Restore-Proof | Nur Producer umgestellt, aber Legacy weiter beschreibbar oder DB ungeprüft gelöscht |
|
||||
| 10 | ✅ Qualitätsgates | Typecheck, Lint, Tests, relevante `verify:*`, API/RLS-Live, Admin-Smoke, Hot-Swap und Interim-Visual sind grün; abhängige Tickets bleiben konsistent | Befehle/CI-Run-IDs in Umsetzungsnotiz | Nur Happy-Path-Unit-Test oder grüne lokale Tests bei RLS-off |
|
||||
|
||||
**Fortschritt:** **R-LEADS: 6/10 DoD = 60 % done.** Der lokal selbst machbare
|
||||
Produktcode und die Qualitätsgates sind abgeschlossen. Offen sind vier operative
|
||||
Cutover-Punkte: Staging-Routing/Delivery, Staging- und Produktions-Canaries,
|
||||
Live-Backfill mit Replay sowie das vorgeschriebene Sieben-Tage-Drain-Fenster mit
|
||||
anschließendem Decommission. `VD-P28` ist ein getrackter Design-Nachzug und kein
|
||||
Dev-Blocker.
|
||||
|
||||
## Verifikation vor Commit/Push
|
||||
|
||||
Zusätzlich zur vollständigen `docs/AGENT-CHECKLIST.md` mindestens:
|
||||
|
||||
```bash
|
||||
pnpm typecheck
|
||||
pnpm lint
|
||||
pnpm test
|
||||
pnpm exec prisma validate
|
||||
pnpm run verify:tenant-policy-contract
|
||||
pnpm run verify:sidebar-routes
|
||||
pnpm run verify:i18n
|
||||
pnpm run test:hot-swap
|
||||
pnpm run verify:ui-visual
|
||||
```
|
||||
|
||||
Hinzu kommen gezielte API-, Idempotency-, Source-Key-, Notification-, Import- und
|
||||
RLS-Live-Tests sowie die Cross-Repo-Tests des HiveGrid-Website-Producers. Auf dem
|
||||
Feature-Branch wird nach AD-21 nur `prisma db push` genutzt; die Phase-Migration
|
||||
wird vor dem Merge gegen eine leere DB verifiziert, ist forward-only und enthält
|
||||
Inverse-SQL als Kommentar.
|
||||
|
||||
## Umsetzungs-Notiz
|
||||
|
||||
### 2026-07-16 — Implementierung gestartet
|
||||
|
||||
- Eigener Worktree: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-r-leads`
|
||||
- Branch: `feat/hivegrid-73-native-platform-leads`
|
||||
- Arbeitsreihenfolge: Safety-Inventar/Backups → Datenmodell/Domain-Service → API →
|
||||
Audit/Notifications → Admin-UI → Producer/Backfill → Cutover/Decommission.
|
||||
- Startstand unverändert: **0/10 DoD = 0 % done**.
|
||||
|
||||
### 2026-07-16 — Ticket-Recut und Implementierungsplan
|
||||
|
||||
- HIVEGRID-73 von historischem Website-QA auf M040a umgeschnitten.
|
||||
- Abhängigkeiten in beide Richtungen geprüft: `J-LIVE`, `H-INBOUND`, `AK-P19`,
|
||||
`VR-P28a`, `VA-P28b`, `VD-P28` und M040.
|
||||
- Entscheidung dokumentiert: native operatorweite AdminLead-Welt statt internem
|
||||
Tenant oder Ausbau des separaten Dienstes.
|
||||
- Cross-Repo-Cutover, Datenquellen, Backups, Rollback, 7-Tage-Drain und
|
||||
Decommission vollständig in Slices zerlegt.
|
||||
- Noch kein Produktivcode, Deploy oder Datenbank-Write ausgeführt.
|
||||
|
||||
**Historischer Startstand:** **0/10 = 0 % done.** Selbst machbar offen: 10 Punkte. Extern
|
||||
blockiert: 0. Design-Nachzug offen, aber nach AD-28 nicht Done-blockierend.
|
||||
|
||||
### 2026-07-16 — Lokale Implementierung und Sicherheitsgates abgeschlossen
|
||||
|
||||
- Lokaler HiveGrid-Cloud-Implementierungscommit nach Rebase auf `ec646f7aa`:
|
||||
`ebae6ad93`; Merge-Readiness/Migration: `5f31fa270`; CI-Regressionstest:
|
||||
`bf3133a97`; Producer-Commit: HiveGrid-Website `c81aca1`.
|
||||
- Native Plattformmodelle, Operator-RLS, enge S2S-/Audit-/Notification-
|
||||
Capabilities, zentraler Ingestion-Service, versionierter S2S-Endpoint,
|
||||
Admin-Inbox, M011-Worker-Retry, Backfill-/Source-Bootstrap-Tooling und
|
||||
Legacy-Retirement sind implementiert.
|
||||
- Die HiveGrid-Website sendet serverseitig mit stabiler Submission-ID an den
|
||||
nativen Vertrag. Ihr Deploy-Workflow nutzt immutable Full-SHA-Images,
|
||||
Coolify-Pull-Deploy und einen revisionsgebundenen `/readyz`-Canary.
|
||||
- Safety-Proof vor jeder externen Mutation: verschlüsseltes Offsite-Backup unter
|
||||
`backups/platform-leads/20260716T033754Z`; Restore-Proof für `lead-inbox`
|
||||
Postgres (1 Datensatz) und HiveGrid-Staging-SQLite (1). Produktion-Website und
|
||||
Cloud-Legacy waren leer. Ein irrtümlich inventarisiertes fremdes Backup bleibt
|
||||
unverändert erhalten, ist im Evidence-Objekt ausdrücklich vom HiveGrid-Import
|
||||
ausgeschlossen und benötigt einen separaten Retention-/Löschentscheid.
|
||||
PII-freies Manifest:
|
||||
`docs/ops/evidence/r-leads-safety-inventory-20260716.json`.
|
||||
- Live-RLS-Gate gegen frisches PostgreSQL und den eingeschränkten
|
||||
`hivegrid_app`-Role: `pnpm run verify:platform-leads-rls-live` mit **14/14**
|
||||
Tests grün, einschließlich Atomicity, Rollback und Notification-Eligibility.
|
||||
- Echter Redis-/BullMQ-Retry: `pnpm run verify:platform-notification-redis-live`
|
||||
mit **1/1** Test grün.
|
||||
- Echter Admin-Smoke unter `RLS_RUNTIME_MODE=required`: Login, temporäre MFA,
|
||||
Lead-Anlage, persistiertes Detail, Notiz, Audit-Outbox und A11y, **1/1**
|
||||
Playwright-Test grün. Kein DB-Owner-/RLS-Bypass.
|
||||
- Interim-Pixelsnapshot **1/1**, Hot-Swap **2/2** plus Verifier, i18n-Parität
|
||||
**11.902 Keys**, Sidebar-/Route-Vertrag **32/32**, API-Inventar **20/20** und
|
||||
Backfill-/Bootstrap-Tooling **25/25** grün.
|
||||
- Abschluss-Checkliste auf dem rebasierten Merge-Stand: `pnpm typecheck`, `pnpm lint`
|
||||
und `pnpm test` grün; **875 Testdateien / 5.770 Tests bestanden**, 10 Dateien/54
|
||||
environmentbedingt übersprungen. Coverage-, A11y-, Secret-, Permission-,
|
||||
Notification-, DB-Boundary-, Docker-, Runtime-Closure-, OpenAPI- und
|
||||
Deployment-Gates grün. Web/API/Worker/MCP/Hocuspocus bauen erfolgreich.
|
||||
- Der erste Remote-CI-Lauf deckte einen fehlenden Metrics-Snapshot-Eintrag für
|
||||
den neuen Plattform-Notification-Job auf. Commit `bf3133a97` ergänzt den
|
||||
Regressionstest; `pnpm test:packages` ist anschließend für alle 36 selektierten
|
||||
Workspace-Pakete grün, darunter **123/123 Queue-Tests**.
|
||||
- Der TypeScript-SDK wurde aus dem aktuellen OpenAPI-Vertrag neu generiert;
|
||||
beide SDK-Typechecks sowie **132/132 SDK-Tests** sind grün. Der nach dem Rebase
|
||||
absichtlich geänderte Legacy-Detail-Redirect und die aktuelle Select-Komponente
|
||||
sind durch Routentest und aktualisierte Interim-Visual-Baseline abgesichert.
|
||||
- Producer-Proof: HiveGrid-Website **24/24** Tests, TypeScript, Next-Build,
|
||||
Docker und revisionsgenaues `/readyz` grün. Producer-Commit:
|
||||
HiveGrid-Website `c81aca1`. Kein Deploy ausgeführt.
|
||||
- Die gemeinsame Forward-only-Migration liegt unter
|
||||
`prisma/migrations/20260716120000_r_leads_native_platform_leads/migration.sql`,
|
||||
enthält Inverse-SQL und ist mit `pnpm run verify:migrations-parity` aus leerer
|
||||
Datenbank sowie mit `prisma validate` grün verifiziert.
|
||||
|
||||
**%-DoD-Stand:** **6/10 = 60 % done.** Offen: vier Punkte, davon vier
|
||||
operativ/external-state-gebunden und **0 lokal im Ticket-Code selbst machbar**.
|
||||
Kein Staging-/Produktions-Deploy, kein Live-Backfill und kein Decommission wurden
|
||||
vorgetäuscht oder ausgeführt. Ticket bleibt in Arbeit und Plane darf noch nicht
|
||||
auf Done gesetzt werden.
|
||||
|
||||
### 2026-07-16 — Website-Scope korrigiert
|
||||
|
||||
- Eine irrtümlich einbezogene fremde Website wurde aus initialen Quellen,
|
||||
Producer-Cutover, Legacy-Stores, CSV-Backfill und den zugehörigen Tests entfernt.
|
||||
- Die generische Multi-Source-API, das Source-/Credential-Schema und die
|
||||
Admin-Quellenverwaltung bleiben unverändert und erlauben weiterhin beliebige
|
||||
explizit freigeschaltete Websites und Partner.
|
||||
- `H-INBOUND`, `VA-P28b`, `VR-P28a` und `VD-P28` wurden in beide Richtungen erneut
|
||||
geprüft. Sie konsumieren nur den generischen AdminLead-/Website-Vertrag; der
|
||||
Cleanup ändert weder ihre Contracts noch ihre Termine.
|
||||
- Das bereits angelegte verschlüsselte Objekt wurde nicht gelöscht. Das
|
||||
Evidence-Inventar markiert es als `excluded_from_hivegrid_import: true`; Aufbewahrung
|
||||
oder Löschung erfordern eine separate, ausdrücklich autorisierte Entscheidung.
|
||||
- Cleanup-Proof: `pnpm typecheck`, `pnpm lint`, `pnpm test` (**877** Testdateien /
|
||||
**5.780** Tests grün), fokussierte API-/DB-/VM-/Backfill-/Bootstrap-Tests
|
||||
**72/72** sowie Coverage-, RLS-Policy-, Sidebar-, i18n-, Hot-Swap-, Visual-,
|
||||
CI-Baseline-, Source-Health- und Docs-Link-Gates grün.
|
||||
|
||||
**%-DoD-Stand unverändert:** **6/10 = 60 % done.** Offen bleiben die vier operativen
|
||||
Cutover-Punkte; das Ticket bleibt in Arbeit.
|
||||
|
||||
### 2026-07-24 — VA-P28b-Consumer-Vertrag erweitert
|
||||
|
||||
- `VA-P28b` ergänzt den bestehenden `AdminLead` additiv um Qualification-, Duplicate- und
|
||||
Conversion-Relationen. Die Inbox-, Ingestion-, Source-, Attribution- und Idempotenzverträge aus
|
||||
R-LEADS bleiben unverändert; es gibt weiterhin genau eine Plattform-Lead-Tabelle.
|
||||
- Der bestehende Detail-DTO liefert zusätzlich Score/Enrichment, offene Dubletten und die
|
||||
idempotenten Conversion-IDs. Alte Listen-, Intake- und Source-Konsumenten behalten ihre bisherigen
|
||||
Felder und Semantik.
|
||||
- Die neuen Child-Tabellen sind tenant-los, an den aktiven Admin gebunden und vollständig im
|
||||
Plattform-RLS-Vertrag klassifiziert. Der R-LEADS-Visual-Fixture- und Route-Regressionstest wurden
|
||||
auf den additiven DTO-Vertrag nachgezogen.
|
||||
- Proof im VA-P28b-Slice: vollständiger Typecheck und Lint, **323/323** RLS-Verträge,
|
||||
**321/321** Modellklassifikationen, dedizierter RLS-Test **3/3**, relevante
|
||||
Lead-/Route-/VM-/Visual-Tests grün sowie vollständiger Repository-Testlauf.
|
||||
|
||||
**%-DoD-Stand unverändert:** **6/10 = 60 % done.** Die vier offenen Punkte bleiben
|
||||
ausschließlich operative Cutover-Gates; VA-P28b verändert weder Backfill noch Drain oder Decommission.
|
||||
|
||||
## Dev-Nachzug (nach Davids `VD-P28`-Delta)
|
||||
|
||||
**Interim-UI (Vorschau, Stand 2026-07-16):** Liste, manuelle Anlage, Detail und
|
||||
Quellenverwaltung sind aus `~/ui` unter
|
||||
`apps/web/app/components/screens/admin/leads/` gebaut; alle Routen injizieren
|
||||
serverseitig erzeugte View-Models und Actions. Proof: echter Admin-Smoke
|
||||
`tests/e2e/platform-leads.smoke.spec.ts`, Hot-Swap-Drill grün und als Interim
|
||||
markierte Pixel-Baseline
|
||||
`tests/component/__screenshots__/r-leads-platform-lead-inbox.png`.
|
||||
|
||||
Refactor-Nachzug offen: finale Subframe-Optik aus `VD-P28`; danach werden die
|
||||
Screen-Internals hinter dem stabilen VM-/Action-Vertrag getauscht, die Visual-
|
||||
Baseline neu gezogen und `design-nachzug` in dieser Doc sowie in Plane erledigt.
|
||||
|
||||
## Quellen
|
||||
|
||||
- `AGENTS.md`
|
||||
- `.planning/ENTITY-MODEL.md` — Domäne 11
|
||||
- `.planning/ROADMAP.md` / `.planning/ROADMAP-V2.md` — Phase 28
|
||||
- `docs/ARCHITECTURE-DECISIONS.md` — AD-21, AD-28, AD-31
|
||||
- `.planning/ticket-docs/AK-P19.md`, `VR-P28a.md`, `VA-P28b.md`, `VD-P28.md`,
|
||||
`H-INBOUND.md`, `J-LIVE.md`, `R-P7.md`
|
||||
- `prisma/schema/marketingLeads.prisma`, `prisma/schema/core.prisma`,
|
||||
`prisma/schema/admin.prisma`
|
||||
- `apps/web/app/routes/api.leads.capture.tsx`,
|
||||
`apps/web/app/routes/admin/marketing-leads/**`,
|
||||
`apps/web/public/embed/marketing.js`
|
||||
- `packages/foundation/src/notifications.ts`, `packages/db/src/outbox.ts`,
|
||||
`apps/web/app/services/admin/admin-action-audit.server.ts`
|
||||
|
||||
## Abhängigkeitsnachzug · CR-007 · 2026-07-27
|
||||
|
||||
`platform_admin_leads` wird als Rollout-Gate entfernt. Admin-Inbox und Einstellungen
|
||||
sind standardmäßig aktiv und bleiben durch AdminUser, `admin_sales.*` und Own-/All-RLS
|
||||
fail-closed. `PLATFORM_LEADS_INGRESS_ENABLED` bleibt der separate externe Ingress-Schalter.
|
||||
Reference in new issue
Block a user