quasar/docs/lessons-learned.md

Lecciones aprendidas y recomendaciones técnicas

Lista priorizada de funcionalidades útiles para el MVP (justificación breve)

1. Import local y verificación básica (hashes/DATs) — esencial: permite que el usuario confirme posesión y garantiza integridad. (Crítico)
2. Enriquecimiento de metadata con fallback en cadena (IGDB → RAWG → TheGamesDB → ScreenScraper) — mejora cobertura y calidad; reduce fallos por datos incompletos.
3. Interfaz de biblioteca básica + búsqueda y filtros — UX central para adopción temprana.
4. Caching de artwork y metadatos (LRU) — reduce llamadas a APIs y mejora rendimiento offline.
5. DAT verification y reporting (No‑Intro/Redump) — importante para usuarios avanzados que quieren sets consistentes.
6. Campos personalizados (compra, precio, notas) — capturar historial de propiedad o compras.
7. Integración opcional de price tracking (PriceCharting / IsThereAnyDeal / eBay) — útil pero no crítico para primer lanzamiento.

---

Patrones comunes observados

• Import local + escaneo incremental (evitar rehash completo en cada arranque).
• Verificación mediante DATs y checksums (CRC/MD5/SHA1) con distinto "nivel" de escaneo (rápido vs. exhaustivo).
• Cadena de fallback para scrapers: API principal → API secundaria → recurso comunitario → fallback manual.
• Cache de artwork con fallback offline y opción de refresco manual.
• Campos personalizados para historial de compra y notas, frecuentemente añadidos por usuarios.

---

Recomendaciones técnicas (stack y librerías útiles)

• Arquitectura: Backend (Node.js + TypeScript / Python Flask) + Postgres (JSONB para campos flexibles) + Redis para caching y rate-limiting.
• Checksum / DATs: usar librerías nativas (Node: crypto, Python: hashlib) y utilidades (chdman para CHD, libarchive/jszip para archives); para DAT parsing, reusar implementaciones existentes (RomVault/Dat readers) si licencia lo permite.
• Cache / LRU: Redis con TTL o librerías LRU (node-lru-cache) para assets en memoria; S3 compatible para almacenamiento de artwork en producción.
• Queue / Background jobs: Bull / Sidekiq para trabajos de scraping y actualización masiva.
• Rate limiting: Implementar token bucket / backoff y conteo por API (respetar 429 y Retry-After).
• Herramientas: sharp para procesamiento de imágenes; axios / node-fetch con retries; pm2 para procesos en producción.

---

Puntos a evitar

• No implementar características que faciliten la piratería (búsqueda/descarga automática de ROMs, enlaces a repos de ROMs).
• Evitar scraping masivo sin acuerdo (puede violar TOS y exponer a bloqueos legales).
• Evitar dependencias propietarias críticas si no se puede negociar un contrato claro.

---

PoC propuesta

PoC propuesta: Backend mínimo (Node/Express) que implemente search IGDB + RAWG y cache LRU de 24h

• Backend mínimo: Node/Express (JavaScript o TypeScript) con endpoints REST simples.
• Endpoint primario: GET /api/search?query=<término> que combine resultados de IGDB (primario) y RAWG (fallback) y normalice campos.
• Cache: LRU en memoria con TTL 24h (ej. node-lru-cache) y opción a Redis con TTL para producción.
• Control de uso: contadores por API y por usuario/IP, circuit breaker y backoff (respetar 429 y header Retry-After).
• Nota: incluir endpoints de privacidad en PoC: GET /api/me/export, DELETE /api/me/delete; retención de logs de aceptación = 2 años.
• Métrica y plan de pruebas: desplegar PoC y medir 1 semana para observar 429, latencia y ratio de cache hit/miss; ajustar estrategia de caching y necesidad de acuerdos comerciales.
• Resultado esperado: validar límites reales, estimar coste y decidir si se requieren acuerdos/premium APIs.

Nota sobre licencias: Si se incorpora código o herramientas bajo GPL, documentar las implicaciones de redistribución y empaquetado; preferir licencias permisivas (MIT/BSD) para componentes que se redistribuirán o empaquetarán con el servicio. Realizar verificación de compatibilidad de licencias y documentar cualquier restricción (compatibilidad de licencias).

Fuentes y lecturas recomendadas

• Proyectos principales: Playnite, LaunchBox, OpenEmu, RetroArch (ver sus repos y docs)
• Herramientas de verificación: ROMVault, No‑Intro (dat‑o‑matic), Redump
• APIs y pricing: IGDB, RAWG, TheGamesDB, ScreenScraper, PriceCharting, IsThereAnyDeal

Metadatos

• Autor: Quasar (investigación automatizada)
• Última actualización: 2026-02-07
• Fecha verificación: 2026-02-07

Resumen: Priorizar import local + verificación + metadata (con fallbacks) y construir una arquitectura que respete límites de APIs y licencias; las integraciones de precio/ofertas pueden añadirse en una fase posterior tras validar acuerdos comerciales.