Refactor code structure for improved readability and maintainability

docs/01-conceptos/requirements.md

@@ -0,0 +1,89 @@
+# 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