Files

T

Laucha1312 70d4217109 5

2026-06-04 15:24:29 -03:00

9.6 KiB

Raw Blame History

🏀 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

🛠️ 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:

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.

# 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

# 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.

9.6 KiB Raw Blame History