GameS (Gestor de Videojuegos)

Plataforma web para descubrir, organizar y gestionar videojuegos, con búsqueda avanzada, historial de precios y recomendaciones personalizadas.

Características Destacadas

+100K Juegos en BD

Tiempo Real Seguimiento

Precios Históricos

JWT Auth Seguro

Redis Cache Ultra Rápido

Inicio Rápido · Documentación · Problemas

Tabla de Contenidos

• Sobre el Proyecto
• Demo y Capturas
• Stack Tecnológico
• Arquitectura
• Inicio Rápido
  • Requisitos Previos
  • Instalación
  • Variables de Entorno
  • Configuración Inicial
• Uso
• API REST
  • Autenticación
  • Endpoints Principales
• Scripts Disponibles
• Estructura del Proyecto
• Pruebas
• Despliegue
• Solución de Problemas
• FAQ
• Licencia y Derechos

Sobre el Proyecto

GameS es un gestor de videojuegos conceptualizado y desarrollado para ofrecer una experiencia completa a los apasionados de los juegos. Permite a los usuarios consultar información extraída de IGDB, planificar sus sesiones, administrar bibliotecas personales, hacer un seguimiento del tiempo y descubrir las mejores ofertas y precios históricos del mercado de claves. Todo bajo una interfaz estilizada y responsiva con un backend dinámico preparado para optimización por tráfico.

Características Principales

Demo y Capturas

Bienvenida

Catálogo de Juegos

Biblioteca Personal

Perfil de Usuario

Stack Tecnológico

APIs Externas

• IGDB API (Twitch) - Base de datos de videojuegos
• AllKeyShop - Comparador de precios de claves

Arquitectura

Inicio Rápido

Requisitos Previos

Asegúrate de contar con lo siguiente instalado en tu host o máquina de despliegue:

• Docker >= 20.x
• Docker Compose >= 2.x
• En caso de ejecutar en formato de pre-desarrollo local y nativo, precisarás Node.js v20+, Python 3.10+, MySQL Server 8+, Redis 7+

Instalación

# 1. Clonar el repositorio
git clone https://github.com/alvarosac99/GameS.git
cd GameS

# 2. Configurar las variables de entorno
cp .env_example .env
# IMPORTANTE: Reemplazar las credenciales, secrets y hosts vacíos del .env de manera acorde.

# 3. Construir y Levantar servicios (Modo Producción con Compose)
docker-compose up -d --build

# (Opcional - Levantando únicamente Frontend aisladamente)
cd frontend
npm install
npm run dev

Variables de Entorno

Variables a completar alojadas en .env:

Generar DJANGO_SECRET_KEY

# Generar una clave secreta segura
python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Configuración Inicial

Una vez levantados los contenedores, es necesario realizar la configuración inicial:

# 1. Ejecutar migraciones de base de datos
docker-compose exec backend python manage.py migrate

# 2. Crear superusuario para el panel de administración
docker-compose exec backend python manage.py createsuperuser

# 3. (Opcional) Cargar datos de prueba
docker-compose exec backend python manage.py loaddata initial_data

# 4. Verificar que Redis está funcionando
docker-compose exec redis redis-cli ping
# Debería responder: PONG

# 5. Acceder a la aplicación
# Frontend: http://localhost (o tu dominio configurado)
# Admin Django: http://localhost/admin

Tip: La primera vez que accedas, el sistema sincronizará automáticamente la base de datos de IGDB con Redis. Este proceso puede tardar varios minutos dependiendo de tu conexión.

Uso

Estructura base

La aplicación centraliza la experiencia en el frontend expuesto nativamente en los puertos de Nginx (habitualmente 443 vía TLS si Cloudflare está enganchado o por el 80 directo).

Redis inicializa inmediatamente una captura del repositorio de IGDB la primera vez que inicia o durante horas de baja actividad programada para almacenar localmente lo mas destacable de la red y optimizar las búsquedas.

Gestión Automática

Nginx se gestiona de forma global en nginx-central fuera del contenedor (para configuraciones custom multiproyecto del host), sin embargo, este proyecto cuenta con un volumen específico ./nginx/conf.d incrustado como solo-lectura para configurar sus virtualhosts de forma modularizada y escalable.

API REST

La API REST de GameS proporciona endpoints para todas las funcionalidades principales del sistema.

Autenticación

El sistema utiliza JWT (JSON Web Tokens) para la autenticación:

# 1. Obtener token de acceso
curl -X POST http://localhost/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "tu_usuario", "password": "tu_contraseña"}'

# Respuesta:
{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

# 2. Usar el token en peticiones
curl -X GET http://localhost/api/juegos/ \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

# 3. Refrescar token expirado
curl -X POST http://localhost/api/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."}'

Endpoints Principales

Ejemplo de búsqueda avanzada

# Buscar juegos por título, género y plataforma
curl -X GET "http://localhost/api/juegos/buscar/?q=zelda&genero=RPG&plataforma=Switch&limit=10" \
  -H "Authorization: Bearer tu_token"

# Respuesta:
{
  "count": 15,
  "next": "http://localhost/api/juegos/buscar/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1234,
      "nombre": "The Legend of Zelda: Breath of the Wild",
      "portada": "https://...",
      "rating": 97,
      "generos": ["Action", "Adventure", "RPG"],
      "plataformas": ["Switch"],
      "fecha_lanzamiento": "2017-03-03"
    }
  ]
}

