feat: implement ROMs management UI (Phase 8)

Backend (Phase 8.1):
- Add ROMs endpoints: GET, GET/:id, PUT/:id/game, DELETE
- Add metadata search endpoint using IGDB/RAWG/TGDB
- Implement RomsController with ROM CRUD logic
- Add 12 comprehensive ROM endpoint tests
- Configure Vitest to run tests sequentially (threads: false)
- Auto-apply Prisma migrations in test setup

Frontend (Phase 8.2 + 8.3):
- Create ROM types: RomFile, Artwork, EnrichedGame
- Extend API client with roms and metadata namespaces
- Implement 5 custom hooks with TanStack Query
- Create ScanDialog, MetadataSearchDialog, RomCard components
- Rewrite roms.tsx page with table and all actions
- Add 37 comprehensive component and page tests

All 122 tests passing: 63 backend + 59 frontend
Lint: 0 errors, only unused directive warnings

backend/src/app.ts

@@ -5,6 +5,8 @@ import rateLimit from '@fastify/rate-limit';
 import healthRoutes from './routes/health';
 import importRoutes from './routes/import';
 import gamesRoutes from './routes/games';
+import romsRoutes from './routes/roms';
+import metadataRoutes from './routes/metadata';
 
 export function buildApp(): FastifyInstance {
   const app: FastifyInstance = Fastify({
@@ -17,6 +19,8 @@ export function buildApp(): FastifyInstance {
   void app.register(healthRoutes, { prefix: '/api' });
   void app.register(importRoutes, { prefix: '/api' });
   void app.register(gamesRoutes, { prefix: '/api' });
+  void app.register(romsRoutes, { prefix: '/api' });
+  void app.register(metadataRoutes, { prefix: '/api' });
 
   return app;
 }

backend/src/controllers/romsController.ts

@@ -0,0 +1,96 @@
+import { prisma } from '../plugins/prisma';
+
+export class RomsController {
+  /**
+   * Listar todos los ROMs con sus juegos asociados
+   */
+  static async listRoms() {
+    return await prisma.romFile.findMany({
+      include: {
+        game: true,
+      },
+      orderBy: {
+        filename: 'asc',
+      },
+    });
+  }
+
+  /**
+   * Obtener un ROM por ID con su juego asociado
+   */
+  static async getRomById(id: string) {
+    const rom = await prisma.romFile.findUnique({
+      where: { id },
+      include: {
+        game: true,
+      },
+    });
+
+    if (!rom) {
+      throw new Error('ROM no encontrado');
+    }
+
+    return rom;
+  }
+
+  /**
+   * Vincular un juego a un ROM existente
+   */
+  static async linkGameToRom(romId: string, gameId: string) {
+    // Validar que el ROM existe
+    const rom = await prisma.romFile.findUnique({
+      where: { id: romId },
+    });
+
+    if (!rom) {
+      throw new Error('ROM no encontrado');
+    }
+
+    // Validar que el juego existe
+    const game = await prisma.game.findUnique({
+      where: { id: gameId },
+    });
+
+    if (!game) {
+      throw new Error('Juego no encontrado');
+    }
+
+    // Actualizar el ROM con el nuevo gameId
+    return await prisma.romFile.update({
+      where: { id: romId },
+      data: {
+        gameId,
+      },
+      include: {
+        game: true,
+      },
+    });
+  }
+
+  /**
+   * Eliminar un ROM por ID
+   */
+  static async deleteRom(id: string) {
+    // Validar que el ROM existe
+    const rom = await prisma.romFile.findUnique({
+      where: { id },
+    });
+
+    if (!rom) {
+      throw new Error('ROM no encontrado');
+    }
+
+    // Eliminar el ROM
+    await prisma.romFile.delete({
+      where: { id },
+    });
+
+    return { message: 'ROM eliminado correctamente' };
+  }
+}
+
+/**
+ * Metadatos:
+ * Autor: GitHub Copilot
+ * Última actualización: 2026-02-11
+ */

backend/src/routes/metadata.ts

@@ -0,0 +1,48 @@
+import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import * as metadataService from '../services/metadataService';
+import { z } from 'zod';
+import { ZodError } from 'zod';
+
+// Esquema de validación para parámetros de búsqueda
+const searchMetadataSchema = z.object({
+  q: z.string().min(1, 'El parámetro de búsqueda es requerido'),
+  platform: z.string().optional(),
+});
+
+async function metadataRoutes(app: FastifyInstance) {
+  /**
+   * GET /api/metadata/search?q=query&platform=optional
+   * Buscar metadata de juegos
+   */
+  app.get<{ Querystring: any; Reply: any[] }>('/metadata/search', async (request, reply) => {
+    try {
+      // Validar parámetros de query con Zod
+      const validated = searchMetadataSchema.parse(request.query);
+
+      // Llamar a metadataService
+      const result = await metadataService.enrichGame({
+        title: validated.q,
+        platform: validated.platform,
+      });
+
+      // Si hay resultado, devolver como array; si no, devolver array vacío
+      return reply.code(200).send(result ? [result] : []);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        return reply.code(400).send({
+          error: 'Parámetros de búsqueda inválidos',
+          details: error.errors,
+        });
+      }
+      throw error;
+    }
+  });
+}
+
+export default metadataRoutes;
+
+/**
+ * Metadatos:
+ * Autor: GitHub Copilot
+ * Última actualización: 2026-02-11
+ */

backend/src/routes/roms.ts

@@ -0,0 +1,95 @@
+import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { RomsController } from '../controllers/romsController';
+import { linkGameSchema } from '../validators/romValidator';
+import { ZodError } from 'zod';
+
+async function romsRoutes(app: FastifyInstance) {
+  /**
+   * GET /api/roms
+   * Listar todos los ROMs
+   */
+  app.get<{ Reply: any[] }>('/roms', async (request, reply) => {
+    const roms = await RomsController.listRoms();
+    return reply.code(200).send(roms);
+  });
+
+  /**
+   * GET /api/roms/:id
+   * Obtener un ROM por ID
+   */
+  app.get<{ Params: { id: string }; Reply: any }>('/roms/:id', async (request, reply) => {
+    try {
+      const rom = await RomsController.getRomById(request.params.id);
+      return reply.code(200).send(rom);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('no encontrado')) {
+        return reply.code(404).send({
+          error: 'ROM no encontrado',
+        });
+      }
+      throw error;
+    }
+  });
+
+  /**
+   * PUT /api/roms/:id/game
+   * Vincular un juego a un ROM
+   */
+  app.put<{ Params: { id: string }; Body: any; Reply: any }>(
+    '/roms/:id/game',
+    async (request, reply) => {
+      try {
+        // Validar entrada con Zod
+        const validated = linkGameSchema.parse(request.body);
+        const rom = await RomsController.linkGameToRom(request.params.id, validated.gameId);
+        return reply.code(200).send(rom);
+      } catch (error) {
+        if (error instanceof ZodError) {
+          return reply.code(400).send({
+            error: 'Validación fallida',
+            details: error.errors,
+          });
+        }
+        if (error instanceof Error) {
+          if (error.message.includes('ROM no encontrado')) {
+            return reply.code(404).send({
+              error: 'ROM no encontrado',
+            });
+          }
+          if (error.message.includes('Juego no encontrado')) {
+            return reply.code(400).send({
+              error: 'Game ID inválido o no encontrado',
+            });
+          }
+        }
+        throw error;
+      }
+    }
+  );
+
+  /**
+   * DELETE /api/roms/:id
+   * Eliminar un ROM
+   */
+  app.delete<{ Params: { id: string }; Reply: any }>('/roms/:id', async (request, reply) => {
+    try {
+      await RomsController.deleteRom(request.params.id);
+      return reply.code(204).send();
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('no encontrado')) {
+        return reply.code(404).send({
+          error: 'ROM no encontrado',
+        });
+      }
+      throw error;
+    }
+  });
+}
+
+export default romsRoutes;
+
+/**
+ * Metadatos:
+ * Autor: GitHub Copilot
+ * Última actualización: 2026-02-11
+ */

