docs: update DOCKER.md and README.md, and add README in spanish

Cruzadera · Cruzadera · commit 2c702bdbcc3c · 2026-04-24T08:56:39.000+02:00
diff --git a/DOCKER.md b/DOCKER.md
@@ -4,45 +4,117 @@ Requirements: Docker and Docker Compose installed.
 
 How to build the image
 
+# Docker Guide
+
+## Requirements
+
+- Docker
+- Docker Compose
+
+## Build image
+
 ```bash
 docker build -t filmaffinity-scores .
 ```
 
-How to run with docker-compose
+## Run with Docker Compose
 
-1. Copy `.env.example` to `.env` and edit values if needed.
-2. Start the app:
+1. Copy `.env.example` to `.env` and configure values.
+2. Start services.
+
+Full stack (API + scheduler):
 
 ```bash
-docker compose up --build
+docker compose up -d --build
 ```
 
-This mounts the local `data/` folder into the container to persist cache between runs.
-
+API only:
 
-Environment variables reference
-
-- `PORT` : port in container and host mapping (default `8085`).
-- `CACHE_TTL` : cache TTL seconds (default `86400`).
-- `JELLYFIN_BASE_URL`: your Jellyfin base URL (e.g. `http://192.168.1.31:8096`).
-- `JELLYFIN_API_KEY`: your Jellyfin API key.
-- `JELLYFIN_AUTH_MODE`: auth mode for Jellyfin client (`auto`|`header`|`query`).
-- `ENABLE_POSTER_BADGES`: enable FilmAffinity badge overlay and poster upload (`true`/`false`, default `false`).
-- `POSTER_BADGE_POSITION`: badge position (`top-right` default, also `top-left`, `bottom-right`, `bottom-left`).
-- `POSTER_BADGE_SIZE`: badge width ratio relative to poster width (default `0.2`).
-- `PUPPETEER_EXECUTABLE_PATH` : optional — set only if you want to use a system-installed Chromium.
-- `DEBUG_SCREENSHOTS` : set to `true` to persist debug screenshots under the `data/` folder inside the container (disabled by default).
+```bash
+docker compose up -d app
+```
 
-Sync script specific variables (see `.env.example`):
+Scheduler only:
 
-- `SYNC_JELLYFIN_DRY_RUN`, `SYNC_JELLYFIN_LIMIT`, `SYNC_JELLYFIN_BATCH_SIZE`, `SYNC_JELLYFIN_DELAY_MS`, `SYNC_JELLYFIN_RETRIES`, `SYNC_JELLYFIN_RETRY_DELAY`, `SYNC_JELLYFIN_SET_CRITIC`, `SYNC_JELLYFIN_FORCE`, `SYNC_JELLYFIN_PAGE_SIZE`, `SYNC_JELLYFIN_INCLUDE_ITEM_TYPES`.
+```bash
+docker compose up -d scheduler
+```
 
-Notes on Puppeteer
+## Defined services
+
+- `app`:
+	- Runs `npm start`
+	- Exposes port `8085` in the container
+	- Maps `${PORT:-8085}:8085` on the host
+- `scheduler`:
+	- Runs `node scripts/scheduler.js`
+	- Executes recurring `update-cache` + `sync-jellyfin` cycles
+
+## Data persistence
+
+Both services mount:
+
+- `./data:/app/data`
+
+This persists:
+
+- SQLite database (default `data/ratings.db`)
+- Original poster backups (default `data/poster-originals`)
+- Debug screenshots when `DEBUG_SCREENSHOTS=true`
+
+## Key environment variables (summary)
+
+See `.env.example` for full details.
+
+- General:
+	- `PORT` (default `8085`)
+	- `LOG_LEVEL` (`debug|info|warn|error`)
+	- `DB_PATH` (default `data/ratings.db`)
+	- `CACHE_TTL` (seconds)
+- Jellyfin:
+	- `JELLYFIN_BASE_URL`
+	- `JELLYFIN_API_KEY`
+	- `JELLYFIN_AUTH_MODE` (`auto|header|query`)
+	- `JELLYFIN_TIMEOUT`
+- Sync:
+	- `SYNC_JELLYFIN_DRY_RUN`
+	- `SYNC_JELLYFIN_LIMIT`
+	- `SYNC_JELLYFIN_BATCH_SIZE`
+	- `SYNC_JELLYFIN_DELAY_MS`
+	- `SYNC_JELLYFIN_RETRIES`
+	- `SYNC_JELLYFIN_RETRY_DELAY`
+	- `SYNC_JELLYFIN_SET_CRITIC`
+	- `SYNC_JELLYFIN_FORCE`
+	- `SYNC_JELLYFIN_PAGE_SIZE`
+	- `SYNC_JELLYFIN_INCLUDE_ITEM_TYPES`
+- Poster processing:
+	- `ENABLE_POSTER_BADGES`
+	- `POSTER_BADGE_POSITION`
+	- `POSTER_BADGE_SIZE`
+	- `POSTER_PRESERVE_ORIGINAL`
+	- `POSTER_ORIGINALS_DIR`
+- Scraping:
+	- `REQUEST_DELAY_MS`
+	- `DEBUG_SCREENSHOTS`
+	- `PUPPETEER_EXECUTABLE_PATH` (optional)
+
+## Puppeteer notes for containers
+
+- The `Dockerfile` installs required system packages for Chromium.
+- A compatible Chromium is installed during `npm ci`.
+- If sandbox issues appear, consider launching Puppeteer with `--no-sandbox --disable-setuid-sandbox` or set `PUPPETEER_EXECUTABLE_PATH` to a system Chromium binary.
+
+## Quick validation
+
+Check the API health endpoint:
 
