Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/03-scaling-infrastructure/tenant-snapshot.md
T

25 KiB

Tenant-Snapshot mit PII-Anonymisierung + Restore

Status: completed Task-ID: #44 Phase: 03 Estimated Effort: 1 Woche Owner: unassigned

Problem

Dev/QA/Sales-Teams brauchen regelmäßig „Production-ähnliche" Test-Datasets, aber:

  • Direkter Prod-DB-Dump in Dev = DSGVO-Verstoß (PII, Stripe-IDs, Emails, IPs).
  • Manuelle Anonymisierung ist fehleranfällig (vergessene Felder, inkonsistente Replacement-Patterns, kein Tracking welche Snapshots welches Anonymisierungs-Profile haben).
  • Bug-Reproduction von einem spezifischen Tenant-State ist heute unmöglich — Operator müsste komplette DB ziehen, was wegen DSGVO blockiert.
  • Sales-Demos brauchen realistische Tenants mit Workflows, Subscriptions, Audit-Trail — Synthetic-Data hat nie die Komplexität.
  • QA-Test-Datasets sind hand-kuratierte Fakten-Sammlungen → veralten, decken Edge-Cases nicht ab.

Use-Cases die wir freischalten:

  1. Bug-Repro: „Customer X meldet Bug in Workflow Y" → Snapshot ziehen, in Dev-Env restore, debuggen.
  2. QA-Datasets: monatlich pro Plan-Tier (Free/Pro/Enterprise) ein Snapshot eines repräsentativen Tenants → CI-Test-Fixture.
  3. Sales-Demos: Snapshot eines „idealen" Production-Tenants → in Demo-Env restore → realistisches Show-and-Tell.
  4. Tenant-Migration: Tenant zu separater Instance umziehen (z.B. Enterprise-Tenant auf dediziertem Server).

Betroffene Codestellen:

  • Prisma-Schema: alle Models mit tenantId-Spalte (User, Row, Entity, Workflow, Subscription, AuditLog, etc.) — Subagent enumeriert alle in Research-Phase.
  • Storage-Layout: tenants/<tenantId>/... Convention.

