docs

docs/lessons-learned.md

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