# Requisitos — Fase 2: Requisitos y criterios de aceptación

## Resumen breve del propósito (MVP)

Quasar es una aplicación **local-first** y **self‑hosted** para gestionar una colección personal de videojuegos: escanear ROMs locales, registrar juegos físicos y digitales, enriquecer metadata (portadas, géneros, fechas) desde APIs públicas, y permitir exportación/importación de la colección. El MVP debe ser utilizable en un entorno de una única máquina/usuario con opción de evolucionar a despliegues multiusuario.

---

## Requisitos funcionales (priorizados)

| #   | Requisito                                         | Prioridad | Criterio mínimo de aceptación                                                                                                               |
| --- | ------------------------------------------------- | --------: | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | Escaneo e importación de ROMs locales (recursivo) |    **P0** | Detecta archivos en directorio configurado, calcula checksum y crea entrada `RomFile` con metadata básica (nombre, tamaño, ruta, checksum). |
| 2   | CRUD de juegos y vinculación de ROMs              |    **P0** | Crear/editar/eliminar juegos; vincular/desvincular archivos ROM a un juego.                                                                 |
| 3   | Enriquecimiento de metadata (IGDB / RAWG)         |    **P0** | Buscar por título y aplicar metadata seleccionada (cover, géneros, fecha).                                                                  |
| 4   | Gestión de artwork local                          |    **P0** | Descargar portada al almacenamiento local optimizado y servirla desde el backend.                                                           |
| 5   | Exportar/Importar (CSV/JSON)                      |    **P0** | Exportar la lista de juegos con campos clave; importar (básico) para recuperación.                                                          |
| 6   | Registro de compras y precios                     |    **P1** | Añadir registro de compra con precio, moneda, fecha y opcionalmente recibo.                                                                 |
| 7   | Dedupe y verificación por checksum                |    **P1** | Detectar duplicados por checksum y ofrecer opciones (fusionar, ignorar).                                                                    |
| 8   | Filtrado, búsqueda y etiquetado                   |    **P1** | Búsqueda por título, plataforma, etiquetas y filtros básicos.                                                                               |
| 9   | Backups y restauración básicos                    |    **P1** | Exportar DB y assets; restaurar desde exportación.                                                                                          |
| 10  | Configuración de carpetas y preferencias          |    **P2** | Interfaz para configurar rutas de escaneo, límites y opciones de importación.                                                               |

---

## Requisitos no funcionales

- **Seguridad**: No almacenar credenciales en el repositorio; variables sensibles en `.env` y GitHub Secrets en CI; saneamiento y validación de inputs en backend.
- **Privacidad**: Local-first por defecto; telemetría deshabilitada.
- **Rendimiento**: Escaneos y enriquecimiento deben ejecutarse como trabajos asíncronos; hashing con streaming para archivos grandes.
- **Escalabilidad y portabilidad**: Arquitectura preparada para migrar de SQLite (dev/local) a Postgres (producción).
- **Disponibilidad**: Backups regulares y endpoint de salud; tolerar fallos de APIs externas con retries y cola.

---

## Casos de uso principales y flujos de usuario

### 1) Importar ROMs (escaneo automático)

1. Usuario configura ruta(s) de escaneo.
2. Backend inicia job de escaneo (worker).
3. Para cada archivo: calcular checksum, extraer tamaño/fecha, crear `RomFile`.
4. Si hay duplicados por checksum, marcar y notificar al usuario.
5. Ofrecer emparejado automático con juegos existentes o sugerir búsqueda externa.

### 2) Crear juego manual

1. Usuario abre formulario "Nuevo juego".
2. Rellenar título, plataforma, fecha, tags, descripción.
3. Guardar y opcionalmente vincular ROM(s) existentes.

### 3) Buscar / enriquecer metadata

1. Usuario busca por título en la UI -> backend consulta IGDB/RAWG.
2. Mostrar resultados con mini-previsualización (cover, plataformas, fecha).
3. Usuario selecciona resultado y aplica metadata al registro local.

### 4) Registrar compra

1. Desde la ficha del juego, usuario añade una compra (precio, moneda, tienda, fecha).
2. Opcionalmente adjunta imagen del recibo.

### 5) Exportar CSV / JSON

1. Usuario elige formato y filtros (plataforma, tags).
2. Backend genera el archivo y lo descarga.

---

## Criterios de aceptación del MVP (ejemplos testables)

- Escanear un directorio y listar ROMs con nombre, tamaño y checksum.
- Crear/leer/editar/eliminar un juego y vincular al menos un `RomFile`.
- Buscar en una API externa y aplicar metadata a un juego.
- Descargar y servir una portada optimizada localmente.
- Exportar colección en CSV y JSON.

---

## Fuentes

- IGDB, RAWG, TheGamesDB (documentación pública).
- Buenas prácticas: Documentación de Prisma, Fastify, React y TanStack Query/Router.

---

**Metadatos**
Autor: Quasar (investigación automatizada)
Última actualización: 2026-02-07