Volley Manager

Sistema web para gestión de torneos de voleibol amateur y profesional. Incluye API REST en PHP, frontend JavaScript con TailwindCSS, MySQL, JWT, Docker, planilla electrónica y sincronización por WebSockets.

Funcionalidades

• Roles: administrador, delegado y público.
• Torneos múltiples con categoría, subcategoría y formato.
• Equipos con logo, delegado, DT y link de ficha online.
• Jugadores con DNI, nacimiento, camiseta, posición y foto opcional.
• Fixture manual y generación automática para formato liga.
• Partidos al mejor de 5 sets, 25 puntos, tie-break a 15 y diferencia mínima de 2.
• Planilla electrónica para puntos, saque, error, ace, bloqueo, ataque, rotación y tarjetas.
• Planilla avanzada con posiciones 1 a 6, líbero, sustituciones reglamentarias, tiempos, rallys, auditoría arbitral y firma digital.
• Tabla de posiciones automática: PJ, ganados, perdidos, sets a favor/en contra, diferencia y puntos.
• Ranking de equipos y jugadores desde eventos.
• Canchas, árbitros, sanciones, upload de imágenes, export CSV y vista imprimible para PDF.
• Dark mode, diseño responsive y vista pública.

Arquitectura

app/
  Controllers/     Controladores HTTP
  Core/            Router, JWT, PDO, Request, Response, Auth, logs
  Repositories/    Acceso a datos
  Services/        Reglas de negocio, fixture, planilla y standings
bin/               Servidor WebSocket PHP
config/            Configuración por variables de entorno
database/          Schema y seeds
public/            SPA, assets y entrada web
scripts/           Instalación local
tests/             Tests básicos
docker/            Configuración Apache

Ejecutar con Docker

docker compose up --build

Abrir:

• Web: http://localhost:8080
• WebSocket: ws://localhost:8081
• MySQL local: 127.0.0.1:3307

Credenciales seed:

• Admin: admin@volley.test / password
• Delegado: delegado@volley.test / password

Imagen Docker para produccion

Para desarrollo, docker-compose.yml monta el codigo local como volumen. Para publicar una version cerrada, construir una imagen y ejecutar docker-compose.prod.yml.

Construir la imagen:

docker build -t volley-manager:1.0.0 .

Crear el archivo de entorno:

Copy-Item .env.example .env

Editar .env y cambiar como minimo JWT_SECRET, DB_PASSWORD y DB_ROOT_PASSWORD.

Levantar produccion con la imagen:

docker compose -f docker-compose.prod.yml up -d

Inicializar o refrescar la plantilla LTV26 despues del primer arranque:

docker compose -f docker-compose.prod.yml --profile init run --rm init

Si vas a subir la imagen a un registry:

docker tag volley-manager:1.0.0 registry.example.com/volley-manager:1.0.0
docker push registry.example.com/volley-manager:1.0.0

En el servidor, usar esa referencia en .env:

APP_IMAGE=registry.example.com/volley-manager:1.0.0

En esta modalidad los cambios de codigo no se reflejan por volumen: hay que reconstruir o descargar una nueva imagen. Los uploads, logs y datos MySQL quedan persistidos en volumenes Docker.

Si ya importaste los datos y ves textos como Cóndores VC, ejecutá:

mysql -h 127.0.0.1 -P 3307 -u volley -pvolley volley_tournaments < database/fix-mojibake.sql

Ejecutar sin Docker

1. Crear una base MySQL volley_tournaments.
2. Configurar variables DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD si difieren de los defaults.
3. Importar datos:

sh scripts/install.sh

En Windows:

.\scripts\install.ps1

4. Levantar PHP:

php -S 127.0.0.1:8080 -t public
php bin/websocket-server.php

Endpoints principales

• POST /api/auth/login
• GET|POST /api/tournaments
• POST /api/tournaments/{id}/fixture
• GET /api/tournaments/{id}/standings
• GET /api/tournaments/{id}/stats
• GET /api/tournaments/{id}/export/csv
• GET /api/tournaments/{id}/export/pdf
• GET|POST /api/teams
• GET|POST /api/players
• POST /api/team-links/{token}/players
• GET|POST /api/matches
• GET /api/matches/{id}/score
• POST /api/matches/{id}/events
• GET /api/matches/{id}/advanced-score
• POST /api/matches/{id}/rotations
• POST /api/matches/{id}/liberos
• POST /api/matches/{id}/substitutions
• POST /api/matches/{id}/timeouts
• POST /api/matches/{id}/rallies
• POST /api/matches/{id}/advanced-sanctions
• POST /api/matches/{id}/signatures
• GET /api/matches/{id}/scoresheet/ltv26
• POST /api/matches/{id}/sanctions
• POST /api/uploads/images

Planilla electrónica

El módulo ScoreSheetService persiste eventos del partido y actualiza el estado:

• Suma puntos por equipo.
• Cierra sets solo si se alcanza el objetivo y diferencia de 2.
• Usa 25 puntos en sets 1 a 4 y 15 en set 5.
• Crea el siguiente set automáticamente.
• Finaliza el partido al llegar a 3 sets ganados.
• Reconstruye standings al finalizar.
• El WebSocket bin/websocket-server.php detecta eventos nuevos y los emite a los clientes conectados.

Para una base Docker ya creada antes de la planilla avanzada:

Get-Content database\migrations\20260519_scoresheet_advanced.sql | docker compose exec -T db mysql -uvolley -pvolley volley_tournaments

Planilla LTV 26

La planilla PLANILLA LTV 26.pdf es una imagen sin campos PDF. El sistema la usa como fondo y superpone los datos por coordenadas.

1. Exportar el PDF a PNG.
2. Guardarlo como public/templates/planilla-ltv-26.png.
3. Ajustar coordenadas en config/templates/ltv26_scoresheet.php si hace falta.
4. Abrir desde la planilla con el botón Planilla PDF.

Multi Plantilla

El sistema soporta múltiples plantillas por torneo:

• sheet_templates: define imagen, tamaño y coordenadas JSON.
• tournament_sheet_templates: asigna una plantilla por defecto a cada torneo.
• match_sheet_template_overrides: permite sobrescribir la plantilla para un partido específico.
• match_sheet_exports: guarda auditoría de exportaciones.

El exportador usa unicamente el config_json guardado en cada plantilla. Los defaults de LTV26 solo se usan al ejecutar el seed inicial; despues, si borras campos o bloques desde el editor visual, dejan de salir en la exportacion.

Para migrar una base existente y registrar la LTV26 inicial:

Get-Content database\migrations\20260519_sheet_templates.sql | docker compose exec -T db mysql -uvolley -pvolley volley_tournaments
docker compose exec app php scripts/seed_ltv26_template.php

Para que el demo de planilla tenga capitanes/observaciones por equipo, aplicar tambien:

Get-Content database\migrations\20260519_ltv26_template_fields.sql | docker compose exec -T db mysql -uvolley -pvolley volley_tournaments

Luego desde Admin usar Demo planilla, o llamar:

POST /api/tournaments/{id}/demo-scoresheet-data

Tests

php tests/ScoreRulesTest.php
php tests/JwtTest.php

Notas de producción

• Cambiar JWT_SECRET.
• Usar HTTPS y proxy reverso para WebSocket.
• Reemplazar la vista imprimible de PDF por una librería como Dompdf si se necesita PDF binario directo.
• Revisar límites de upload y almacenamiento persistente para logos/fotos.