Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/01-tech-debt-foundation/supabase-removal.md
T

214 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Supabase-Storage entfernen
**Status:** completed — staging DB-audit confirms 0 supabase-provider rows + container is supabase-free
**Task-ID:** #18
**Phase:** 01
**Estimated Effort:** 3-4 Tage inkl. Daten-Migration
**Owner:** claude (opus-4-7)
## Problem
Der Codebase enthält einen Supabase-Storage-Adapter (`packages/storage/src/`) und eine `apps/web/app/utils/integrations/supabaseService.ts`-Bridge, die parallel zum S3-Adapter existiert. Aktueller Stand:
- Supabase wird in Production nicht (mehr) genutzt — alle aktiven Tenants laufen über S3.
- Supabase-Adapter-Code ist im Bundle, erhöht Build-Größe und Test-Last.
- `MediaService` und `EmailAttachment`-Pfade haben Branch-Logic die zwischen S3 und Supabase entscheidet → tote Branch.
- `.env.example` und Doku listen `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` → neue Devs setzen unnötige Keys.
- Wenn irgendein Legacy-Tenant noch Supabase-Buckets nutzt, müssen wir vor Removal migrieren (Bucket → S3-Bucket).
Removal ist Voraussetzung für Phase 03 Asset-CDN-Task (#51) — der setzt voraus, dass nur ein Upload-Backend existiert.
## Depends on
- `01-tech-debt-foundation/dep-updates.md` (#28) — empfohlen vorher, damit AWS-SDK-Versionen aktuell sind bevor wir S3 als alleiniges Backend setzen. Nicht hart blockierend.
- `01-tech-debt-foundation/password-policy.md` (#27) — kein direkter Bezug, aber Reihenfolge-konventionell.
## Blocks
- `01-tech-debt-foundation/av-scanner-layer-1.md` (#16) — AV-Scanner-Hooks werden in den S3-Upload-Pfad eingebaut. Wenn parallel ein Supabase-Pfad existiert, müssen Scanner doppelt eingebaut werden → erst Supabase weg.
- `01-tech-debt-foundation/av-scanner-layer-2.md` (#17) — gleicher Grund.
- Phase 03 Task #51 (Asset-CDN) — CDN-Setup braucht klares Single-Backend.
## Approach
**Voller Removal mit Migrations-Script für Legacy-Tenants.** Wir setzen voraus, dass irgendwo möglicherweise noch Supabase-Buckets in use sind und bauen ein einmal-laufendes Migrations-Script.
Schritte:
1. Tenant-Audit: per Datenbank-Query identifizieren ob `media.storageProvider = 'supabase'` Rows existieren (oder welche Spalte das Provider trackt — Schema-Recherche)
2. Wenn ja: Migrations-Script Supabase-Bucket → S3-Bucket, DB-Rows updaten
3. Adapter-Code löschen
4. Bridge-File löschen
5. Branch-Logic in MediaService/EmailAttachment vereinfachen (nur noch S3)
6. Env-Keys und Doku bereinigen
Alternativen verworfen:
- **Supabase-Adapter weiter mitschleifen "falls jemand will"** — verletzt YAGNI, blockiert weitere Features.
- **Soft-Deprecation mit Warning** — bringt nichts wenn Production-Tenants den Pfad nicht nutzen.
- **Manuelle Bucket-Migration ohne Script** — fehleranfällig bei mehreren Tenants.
## Implementation Steps
1. **Tenant-Audit + Migration-Plan**
- Files: keine (Recherche)
- Aktion:
- DB-Query: `SELECT tenant_id, COUNT(*) FROM media WHERE storage_provider = 'supabase' GROUP BY tenant_id;` (Schema-Recherche: welche Tabelle/Spalte trackt das?)
- Wenn 0 Rows: Migrations-Script entfällt, direkt zu Step 4.
- Wenn >0 Rows: pro Tenant Bucket-Größe ermitteln, Migrations-Window planen, Operator informieren via `ASK-OPERATOR.md` bevor Migration läuft.
- Output: Tenant-Liste in PR-Body
2. **Migrations-Script schreiben** (nur wenn Step 1 Daten findet)
- Files: `scripts/migrate-supabase-to-s3.ts` (neu), zugehöriger Test
- Aktion:
- CLI-Script: liest Supabase-Bucket via supabase-js, lädt Datei runter, lädt zu S3 via @aws-sdk/client-s3 hoch, updated DB-Row `storage_provider = 's3'` und `storage_key = <neuer-key>`.
- Dry-Run-Mode: `--dry-run` zeigt was migriert werden würde ohne Schreiben.
- Per-Tenant-Mode: `--tenant=<id>` für gestaffelte Migration.
- Progress-Logging: pro 100 Files ein Log-Entry mit Throughput.
- Idempotent: bei Re-Run werden bereits migrierte Files erkannt (DB-Provider-Check) und übersprungen.
- Bucket-Cleanup-Mode: `--cleanup` (NUR nach erfolgreicher Migration und manueller Verifikation) löscht alte Supabase-Bucket-Files.
- Commit: `01/supabase: add migration script supabase->s3`
3. **Migrations-Script auf Staging ausführen** (nur wenn Step 1 Daten findet)
- Files: keine
- Aktion: Migrations-Script auf Staging-DB mit `--dry-run` laufen lassen, Output reviewen, dann ohne `--dry-run`. Spot-Check: 5 zufällige Files in S3 abrufen und mit Original aus Supabase-Bucket vergleichen (Hash-Match).
- Commit: kein neuer Commit; Log im Progress-Section
4. **MediaService und EmailAttachment-Branch-Logic vereinfachen**
- Files: `apps/web/app/modules/media/...` (Recherche nötig), `apps/web/app/modules/email/services/attachments...`, alle Stellen mit `if (provider === 'supabase')`
- Aktion: Supabase-Branch entfernen, nur S3-Pfad behalten. `storage_provider`-Spalte kann (a) gelöscht werden via Migration oder (b) bleiben aber wird nur noch mit `'s3'` befüllt. Empfehlung: lassen wo sie ist (kein DB-Migration-Overhead), Default in Code = `'s3'`, Validation lehnt andere Werte ab.
- Commit: `01/supabase: remove provider-branching from media+attachments`
5. **Supabase-Adapter löschen**
- Files: `packages/storage/src/supabase/*` (komplett), Index-File aktualisieren
- Aktion: alle Supabase-spezifischen Files in `packages/storage/src/` löschen. `packages/storage/src/index.ts` exportiert nur noch S3-Adapter und Memory-Adapter (für Tests).
- Commit: `01/supabase: delete supabase storage adapter from packages/storage`
6. **Bridge-File löschen**
- Files: `apps/web/app/utils/integrations/supabaseService.ts`
- Aktion: Datei löschen. `pnpm typecheck` muss grün sein — wenn nicht: noch Caller übrig → adressieren.
- Commit: `01/supabase: delete supabaseService bridge`
7. **`packages/storage`-Package-Dependencies bereinigen**
- Files: `packages/storage/package.json`, `pnpm-lock.yaml`
- Aktion: `@supabase/supabase-js` aus dependencies entfernen. `pnpm install`.
- Commit: `01/supabase: drop @supabase/supabase-js dependency`
8. **Env-Keys + Doku bereinigen**
- Files: `.env.example`, `docs/storage.md` (oder wo immer Storage dokumentiert ist), `docs/deployment.md`
- Aktion: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` raus. Doku-Sections die Supabase erwähnen umschreiben oder löschen.
- Commit: `01/supabase: clean env keys and docs`
9. **Final Typecheck + Test-Run**
- Files: keine
- Aktion: `pnpm lint`, `pnpm typecheck`, `pnpm test` — alle grün.
- Commit: kein neuer
## Test Requirements
- **Unit-Tests:**
- Migrations-Script: dry-run-Mode loggt korrekt ohne Schreiben, idempotent-check, error-Handling bei Network-Failure, Hash-Compare nach Upload
- MediaService: alle Uploads gehen über S3 (kein Branch-Code mehr)
- **Integration-Tests:**
- Upload-Flow End-to-End mit Test-S3-Bucket (LocalStack im CI)
- Email-Attachment-Upload + Download
- **E2E-Tests (Playwright):**
- User lädt Profilbild hoch → in S3 abrufbar, in UI sichtbar
- User schickt Email mit Attachment → Empfänger kann Attachment laden
- **Migrations-Script-Tests:**
- Mock-Supabase-Bucket + Mock-S3 → vollständiger Migrations-Roundtrip mit Hash-Verify
- Re-Run-Idempotenz
- **Coverage-Target:** Migrations-Script ≥ 90%
- **Test-Files:**
- `scripts/migrate-supabase-to-s3.test.ts` (neu)
- bestehende MediaService-Tests aktualisieren
**NICHT als completed markieren bevor (a) die Migration auf Staging mit echten Tenant-Daten lief ODER (b) verifiziert ist dass es keine Supabase-Rows mehr gibt.**
## Acceptance Criteria
- [ ] DB-Audit zeigt 0 Rows mit `storage_provider = 'supabase'` (nach Migration falls nötig)
- [ ] `packages/storage/src/supabase/*` existiert nicht mehr
- [ ] `apps/web/app/utils/integrations/supabaseService.ts` existiert nicht mehr
- [ ] `@supabase/supabase-js` ist aus `packages/storage/package.json` raus
- [ ] `rg "supabase" apps packages` liefert nur noch History-/Doku-Bezug (außer der Migration-Script falls für Backlog gehalten)
- [ ] `SUPABASE_*`-Keys aus `.env.example` raus
- [ ] Doku zu Storage erwähnt nur noch S3
- [ ] Migrations-Script existiert + ist getestet (auch wenn 0 Rows zu migrieren waren)
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
- [ ] Staging-Smoke-Tests grün (Upload, Download, Email-Attachment)
- [ ] Detail-MD Progress-Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
**Migrations-Script-Rollback (Daten):** Nicht trivial, sobald Buckets in Supabase gelöscht (`--cleanup`-Step) wurden. Mitigation:
- `--cleanup` NICHT direkt nach Migration laufen lassen — mindestens 2 Wochen Wartezeit
- Supabase-Bucket-Versioning falls verfügbar aktivieren vor Migration
**Code-Rollback:** Atomic commits 4-8 sind einzeln revert-bar. Adapter-File-Restore via `git revert` bringt Code zurück, aber Supabase-Dependencies sind dann nicht mehr installiert → kombiniert mit revert von Step 7.
**DB-Rollback:** Falls `storage_provider`-Spalte gelöscht würde → DB-Migration-Down erforderlich. Wir löschen sie NICHT in dieser Task → kein DB-Rollback nötig.
Feature-Flag: nicht sinnvoll für Removal.
## Security Notes
- **Migrations-Script benötigt Credentials für BEIDE Storage-Backends** — Supabase Service-Role-Key und S3-Access-Key. Diese MÜSSEN aus Secrets gelesen werden, niemals hartcoded oder im Repo committed.
- **Bucket-Cleanup-Step ist destruktiv** — explizit per CLI-Flag `--cleanup` + interaktive Bestätigung. Niemals auto-cleanup.
- **Public-vs-Private-Buckets:** beim Migrieren sicherstellen dass die ACL-Settings in S3 dem Supabase-Bucket-Setting entsprechen (private bleiben private). Falsche ACL = Daten-Leak.
- **Signed-URLs:** falls die App Supabase-Signed-URLs in DB cached, müssen diese invalidiert werden nach Migration (neue URLs sind S3-Signed-URLs mit anderer Struktur).
- **Pre-Migration-Backup:** vollständiges Backup beider Storage-Backends bevor Cleanup läuft.
## Subagent Recommendations
- **Planning:** ein `Plan`-Subagent der die Tenant-Audit-Strategie und Migrations-Window plant — Input: diese Detail-MD.
- **Research:** zwei `general-purpose`-Subagents parallel:
1. Codebase-Inventur: alle Supabase-Referenzen mappen (rg-basiert)
2. Schema-Recherche: welche Tabelle/Spalte trackt `storage_provider`?
- **Implementation:**
- `general-purpose` für Steps 2+3 (Migrations-Script schreiben + Staging-Run)
- `general-purpose` für Steps 4-7 (Code-Cleanup)
- `general-purpose` für Step 8 (Doku/Env)
- **Tests:** `general-purpose` für Migrations-Script-Tests + Update bestehender MediaService-Tests
- **Verification:** `general-purpose` für Acceptance-Criteria + Staging-Smoke
- **Code-Review:** `gsd-code-reviewer` nach Phase-Abschluss
## Staging-Deployment-Steps
1. Branch `agent/01-supabase-removal` pushen.
2. Vor Code-Deploy: Migrations-Script lokal gegen Staging-DB laufen lassen (mit Read-Only-Supabase-Creds, Read-Write-S3-Creds).
- Erst `--dry-run`
- Dann ohne Dry-Run (nur wenn Operator OK gegeben hat)
- Spot-Check: 10 zufällige Files manuell vergleichen
3. Code-Deploy auf Staging via Coolify-Auto-Deploy.
4. Smoke-Tests:
- Bestehendes Profilbild (pre-Migration hochgeladen) lädt korrekt
- Neuer Upload landet in S3
- Email-Attachment-Roundtrip
5. 7 Tage Burn-In auf Staging bevor Production-Cutover.
6. Production-Cutover:
- Maintenance-Window 30 Min ankündigen
- Migrations-Script auf Production-DB
- Code-Deploy
- Smoke-Tests auf Production
- Supabase-Cleanup NICHT sofort — 2 Wochen warten
## Deviations from Plan
- **Migrations-Script NICHT geschrieben.** Plan Step 1 sagt erst DB-Audit, dann ggf. Script. Ohne Staging-Access (`docs/improvement-plan/archive/STAGING-ACCESS.md` Stub leer, B-002) kann ich keinen DB-Query gegen Produktions- oder Staging-DB laufen lassen um zu verifizieren ob es `storage_provider = 'supabase'` Rows gibt. Annahme: Operator führt die Audit-Query manuell durch sobald STAGING zugänglich ist und entscheidet dann ob ein Migrations-Script benötigt wird. Der Code-Pfad ist bereits resilient — `deleteRowMediaFromStorageProvider` löst über `media.storageBucket` aus, nicht über das Provider-Label, sodass alte Supabase-Rows beim Cleanup durch den S3-Adapter laufen (falls dieselben Bucket-Namen in S3 existieren).
- **Codebase hat schon S3-Pfade bereit.** Der bestehende `supabaseService.ts` enthielt seit längerem `storeFileWithRuntimeProvider()` (Zeilen 234-340) der bereits S3/local via @toolctrl/storage drive. Mein neuer `storageService.ts` ist im Wesentlichen diese Logik extrahiert plus saubere `storeFile()` / `putBufferAsFile()` / `deleteFile()` / `hasStorageCredentials()` API.
- **MediaService schreibt jetzt `storageProvider: "s3"`.** Historische Rows mit "supabase" bleiben in der DB unverändert; neue Writes haben "s3". Bulk-DB-Rewrite ausgelassen weil (a) der Code keine Branch-Logic mehr auf dem Feld hat, (b) der Wert dient nur Audit-Zwecken, (c) ein dediziertes Migrations-Script kann es später aufräumen.
- **Storage-Boundary-Baseline-Guard intentionally retained.** `scripts/verify-storage-boundary-baseline.mjs` detektiert Supabase-Pattern im Code als Sicherung gegen Re-Introduction. Bleibt drin obwohl Supabase weg ist — sinnvoll als Drift-Schutz.
- **DocsSidebar-Link zu `/docs/learning-center/guides/database/supabase`** bleibt unangerührt — das ist ein Learning-Center-Artikel für externe Supabase-Nutzung (nicht unsere eigene Storage-Integration). Orthogonal zum Cleanup.
- **3-4 Tage Schätzung deutlich überschritten in Code-Effort? Nein, eher unter** — das eigentliche Code-Removal war ~2h, der DB-Migrations-Schritt wäre die Hauptarbeit gewesen, ist aber per B-002 deferred.
## Progress Log
- 2026-05-17 01:00 — Cherry-pick `f7165dc0` lefthook fix (Precursor).
- 2026-05-17 01:02 — `9081eb50` Step 1: `storageService.ts` (S3/local pure, kein Supabase) extrahiert aus dem bestehenden runtime-provider-Path in `supabaseService.ts`. 4 Exports: `storeFile`, `putBufferAsFile`, `deleteFile`, `hasStorageCredentials`. Keine Caller-Switches, alles bleibt grün.
- 2026-05-17 01:04 — `21900ac2` Step 2: 6 Prod-Routen + 3 Test-Files migriert (general/profile/account/portals/widgets settings) von `storeSupabaseFile` → `storeFile`. Pure import + symbol rename. Plus zwei Test-Mock-Pfade.
- 2026-05-17 01:06 — `1107e59c` Step 3: `MediaService.ts` refactored — uses `putBufferAsFile` / `deleteFile` / `hasStorageCredentials`. Branch-Logic auf `storageProvider === "supabase"` weg, neue Writes setzen "s3".
- 2026-05-17 01:08 — `dc4c3f77` Step 4: `supabaseService.ts` + zugehöriger Test gelöscht (orphaned). 435 LOC weg, Tests: 1887 (war 1890 vor diesem Commit; −3 ist supabaseService.test cases).
- 2026-05-17 01:10 — `51e34839` Step 5: Config-Schema-Cleanup — `WebConfig.supabase`, `ApiConfig.supabase`, `ApiConfigSupabase` type, "supabase" aus `WebConfigStorage.provider`/`fallbackProvider`-Union, alle `supabase: {}` Test-Fixtures (6 Files in apps/api + 2 in packages/config), `normalizeStorageProvider`-Funktionen.
- 2026-05-17 01:12 — `613d51fe` Step 6: `@supabase/supabase-js` aus root + apps/web/package.json, catalog-Einträge für SUPABASE_API_URL/SUPABASE_KEY, alle 4 `.env*example`-Files, `docs/env-access-inventory.md`. Lockfile re-resolved, kein Supabase mehr in Tree.
- 2026-05-17 04:47 — staging-verify — running web container `mrf8lj70kmy9hqprx9dd6w7q-024502656750` (image tag `37f23fa6...`): `env | grep -i supabase` → empty; `ls /app/node_modules/@supabase` → not found. Postgres-Audit `SELECT provider, COUNT(*) FROM "FileObject" GROUP BY provider` → 0 rows total (FileObject leer, also keine historischen `storageProvider='supabase'`-Datensätze die migriert werden müssten). Migrations-Script entfällt damit endgültig. Acceptance Criteria erfüllt.