# 🏀 OnAPB — Sistema de Gestión de Asociación de Básquet

**OnAPB** es una plataforma web integral para la gestión digital de asociaciones de básquet. Digitaliza la administración de clubes, equipos, jugadores, torneos y el acceso a eventos mediante códigos QR, reemplazando procesos que antes eran 100% manuales o en papel.

> **Sitio en Producción:** [onapb.com](https://onapb.com)

---

## 🛠️ Stack Tecnológico

| Capa | Tecnología |
|---|---|
| **Backend Framework** | Laravel 12.x (PHP 8.2+) |
| **ORM** | Eloquent ORM |
| **Base de Datos** | MySQL / MariaDB |
| **Frontend** | Bootstrap 5 + CSS Vainilla personalizado |
| **Build Tool** | Vite + NPM |
| **Gestión de Paquetes** | Composer |
| **Anti-Bot** | Cloudflare Turnstile |
| **Correo** | Laravel Mailer (SMTP) |
| **QR Generation** | `simplesoftwareio/simple-qrcode` |
| **Backups** | `spatie/laravel-backup` |
| **Testing** | PHPUnit 11 (Feature Tests) |

---

## 🏛️ Arquitectura del Sistema

El sistema sigue el patrón **MVC (Modelo-Vista-Controlador)** provisto por Laravel, con las siguientes capas:

```
┌───────────────────────────────────────────────────────────────┐
│                          CLIENTE                              │
│              Browser (Bootstrap 5 + JavaScript)               │
└────────────────────────────┬──────────────────────────────────┘
                             │ HTTP / HTTPS
┌────────────────────────────▼──────────────────────────────────┐
│                        RUTAS (web.php)                        │
│     Rutas públicas / Panel usuario / Panel admin              │
└────────────────────────────┬──────────────────────────────────┘
                             │
┌────────────────────────────▼──────────────────────────────────┐
│                      CONTROLADORES                            │
│  AdminController · PanelController · AuthController           │
│  TorneoController · FixtureController · PaseController · ...  │
└─────────┬───────────────────────────────────────┬─────────────┘
          │                                       │
┌─────────▼─────────┐                 ┌───────────▼─────────────┐
│      MODELOS      │                 │        SERVICIOS         │
│  Club / Equipo    │                 │  NotificacionService     │
│  Jugador / Evento │                 │  FixtureService          │
│  QrCode / Torneo  │◄────────────────│  TournamentService       │
│  Promocion / ...  │   Eloquent ORM  └─────────────────────────┘
└─────────┬─────────┘
          │
┌─────────▼─────────┐
│    BASE DE DATOS  │
│  MySQL / MariaDB  │
└───────────────────┘
```

### Capas Adicionales

- **Observers** — Lógica de negocio automatizada ante eventos de modelos.
- **Console Commands** — Tareas programadas: `CleanupOldEvents`, `RecordatorioPartidos`, `ReporteSemanal`.
- **Mails** — Notificaciones por correo: bienvenida, QRs generados, reset de contraseña.

---

## 🗄️ Esquema de Base de Datos (Entidades Principales)

```
clubes ──────────────────────────────────────────┐
  │ id_club, nombre, imagen, qr_background        │
  │                                               │
  ├──► equipos                                   │
  │      id_equipo, id_club, categoria, division  │
  │           │                                   │
  │           └──► jugador_equipo ◄──── jugadores ┘
  │                   id_jugador, id_equipo            id_jugador, documento,
  │                   fecha_alta                       nombre, apellido,
  │                                                    fecha_nacimiento,
  │                                                    id_club_actual, activo
  │
  └──► eventos
         id_evento (UUID), nombre_evento,
         fecha_evento, hora_inicio, hora_fin,
         id_equipo_local, id_equipo_visitante,
         marcador_local, marcador_visitante,
         id_torneo, limite_qr_jugador
              │
              └──► qr_codes
                     id_qr, id_evento,
                     id_jugador | id_aficionado,
                     tipo_qr, escaneos_restantes

torneos
  id_torneo, nombre, año
       │
       └──► torneo_equipo (grupo, puntos, ...)
       └──► eventos (fase del torneo)

promociones ──► promo_qrs
aficionados
admin_users (role: 1=SuperAdmin, 2=Admin Club)
```

---

## 👥 Roles del Sistema

El sistema implementa **RBAC (Control de Acceso Basado en Roles)** con 4 perfiles:

| Rol | Descripción | Acceso |
|---|---|---|
| **Visitante** | Sin cuenta | Solo páginas públicas |
| **Jugador** | Deportista federado | Panel usuario (acceso federado) |
| **Aficionado** | Hincha registrado | Panel usuario (acceso general) |
| **Admin de Club** | Gestor de una institución | Panel admin (scope limitado a su club) |
| **Súper Admin** | Personal de OnAPB | Panel admin (acceso total) |

---

## 🌐 Funcionalidades por Rol

### Visitante (sin cuenta)
- Navegar la cartelera de próximos eventos
- Ver el detalle de cada partido (equipos, fecha, sede)
- Ver la sección de Noticias
- Ver Promociones y locales con beneficios
- Ver Posiciones y Tabla de Goleadores de torneos

### Jugador / Aficionado (panel usuario)
- Solicitar y ver sus Códigos QR de acceso a partidos
- Generar QR de beneficio para promociones
- Editar datos de contacto y cambiar contraseña
- Recibir notificaciones internas del sistema
- Seguir equipos favoritos

### Admin de Club (panel admin — scope de su club)
- Ver y gestionar jugadores del club
- Ver y gestionar equipos del club
- Editar logo e identidad visual del club (QR Background)
- Gestionar pases (traspasos) de jugadores
- Escanear y validar QRs en eventos de su club

### Súper Admin (panel admin — acceso total)
- **Todo lo del Admin de Club**, más:
- ABM completo de Clubes, Equipos y Jugadores (globalmente)
- ABM de Eventos / Partidos (calendarización)
- ABM de Torneos + generación de fixtures + bracket de playoffs
- Gestión del carrusel/hero de la página de inicio
- Gestión de Sponsors
- ABM de Noticias y Promociones
- Configuración general del sistema
- Gestión de usuarios administradores
- Importación/Exportación masiva de jugadores (CSV multiformato)

---

## ✅ Suite de Pruebas

El proyecto cuenta con **Feature Tests** ejecutables con PHPUnit:

```bash
php artisan test
```

| Archivo | Casos de Prueba |
|---|---|
| `AuthTest.php` | Login admin · Login jugador · Login aficionado · Cierre de sesión |
| `AdminTest.php` | Acceso denegado a visitantes/jugadores · Acceso SuperAdmin · Creación de club |
| `EventoQRTest.php` | Solicitud de QR por aficionado · Prevención de QR duplicado |
| `JugadorCreationTest.php` | Error por DNI duplicado con nombre de club · Vista de admin de club |
| `CleanupTest.php` | Limpieza de eventos viejos |

---

## 💾 Recuperación ante Fallos

- **SoftDeletes** en modelos críticos: `Club`, `Equipo`, `Jugador`, `Evento` — los registros eliminados no se borran físicamente de la base de datos, son recuperables.
- **Backups automáticos** con `spatie/laravel-backup` — respalda la base de datos y los archivos de almacenamiento en forma programada.

```bash
# Ejecutar backup manual
php artisan backup:run --only-db
```

---

## 🤖 Tareas Automáticas (Scheduler)

| Comando | Descripción | Frecuencia |
|---|---|---|
| `reportes:semanal` | Genera y envía reporte de actividad a admins | Semanal |
| `recordatorio:partidos` | Envía recordatorio de próximos partidos | Diaria |
| `cleanup:old-events` | Limpia QRs de eventos finalizados | Configurable |

---

## ⚙️ Instalación Local

```bash
# 1. Clonar el repositorio
git clone <repo-url>

# 2. Instalar dependencias
composer install
npm install && npm run build

# 3. Configurar entorno
cp .env.example .env
php artisan key:generate

# 4. Configurar .env (DB_DATABASE, DB_USERNAME, DB_PASSWORD, MAIL_*, etc.)

# 5. Migrar y poblar la base de datos
php artisan migrate:fresh --seed

# 6. Enlazar carpeta de almacenamiento
php artisan storage:link

# 7. Iniciar servidor
php artisan serve
```

---

## 🧪 Variables de Entorno Relevantes

| Variable | Descripción |
|---|---|
| `DB_DATABASE` | Nombre de la base de datos |
| `MAIL_HOST` / `MAIL_PORT` | Servidor SMTP para envío de correos |
| `TURNSTILE_SITE_KEY` | Clave pública de Cloudflare Turnstile (anti-bot) |
| `TURNSTILE_SECRET_KEY` | Clave privada de Cloudflare Turnstile |
| `APP_URL` | URL base de la aplicación |

---

*Proyecto desarrollado como Software Integrador para la materia Taller de Integración — FCYT UADER, Oro Verde.*