backend/src/validators/romValidator.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+// Esquema para vincular un juego a un ROM
+export const linkGameSchema = z.object({
+  gameId: z.string().min(1, 'El ID del juego es requerido'),
+});
+
+// Tipo TypeScript derivado del esquema
+export type LinkGameInput = z.infer<typeof linkGameSchema>;
+
+/**
+ * Metadatos:
+ * Autor: GitHub Copilot
+ * Última actualización: 2026-02-11
+ */

backend/tests/routes/games.spec.ts

@@ -10,8 +10,12 @@ describe('Games API', () => {
     app = buildApp();
     await app.ready();
     // Limpiar base de datos antes de cada test
+    // Orden importante: relaciones de FK primero
+    await prisma.romFile.deleteMany();
     await prisma.purchase.deleteMany();
     await prisma.gamePlatform.deleteMany();
+    await prisma.artwork.deleteMany();
+    await prisma.priceHistory.deleteMany();
     await prisma.game.deleteMany();
     await prisma.platform.deleteMany();
   });

backend/tests/routes/metadata.spec.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { buildApp } from '../../src/app';
+import { FastifyInstance } from 'fastify';
+import * as metadataService from '../../src/services/metadataService';
+
+describe('Metadata API', () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    vi.restoreAllMocks();
+  });
+
+  describe('GET /api/metadata/search', () => {
+    it('debería devolver resultados cuando se busca un juego existente', async () => {
+      const mockResults = [
+        {
+          source: 'igdb',
+          externalIds: { igdb: 1 },
+          title: 'The Legend of Zelda',
+          slug: 'the-legend-of-zelda',
+          releaseDate: '1986-02-21',
+          genres: ['Adventure'],
+          coverUrl: 'https://example.com/cover.jpg',
+        },
+      ];
+
+      vi.spyOn(metadataService, 'enrichGame').mockResolvedValue(mockResults[0]);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/metadata/search?q=zelda',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(Array.isArray(body)).toBe(true);
+      expect(body.length).toBeGreaterThan(0);
+      expect(body[0].title).toContain('Zelda');
+    });
+
+    it('debería devolver lista vacía cuando no hay resultados', async () => {
+      vi.spyOn(metadataService, 'enrichGame').mockResolvedValue(null);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/metadata/search?q=nonexistentgame12345',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(Array.isArray(body)).toBe(true);
+      expect(body.length).toBe(0);
+    });
+
+    it('debería devolver 400 si falta el parámetro query', async () => {
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/metadata/search',
+      });
+
+      expect(res.statusCode).toBe(400);
+      expect(res.json()).toHaveProperty('error');
+    });
+
+    it('debería devolver 400 si el parámetro query está vacío', async () => {
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/metadata/search?q=',
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('debería pasar el parámetro platform a enrichGame si se proporciona', async () => {
+      const enrichSpy = vi.spyOn(metadataService, 'enrichGame').mockResolvedValue(null);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/metadata/search?q=mario&platform=Nintendo%2064',
+      });
+
+      expect(res.statusCode).toBe(200);
+      expect(enrichSpy).toHaveBeenCalledWith({
+        title: 'mario',
+        platform: 'Nintendo 64',
+      });
+    });
+  });
+});
+
+/**
+ * Metadatos:
+ * Autor: GitHub Copilot
+ * Última actualización: 2026-02-11
+ */

