189 lines
8.6 KiB
Markdown
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.
|