# ZXDB Downloader

Script que descarga juegos de ZX Spectrum a partir de la base de datos [ZXDB](https://github.com/zxdb/ZXDB) (MySQL en Docker).

## Requisitos

- Python 3.x
- Docker

## Setup

### Entorno virtual

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Configuración

Edita `config.py` en la raíz del proyecto. Variables principales:

| Variable | Descripción |
|----------|-------------|
| `DB_*` | Parámetros de conexión a MySQL |
| `DESTINATION_PATH` | Carpeta donde se depositan los juegos organizados |
| `CACHE_PATH` | Carpeta de caché (evita re-descargar ficheros) |
| `TEMP_FILE` | Fichero temporal durante la descarga |
| `SHOULD_CLEAR_DESTINATION_PATH` | Si es `True`, limpia el destino antes de cada ejecución |
| `SHOULD_SPLIT_MODERN_AND_CLASSIC` | Divide los juegos en carpetas `classics`/`modern` |
| `SHOULD_SORT_BY_YEAR` | Organiza por año de lanzamiento |
| `SHOULD_SORT_BY_LETTER` | Organiza por primera letra del título |
| `SHOULD_SORT_BY_DEVELOPER` | Organiza por desarrollador |
| `WAIT` / `MIN_WAIT` / `MAX_WAIT` | Control de velocidad de descarga |
| `LAST_CLASSIC_YEAR` | Año de corte entre clásicos y modernos |
| `ZXDB_SQL_PATH` | Ruta temporal donde se extrae `ZXDB_mysql.sql` |
| `ZXDB_STATE_FILE` | Fichero JSON con el estado del último import |

## Ejecución

```bash
source .venv/bin/activate
python main.py
```

`main.py` hace el setup automáticamente al arrancar:
1. Asegura que el contenedor MySQL Docker existe y está corriendo (lo crea si no existe).
2. Comprueba en GitHub si hay una versión más nueva de ZXDB.
3. Si es necesario: descarga `ZXDB_mysql.sql.zip` e importa en MySQL.
4. Descarga y organiza los juegos.
5. Al terminar (o con Ctrl+C), detiene el contenedor Docker.

El estado del último import se guarda en `/tmp/zxdb_state.json`. Una segunda ejecución sin cambios en GitHub omite el import.

Para conectar manualmente a MySQL mientras el contenedor está en marcha:

```bash
mysql -h 127.0.0.1 -P 3306 -u root -p
# Contraseña: unJEPimbJddHP8
# Luego: use zxdb
```

## Estructura del proyecto

```
zxdb/
├── main.py             # Punto de entrada: orquesta el flujo principal
├── config.py           # Configuración (credenciales y rutas locales, no en git)
├── requirements.txt    # Dependencias Python
│
└── zxdb/               # Paquete con la lógica del programa
    ├── __init__.py
    ├── database.py     # Conexión a MySQL y ejecución de consultas
    ├── queries.sql     # Consultas SQL (índices 0-3)
    ├── organizer.py    # Construcción de rutas y enriquecimiento de elementos
    ├── downloader.py   # Descargas, caché y descompresión de ficheros
    ├── filesystem.py   # Utilidades de sistema de ficheros y salida por pantalla
    └── setup/
        ├── __init__.py
        ├── __main__.py         # Orquestador: Docker + detección de cambios + import
        ├── database_import.py  # Descarga y extracción de ZXDB_mysql.sql.zip
        └── docker_manager.py   # Gestión del contenedor MySQL e import SQL
```

## Módulos

### `zxdb/database.py`
Gestiona la conexión a MySQL. `connect(query_index)` devuelve la lista de elementos obtenidos de la base de datos.

### `zxdb/organizer.py`
Construye rutas y enriquece cada elemento con metadatos: `game_folder_name`, URL completa, nombre de fichero, subcarpeta y flag de ZIP. `get_final_destination_folder()` aplica la lógica de organización según la configuración.

### `zxdb/downloader.py`
Gestiona las descargas desde internet y el uso de la caché. `get_files(elements)` itera sobre todos los elementos, sirve desde caché si es posible, o descarga y almacena en caché.

### `zxdb/filesystem.py`
Utilidades de sistema de ficheros: limpiar carpeta de destino, eliminar directorios vacíos, e imprimir el progreso por pantalla.

### `zxdb/queries.sql`
Cuatro consultas SQL (índices 0-3). La consulta 3 (usada por defecto) filtra juegos de ZX Spectrum (`m.text like 'ZX-%'`) y devuelve solo ficheros de cinta, disco, snapshot y pokes.

### `zxdb/setup/` — Setup de la base de datos

Invocado automáticamente por `main.py`. También puede ejecutarse de forma independiente con `python -m zxdb.setup`.

- **`__main__.py`**: Orquestador del flujo completo (Docker + detección de cambios + import).
- **`docker_manager.py`**: `ensure_container()`, `wait_for_mysql()`, `db_exists()`, `import_sql()`, `stop_container()` — gestión del contenedor Docker y del import SQL.
- **`database_import.py`**: `download_zxdb(destination)` — descarga `ZXDB_mysql.sql.zip` desde GitHub (streaming, ~150 MB) y extrae `ZXDB_mysql.sql`. Ejecutable directamente con `python -m zxdb.setup.database_import`.