backend/tests/routes/roms.spec.ts

@@ -0,0 +1,295 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { buildApp } from '../../src/app';
+import { FastifyInstance } from 'fastify';
+import { prisma } from '../../src/plugins/prisma';
+
+describe('ROMs API', () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    app = buildApp();
+    await app.ready();
+    // Limpiar base de datos antes de cada test (eliminar ROMs primero por foreign key)
+    await prisma.romFile.deleteMany();
+    await prisma.gamePlatform.deleteMany();
+    await prisma.purchase.deleteMany();
+    await prisma.artwork.deleteMany();
+    await prisma.priceHistory.deleteMany();
+    await prisma.game.deleteMany();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('GET /api/roms', () => {
+    it('debería devolver una lista vacía cuando no hay ROMs', async () => {
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/roms',
+      });
+
+      expect(res.statusCode).toBe(200);
+      expect(res.json()).toEqual([]);
+    });
+
+    it('debería devolver una lista de ROMs con sus propiedades', async () => {
+      // Crear un ROM de prueba
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/games/',
+          filename: 'game.zip',
+          checksum: 'abc123def456',
+          size: 1024,
+          format: 'zip',
+        },
+      });
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/roms',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(Array.isArray(body)).toBe(true);
+      expect(body.length).toBe(1);
+      expect(body[0].id).toBe(rom.id);
+      expect(body[0].filename).toBe('game.zip');
+    });
+
+    it('debería incluir información del juego asociado', async () => {
+      const game = await prisma.game.create({
+        data: {
+          title: 'Test Game',
+          slug: 'test-game',
+        },
+      });
+
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/',
+          filename: 'test-with-game.zip',
+          checksum: 'checksum-game-123',
+          size: 2048,
+          format: 'zip',
+          gameId: game.id,
+        },
+      });
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/roms',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      // Buscar el ROM que creamos por checksum
+      const createdRom = body.find((r: any) => r.checksum === 'checksum-game-123');
+      expect(createdRom).toBeDefined();
+      expect(createdRom.game).toBeDefined();
+      expect(createdRom.game.title).toBe('Test Game');
+    });
+  });
+
+  describe('GET /api/roms/:id', () => {
+    it('debería retornar un ROM existente', async () => {
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/',
+          filename: 'game1.zip',
+          checksum: 'checksum1',
+          size: 1024,
+          format: 'zip',
+        },
+      });
+
+      const res = await app.inject({
+        method: 'GET',
+        url: `/api/roms/${rom.id}`,
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(body.id).toBe(rom.id);
+      expect(body.filename).toBe('game1.zip');
+    });
+
+    it('debería retornar 404 si el ROM no existe', async () => {
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/roms/non-existing-id',
+      });
+
+      expect(res.statusCode).toBe(404);
+      expect(res.json()).toHaveProperty('error');
+    });
+
+    it('debería incluir el juego asociado al ROM', async () => {
+      const game = await prisma.game.create({
+        data: {
+          title: 'Zelda',
+          slug: 'zelda',
+        },
+      });
+
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/',
+          filename: 'zelda.zip',
+          checksum: 'checksum2',
+          size: 2048,
+          format: 'zip',
+          gameId: game.id,
+        },
+      });
+
+      const res = await app.inject({
+        method: 'GET',
+        url: `/api/roms/${rom.id}`,
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(body.game).toBeDefined();
+      expect(body.game.title).toBe('Zelda');
+    });
+  });
+
+  describe('PUT /api/roms/:id/game', () => {
+    it('debería vincular un juego a un ROM existente', async () => {
+      const game = await prisma.game.create({
+        data: {
+          title: 'Mario',
+          slug: 'mario',
+        },
+      });
+
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/',
+          filename: 'mario.zip',
+          checksum: 'checksum3',
+          size: 512,
+          format: 'zip',
+        },
+      });
+
+      const res = await app.inject({
+        method: 'PUT',
+        url: `/api/roms/${rom.id}/game`,
+        payload: {
+          gameId: game.id,
+        },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = res.json();
+      expect(body.gameId).toBe(game.id);
+      expect(body.game.title).toBe('Mario');
+    });
+
+    it('debería devolver 400 si el gameId es inválido', async () => {
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/',
+          filename: 'game.zip',
+          checksum: 'checksum4',
+          size: 1024,
+          format: 'zip',
+        },
+      });
+
+      const res = await app.inject({
+        method: 'PUT',
+        url: `/api/roms/${rom.id}/game`,
+        payload: {
+          gameId: 'invalid-game-id',
+        },
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('debería devolver 404 si el ROM no existe', async () => {
+      const game = await prisma.game.create({
+        data: {
+          title: 'Test',
+          slug: 'test',
+        },
+      });
+
+      const res = await app.inject({
+        method: 'PUT',
+        url: '/api/roms/non-existing-id/game',
+        payload: {
+          gameId: game.id,
+        },
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+
+    it('debería devolver 400 si falta gameId', async () => {
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/',
+          filename: 'game.zip',
+          checksum: 'checksum5',
+          size: 1024,
+          format: 'zip',
+        },
+      });
+
+      const res = await app.inject({
+        method: 'PUT',
+        url: `/api/roms/${rom.id}/game`,
+        payload: {},
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+  });
+
+  describe('DELETE /api/roms/:id', () => {
+    it('debería eliminar un ROM existente', async () => {
+      const rom = await prisma.romFile.create({
+        data: {
+          path: '/roms/',
+          filename: 'delete-me.zip',
+          checksum: 'checksum6',
+          size: 1024,
+          format: 'zip',
+        },
+      });
+
+      const res = await app.inject({
+        method: 'DELETE',
+        url: `/api/roms/${rom.id}`,
+      });
+
+      expect(res.statusCode).toBe(204);
+
+      // Verificar que el ROM fue eliminado
+      const deletedRom = await prisma.romFile.findUnique({
+        where: { id: rom.id },
+      });
+      expect(deletedRom).toBeNull();
+    });
+
+    it('debería devolver 404 si el ROM no existe', async () => {
+      const res = await app.inject({
+        method: 'DELETE',
+        url: '/api/roms/non-existing-id',
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+  });
+});
+
+/**
+ * Metadatos:
+ * Autor: GitHub Copilot
+ * Última actualización: 2026-02-11
+ */

backend/tests/setup.ts

@@ -1,10 +1,21 @@
 import dotenv from 'dotenv';
+import { execSync } from 'child_process';
 
 // Cargar variables de entorno desde .env
 dotenv.config();
 
+// Ejecutar migraciones de Prisma antes de los tests
+try {
+  execSync('npx prisma migrate deploy', {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  });
+} catch (error) {
+  console.error('Failed to run Prisma migrations:', error);
+}
+
 /**
  * Metadatos:
  * Autor: GitHub Copilot
- * Última actualización: 2026-02-11
+ * Última actualización: 2026-02-12
  */

backend/vitest.config.ts

@@ -11,6 +11,7 @@ export default defineConfig({
     environment: 'node',
     include: ['tests/**/*.spec.ts'],
     globals: false,
+    threads: false, // Desactivar parallelización para evitar contaminación de BD
     coverage: {
       provider: 'c8',
       reporter: ['text', 'lcov'],