feat: Initial commit - Ruleta con PIN (credenciales sanitizadas)
This commit is contained in:
Isaac_Aracena
@@ -0,0 +1,232 @@
|
||||
# 🎰 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](#-características)
|
||||
- [Requisitos](#-requisitos)
|
||||
- [Instalación](#-instalación)
|
||||
- [Configuración de Base de Datos](#-configuración-de-base-de-datos)
|
||||
- [Configuración de PINs](#-configuración-de-pins)
|
||||
- [Estructura del Proyecto](#-estructura-del-proyecto)
|
||||
- [Flujo del Sistema](#-flujo-del-sistema)
|
||||
- [Operación Diaria](#-operación-diaria)
|
||||
- [Solución de Problemas](#-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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
cp config.example.php config.php
|
||||
```
|
||||
|
||||
Editar `config.php` con los datos reales:
|
||||
|
||||
```php
|
||||
$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:
|
||||
|
||||
```bash
|
||||
mysql -u root -p < database/schema.sql
|
||||
```
|
||||
|
||||
### 5. Cargar premios y PINs
|
||||
|
||||
Ver sección [Configuración de PINs](#-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
|
||||
|
||||
```sql
|
||||
UPDATE girospermitidos SET cantidad = 50000 WHERE id = 1;
|
||||
```
|
||||
|
||||
### Cargar un premio
|
||||
|
||||
```sql
|
||||
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)
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```sql
|
||||
SELECT * FROM premiosentregados ORDER BY created_at DESC;
|
||||
```
|
||||
|
||||
### Consultar stock restante
|
||||
|
||||
```sql
|
||||
SELECT nombre, nombre_usuario, cantidad FROM premiosnew;
|
||||
```
|
||||
|
||||
### Aumentar cupo de giros
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## 📄 Licencia
|
||||
|
||||
Proyecto interno de **Gomez Lee Marketing**. Uso privado.
|
||||
Reference in New Issue
Block a user