Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,213 @@
# 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.