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/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
+ */