Flimmer — Arbeitsauftrag & Projektgedächtnis

Diese Datei ist mein (Claude) Gedächtnis für dieses Projekt. Sie hält fest, was gebaut werden soll, wie gearbeitet wird und wo ich gerade stehe. Nach jeder Etappe wird der Abschnitt „Fortschritt" aktualisiert.

Was ist Flimmer?

Selbst hostbarer Serien- & Film-Tracker (angelehnt an „Flimmerkiste"). Multi-User, TMDB-Metadaten, Episodenfortschritt, eigene Universen mit mehreren Reihenfolgen, Statistiken, Benachrichtigungen, REST-API, PWA. Oberflächensprache Deutsch.

Verbindliche Entscheidungen (nicht ohne Rückfrage ändern)

Bereich	Entscheidung	Begründung
Framework	Next.js 15, App Router, TypeScript	UI + REST-API + Cron in einem Deployment; Server Components halten Prisma serverseitig; `output: "standalone"` ergibt ein schlankes Docker-Image
DB	PostgreSQL + Prisma (Schema + Migrationen)	vorgegeben
Styling	Tailwind CSS v4 (`@theme`, CSS-Variablen)	Design-Tokens sind in v4 nativ CSS-Variablen → Dark/Light/Themes bauen sauber darauf auf
Auth	eigene Session-Schicht: bcryptjs + opake Tokens in DB-Tabelle `Session`, httpOnly-Cookie; OIDC optional über `jose` + Discovery	DB-Sessions erlauben Sperren/Abmelden durch Admin; kein Beta-API-Risiko von next-auth v5; Credentials + OIDC parallel möglich
Passwort-Hash	bcryptjs (pure JS)	keine nativen Build-Abhängigkeiten im Docker-Image
Scheduler	in-process über `instrumentation.ts` (`ENABLE_SCHEDULER`) plus `/api/cron/*` mit `CRON_SECRET`	kein zweiter Container nötig, externe Scheduler trotzdem möglich
Bild-Cache	Dateien unter `DATA_DIR/images`, ausgeliefert über `/api/image`	kein TMDB-Abruf pro Seitenaufruf
Charts	handgeschriebene SVG-Komponenten	volle Kontrolle über Design-Tokens, keine Chart-Lib-Abhängigkeit
PWA	eigenes `sw.js` + `manifest.webmanifest`	keine zusätzliche Abhängigkeit
i18n	Dictionary `src/i18n/de.ts` + `t()`-Helper mit Punkt-Keys	weitere Sprachen ergänzbar
API	`/api/v1/**`, Bearer-API-Keys pro Nutzer, OpenAPI unter `/api/v1/openapi.json`	für spätere Mobile-App/Skripte

Branding (fix)

Name Flimmer, Motiv: warmes Flimmern des Bildschirms
Logo als SVG: abgerundetes Bildschirm-Rechteck, weiches warmes Glühen (Gradient), dezentes Play-Dreieck; Wortmarke in moderner, leicht gerundeter Sans
Drei Varianten: Icon, Icon + Wortmarke horizontal, monochrom
Favicon + PWA-Icons (inkl. maskable) aus dem Icon generiert
Farbwelt: sehr dunkles Blauviolett/Anthrazit als Grund, Signatur = Glow-Gradient Bernstein → Magenta; Light Mode = dieselben Akzente auf warmgrauem Grund
Alle Kombinationen müssen WCAG AA erfüllen
UI: posterlastig, großzügige Karten mit sanftem Hover-Glow, runde Ecken, weiche Verläufe, ruhige Mikro-Animationen (Aufglimmen beim Abhaken)
Logo + Name konsistent in Header, Login, E-Mail-/Notification-Templates, README

Arbeitsregeln

Git-Repo mit Remote origin → https://git.wilde-server.de/florian.wilde/flimmer.git, Branch main
Conventional Commits (feat:, fix:, chore:, docs: …), Nachrichten deutsch
Kleine Commits nach jedem abgeschlossenen Schritt — kein Riesen-Commit
.env niemals committen (nur .env.example)
CHANGELOG.md im Keep-a-Changelog-Format, SemVer ab 0.1.0; jede Etappe = neue Minor-Version
Pro Version: Git-Tag vX.Y.Z + Gitea-Release (via Gitea-MCP, gh/tea sind nicht installiert), Titel = Version, Notes = Changelog-Abschnitt; zusätzlich releases/vX.Y.Z.md ablegen
DEVLOG.md: pro Arbeitsphase Start-/Endzeit per date-Befehl (nicht schätzen) + Kurzbeschreibung; je Etappe Summe, am Ende Gesamtübersicht
Versionsnummer aus package.json im UI anzeigen (Footer/Einstellungen)
Umgebung: Windows + PowerShell/Git-Bash, VS Code. curl → curl.exe. Keine Desktop-Benachrichtigungen.

Etappen

Projektgerüst, Branding, Docker-Compose, DB-Schema, Auth → v0.1.0
TMDB-Anbindung: Suche, Detailimport, Episodendaten, Bild-Cache → v0.2.0
Kern-Tracking: Bibliothek, Status, Episodenfortschritt, Watchlist → v0.3.0
Universen mit Reihenfolgen und Fortschritt → v0.4.0
Dashboard, Kalender, Statistiken → v0.5.0
Benachrichtigungen, Sync-Job, Import/Export, REST-API, PWA-Feinschliff → v0.6.0

Ausdrücklich gewünscht (nicht vergessen!)

Bebilderte Anleitung docs/ANLEITUNG.md mit Screenshots der laufenden App (Playwright gegen die geseedete Instanz, Bilder nach docs/screenshots/)
Papierkorb (30 Tage) statt hartem Löschen + Undo für „als gesehen markiert"
Seed-Skript mit Beispieldaten
Backup-Hinweise (DB-Dump) in der README
Healthcheck /api/health
Öffentliche Profilseite (abschaltbar)
Rewatch-Tracking (Durchläufe, bei Serien pro Durchlauf)
Streaming-Verfügbarkeit (TMDB Watch Providers), Region konfigurierbar, Standard DE
Import: Trakt.tv-Export + CSV; Export: CSV/JSON
Benachrichtigungen: SMTP, ntfy, Gotify, generischer Webhook — pro Nutzer
Streamingdienste mit konsistenten Akzentfarben/Badges im ganzen UI
Optional per ENV: OIDC/SSO (Authelia, Keycloak)
Registrierung durch Admin abschaltbar; erster Nutzer wird Admin

Wichtige technische Merkposten

Next 16: Request-APIs sind async (cookies(), headers(), params, searchParams). middleware.ts heißt jetzt proxy.ts. Turbopack ist Standard. Breaking Changes stehen in node_modules/next/dist/docs/01-app/02-guides/upgrading/version-16.md.
Prisma 7: keine url im Schema — Treiber-Adapter (@prisma/adapter-pg) im Client, URL in prisma.config.mjs. Generator ist prisma-client (TypeScript-Ausgabe nach src/generated/prisma, gitignored). Config bewusst .mjs, damit die CLI im Produktionsimage ohne TS-Loader läuft.
Tailwind v4: @theme inline reicht die --fl-*-Variablen durch, @custom-variant dark hängt an [data-theme="dark"].
Zwei Verläufe: --fl-gradient für Flächen, --fl-gradient-ink für Text (im Light Mode abgedunkelt, sonst kein AA). Logo-Stops --fl-brand-1/2/3.
Dev-Umgebung: Postgres auf localhost:5439 (docker-compose.dev.yml), Dev-Server auf Port 3011 (3000 und 3010 sind von anderen Projekten belegt).
Screenshots: node scripts/shot.mjs <url> <ziel.png> [w] [h] [theme].
Next hängt selbst einen Block an diese Datei an — der bleibt drin.

Fortschritt

✅ Etappe 1 (v0.1.0) — Gerüst, Branding, Docker, Schema, Auth. 38 min.
✅ Etappe 2 (v0.2.0) — TMDB: Suche, Import, Episoden, Bild-Cache. 14 min.
✅ Etappe 3 (v0.3.0) — Bibliothek, Status, Episodenfortschritt, Papierkorb. 24 min.
✅ Etappe 4 (v0.4.0) — Universen mit Reihenfolgen, Freigaben. 14 min.
✅ Etappe 5 (v0.5.0) — Übersicht, Kalender, Statistik. 15 min.
✅ Etappe 6 (v0.6.0) — Benachrichtigungen, Abgleich, Import/Export, REST-API, PWA, Anleitung. 31 min.

Alle sechs Etappen abgeschlossen. Gesamtzeit: 2 h 16 min.

Nützliches für spätere Arbeiten

Suche ohne TMDB-Schlüssel ausprobieren: npm run tmdb:stub und dann TMDB_API_KEY=stub TMDB_BASE_URL=http://127.0.0.1:3099/3 PORT=3011 npm run dev
Screenshots neu aufnehmen: npm run screenshots (nimmt auf und verkleinert)
npm test läuft seriell gegen die Dev-Datenbank, braucht keinen TMDB-Schlüssel
Deutsche Anführungszeichen („…") niemals in JS-String-Literalen — das ASCII-Schlusszeichen beendet den String. In JSX-Text und Kommentaren ok.
Heredocs im Bash-Tool sind bei langen TSX-Dateien unzuverlässig — dann das Write-Werkzeug benutzen.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

8.3 KiB Raw Blame History