quasar/plans/gestor-coleccion-plan-phase-4.md

## Plan: Importador de ROMs (Fase 4)

TL;DR: Estabilizar el entorno de tests y, mediante TDD, implementar la pipeline de importación de ROMs: escaneo de ficheros, cálculo de checksums, verificación contra DATs, persistencia en Prisma y un runner en background. Se comenzará con un runner en memoria y se dejará la puerta abierta para migrar a Redis posteriormente.

**Phases**

1. **Phase 1: Estabilizar entorno y ejecutar tests**
   - **Objective:** Obtener una línea base reproducible donde `yarn --cwd backend test` se ejecute y muestre resultados claros.
   - **Files/Functions to Modify/Create:** `backend/tsconfig.json`, `backend/package.json`, `backend/prisma/schema.prisma`, `backend/src/plugins/prisma.ts`.
   - **Tests to Write:** Ninguno nuevo; ejecutar y capturar los tests existentes (`backend/tests/**`).
   - **Steps:**
     1. Ejecutar `yarn install` en la raíz y generar el cliente Prisma (`prisma generate`) en `backend/`.
     2. Ejecutar `yarn --cwd backend test` y documentar fallos.
     3. Corregir problemas de `prisma generate` o `tsconfig` y validar que los tests relevantes pasan.

2. **Phase 2: Persistencia básica e integración con la ruta de import**
   - **Objective:** Implementar `importService` que use `scanDirectory` y `computeHashes` para persistir `RomFile` (upsert por checksum) y, cuando sea posible, vincular/crear `Game`.
   - **Files/Functions to Modify/Create:** `backend/src/services/importService.ts`, actualizar `backend/src/routes/import.ts` para invocar el servicio.
   - **Tests to Write:** `backend/tests/services/importService.spec.ts`, actualizar `backend/tests/routes/import.spec.ts` para escenarios `persist: true/false`.
   - **Steps:**
     1. Escribir tests (falla roja).
     2. Implementar mínimo para pasar tests (green).
     3. Refactor y asegurar idempotencia (re-run tests).

3. **Phase 3: ArchiveReader — soportar zip/7z/chd**
   - **Objective:** Leer/listar contenido de contenedores (ZIP, 7z, CHD) sin extracción completa para indexar ROMs internos.
   - **Files/Functions to Modify/Create:** `backend/src/services/archiveReader.ts`; adaptar `backend/src/services/fsScanner.ts` para delegar en `archiveReader` cuando `isArchive`.
   - **Tests to Write:** `backend/tests/services/archiveReader.spec.ts` (fixtures: zips/7z/CHD bajo `backend/tests/fixtures`).
   - **Steps:**
     1. Añadir tests que describan el comportamiento esperado (falla roja).
     2. Implementar con librería elegida y validar en CI con binarios instalados.

4. **Phase 4: DAT parsing y verificación**
   - **Objective:** Parsear DAT XML y comprobar si un ROM coincide con una entrada DAT (por checksums/size/name).
   - **Files/Functions to Modify/Create:** `backend/src/services/datVerifier.ts` (completar), añadir utilidades de parseo XML.
   - **Tests to Write:** `backend/tests/services/datVerifier.spec.ts` (unidad + integración, usar `INTEGRATION=1` para pruebas que dependan de binarios/fixtures grandes).
   - **Steps:**
     1. Implementar parseo y matching (falla roja).
     2. Integrarlo en `importService` para sugerir o asociar `Game`.

5. **Phase 5: Job runner en memoria (inicio) — migrable a Redis**
   - **Objective:** Implementar un runner en memoria que procese jobs de import con control de concurrencia (`IMPORT_CONCURRENCY`), estado básico y capacidad de encolar tareas desde la ruta `/api/import/scan`.
   - **Files/Functions to Modify/Create:** `backend/src/config.ts`, `backend/src/jobs/importRunner.ts`, tests en `backend/tests/jobs/importRunner.spec.ts`, actualizar `backend/src/routes/import.ts` para encolar jobs.
   - **Tests to Write:** `backend/tests/jobs/importRunner.spec.ts` (enqueue/resolución, concurrencia, getStatus).
   - **Steps:**
     1. Escribir tests (falla roja).
     2. Implementar runner in-memory (green).
     3. Integrar con la ruta de import y validar comportamiento en tests.

6. **Phase 6: CI e integración de binarios**
   - **Objective:** Preparar workflows para ejecutar pruebas de integración que dependan de binarios (`7z`, `chdman`) y asegurar `prisma generate` en CI.
   - **Files/Functions to Modify/Create:** `.github/workflows/ci.yml`, documentación en `README.md`.
   - **Steps:**
     1. Crear workflow que haga `yarn install`, `yarn --cwd backend prisma generate`, instale binarios (o use contenedor preparado) y ejecute `yarn --cwd backend test` con `INTEGRATION=1` cuando corresponda.

**Open Questions**