Ejemplo de registro de sesión de juego

# Registrar sesión de juego
curl -X POST http://localhost/api/actividad/ \
  -H "Authorization: Bearer tu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "juego_id": 1234,
    "duracion_minutos": 120,
    "fecha": "2025-02-21",
    "notas": "Completada la primera mazmorra"
  }'

# Respuesta:
{
  "id": 567,
  "juego": {
    "id": 1234,
    "nombre": "The Legend of Zelda: Breath of the Wild"
  },
  "duracion_minutos": 120,
  "fecha": "2025-02-21T14:30:00Z",
  "notas": "Completada la primera mazmorra"
}

Scripts Disponibles

Frontend (NPM)

Comando	Descripción
npm run dev	Servidor de desarrollo con hot reload en localhost:5173
npm run build	Compilación optimizada para producción
npm run lint	Análisis estático con ESLint
npm run preview	Preview del build de producción
npm run test	Ejecutar tests unitarios

Backend (Django)

Comando	Descripción
python manage.py migrate	Aplicar migraciones a la BD
python manage.py makemigrations	Crear nuevas migraciones
python manage.py createsuperuser	Crear usuario administrador
python manage.py runserver	Servidor desarrollo en localhost:8000
python manage.py test	Ejecutar suite de tests
python manage.py collectstatic	Recopilar archivos estáticos
python manage.py sync_igdb	Sincronizar con IGDB
python manage.py actualizar_precios	Actualizar precios de juegos

Docker

Comando	Descripción
docker-compose up -d	Levantar todos los servicios en background
docker-compose down	Detener todos los servicios
docker-compose logs -f [servicio]	Ver logs en tiempo real
docker-compose ps	Ver estado de contenedores
docker-compose restart [servicio]	Reiniciar servicio específico
docker-compose exec backend bash	Acceder a shell del backend

Tip: En producción con Docker, Gunicorn arranca automáticamente con gunicorn gestor_videojuegos.wsgi:application --bind 0.0.0.0:8000

Estructura del Proyecto

GameS/
├── backend/                # Aplicación en Django Rest Framework
│   ├── actividad/          # Lógica para registro de actividades y estadísticas
│   ├── apiPrecios/         # Core Scraper y parser de APIs comerciales (Aks)
│   ├── comentarios/        # Gestión del sistema social de reseñas
│   ├── gestor_videojuegos/ # Entrada principal, urls core y Settings.
│   ├── juegos/             # Gestión de la caché Redis e integracion con IGDB.
│   ├── notificaciones/     # Envío de alertas on-the-fly al front.
│   ├── usuarios/           # Custom User Auth, perfiles en JWT y recomendaciones.
│   ├── manage.py           # CLI de desarrollo nativo Django
│   └── requirements.txt    # Manifiesto de PIP Python
├── frontend/               # SPA construida con React + Vite
│   ├── public/             # Estáticos base, íconos y Favicon de identidad
│   ├── src/                # Vistas, context, utilidades, librerías y componentes.
│   ├── package.json        # Deps de NPM (+ Tailwind, Radix)
│   └── vite.config.js      # Rulesets de bundler
├── nginx/                  # Reglas del proxy Nginx para el módulo GameS
├── cloudflare/             # Certificados TLS preconfigurados mTLS/Origin
├── docker-compose.yml      # Declarativa Infra con BD, Backend, Frontend y Caché
└── README.md               # Esta extensa hoja de Vida del proyecto

Pruebas

Lanza la consola interactiva test del framework de Python directamente con:

cd backend
python manage.py test

Verificación del Frontend (Análisis estático modularizado):

cd frontend
npm run lint

Despliegue

La plataforma usa docker-compose atada fuertemente a mecanismos del orquestador exterior:

• Consta de etiquetas de Sablier (sablier.enable=true / sablier.strategy=dynamic) en el servicio del backend, dispuestas para paralogizar auto-suspensión de los bins Docker bajo falta de tráfico web, optimizando al máximo un despliegue VPS o Host de baja capacidad.
• Contempla el enrutamiento directo de sus volúmenes hacia la recolección estática (media_data), y la incrustación de certificados firmados por Cloudflare.

docker-compose --env-file .env up --build -d

Optimizaciones de Producción

El proyecto incluye varias optimizaciones para entornos de producción:

• Auto-suspensión con Sablier: Los contenedores se suspenden automáticamente cuando no hay tráfico, reduciendo el consumo de recursos
• Caché Redis: Base de datos de juegos completamente cacheada para respuestas instantáneas
• Compresión Nginx: Assets comprimidos con gzip/brotli para tiempos de carga menores
• Certificados TLS: Integración lista con Cloudflare Origin Certificates
• Gunicorn Workers: Configuración optimizada de workers basada en CPU cores disponibles

