ki
9a4909f083
CI / test (push) Has been cancelled
Quivio (Kofferwort aus Quire + Video) ersetzt den Arbeitstitel WatchStack. Es ist origineller, frei auf PyPI/npm, und passt perfekt zur Doppelnatur der App: Buecher (Quire) + Serien (Video). Geaendert: - Python-Paket app/ -> quivio/ (+ alle Imports angepasst) - DB-File watchstack.db -> quivio.db - Docker-Image: quivio:0.5.1-beta, Container-Name quivio - Compose-Services: quivio, quivio-local - ENV-Vars: QUIVIO_VERSION, QUIVIO_PORT, Volume quivio-data - Frontend-Logo "W" -> "Q", Titel "Quivio", Footer - Favicon "Q" (Georgia serif fuer klassischen Look) - Logger-Name: watchstack -> quivio - README, NOTICE, dist/README, data/README: Quivio - CI-Workflow: testet quivio/ Pfade - build-and-push.sh: lokaler Tag "quivio:VERSION" - service-Feld in /api/health: quivio - OpenAPI title: Quivio Bugfix (gefunden beim Renaming): - seed.py hatte versteckten "from app.database import DB_PATH" — gefixt Verifiziert end-to-end: - Python-Import OK - Backend: service=quivio, version=0.5.1-beta, 8 unique items - Docker-Build OK, Push in Gitea-Registry OK (neuer sha256-Digest) - Container: Quivio 0.5.1-beta ready (logger), HTML ohne WatchStack-Rest - OpenAPI title=Quivio - 8 unique items nach cold start (Race-Fix haelt)
171 lines
6.7 KiB
Markdown
171 lines
6.7 KiB
Markdown
# Quivio
|
||
|
||
> **v0.5.1-beta** — eine Watchlist für **Bücher, Serien & mehr** — inspiriert von MyAnimeList, aber mit eigenem Konzept.
|
||
|
||
[](https://www.apache.org/licenses/LICENSE-2.0)
|
||
[](https://git.pkop.de/Vibecode/watchlist)
|
||
[](https://www.python.org)
|
||
[](#-docker)
|
||
|
||
**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](https://git.pkop.de/Vibecode/watchlist) melden.
|
||
|
||
## 🚀 Quickstart
|
||
|
||
### Option A: Image aus Gitea-Registry (empfohlen)
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 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](./LICENSE) (vollständiger Text) und [NOTICE](./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
|