-- The image installs runtime libraries required by Chromium; Puppeteer will download a compatible Chromium during `npm install` inside the image.
-- If you encounter Chromium sandbox issues, try launching Puppeteer with `--no-sandbox --disable-setuid-sandbox` flags or set `PUPPETEER_EXECUTABLE_PATH` to a system Chromium binary.
+```bash
+curl "http://localhost:${PORT:-8085}/health"
+```
 
-Validation
+View logs:
 
-- The compose service exposes the app on `http://localhost:PORT`.
-- Data is persisted in `./data/ratings.json`.
+```bash
+docker compose logs -f app
+docker compose logs -f scheduler
+```
diff --git a/README-ES.md b/README-ES.md
@@ -0,0 +1,214 @@
+# FilmAffinity Scores (API + Jellyfin Sync)
+
+![Node.js](https://img.shields.io/badge/Node.js-20.x-brightgreen?logo=node.js)
+![Docker](https://img.shields.io/badge/Docker-ready-blue?logo=docker)
+![License](https://img.shields.io/badge/license-MIT-lightgrey)
+
+## ES
+
+Servicio Node.js para:
+
+1. Consultar valoraciones de FilmAffinity (scraping con Puppeteer).
+2. Exponerlas vía API REST.
+3. Guardarlas en caché persistente (SQLite).
+4. Sincronizar ratings en Jellyfin.
+5. Opcionalmente reescribir pósters en Jellyfin con badge visual de nota.
+
+No es solo una API: también incluye un flujo batch y un scheduler para mantener la librería actualizada.
+
+### Qué hace hoy el proyecto
+
+- API HTTP para consultar una película por título/año.
+- Caché en memoria (node-cache) + caché persistente (data/ratings.db).
+- Scraper con puppeteer-extra + stealth plugin.
+- Sincronización de metadatos en Jellyfin (CommunityRating, opcional CriticRating).
+- Procesamiento de póster y subida de imagen a Jellyfin.
+- Scheduler para ejecutar ciclos automáticos de actualización.
+
+### Arquitectura rápida
+
+- npm start: levanta la API (src/index.js).
+- npm run update-cache: recorre la librería de Jellyfin y refresca caché en SQLite.
+- npm run sync-jellyfin: sincroniza ratings FilmAffinity -> Jellyfin.
+- npm run scheduler: bucle continuo que ejecuta update-cache + sync-jellyfin en cada ciclo.
+
+### Requisitos
+
+- Node.js 20+
+- Acceso a una instancia de Jellyfin (si vas a usar sync/scheduler)
+- JELLYFIN_API_KEY con permisos para leer y actualizar metadata
+
+### Instalación
+
+```bash
+git clone https://github.com/Cruzadera/filmaffinity-scores.git
+cd filmaffinity-scores
+npm install
+cp .env.example .env
+```
+
+Edita .env con tus valores reales antes de ejecutar sincronizaciones.
+
+### Modo API (REST)
+
+Arranque:
+
+```bash
+npm start
+```
+
+Por defecto expone en http://localhost:8085
+
+Endpoints:
+
+- GET /movie?title=...&year=...
+  - title obligatorio
+  - year obligatorio (4 dígitos)
+  - Devuelve 400/404/502 según validación, no encontrado o fallo de scraping
+- GET /rating?title=...&year=...
+  - title obligatorio
+  - year opcional
+- GET /health
+
+Ejemplo:
+
+```bash
+curl "http://localhost:8085/movie?title=Alien&year=1979"
+```
+
+Respuesta típica:
+
+```json
+{
+  "title": "Alien",
+  "year": "1979",
+  "rating": 8.1,
+  "votes": "123456",
+  "url": "https://www.filmaffinity.com/es/film123456.html"
+}
+```
+
+### Sincronización con Jellyfin
+
+Script recomendado:
+
+```bash
+npm run sync-jellyfin
+```
+
+Por defecto corre en dry-run (SYNC_JELLYFIN_DRY_RUN=true): calcula cambios pero no los aplica.
+
+Prueba controlada:
+
+```bash
+LOG_LEVEL=debug \
+SYNC_JELLYFIN_DRY_RUN=true \
+node scripts/sync-jellyfin.js --limit=5 --batch-size=2
+```
+
+Aplicar cambios reales:
+
+```bash
+LOG_LEVEL=debug \
+SYNC_JELLYFIN_DRY_RUN=false \
+node scripts/sync-jellyfin.js --limit=20 --batch-size=2
+```
+
+Sincronizar también pósters con badge:
+
+```bash
+LOG_LEVEL=debug \
+SYNC_JELLYFIN_DRY_RUN=false \
+ENABLE_POSTER_BADGES=true \
+POSTER_BADGE_POSITION=top-right \
+POSTER_BADGE_SIZE=0.2 \
+node scripts/sync-jellyfin.js --limit=20 --batch-size=2
+```
+
+### Scheduler automático
+
+```bash
+npm run scheduler
+```
+
+Ciclo:
+
+1. Ejecuta update-cache
+2. Ejecuta sync-jellyfin
+3. Espera SLEEP_SECONDS (default 86400)
+4. Repite en bucle
+
+SYNC_JELLYFIN_FORCE_ON_STARTUP=true permite forzar la primera pasada.
+
+### Variables de entorno (resumen)
+
+Consulta .env.example para lista completa.
+
+- Generales:
+  - PORT (default 8085)
+  - LOG_LEVEL (debug|info|warn|error, default info)
+  - DB_PATH (default data/ratings.db)
+  - CACHE_TTL en segundos (default 86400)
+- Jellyfin:
+  - JELLYFIN_BASE_URL
+  - JELLYFIN_API_KEY
+  - JELLYFIN_AUTH_MODE (auto|header|query)
+  - JELLYFIN_TIMEOUT
+- Sync:
+  - SYNC_JELLYFIN_DRY_RUN, SYNC_JELLYFIN_LIMIT, SYNC_JELLYFIN_BATCH_SIZE
+  - SYNC_JELLYFIN_DELAY_MS, SYNC_JELLYFIN_RETRIES, SYNC_JELLYFIN_RETRY_DELAY
+  - SYNC_JELLYFIN_SET_CRITIC, SYNC_JELLYFIN_FORCE, SYNC_JELLYFIN_PAGE_SIZE
+  - SYNC_JELLYFIN_INCLUDE_ITEM_TYPES
+- Pósters:
+  - ENABLE_POSTER_BADGES
+  - POSTER_BADGE_POSITION
+  - POSTER_BADGE_SIZE
+  - POSTER_PRESERVE_ORIGINAL
+  - POSTER_ORIGINALS_DIR
+  - POSTER_BADGE_DRY_RUN / POSTER_BADGE_FORCE
+- Scraping/cache incremental:
+  - REQUEST_DELAY_MS
+  - RECENT_TTL_DAYS
+  - RECENT_YEARS
+  - DEBUG_SCREENSHOTS
+
+### Docker
+
+En docker-compose.yml hay dos servicios:
+
+- app: API REST
+- scheduler: ciclo automático cache + sync
+
+Arrancar stack completo:
+
+```bash
+docker compose up -d --build
+```
+
+Solo scheduler:
+
+```bash
+docker compose up -d scheduler
+```
+
+El volumen ./data:/app/data persiste SQLite y backups de pósters.
+
+### Tests
+
+```bash
+npm test
+```
+
+### Notas
+
+- El scraping puede romperse si FilmAffinity cambia HTML o anti-bot.
+- Las actualizaciones en Jellyfin dependen de permisos del API key.
+- En producción, empezar en dry-run y luego pasar a modo escritura.
+
+## Disclaimer
+
+Proyecto orientado a uso personal/autoalojado y fines educativos. Respeta los términos de uso de servicios externos.
+
+## License
+
+Ver LICENSE.
diff --git a/README.md b/README.md