Solución de Problemas

Error: "Connection refused" al acceder a la aplicación

Problema: No se puede conectar a la aplicación después del despliegue.

Solución:

# 1. Verificar que todos los contenedores están ejecutándose
docker-compose ps

# 2. Verificar logs de los servicios
docker-compose logs backend
docker-compose logs nginx

# 3. Verificar conectividad de red entre contenedores
docker-compose exec backend ping db
docker-compose exec backend ping redis

Redis no se conecta o falla al iniciar

Problema: El backend no puede conectarse a Redis.

Solución:

# Limpiar volúmenes de Redis y reiniciar
docker-compose down
docker volume rm games_redis_data
docker-compose up -d redis

# Verificar estado de Redis
docker-compose exec redis redis-cli ping

MySQL: "Access denied for user"

Problema: Error de autenticación con MySQL.

Solución:

1. Verificar que las variables de entorno en .env son correctas
2. Asegurarse de que MYSQL_USER y MYSQL_PASSWORD coinciden con DB_USER y DB_PASSWORD
3. Recrear los contenedores:

docker-compose down -v
docker-compose up -d

La sincronización de IGDB es muy lenta

Problema: La primera carga de datos de IGDB tarda demasiado.

Solución:

• Es normal en la primera ejecución (puede tardar 10-30 minutos)
• Puedes monitorear el progreso en los logs:

docker-compose logs -f backend | grep -i igdb

• Para cargas incrementales posteriores, el proceso es mucho más rápido gracias a Redis

Frontend no se actualiza después de cambios

Problema: Los cambios en el código del frontend no se reflejan.

Solución:

# Limpiar caché de Vite y node_modules
cd frontend
rm -rf node_modules/.vite
npm run build

# Reconstruir contenedor de frontend
docker-compose up -d --build frontend

Problemas con CORS en el frontend

Problema: Errores de CORS al hacer peticiones a la API.

Solución:

1. Verificar que CSRF_TRUSTED_ORIGINS en .env incluye tu dominio:

CSRF_TRUSTED_ORIGINS=http://localhost,http://127.0.0.1,https://tu-dominio.com

2. Reiniciar el backend:

docker-compose restart backend

FAQ

¿Necesito pagar por las APIs de IGDB o AllKeyShop?

IGDB: La API es gratuita pero requiere registro en Twitch Developers. El proyecto incluye credenciales de ejemplo, pero para uso en producción debes obtener las tuyas propias.

AllKeyShop: El proyecto usa web scraping público. No se requiere API key. Nota: El uso de web scraping podría suponer un consumo de tráfico no deseado en su página web, por lo que no se debería implementar en entornos de producción abiertos.

¿Puedo usar otra base de datos en lugar de MySQL?

Sí, Django soporta PostgreSQL, SQLite y otros motores. Necesitarás:

1. Modificar la configuración de DATABASES en backend/gestor_videojuegos/settings.py
2. Actualizar las dependencias en backend/requirements.txt
3. Modificar docker-compose.yml

¿Con qué frecuencia se actualizan los precios?

Por defecto, el sistema actualiza los precios cada 6 horas mediante tareas programadas. Puedes configurar la frecuencia modificando los comandos cron en el backend o ejecutar manualmente:

docker-compose exec backend python manage.py actualizar_precios

¿Cómo agrego más plataformas o géneros?

Las plataformas y géneros se sincronizan automáticamente desde IGDB. Para forzar una resincronización:

docker-compose exec backend python manage.py sync_igdb --full

¿El sistema soporta múltiples usuarios?

Sí, GameS soporta múltiples usuarios con autenticación JWT. Cada usuario tiene:

• Biblioteca personal independiente
• Estadísticas propias
• Recomendaciones personalizadas basadas en su colección
• Sistema de notificaciones individual

¿Puedo exportar mis datos?

Actualmente el sistema no incluye exportación directa, pero puedes acceder a tus datos mediante:

• La API REST con tu token de autenticación
• Acceso directo a la base de datos MySQL
• Panel de administración de Django en /admin

¿Qué recursos necesito para ejecutar GameS?

Requerimientos mínimos:

• 2 CPU cores
• 4GB RAM
• 20GB almacenamiento (incluyendo caché de Redis)
• Docker 20.x+

Recomendado para producción:

• 4 CPU cores
• 8GB RAM
• 50GB SSD
• Cloudflare como CDN/proxy

Licencia y Derechos

© Copyright - Todos los derechos del código fuente y logotipos de GameS pertenecen y están adjudicados exclusivamente a su autor principal.

Este es un proyecto privativo y la copia, reproducción, venta o uso no autorizado en terceros servicios externos se encuentra prohibido según la jurisdicción actual. No se aceptan Pull Requests ni participaciones externas.

Política de Uso

• ✅ Uso personal y educativo
• ✅ Estudio del código fuente
• ✅ Reportar issues y bugs
• ❌ Uso comercial sin autorización
• ❌ Redistribución o venta
• ❌ Fork público del proyecto