Files

189 lines
8.6 KiB
Markdown

# Plattform-Leads: Backup, Backfill und Cutover
Dieses Runbook ist der operative Vertrag fuer `R-LEADS` (`HIVEGRID-73`). Es
ersetzt den separaten `lead-inbox`-Schreibpfad kontrolliert durch
`POST /v1/platform/leads`, ohne die letzte restorable Kopie der Altdaten zu
loeschen.
## Sicherheitsregeln
- Kein Producer-Deploy ohne unmittelbar davor wiederholte Inventur und Sicherung
seines tatsaechlich beschriebenen Fallback-Stores.
- Backups enthalten PII und werden deshalb nie unverschluesselt im Repo, in
Tickets, Logs oder Import-Manifests abgelegt.
- Der verschluesselte Offsite-Stand liegt im privaten Hetzner-Bucket
`hivegrid-prod`; Objektpraefixe und Hashes duerfen als PII-freier Proof
dokumentiert werden.
- Import-Manifests enthalten nur Quelle, Zaehler, Zeitbereich, Hashes und
technische Run-IDs.
- Ein Import erzeugt weder Benachrichtigungen noch Marketing-Automationen.
- Das letzte verschluesselte Backup bleibt erhalten, bis ein eigener
Retention-/Loeschentscheid bestaetigt wurde.
## Erster Safety-Snapshot
Der Snapshot vom 2026-07-16 liegt unter
`backups/platform-leads/20260716T033754Z`. Sein PII-freies Inventar und die
Restore-Ergebnisse stehen in
`docs/ops/evidence/r-leads-safety-inventory-20260716.json`.
Ergebnis:
- `lead-inbox` Postgres: 1 Datensatz, Custom-Dump in frisches Postgres 16
restauriert.
- HiveGrid-Website Produktion: kein SQLite-File im laufenden Container und kein
persistentes Volume; 0 Datensaetze.
- HiveGrid-Website Staging: 1 Datensatz, konsistentes SQLite-Backup,
`integrity_check=ok`.
- HiveGrid-Cloud `Lead`/`LeadEvent`: Produktion 0/0, Staging 0/0.
Zusaetzlich wurde irrtuemlich ein nicht zu HiveGrid gehoerender Website-Dateistore
inventarisiert und verschluesselt gesichert. Das Objekt bleibt zur Vermeidung einer
unautorisierten Datenvernichtung erhalten, ist im Evidence-Inventar jedoch mit
`excluded_from_hivegrid_import: true` markiert und darf weder als Quelle
konfiguriert noch importiert werden. Aufbewahrung oder Loeschung erfordern einen
separaten, ausdruecklich autorisierten Retention-/Loeschentscheid.
## Operator-Tooling
Vor dem Source-Dry-Run muss der Canary `/leads` mit einer aktiven AdminUser-
Identität und der vorgesehenen Sales-Rolle erreichen. Der API-Schalter
`PLATFORM_LEADS_INGRESS_ENABLED` schützt unabhängig davon nur den externen Ingress.
Der Routing-Operator erhaelt vor dem Bootstrap eine Plattformrolle mit mindestens
`admin.leads.read_own` und `admin.leads.write`. Der ausfuehrende Operator braucht
`admin.leads.admin`. Das Bootstrap-Tool prueft aktiven AdminUser und diese
Rechte fail-closed, bevor es einen Plan erzeugt oder Quellen mutiert. Fuer den
Haris-Canary wird zusaetzlich verifiziert: Login auf `admin.hivegrid.de`,
`/leads` erreichbar, zugewiesener synthetischer Lead sichtbar und eine
Status-/Notizmutation erfolgreich.
Die nativen Quellen werden idempotent ueber den AdminLead-Domain-Service
konfiguriert. Haris' Admin-User-ID wird zur Laufzeit uebergeben und ist keine
Code-Konstante. Der Dry-Run erzeugt einen PII-freien Plan-Hash; Apply akzeptiert
nur genau diesen Stand:
```bash
pnpm platform-leads:source-bootstrap -- \
--mode dry-run \
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
--routing-admin-user-id "$HARIS_ADMIN_USER_ID" \
--manifest "$EVIDENCE_DIR/source-bootstrap.dry-run.json"
pnpm platform-leads:source-bootstrap -- \
--mode apply \
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
--routing-admin-user-id "$HARIS_ADMIN_USER_ID" \
--expected-plan-sha256 "$PLAN_SHA256" \
--manifest "$EVIDENCE_DIR/source-bootstrap.apply.json"
```
Die aktuelle Website-Quelle wird aktiviert, Haris wird als Default-Assignee
und mindestens als Notification-Empfaenger konfiguriert. Bereits vorhandene
weitere Empfaenger bleiben erhalten. Die beiden reinen Importquellen bleiben
deaktiviert. Das Bootstrap-Tool stellt bewusst keine Credentials aus; deren
einmalig angezeigter Klartext wird ueber `/leads/sources` erzeugt und direkt in
den jeweiligen Server-Runtime-Secrets hinterlegt.
Der Backfill liest UTF-8-JSONL oder ein JSON-Array. Die feste Zuordnung ist:
| Legacy-Store | Native Source |
|---|---|
| `lead-inbox-postgres` | `lead-inbox-legacy` |
| `hivegrid-website-production-sqlite` | `hivegrid-website` |
| `hivegrid-website-staging-sqlite` | `hivegrid-website` |
| `hivegrid-cloud-legacy` | `hivegrid-legacy-cloud` |
Pro Store wird zuerst ein Dry-Run mit einer neuen Manifest-Datei ausgefuehrt.
Apply und Replay verlangen sowohl dessen exakten Input-Hash als auch die
akzeptierte Zeilenzahl und schreiben bei Drift oder Rejections keine Zeile:
```bash
pnpm platform-leads:backfill -- \
--mode dry-run \
--store "$LEGACY_STORE" \
--input "$RESTORED_EXPORT" \
--manifest "$EVIDENCE_DIR/$LEGACY_STORE.dry-run.json"
pnpm platform-leads:backfill -- \
--mode apply \
--store "$LEGACY_STORE" \
--input "$RESTORED_EXPORT" \
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
--expected-input-sha256 "$INPUT_SHA256" \
--expected-accepted "$ACCEPTED_COUNT" \
--manifest "$EVIDENCE_DIR/$LEGACY_STORE.apply.json"
pnpm platform-leads:backfill -- \
--mode replay \
--store "$LEGACY_STORE" \
--input "$RESTORED_EXPORT" \
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
--expected-input-sha256 "$INPUT_SHA256" \
--expected-accepted "$ACCEPTED_COUNT" \
--manifest "$EVIDENCE_DIR/$LEGACY_STORE.replay.json"
```
Ein erfolgreicher Replay hat `created=0`, `failed=0` und keine Gate-Failures.
Die Manifeste enthalten nur Hashes, Zaehler, technische IDs und Zeitbereiche;
Input-Pfade, Lead-Inhalte und Klartext-Legacy-IDs werden nicht aufgenommen. Jede
Manifest-Datei wird exklusiv mit Modus `0600` angelegt und nicht ueberschrieben.
Importe laufen ausschliesslich ueber `importLead`, bewahren Originalzeitpunkte,
native Legacy-Status und unterstuetzte Activities und loesen weder M011-
Benachrichtigungen noch Automationen aus.
Cloud-Legacy-Status werden verlustarm auf den nativen M040a-Vertrag abgebildet:
`trial` und `customer` werden `qualified`, `churned` wird `disqualified`; der
Originalwert bleibt als `metadata.legacyStatus` erhalten. Historische
`score-changed`- und `converted`-Events werden als `legacy_event` mit
`legacyType` im begrenzten Activity-Payload uebernommen. Unbekannte Status- oder
Eventtypen bleiben Rejections und stoppen Apply. Damit wird keine M040b-
Deal-Semantik vorgezogen, aber der historische Verlauf geht nicht verloren.
## Cutover-Reihenfolge
1. Native Tabellen, RLS/Pre-Tenant-Capability, Domain-Service, API, Worker und
Admin-Inbox nach Staging deployen; Operatorrolle wie oben anlegen und
Berechtigungs- sowie Direkt-Routen gegen 404 pruefen.
2. Source-Credentials einmalig erzeugen und ausschliesslich in den jeweiligen
Server-Runtime-Secrets speichern.
3. Staging-Canary je Source ausfuehren: Create, identischer Replay, Hash-Konflikt,
Auth-Fehler, Rate-Limit, Delivery/Retry und Admin-Bearbeitung.
4. Alle Altquellen dry-run importieren. Zaehler und Hashes gegen das Safety-
Inventar pruefen.
5. Apply und anschliessenden Replay ausfuehren. Der Replay muss `created=0`
liefern.
6. Direkt vor jedem Website-Deploy den jeweiligen aktuellen Store erneut sichern
und nur das Finaldelta importieren.
7. Producer einzeln umstellen; nach jeder Quelle einen synthetisch markierten
Produktions-Canary und den Admin-/Delivery-Nachweis abwarten.
8. Legacy-Endpoint read-only/drain-faehig belassen und mindestens sieben volle
Tage auf eingehenden Traffic, Fehler, Queue-Failures und Source-Lag beobachten.
9. Nur bei Nulltraffic: App stoppen, Secrets revoken, DNS entfernen und Repo
archivieren. Die Datenbank nicht irreversibel loeschen.
## Rollback
Innerhalb des Drain-Fensters werden Producer-Secrets/URLs auf den weiterhin
laufenden Legacy-Endpoint zurueckgestellt. Nach einem bereits erfolgten Stop wird
das letzte bekannte Image gestartet und Postgres aus dem geprueften Custom-Dump
restauriert. Native Importe sind idempotent und loeschen keine Quelle; sie muessen
fuer einen Rollback nicht rueckgaengig gemacht werden.
## Decommission-Gates
Der externe Dienst darf erst gestoppt werden, wenn alle folgenden Nachweise gruen
sind:
- der HiveGrid-Website-Producer produktiv auf dem nativen Endpoint;
- Finaldelta importiert und Replay `created=0`;
- sieben volle Tage kein Legacy-Write-Traffic;
- Native-API-, Admin- und Notification-Monitoring ohne offene kritische Fehler;
- letzter Dump offsite vorhanden und Restore erneut erfolgreich;
- DNS-/Secret-/Mailjet-Abhaengigkeiten inventarisiert und Rollback-Werte sicher
hinterlegt.
DNS-Loeschung, Secret-Revoke und App-Stop werden mit Zeitstempel und externer
Run-ID in der Ticket-Doc dokumentiert. Eine endgueltige Backup- oder DB-Loeschung
ist nicht Teil dieses Tickets.