🎰 Ruleta con PIN

Aplicación web de ruleta de premios protegida por PIN, con registro de resultados vía backend PHP y base de datos MySQL/MariaDB.

Desarrollada para campañas promocionales de Gomez Lee Marketing (GLM).

---

📋 Tabla de Contenidos

• Características
• Requisitos
• Instalación
• Configuración de Base de Datos
• Configuración de PINs
• Estructura del Proyecto
• Flujo del Sistema
• Operación Diaria
• Solución de Problemas

---

✨ Características

• Autenticación por PIN antes de girar la ruleta
• Selección aleatoria ponderada de premios según probabilidades configurables
• Control de stock por premio y cupo global de giros
• Registro de auditoría con IP, user agent y timestamp
• Animación fluida de ruleta con CSS transitions
• Efecto confeti al ganar (canvas-confetti)
• Diseño responsive con soporte de pantalla completa
• Redirección a formulario JotForm para reclamar el premio

---

📦 Requisitos

Componente	Versión mínima
PHP	8.0+ con extensión mysqli
MySQL / MariaDB	5.7+ / 10.3+
Servidor Web	Apache (XAMPP) o Nginx
Navegador	Cualquier navegador moderno con JS habilitado

La aplicación requiere acceso HTTP saliente a https://api.ipify.org para obtener la IP pública del usuario.

---

🚀 Instalación

1. Clonar el repositorio

git clone https://git.digitalcompass.agency/Isaac_Aracena/ruleta-con-pin.git

2. Colocar en el servidor web

• Windows (XAMPP): Copiar a C:\xampp\htdocs\ruleta\
• Linux (Apache/Nginx): Copiar a /var/www/ruleta/

3. Configurar credenciales de BD

cp config.example.php config.php

Editar config.php con los datos reales:

$servername = "localhost";
$username   = "tu_usuario";
$password   = "tu_contraseña";
$dbname     = "ruleta_db";

⚠️ config.php está en .gitignore y nunca se versiona. Las credenciales quedan solo en tu servidor.

4. Crear la base de datos

Ejecutar el script SQL incluido:

mysql -u root -p < database/schema.sql

5. Cargar premios y PINs

Ver sección Configuración de PINs.

6. Probar

Abrir http://localhost/ruleta/index.html e ingresar un PIN válido.

---

🗄️ Configuración de Base de Datos

Tablas

Tabla	Descripción
girospermitidos	Control global de cupo de giros (1 registro, id=1)
premiosnew	Premios con stock, probabilidad y PIN asignado
premiosentregados	Auditoría de premios entregados

Ajustar cupo de giros

UPDATE girospermitidos SET cantidad = 50000 WHERE id = 1;

Cargar un premio

INSERT INTO premiosnew (nombre, probabilidad, cantidad, inicio, final, nombre_usuario)
VALUES ('Gorra', 1.0, 10, 0, 45, '1989');

• inicio / final = ángulos en la imagen de la ruleta (0–360°)
• nombre_usuario = el PIN que podrá ganar este premio
• cantidad = stock disponible

---

🔑 Configuración de PINs

Los PINs deben estar sincronizados en dos lugares:

1. Base de datos: columna premiosnew.nombre_usuario
2. Frontend: array validPins en script.js (línea 35)

const validPins = ["1989", "4708", "6823", "7591", ...];

Si un PIN está en la BD pero no en validPins, el modal del frontend no dejará pasar. Si un PIN está en validPins pero no en la BD, el backend responderá "No hay premios disponibles".

---

📁 Estructura del Proyecto

ruleta-con-pin/
├── index.html            # Página principal (modal PIN + ruleta)
├── script.js             # Lógica del juego, validación, animación
├── style.css             # Estilos, responsive, modales
├── seleccionar_premio.php # Backend: selección aleatoria + registro BD
├── config.example.php    # Plantilla de configuración de BD
├── config.php            # ⛔ Credenciales reales (no versionado)
├── database/
│   └── schema.sql        # Script de creación de BD y tablas
└── img/
    ├── background.png    # Fondo de la página
    ├── ruleta.png        # Imagen de la ruleta
    ├── puntero.png       # Flecha/puntero de la ruleta
    ├── fullscreen-icon.png
    ├── BANNER-1.png      # Logo GLM
    ├── BANNER-2.png      # Banner lateral
    └── BANNER-4.png      # Banner inferior

---

🔄 Flujo del Sistema

Usuario → Ingresa PIN → Validación frontend (validPins)
  → Muestra ruleta → Click en puntero → Obtiene IP (ipify)
  → POST a seleccionar_premio.php
    → Verifica cupo global (girospermitidos)
    → Selecciona premio aleatorio ponderado (premiosnew)
    → Descuenta stock + registra en premiosentregados
    → Retorna JSON {id, nombre, inicio, final}
  → Anima ruleta al ángulo del premio
  → Confeti 🎊 + Modal "¡Ganaste!"
  → Botón "Ir al formulario" → JotForm

---

📊 Operación Diaria

Agregar PINs/premios

1. Insertar en premiosnew con el PIN deseado
2. Agregar el PIN al array validPins en script.js

Consultar premios entregados

SELECT * FROM premiosentregados ORDER BY created_at DESC;

Consultar stock restante

SELECT nombre, nombre_usuario, cantidad FROM premiosnew;

Aumentar cupo de giros

UPDATE girospermitidos SET cantidad = cantidad + 1000 WHERE id = 1;

---

🔧 Solución de Problemas

Problema	Causa
"Conexión fallida…"	Credenciales en config.php incorrectas o BD inaccesible
"No hay premios disponibles"	No hay fila en premiosnew con ese PIN y cantidad > 0
No pasa del modal de PIN	El PIN no está en validPins en script.js
No registra IP	Navegador no puede acceder a https://api.ipify.org
"Se ha alcanzado el límite de giros"	girospermitidos.cantidad llegó a 0

---

🛡️ Notas de Seguridad

• Las credenciales de BD se cargan desde config.php (no versionado)
• Los INSERT usan prepared statements para prevenir SQL injection
• La validación de PINs en el frontend es solo UX; la validación real ocurre en el backend vía nombre_usuario en la consulta SQL

---