From 833b4e198b3e1fd0933e363e4edd15391562d699 Mon Sep 17 00:00:00 2001 From: -chelo Date: Thu, 28 May 2026 00:42:18 -0300 Subject: [PATCH] first commit --- README.md | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..79d26bd --- /dev/null +++ b/README.md @@ -0,0 +1,224 @@ +# 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.