watchlist/README.md

Quivio

v0.5.1-beta — eine Watchlist für Bücher, Serien & mehr — inspiriert von MyAnimeList, aber mit eigenem Konzept.

Quivio (Kofferwort aus Quire + Video) ist eine single-user-lokale Watchlist-App. Bücher und Serien teilen sich eine Oberfläche, ein Datenmodell und eine Such- und Filterlogik. Keine Anmeldung, kein Cloud-Zwang — läuft komplett auf deiner Maschine oder in einem Docker-Container.

✨ Features

• 📚 Bücher: Titel, Autor, Bände / Kapitel / Seiten, ISBN, Cover via Open Library
• 📺 Serien: Staffeln, Episoden, Sender / Streaming, Sendezeitraum, Cover-URL
• 🗂 Status: Plan · Laufend · Abgeschlossen · Pausiert · Abgebrochen (5 Stufen, MAL-ähnlich)
• ⭐ Bewertungen 1–10 mit Auto-Status: 0% → Plan, 100% → Done (+ end_date)
• 🔎 Suche & Filter: Volltext, Status, Genre, Tag, Sortierung
• 📊 Dashboard: Verteilung pro Medium, Durchschnittsbewertung
• 🏷 Genres & Tags frei verwaltbar
• 🌙 Dark Theme Default, modernes UI mit Hero + Drawer + Modals
• 🐳 Docker: Image in der Gitea Container Registry — docker pull git.pkop.de/vibecode/watchlist:<ver>
• 🌐 CORS offen für lokale Entwicklung; in Produktion via Reverse-Proxy einschränken

⚠️ Beta-Hinweis

v0.5.1-beta bedeutet:

• Kernfunktionalität (CRUD, Suche, Stats, Progress) ist stabil und getestet
• Datenmodell kann sich noch ändern (siehe quivio/models.py — additive Änderungen wahrscheinlich)
• Datenbank-Migrationen sind nicht enthalten — bei Major-Upgrades DB sichern
• Public-API-Pfade stabil; Sub-Ressourcen (Genres/Tags) noch in Bewegung

Bitte Issues und Wünsche im Repo melden.

🚀 Quickstart

Option A: Image aus Gitea-Registry (empfohlen)

docker pull git.pkop.de/vibecode/watchlist:0.5.1-beta
docker run -d --name quivio -p 8000:8000 -v quivio-data:/data git.pkop.de/vibecode/watchlist:0.5.1-beta

Das Image liegt im Packages-Tab des Repos (Gitea Container Registry, OCI-konform). Auch über die Web-UI einsehbar unter https://git.pkop.de/Vibecode/-/packages.

Option B: Docker Compose / lokal bauen

docker compose up -d
# → http://localhost:8000

# Oder direkt:
docker build -t quivio:beta .
docker run -d --name quivio -p 8000:8000 -v quivio-data:/data quivio:beta

Option C: Python direkt

git clone https://git.pkop.de/Vibecode/watchlist.git
cd watchlist
./run.sh        # legt venv an, installiert deps, startet auf 127.0.0.1:8000

🔧 Konfiguration (Umgebungsvariablen)

Variable	Default	Zweck
WATCHSTACK_DATA_DIR	./data	Pfad für SQLite-DB (im Container: /data)
WATCHSTACK_HOST	127.0.0.1	Bind-Adresse (Docker: 0.0.0.0)
WATCHSTACK_PORT	8000	HTTP-Port
WATCHSTACK_WORKERS	2	gunicorn-Worker (nur Docker)
WATCHSTACK_HTTP_TIMEOUT	8	Timeout für Open-Library-Lookup (Sek.)

Hinweis: Die ENV-Variablen heißen weiterhin WATCHSTACK_*, weil das der Docker-konforme Standard ist. Im lokalen Dev ist das egal, da die Defaults passen.

📚 API-Übersicht

Methode	Pfad	Zweck
GET	/api/health	Service-Info + Version
GET	/api/media	Liste, Filter via Query-Params
POST	/api/media	Anlegen (201)
GET	/api/media/{id}	Detail
PATCH	/api/media/{id}	Teil-Update
DELETE	/api/media/{id}	Löschen (204)
POST	/api/media/{id}/progress	{"delta":1} oder {"set_to":N}
GET	/api/genres, /api/tags	Taxonomien
GET	/api/stats	Verteilungen + ⌀-Bewertung
GET	/api/lookup/book?isbn=…	Cover via Open Library

Beispiel — neuen Eintrag anlegen:

curl -X POST http://localhost:8000/api/media \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "book",
    "title": "Der Name des Windes",
    "author": "Patrick Rothfuss",
    "total_pages": 662, "pages_read": 100,
    "status": "reading", "rating": 9.0,
    "genres": ["Fantasy"], "tags": ["Königsmörder"]
  }'

Vollständige interaktive Doku: http://localhost:8000/docs (Swagger UI, von FastAPI generiert).

🏗 Projektstruktur

watchlist/
├── quivio/                 # Python-Paket (FastAPI, SQLAlchemy, ...)
│   ├── __init__.py        # __version__
│   ├── main.py            # FastAPI-App + Routen
│   ├── database.py        # Engine + Session
│   ├── models.py          # SQLAlchemy-Modelle
│   ├── schemas.py         # Pydantic-Schemas
│   ├── crud.py            # DB-Operationen
│   ├── external.py        # Open-Library-Client
│   ├── seed.py            # Demo-Daten
│   └── static/            # Frontend (HTML/CSS/JS)
├── data/                  # SQLite-DB (gitignored, Volume im Container)
├── bin/                   # build-and-push.sh, build-image.sh, write-manifest.sh, get-version.py
├── .github/workflows/     # CI
├── Dockerfile             # Multi-stage Build
├── docker-compose.yml
├── LICENSE                # Apache-2.0 (offizieller Volltext)
├── NOTICE                 # Copyright + Drittanbieter
└── README.md

🛠 Entwicklung

# Lokales Backend
./run.sh

# Tests (bisher Smoke-Tests ad-hoc; pytest-Suite ist Roadmap)
python3 -c "from quivio.main import app; print(app.title, app.version)"

📜 Lizenz

Apache License 2.0 — siehe LICENSE (vollständiger Text) und NOTICE (Drittanbieter-Hinweise).

Kurzfassung: Du darfst das Projekt privat und kommerziell nutzen, verändern, weitergeben — unter Beibehaltung des Copyright-Hinweises und der Lizenz. Es gibt keine Patent-Gewähr; Änderungen müssen markiert werden. Volltext in der LICENSE-Datei.

🤝 Contributing

PRs willkommen — am besten mit Issue vorab. Bitte:

• Coding-Style einhalten (PEP 8, KISS, DRY)
• Keine externen Tracker; Issues im Gitea-Repo
• Tests für neue Logik (pytest-Suite kommt)

🔮 Roadmap

• pytest-Suite mit Coverage-Report
• Backup-/Restore-Endpoint
• Import von MAL-XML / Trakt-Listen
• Manga als dritte Medienart (Volumes, Chapters)
• Multi-User mit OIDC-Login (optional, hinter Feature-Flag)
• Cover-Caching-Proxy
• Deutsche Übersetzungen der Status-Labels i18n-ready