Depends on

  • 03-scaling-infrastructure/backup-cli.md — Tenant-Snapshot baut auf der gleichen CLI-Infrastruktur (Citty-Commands, Encryption-Layer, S3-Sink, Manifest-Schema-Pattern). Reuse statt Parallelentwicklung.
  • 01-tech-debt-foundation/supabase-removal.md — Saubere einheitliche Storage-Abstraktion damit Tenant-Files konsistent iterierbar sind.
  • 03-scaling-infrastructure/shared-store-package.md — Tenant-Plan-Info-Lookup im Anonymisierungs-Profile (verschiedene Anonymisierungs-Strenge je Plan möglich, z.B. Enterprise-Tenants wollen vielleicht „weniger" anonymisiert für Sales-Repros).

Blocks

  • 08-mobile-cli-storybook-sdk/cli-ops.md — CLI-Ops-Package bündelt Tenant-Snapshot als weiteres Sub-Tool.
  • 10-compliance-polish/dsgvo-bulk-ops.md — DSGVO-Datenexport pro User profitiert vom gleichen Selector-Pattern (tenantId + userId-Filter).

Approach

CLI-Command tenant:snapshot und tenant:restore im selben packages/cli/-Package wie Backup, separater Command-Tree.

Anonymisierungs-Profile (deklarativ):

  • profile=full-anonymized (Default für Snapshots) — alle PII ersetzt, deterministisch (gleicher Input → gleicher Output für Foreign-Key-Konsistenz).
  • profile=minimal-anonymized — nur Felder die DSGVO-strikt sind (Email, Phone, Address, IP, Stripe-IDs); FirstName/LastName bleiben.
  • profile=none — KEINE Anonymisierung. Nur durch Operator mit Super-Admin-Recht erlaubt, hard-gated, separater Audit-Eintrag.

Anonymisierungs-Mapping (profile=full-anonymized):

Feld-Typ Mapping
Email user{seq}@anonymized.test — deterministisch via SHA256(originalEmail)[:8]
FirstName faker.person.firstName(seed=hashedId)
LastName faker.person.lastName(seed=hashedId)
Phone null
Address (Street/City/Country) faker.location.*(seed=hashedId)
ZipCode erste 2 Ziffern behalten + Rest random (Postleitzahl-Bereich)
IPAddress 127.0.0.{seq % 255}
Stripe-CustomerID cus_anon{seq}
Stripe-SubscriptionID sub_anon{seq}
Stripe-PaymentMethodID pm_anon{seq}
API-Keys / Secrets (in Settings-JSON) [REDACTED]
Webhook-URLs (custom) https://anonymized.test/webhook/{seq}
User-Avatar-URLs https://anonymized.test/avatar/{seq}.png (Storage-Objects werden trotzdem mitexportiert aber Public-Hosts darin rewritten)

Konsistenz-Hash: Pro Snapshot wird ein Salt generiert, alle Anonymisierungen nutzen hash(salt + originalValue) als Seed. → Innerhalb eines Snapshots ist Anonymisierung deterministisch (User Alice referenziert in Workflow X = User Alice referenziert in Workflow Y), aber zwischen Snapshots verschieden (kein Cross-Snapshot-Reverse-Engineering).

Snapshot-Format: Gleiche Struktur wie Backup, aber tenant-scoped.

toolctrl-snapshot-<tenant-slug>-<iso8601>-<short-uuid>.tar.gz
├── manifest.json              # Tenant-ID, Source-Slug, Schema-Version, Anonymization-Profile, Anonymization-Salt-Hash, ExportDate, CreatedBy
├── prisma/
│   └── data.jsonl             # NDJSON: { model: 'User', data: {...} } — pro Row eine Zeile
├── storage/
│   ├── manifest.jsonl         # { originalKey, newKey, size, etag }
│   └── objects.tar
└── audit/
    └── snapshot-event.json    # Audit-Trail-Entry für diesen Snapshot (im Source-System)

Restore-Logik:

  • tenant:restore <snapshot> --target-tenant-slug=<new-slug> legt neuen Tenant in Target-DB an (oder failt wenn slug existiert ohne --force).
  • Rewrited alle FK-Beziehungen (Snapshot-Tenant-ID → Neu-Tenant-ID), generiert neue IDs für alle Rows (UUID-Remapping-Table im Memory).
  • Storage-Objects landen unter tenants/<new-tenant-id>/... in der lokal-konfigurierten Storage.
  • Sanity-Check am Ende: alle FKs valid, keine dangling references.

Permission-Model:

  • Source-System (Snapshot-Export): nur Super-Admin (Plattform-Owner). Tenant-Admin darf NICHT seinen eigenen Tenant snapshotten — könnte Daten anderer User des Tenants exfiltrieren in unverschlüsselter Form. Mitigation: User-DSGVO-Export ist separater Pfad (Task 10-compliance/dsgvo-bulk-ops.md).
  • Target-System (Restore): jeder Operator des Ziel-Systems (Dev-Box etc.). Kein hardes Gate, weil Snapshot-File ist die Berechtigung.
  • Audit-Log-Eintrag pro Snapshot im Source-System (Actor, TenantID, Profile, Timestamp).

Begründung gegen Alternativen:

  • Anonymisierung in einem separaten Post-Processing-Step (Snapshot raw, dann anonymize): doppelter Speicher, Risiko dass raw Snapshot „vergessen" wird. Lieber inline.
  • DB-Trigger-basierte Anonymisierung in einer separaten Anonymized-Replica: zu viel Infra-Aufwand für Toolctrl-Boilerplate-Größe.
  • Library wie pg_anonymize: nicht TS-nativ, kein Storage-Backup, kein Foreign-Key-Awareness wie wir es brauchen.

Implementation Steps

  1. Tenant-Model-Enumeration — alle Tenant-scoped Models entdecken

    • Files: packages/cli/src/commands/tenant/models.ts (neu) — exportiert TENANT_SCOPED_MODELS: Array<{ model: string; tenantField: string }>. Enthält explizite Liste (User, Row, Entity, Workflow, Subscription, AuditLog, ApiKey, EmailMarketingCampaign, etc.). Subagent recherchiert Prisma-Schema und liefert vollständige Liste.
    • Tests: models.test.ts — assert dass jede Prisma-Model-Klasse mit tenantId-Spalte in der Liste ist (introspection via Prisma._dmmf).
    • Commit: 03-scaling/tenant-snapshot: enumerate tenant-scoped models
  2. Anonymizer-Engine — Profile-basierte Field-Transformations

    • Files:
      • packages/cli/src/commands/tenant/anonymizer.ts — Klasse Anonymizer({ profile, salt }). Methode transform(model, row) returnt anonymisiertes Row-Object. Lookup-Table pro Model: welche Felder welche Transform-Funktion (Email-Anonymizer, Faker-Person-Name, IP-Mask, etc.).
      • packages/cli/src/commands/tenant/profiles.ts — die 3 Profile als Konfiguration.
      • Faker-Seed-Mechanismus: faker.seed(parseInt(hash(salt + rowId), 16) % MAX_INT).
    • Tests: anonymizer.test.ts — pro Profile pro Feld-Typ ein Test; Determinismus-Test (gleicher salt + input → gleicher output).
    • Commit: 03-scaling/tenant-snapshot: anonymizer engine with 3 profiles
  3. Data-Extractor — Prisma-Query pro Model filtered by tenantId

    • Files: packages/cli/src/commands/tenant/extractor.ts — extractTenantData(prisma, tenantId, anonymizer) async iterator yieldet { model, data } Objects. Nutzt Cursor-basiertes Paging (1000er-Chunks) damit large Tenants nicht den Speicher sprengen. Foreign-Key-Order-aware: User vor Row, Row vor RowSetting, etc. (Topological-Sort der Models).
    • Tests: extractor.test.ts — Test-Tenant in testcontainers-Postgres, assert dass alle Models extrahiert werden, anonymisiert, in richtiger FK-Order.
    • Commit: 03-scaling/tenant-snapshot: cursor-based data extractor
  4. Storage-Extractor — Tenant-Files aus S3 holen, ggf. anonymized rewrites

    • Files: packages/cli/src/commands/tenant/storage-extractor.ts — listet alle Objects mit Prefix tenants/<tenantId>/, download streamt in tar, schreibt manifest.jsonl mit { originalKey, newKey, size, etag }. newKey ist tenants/SNAPSHOT_TENANT_ID/... mit Platzhalter, der beim Restore ersetzt wird.
    • Tests: storage-extractor.test.ts — gegen MinIO mit 50 Test-Files unter tenants/abc/..., assert alle drin.
    • Commit: 03-scaling/tenant-snapshot: storage extractor for tenant files
  5. tenant:snapshot-Command — Glue

    • Files: packages/cli/src/commands/tenant/snapshot.ts — Citty-Command.
      • Args: <tenantId>, --target=<output-file> (default ./toolctrl-snapshot-<tenant-slug>-<ts>.tar.gz), --profile=full-anonymized|minimal-anonymized|none, --include-storage (default true), --encrypt=age|none
      • Flow:
        1. Permission-Check: SUPER_ADMIN_API_KEY env-set, prompt for confirmation if profile=none.
        2. Generate Salt.
        3. Iterate extractTenantData → schreibe prisma/data.jsonl (im tempdir).
        4. Storage-Extract → storage/.
        5. Manifest erzeugen (inkl. Salt-Hash, nicht Salt selbst).
        6. tar.gz.
        7. Encrypt (optional).
        8. AuditLog-Entry im Source-System (separater Prisma-Write).
    • Tests: snapshot.integration.test.ts — gegen testcontainers, assert Output-Datei existiert + parsbar + Anonymisierung wirksam (Sample-Check: kein Email-Pattern *@*.com außer *@anonymized.test).
    • Commit: 03-scaling/tenant-snapshot: tenant:snapshot command
  6. Restorer + FK-Remapper — Snapshot in Target-DB einspielen

    • Files: packages/cli/src/commands/tenant/restorer.ts — restoreTenantSnapshot(prisma, snapshotPath, { targetSlug }). Flow:
      1. Untar.
      2. Neuer Tenant-Row erstellen (slug aus --target-tenant-slug).
      3. ID-Mapping-Table: Map<oldId, newId> pro Model (alle Primary-Keys neu generieren).
      4. Iterate NDJSON, FK-Felder via Mapping ersetzen, Insert.
      5. Storage-Objects: Tar entpacken, jeden Key tenants/SNAPSHOT_TENANT_ID/... → tenants/<new-tenant-id>/... umbenennen, upload.
      6. Sanity-Check: Foreign-Key-Integrity (SELECT COUNT(*) FROM Row WHERE tenantId NOT IN (SELECT id FROM Tenant) muss 0 sein, etc. pro Model).
    • Tests: restorer.test.ts — Full-Cycle: snapshot eines Tenants → restore in zweiter DB → assert Row-Counts matchen + Sample-File downloadbar.
    • Commit: 03-scaling/tenant-snapshot: restorer with fk remapping
  7. tenant:restore-Command — CLI-Wrapper für Restorer

    • Files: packages/cli/src/commands/tenant/restore.ts — Citty-Command. Args: <snapshot-file>, --target-tenant-slug=<slug>, --target-db=<connStr> (default aus Env), --force (existing slug erlaubt).
    • Confirmation-Prompt (außer --yes).
    • Commit: 03-scaling/tenant-snapshot: tenant:restore command
  8. Audit-Log-Hook — Im Source-System loggen

    • Files: packages/cli/src/commands/tenant/audit.ts — logSnapshotEvent(prisma, { tenantId, actorUserId, profile, snapshotKey }) schreibt AuditLog-Entry mit Event TENANT_SNAPSHOT_CREATED. Permission-Check: nur Super-Admin-API-Key darf Snapshot triggern.
    • Tests: audit.test.ts — assert Entry geschrieben.
    • Commit: 03-scaling/tenant-snapshot: audit log entry for snapshot ops
  9. Doku — docs/operations/tenant-snapshot.md

    • Files: neu. Inhalt:
      • Use-Cases (Bug-Repro, QA, Sales-Demos, Migration)
      • Anonymisierungs-Profile + Mapping-Tabelle
      • Permission-Model (Source vs Target)
      • CLI-Beispiele für alle 3 Use-Cases
      • Restore-in-Dev-Workflow (mit lokal Setup)
      • Sicherheitswarnung für profile=none
      • Troubleshooting (FK-Errors beim Restore, Storage-Bucket-Mismatch)
    • Commit: 03-scaling/tenant-snapshot: operations doc
  10. Lint-Rule für PII-Fields — Optional aber empfohlen

    • Files: packages/cli/src/commands/tenant/lint.ts (oder als Test) — ESLint-Custom-Rule oder Vitest-Test der das Prisma-Schema scant und sicherstellt, dass alle Felder mit @map("email"), @map("phone"), etc. im Anonymizer-Mapping abgedeckt sind. Verhindert vergessene PII-Felder bei Schema-Erweiterungen.
    • Tests: lint.test.ts — synthetisches Schema mit „vergessenem" PII-Feld → Lint failed.
    • Commit: 03-scaling/tenant-snapshot: schema lint for pii field coverage

Test Requirements

  • Unit-Tests:
    • anonymizer.test.ts — pro Profile pro Feld-Typ; Determinismus-Test.
    • models.test.ts — vollständige Tenant-Model-Coverage gegen Prisma-DMMF.
    • extractor.test.ts — Cursor-Paging, FK-Order.
    • restorer.test.ts — FK-Remapping, Sanity-Checks.
    • audit.test.ts — Permission-Gate funktioniert.
  • Integration-Tests:
    • packages/cli/test/integration/tenant-snapshot-cycle.test.ts — End-to-End: 2-Tenant-Test-DB → snapshot Tenant A → restore in zweite DB als Slug tenant-a-clone → assert:
      • alle Tenant-A-Rows da (Counts identisch)
      • alle Anonymisierungen angewendet (Sample-Emails matchen *@anonymized.test)
      • alle FKs valid
      • Storage-Objects unter neuem Tenant-Prefix
      • Audit-Eintrag im Source-System
  • E2E: kein UI → kein Playwright.
  • Coverage-Target: ≥ 85% für packages/cli/src/commands/tenant/.
  • Test-Files: wie aufgelistet.

NICHT als completed markieren bevor alle Tests grün sind. Daten-Anonymisierungs-Bugs sind DSGVO-Risiken.

Acceptance Criteria

  • tenant:snapshot und tenant:restore CLI-Commands implementiert
  • 3 Anonymisierungs-Profile (full/minimal/none) wählbar
  • Anonymisierung deterministisch (Salt-basiert) → FK-Konsistenz innerhalb Snapshot
  • Snapshot enthält Manifest mit Anonymisierungs-Profile-Hinweis
  • Storage-Objects mitexportiert und beim Restore unter neuem Tenant-Prefix landen
  • FK-Remapping beim Restore funktioniert (Sanity-Check grün)
  • Permission: Snapshot nur mit Super-Admin-API-Key
  • Audit-Log-Entry pro Snapshot im Source-System
  • PII-Coverage-Lint sichert alle bekannten PII-Felder
  • docs/operations/tenant-snapshot.md enthält alle 4 Use-Cases
  • Tests grün (lint, typecheck, unit, integration)
  • Staging-Verifikation: snapshot real-Tenant → restore in Dev-Box → manueller Smoke-Test in Dev-UI
  • Detail-MD Progress Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

  • Code-Rollback: Eigenes CLI-Package, kein Production-Impact. Commits revertieren.
  • Existierende Snapshots: bleiben gültig (versioniert via Manifest-Schema-Version). Restore-Pfad muss alte Schema-Versionen weiterhin lesen können → Migration-Logic in restorer.ts falls Schema sich ändert.
  • Audit-Log-Entries: bleiben bestehen (read-only by design).

Security Notes

  • PII-Vollständigkeit: Höchstes Risiko. Wenn ein PII-Feld in der Anonymizer-Map vergessen wird, leakt es im Snapshot. Mitigation:
    • PII-Coverage-Lint (Step 10).
    • Code-Review mit Security-Track-Subagent.
    • Stichproben-Test: Snapshot eines Test-Tenants generieren, grep -E "[\\w.]+@[\\w.]+\\.[a-z]+" snapshot.tar.gz (nach Decompression) sollte nur @anonymized.test-Matches finden.
  • profile=none Missbrauch: Hard-gated via Confirmation-Prompt + Audit-Log + Super-Admin-Permission. Doku enthält explizite Warnung dass das DSGVO-Verletzung sein kann wenn unverschlüsselt geteilt.
  • Salt-Speicherung: Nur Salt-Hash im Manifest (für Reproduzierbarkeits-Check), nicht Salt selbst. Salt wird verworfen nach Snapshot-Erstellung — keine Reverse-Engineerable.
  • Snapshot-File-Distribution: Snapshots sind selbst sensitiv (auch anonymisiert: Geschäftsdaten, Workflows). Encryption-by-Default (age) empfohlen. Doku weist darauf hin.
  • Restore-in-Production-Schutz: tenant:restore checkt process.env.NODE_ENV !== 'production' ODER explizites --allow-production-restore-Flag (gefährliche Operation). Standard: Production-Restore failed mit klarer Error-Message.
  • Stripe-IDs: Müssen ersetzt werden, sonst könnte ein Dev-Tenant-Restore versehentlich gegen die echte Stripe-API operieren. Im Mapping abgedeckt.
  • Webhook-URLs: Wenn ein Tenant einen Custom-Webhook bei Drittsystem registriert hat (https://customer-x.com/webhook), und der Restore-Tenant feuert das ab → Drittsystem bekommt Test-Daten. Mapping ersetzt durch anonymized.test-URL → kein Outgoing.

Subagent Recommendations

  • Planning: Plan-Subagent mit Detail-MD; recherchiert ob packages/cli/ schon existiert (aus backup-cli.md-Task) für Code-Reuse.
  • Research: Explore-Subagent enumeriert vollständig alle Tenant-scoped Models aus Prisma-Schema und alle PII-Felder. Output → models.ts und anonymizer.ts Profile-Definition.
  • Implementation: general-purpose-Subagent pro Step. Step 2 (Anonymizer) und Step 6 (Restorer) sind die kritischsten — eigene Subagents mit besonderer Sorgfalt.
  • Tests: separater general-purpose-Subagent, Schwerpunkt auf Determinismus-Tests und FK-Sanity-Checks.
  • Verification: gsd-verifier-Subagent + zusätzlich gsd-security-reviewer (falls existent) auf den Anonymizer für PII-Coverage.
  • Code-Review: gsd-code-reviewer mit Fokus auf Daten-Leak-Pfade.

Staging-Deployment-Steps

  1. Branch agent/03-tenant-snapshot pushen.
  2. Coolify-Auto-Deploy auf Staging.
  3. Setup: Staging-Tenant mit realistischem Test-Dataset (mind. 100 Users, 500 Rows, 10 Workflows, 50 Storage-Files).
  4. Smoke-Tests:
    # Snapshot
    ssh staging-host "docker compose run --rm cli toolctrl-cli tenant:snapshot \
      <tenant-id> \
      --target=/snapshots/tenant-acme-test.tar.gz \
      --profile=full-anonymized \
      --include-storage \
      --encrypt=age"
    
    # Download lokal
    scp staging-host:/snapshots/tenant-acme-test.tar.gz ~/
    
    # PII-Stichprobe
    age -d -i ~/.age-key.txt ~/tenant-acme-test.tar.gz | tar -xzO prisma/data.jsonl | grep -E "@" | head
    # → erwartet: nur @anonymized.test, keine echten Emails
    
    # Restore in lokale Dev-DB
    pnpm tsx packages/cli/bin/toolctrl-cli tenant:restore \
      ~/tenant-acme-test.tar.gz \
      --target-tenant-slug=acme-restored \
      --target-db=postgres://dev:dev@localhost:5432/devdb
    
  5. Manueller Smoke-Test in lokaler Dev-UI: Login als restorierte User, Workflows ansehen, Subscription-State plausibel.
  6. Permission-Test: ohne SUPER_ADMIN_API_KEY → Command failed mit klarer Message.
  7. Audit-Eintrag in Source-DB prüfen.

Deviations from Plan

  • No external faker dep. Spec mentioned @faker-js/faker. Implementation uses a small curated word-pool seeded by sha256(salt + value) to keep the CLI free of an additional 500 KB dependency and to make every anonymizer output 100% deterministic. The mapping in the runbook lists every field-type and its strategy.
  • Audit log is file/stdout, not a Prisma write. The CLI deliberately does not depend on @prisma/client (mirroring the backup-cli approach). The audit module emits a structured JSON line that operators redirect into their audit pipeline. Future work can replace this with a DB write when the CLI adopts a runtime Prisma adapter.
  • Prisma is dependency-injected. Snapshot and restore expose a PrismaRunner / PrismaRestoreRunner interface; production consumers wire up the real client in bin/toolctrl-cli.mjs. This avoids a hard Prisma dep in the CLI package and makes unit tests trivial.
  • FK remapping is tenantId-only. None of the tenant-scoped models reference other tenant-scoped rows by id in a way that would survive a snapshot — everything roots at tenantId. Row primary keys are kept as the source emitted them.

Progress Log

  • 2026-05-25 (Task G — globaler-Row-Extractor, schließt B7-Design-Limit):

    • Commit 1 (e9fe18fc) — models.ts::GLOBAL_REFERENCED_MODELS + PLATFORM_CATALOG_GLOBALS enumerieren jede User-Referenz aus tenant-scoped Models (38 FK-Spalten in 31 Source-Models) und kategorisieren die übrigen Schema-Globals (Entity/EntityGroup/Formula/Onboarding/PromptFlow/RowComment/WorkflowBlock) als deployment-baseline. models.test.ts parsed jedes prisma/schema/*.prisma und scheitert wenn eine neue FK-Relation eingebaut wird die in keiner der beiden Listen steht — verhindert stille Regressionen.
    • Commit 2 (6e0aafa3) — globals-runner.ts::collectAndWriteGlobals(): streamed jede tenant-JSONL, sammelt FK-IDs pro Global, chunked findManyByIds (default 500), Anonymizer (gleicher Salt wie tenant-Slice), schreibt globals/<Model>.jsonl. Manifest-Schema um optionales globals: TenantManifestGlobalsEntry[] erweitert (backward-compat: alte Snapshots haben kein globals und werden weiter akzeptiert). PrismaRunner extends Partial<GlobalsPrismaRunner> mit findManyByIds(model, ids); createPrismaSnapshotRunner implementiert es. CLI-Flag --include-globals=true|false (default true). Anonymizer-Coverage für User: email/firstName/lastName/phone/avatar scrubbed; passwordHash, verifyToken, githubId, googleId, totpSecretEncrypted, totpPendingSecretEncrypted, mfaRecoveryCodeHashes, deletionRequestId nullified. 6 globals-runner-Tests + 3 snapshot-Tests + 2 manifest-Tests + 4 anonymize-Tests.
    • Commit 3 (a4cdf6ef) — Restore replayed globals VOR tenant-scoped slice. Drei Modi:
      • upsert (default): findUnique + create-loop, idempotent, gibt {created, updated} zurück
      • skip: createMany({skipDuplicates:true}), legacy-runner-kompatibel
      • error: aborts wenn updated > 0 (sensitiver Restore in known-empty DB) PrismaRestoreRunner.upsertManyById? optional; legacy-fakes fallen automatisch auf skip-Semantik zurück mit warn. CLI-Flag --globals=upsert|skip|error. RunRestoreResult.globals[] mit per-model created/existed/expected counters. 5 restore-Tests + 4 prisma-runner-Tests.
    • Commit 4 (27cad89d) — round-trip.integration.test.ts neuer dritter Case: seedet je 1 Row in den 6 zuvor-broken Models (TenantUser, TenantIpAddress, UserRole, Event, Log, SupportTicket) + 2 referenzierte User auf Source. Target hat den Target-Tenant aber KEINE referenzierten User (verified via target.user.count() === 0 pre-check). Round-Trip führt Globals-Replay zuerst aus, dann tenant-scoped Models — alle 6 reportet written === expected > 0, jeder restored TenantUser-FK resolved gegen target.user.findUnique. Live verifiziert gegen zwei frische pgvector/pgvector:pg16 Container (Ports 55801/55802) mit allen 138 Migrationen: 365/365 Tests grün.
    • Commit 5 (<docs>) — Runbook entschärft: ## Restore prerequisites: global rows are NOT in the snapshot → ## How globals are handled in restore mit 3-Modi-Tabelle, platform-catalog-Erklärung, Backward-Compat-Note, Anonymization-Block. Troubleshooting um 2 neue Symptome erweitert.
  • Coverage: Nur User ist heute in GLOBAL_REFERENCED_MODELS. Andere FK-Targets (Entity/Formula/EntityGroup/Onboarding/PromptFlow/RowComment/WorkflowBlock) sind als platform-catalog markiert und bleiben deployment-baseline; per-tenant-Kopie wäre semantisch falsch. Der Test scheitert wenn jemand eine neue tenant-scoped FK in irgendeine andere globale Tabelle einbaut → forciert bewusste Entscheidung.

  • Live-Verifikation: durchgeführt via TENANT_TEST_DATABASE_URL + TENANT_TEST_TARGET_DATABASE_URL gegen Docker-pgvector-DBs. Alle 365 Tests inkl. der 3 round-trip-Cases grün. Container nach Lauf gestoppt.

  • 2026-05-17 (agent/03-tenant-snapshot):

    • Commit 1 — scaffolded tenant command group under packages/cli (registered in src/index.ts).
    • Commit 2 — enumerated 54 tenant-scoped Prisma models (models.ts); Vitest parses every prisma/schema/*.prisma to enforce coverage.
    • Commit 3 — 3 anonymization profiles (full-anonymized / minimal-anonymized / none) plus deterministic salt-seeded engine (anonymize.ts); 21 unit tests cover all strategies + determinism + FK consistency.
    • Commit 4 — zod manifest schema (manifest.ts); 10 tests.
    • Commit 5 — tenant:snapshot (runTenantSnapshot() in snapshot.ts) — Prisma streaming + inline anonymization + storage object download + tar.gz + optional age/gpg encryption + multipart S3 upload. Reuses backup/encryption.ts and backup/s3-upload.ts. 9 tests with mocked Prisma + aws-sdk-client-mock.
    • Commit 6 — tenant:restore (runTenantRestore() in restore.ts) — download/decrypt/untar/replay-with-new-tenantId/storage-reupload, NODE_ENV=production guardrail, --yes skip-prompt. 3 tests including full round-trip.
    • Commit 7 — tenant:list-snapshots (list-snapshots.ts); 7 tests.
    • Commit 8 — super-admin guardrail (audit.ts); hard-rejects --profile=none without --i-am-the-super-admin; emits structured TENANT_SNAPSHOT_CREATED audit record. 7 tests.
    • Commit 9 — operator runbook (docs/ops/tenant-snapshot.md); 4 use cases, profile-selection table, DSGVO notes, restore drill, troubleshooting.
    • Commit 10 — this entry + PROGRESS.md row #44 → completed.
  • Final gates: pnpm typecheck ✅, pnpm test src ✅ (107 cli tests after commit 10), pnpm lint --max-warnings=0 ✅ on the root.

  • Staging-Verifikation pending operator per the ## Staging-Deployment-Steps recipe (snapshot real tenant → restore in dev → smoke).

Lessons Learned

(Optional am Task-Ende.)