diff --git a/tasks/v5.0.0-goal.md b/tasks/v5.0.0-goal.md new file mode 100644 index 0000000..272d6a9 --- /dev/null +++ b/tasks/v5.0.0-goal.md @@ -0,0 +1,275 @@ +# Twitch VOD Manager — v5.0.0 Goal + +**Baseline:** v4.6.155 (Stand 2026-05-11) +**Target:** v5.0.0 +**Status:** Draft / nicht freigegeben +**Sprache:** Deutsch (Stack-Begriffe englisch) + +--- + +## 1. Executive Summary + +Nach 155 Patches im 4.6er-Zyklus ist das Produkt poliert, aber im Kern unverändert seit 4.0: monolithische `main.ts` (~3700 Zeilen), JSON-File-Persistenz, Vanilla-DOM-Renderer, kein Live-Recording, keine sub-only Unterstützung, keine Tests jenseits Playwright-Smoke. + +**v5.0.0 ist der Bruch:** Aufnahme statt nur Download, SQLite statt JSON, modulare Domain-Architektur, Twitch-OAuth, optionales Web-Worker-Offloading für grosse Listen. Sieben Feature-Pillars, drei harte Breaking Changes, klarer Migrationspfad von 4.6.x. + +**Was 5.0.0 NICHT ist:** kein React/Vue-Rewrite, kein Plattform-Hop (bleibt Electron + Win), kein neues Bezahlmodell. Es bleibt der gleiche Single-User-Desktop-Client — nur deutlich erwachsener. + +--- + +## 2. Why Major Bump? + +Ein Major-Sprung ist gerechtfertigt, wenn **mindestens zwei** Kriterien erfuellt sind: + +| Kriterium | 5.0.0 trifft zu? | Belege | +|---|---|---| +| Breaking Change im Config-/Datenformat | Ja | JSON → SQLite Migration, Schema v4 → v5 | +| Neues Kern-Feature (nicht Inkrement) | Ja | Live-Stream-Recording (sub-only via OAuth), Scheduled-Recording | +| Architektur-Bruch | Ja | main.ts Split in 6+ Domain-Module | +| Min-OS-/Runtime-Bump | Ja | Electron 28 → 32, Node 18 → 22, Drop Win < 10 1809 | +| User-spuerbare UI-Verschiebung | Ja | Virtual-List, Mini-Player, Theme-Engine | + +--- + +## 3. Themes & Vision + +Drei Leitthemen ueber allen Features: + +### 3.1 Vom Downloader zum Recorder +v4 reagiert: VOD existiert auf Twitch → wir laden runter. v5 agiert proaktiv: Stream geht live → wir nehmen direkt mit. Damit fallen Sub-Only-VODs (oft 60 Tage Retention), 7-Tage-Standard-Retention und geloeschte VODs als Verlust-Szenarien weg. + +### 3.2 Vom Tool zur Platform +Domain-Module mit klaren Schnittstellen statt einem 3700-Zeilen-Monolith. Optionaler Plugin-Hook fuer Post-Download-Actions (z. B. Auto-Upload-Skript, Custom-Rename, Notify-Discord). Spaeter wartbar, leichter testbar. + +### 3.3 Vom Hobby zum stabilen Daily-Driver +SQLite + Crash-Recovery + Chunk-Hashing + echte Unit-Tests. Wer 500 VODs queued, soll nicht in JSON-Lock-Konflikte laufen oder beim Crash 4 Stunden Download verlieren. + +--- + +## 4. Feature-Pillars + +### Pillar 1 — Live Stream Recording (P0) + +**Was:** App kann laufende Streams in Echtzeit mitschneiden, nicht nur VODs post-hoc downloaden. + +**Warum:** Sub-only Streams haben oft keine VOD-Retention oder Sub-only-VODs werden nach 60 Tagen geloescht. Recording ist der einzige Weg, sie dauerhaft zu sichern. + +**Scope:** +- Streamlink-basierte Aufnahme aktiver Live-Streams (Quality-Selector wie bei VODs) +- Auto-Start: "wenn Streamer X live geht, Recording starten" (Polling-Intervall pro Streamer konfigurierbar, default 60s) +- Auto-Stop bei Stream-Ende + Final-Mux mit ffmpeg +- Resume bei Mid-Stream-Disconnect (neuer HLS-Segment-Pointer, append-Mode) +- Sub-only Streams: nutzt OAuth-Token aus Pillar 2 + +**Acceptance:** +- 4-Stunden-Test-Stream wird ohne Datenverlust aufgenommen +- Disconnect-Wiederherstellung in < 15s +- File-Output ist mux-fertig MP4 (kein .ts-Reste, kein orphan-Index) +- UI zeigt "LIVE REC" Badge + Recording-Dauer im Streamer-Eintrag + +### Pillar 2 — Twitch-OAuth (Device Code Flow) (P0) + +**Was:** Native Anmeldung mit Twitch-Account, OAuth-Token wird verschluesselt in OS-Keychain (Win Credential Manager) gespeichert. + +**Warum:** Sub-only Inhalte, hoehere Rate-Limits (Helix mit User-Token > App-Token in vielen Endpoints), private Follow-Liste fuer Auto-Discovery, korrekte Mature-Content-Gating-Behandlung. + +**Scope:** +- Device Code Flow (kein Browser-Embed, kein localhost-Callback noetig — sauberer fuer Desktop) +- Multi-Account: bis zu 3 parallele Accounts (Haupt, Alt, Auto-Sub) +- Token-Refresh automatisch, Fail-Soft auf App-Token +- Settings-Tab "Accounts" mit Liste, Login/Logout, "Default fuer Recording" + +**Acceptance:** +- Login dauert < 60s vom Klick bis Token in Keychain +- Sub-only Test-Channel laesst sich aufnehmen mit eingeloggtem Sub-Account +- Logout entfernt Token sauber aus Keychain (audit per Tool: kein orphan-Entry) + +### Pillar 3 — SQLite-Migration (P0, Breaking) + +**Was:** Alle App-Daten (Queue, Stats, Archiv-Index, Streamer-Liste, Recording-History) wandern von JSON-Files nach `app.db` (better-sqlite3 oder besser-im-Bundle-Alternative). + +**Warum:** JSON wird ab ~1000 VODs spuerbar lahm (Full-File-Rewrite bei jedem Save). SQLite gibt indexed lookups, atomic transactions, kein Lock-Konflikt bei parallelen Writes, einfache Migrationen. + +**Scope:** +- Schema v5 mit Tabellen: `queue`, `archive`, `streamers`, `recordings`, `stats_daily`, `clip_index`, `config_blob` +- Migrator-Script: liest alle `C:\ProgramData\Twitch_VOD_Manager\*.json` und schreibt in `app.db` +- Backup vor Migration: `.json` → `.json.v4-backup` +- Read-Path bleibt API-kompatibel fuer Renderer (IPC-Surface unveraendert) +- WAL-Mode + busy-timeout 5000ms + +**Acceptance:** +- Migrator laeuft idempotent (zweimal aufrufen = gleicher Endzustand, kein Daten-Duplikat) +- Failure-Rollback: bei Migrator-Crash bleibt App auf JSON, kein Daten-Verlust +- Query "alle VODs eines Streamers" < 50ms bei 10k Archiv-Eintraegen (gemessen) + +### Pillar 4 — Architektur-Refactor: main.ts Split (P1) + +**Was:** `main.ts` (3700 LoC) wird in Domain-Module zerlegt. + +**Ziel-Struktur:** +``` +src/main/ + index.ts Entry, app lifecycle, BrowserWindow + domain/ + twitch-api.ts Helix + GraphQL Calls, Rate-Limit-Handling + downloader.ts Streamlink/ffmpeg Orchestration (VOD + Live) + recorder.ts Live-Stream-Recording (NEU) + queue.ts Queue-State-Machine, persistence-call + config.ts Settings-Schema, defaults, validation + auth.ts OAuth, Token-Storage, Keychain (NEU) + cache.ts In-Memory-TTL-Caches + updater.ts electron-updater Wrapper + infra/ + db.ts SQLite-Wrapper, prepared statements + logger.ts Strukturiertes Logging (JSON-Lines) + ipc.ts Channel-Registry, type-safe Handler + ipc-bridge.ts exportiert nur die API-Surface fuer preload.ts +``` + +**Constraint:** Renderer-IPC-Surface bleibt rueckwaertskompatibel — kein Renderer-Rewrite noetig. + +**Acceptance:** +- Kein Modul groesser als 800 LoC +- Zyklische Imports = 0 (`madge --circular` oder aequivalent) +- E2E-Tests gruen ohne Anpassung + +### Pillar 5 — UI Power-Features (P1) + +**Was:** Renderer-seitige Spruenge, die User direkt sehen. + +**Scope:** +- **Virtualized List** fuer Queue/Archive (react-window-aequivalent vanilla, oder `@tanstack/virtual-core` vanilla-Adapter) — 10k Eintraege ohne Lag +- **Mini-Player Panel**: HLS-Stream in App-eigenem `