225 lines
7.1 KiB
Markdown
225 lines
7.1 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker build -t volley-manager:1.0.0 .
|
|
```
|
|
|
|
Crear el archivo de entorno:
|
|
|
|
```powershell
|
|
Copy-Item .env.example .env
|
|
```
|
|
|
|
Editar `.env` y cambiar como minimo `JWT_SECRET`, `DB_PASSWORD` y `DB_ROOT_PASSWORD`.
|
|
|
|
Levantar produccion con la imagen:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml up -d
|
|
```
|
|
|
|
Inicializar o refrescar la plantilla LTV26 despues del primer arranque:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml --profile init run --rm init
|
|
```
|
|
|
|
Si vas a subir la imagen a un registry:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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á:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sh scripts/install.sh
|
|
```
|
|
|
|
En Windows:
|
|
|
|
```powershell
|
|
.\scripts\install.ps1
|
|
```
|
|
|
|
4. Levantar PHP:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```text
|
|
POST /api/tournaments/{id}/demo-scoresheet-data
|
|
```
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
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.
|