1. ¿Persistimos `ImportJob` en DB desde el inicio (útil para resume/retry) o lo dejamos para una futura migración a Redis? (Persistir ahora / Posponer)
2. ¿En CI preferís instalar `7z`/`chdman` o marcar tests de archive/CHD como opcionales con `INTEGRATION=1` y ejecutarlos solo si runner proporciona binarios? (Instalar / Opcional)
3. ¿Creación automática de `Game` al no encontrar DAT match? (Crear placeholder con `slug` / Solo guardar `RomFile`)
4. Política de colas a largo plazo: ¿Redis desde el inicio o in-memory ahora y migrar luego? (Usuario eligió: in-memory ahora)

## Plan: Importadores y gestión de ROMs (Fase 4)

Implementar servicios para escanear directorios de ROMs, detectar formatos (ZIP/7z/CHD), calcular checksums (CRC32/MD5/SHA1), verificar contra DATs (No-Intro/Redump) y persistir `RomFile` en la BD. El escaneo se lanzará desde el frontend, correrá como job en background y la ruta a las ROMs será una configuración del sistema (no se envía en cada request). Se añadirá la variable `IMPORT_CONCURRENCY` con cálculo por defecto.

**Phases 4**

1. **Phase 4.1: Tests y fixtures (TDD)**
   - **Objective:** Escribir tests y fixtures que guiarán la implementación; los tests deben fallar inicialmente.
   - **Files a crear:**
     - `backend/tests/fixtures/simple-rom.bin` — fixture ROM sintética
     - `backend/tests/fixtures/nested/nested-rom.bin` — fixture en subdirectorio
     - `backend/tests/fixtures/dats/sample-no-intro.dat.xml` — DAT XML mínimo
     - `backend/tests/services/fsScanner.spec.ts`
     - `backend/tests/services/checksumService.spec.ts`
     - `backend/tests/services/datVerifier.spec.ts` (marcar integración para binarios cuando aplique)
     - `backend/tests/routes/import.spec.ts`
   - **Criterio de aceptación:** Los tests existen y fallan por falta de implementación (TDD).

2. **Phase 4.2: Core — Scanner y checksums**
   - **Objective:** Implementar `fsScanner` y `checksumService` con streaming y control de concurrencia.
   - **Files a crear:**
     - `backend/src/services/fsScanner.ts`
     - `backend/src/services/checksumService.ts`
     - `backend/src/lib/fileTypeDetector.ts`
   - **Criterio de aceptación:** Tests unitarios de Phase 4.1 pasan para los casos no relacionados con archives/CHD.

3. **Phase 4.3: Archives y DAT verification**
   - **Objective:** Implementar `archiveReader` (ZIP, 7z opcional) y `datVerifier`.
   - **Files a crear:**
     - `backend/src/services/archiveReader.ts`
     - `backend/src/services/datVerifier.ts`
   - **Notas:** CHD será soportado opcionalmente mediante `chdman` (si está instalado en el sistema); en la MVP se tratará CHD como blob para checksums si `chdman` no está presente.

4. **Phase 4.4: API, job en background y E2E**
   - **Objective:** Añadir endpoint `POST /api/import/scan` (sin recibir path; usa la ruta preconfigurada), job runner en background, endpoints `GET /api/import/status/:taskId` y `GET /api/import/result/:taskId`, y pruebas E2E que verifiquen persistencia en Prisma.
   - **Files a crear:**
     - `backend/src/routes/import.ts`
     - `backend/src/controllers/importController.ts`
     - `backend/src/plugins/importJobs.ts` (cola en proceso; migrable a Redis/BullMQ)
   - **Criterio de aceptación:** E2E de import completo pasa en CI (con binarios instalados según sea necesario).

**Decisiones tomadas**

- `chdman` soporte: opcional. Si está instalado, lo usaremos; si no, se calcula checksum y se trata como blob.
- Endpoint `POST /api/import/scan`: no recibe `path`; la ruta a las ROMs se configura en el sistema (env var `ROMS_PATH`).
- El job se ejecuta en background; el frontend lanza el job a petición del usuario (botón "Scan").
- Añadir `IMPORT_CONCURRENCY` (env var). Valor por defecto: `min(8, max(1, os.cpus().length - 1))` si no se configura.
- Tests que dependen de binarios (7z/chdman): se incluirán como tests de integración y se habilitarán en CI (instalación de binarios en workflow).

**Open Questions (resueltas por el usuario):**

1. Soporte `chdman` opcional — Aprobado.
2. No enviar `path` en payload; usar ruta preconfigurada — Aprobado (`ROMS_PATH`).
3. Job en background — Aprobado.
4. `IMPORT_CONCURRENCY` variable y fórmula por defecto — Aprobado.
5. Incluir tests dependientes de binarios y instalarlos en CI — Aprobado.

**Siguientes pasos (Phase 4.1 - TDD):**

1. Crear fixtures y tests unitarios marcados en Phase 4.1.
2. Ejecutar `yarn --cwd backend test` y observar tests fallidos.
3. Implementar servicios mínimos en Phase 4.2 para pasar tests básicos.

---

Metadatos:

- Autor: GitHub Copilot
- Fecha: 2026-02-08