5

2026-06-04 15:24:29 -03:00
parent aa9bc585fd
commit 70d4217109
12 changed files with 16921 additions and 0 deletions
@@ -0,0 +1,241 @@
+# 🏀 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.*