Laucha1312
242 lines
9.6 KiB
Markdown
242 lines
9.6 KiB
Markdown
# 🏀 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.*
|