Glicko BD
Documentación: Español | English | Português
Glicko BD es una aplicación Flask y SQLite para administrar jugadores, ratings, partidas y torneos de una comunidad de Go. Ofrece posiciones y estadísticas públicas, junto con pantallas de administración protegidas para importaciones, configuración del rating, copias de seguridad y operaciones de torneos.
Tabla de contenidos
- Funciones
- Ayuda para usuarios
- Requisitos
- Ejecución local
- Configuración
- Hoja de ruta del proyecto
- Desarrollo
- Organización del código
- Instalación en hosting Linux
- Copias programadas y pruebas de restauración
- Despliegue de la API autenticada
- Licencia y atribución
Funciones
- Clasificaciones, búsqueda, perfiles, historial de partidas y gráficos de rating
- Cálculo Glicko-2 configurable e interfaz en español, inglés y portugués
- Importación de Excel, CSV y OpenGotha; las importaciones de torneos OpenGotha se revisan y confirman antes de aplicar cambios
- Sistemas Suizo, Suizo por Categoría, Suizo Acelerado y McMahon
- Registro de miembros, solicitudes moderadas de vínculo con jugadores sin cuenta y envío de resultados para aprobación administrativa
- Reportes con filtros y exportación CSV/PDF, además de noticias y biblioteca pública de registros SGF
- Copias de seguridad, restauración protegida y migraciones SQLite
- Clasificaciones por país, región, edad y categoría femenina; la región predeterminada de la web y API es configurable (inicialmente América Latina)
- Tres niveles de acceso: global (administradores), regional y país; organizadores con Operaciones de torneos (incluyendo jugadores) y gestores con Operaciones de torneos y Gestión de datos
- Torneos con hándicap, descansos y ausencias
- Los borradores permanecen ocultos y los cancelados no aparecen en listas públicas; el detalle individual cancelado sigue accesible por enlace directo. Los torneos completados no puntuables muestran sus partidas sin afectar los ratings
- Torneos PairGo de dos jugadores por pareja, sin restricciones de género; son siempre no puntuables y no modifican las estadísticas ni los enfrentamientos individuales
- Navegación accesible por teclado, soporte para movimiento reducido y filtros con controles nativos de respaldo
Ayuda para usuarios
Los procedimientos de despliegue y las observaciones se resumen en las notas operativas (inglés); el roadmap contiene el trabajo pendiente. Consulta la matriz de permisos para conocer los roles y sus operaciones.
La guía de la interfaz es la referencia para las tareas diarias. También está disponible desde el botón ? de la barra superior o en /help?lang=es.
En navegadores móviles compatibles, puedes agregar Glicko BD a la pantalla de inicio como aplicación.
Requisitos
- Python 3.10, 3.11, 3.12 o 3.13 (versiones incluidas en la matriz de CI)
pip- Dependencias de Python: requirements.txt
- Dependencias de desarrollo y pruebas: requirements-test.txt
Ejecución local
Windows PowerShell:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
$env:APP_SECRET_KEY = "reemplaza-por-un-valor-aleatorio-largo"
$env:ADMIN_PASSWORD = "elige-una-contrasena-segura"
python app.py
macOS o Linux:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export APP_SECRET_KEY="reemplaza-por-un-valor-aleatorio-largo"
export ADMIN_PASSWORD="elige-una-contrasena-segura"
python app.py
Abre http://127.0.0.1:5000 en el navegador. La aplicación crea la base de datos SQLite en data/acg_ratings.db durante el primer inicio.
Solo para datos de ejemplo locales, define LOAD_SAMPLE_DATA=1 antes de iniciar. No uses datos de ejemplo en una base de datos de producción.
Configuración
Configura los valores necesarios en el entorno; la mayoría de los valores predeterminados están en config.py.
APP_SECRET_KEYyADMIN_PASSWORD: clave de sesión y contraseña de un solo uso para crear la cuenta administradora inicial. Usa secretos seguros en producción.APP_PUBLIC_ORIGIN: origen HTTPS público para enlaces de recuperación de contraseña.DB_PATHenconfig.py: ubicación de la base de datos SQLite; no se configura mediante una variable de entorno.- La analítica usa un archivo independiente junto a
DB_PATH, con sufijo.analytics.db(por defectodata/acg_ratings.analytics.db); las copias y restauraciones de la aplicación no lo incluyen. Al iniciar se importan las filas históricas faltantes de la tabla antigua, sin modificarla. SQLITE_JOURNAL_MODE=DELETE(predeterminado) oWAL: modo del diario de la base principal, aplicado al iniciar. WAL requiere un sistema de archivos local compatible y validación en staging; todas las conexiones de la aplicación esperan hasta 5000 ms ante bloqueos. Consulta el procedimiento WAL.GEOIP_COUNTRY_DB: ruta de la base local GeoLite2 Country, por defectodata/GeoLite2-Country.mmdb. Se usa para la visualización de perfiles y las estadísticas agregadas del sitio; no se incluye, obténla conforme a su licencia.MAIL_SERVER,MAIL_PORT,MAIL_USERNAME,MAIL_PASSWORD,MAIL_USE_TLSyMAIL_FROM: configuración SMTP para recuperación y alertas.RECAPTCHA_SITE_KEYyRECAPTCHA_SECRET_KEY: claves reCAPTCHA v3 para el registro de miembros.LOAD_SAMPLE_DATA=1: carga datos de ejemplo locales; no lo uses en producción.AUDIT_RETENTION_DAYSySCHEDULED_BACKUP_KEEP: retención de auditoría y copias programadas.BACKUP_FRESHNESS_ENABLED(predeterminadofalse) yBACKUP_FRESHNESS_MAX_AGE_HOURS(predeterminado768): habilitan y configuran el verificador independiente de copias.API_RATE_LIMIT_READS_PER_TOKEN=60,API_RATE_LIMIT_WRITES_PER_TOKEN=20yAPI_RATE_LIMIT_REQUESTS_PER_IP=120: límites API por ventana fija de 60 segundos.API_MAX_REQUEST_BYTES=1048576: tamaño máximo del cuerpo de una solicitud API (1 MiB).API_REQUIRE_HTTPS=true: exige HTTPS para llamadas bearer y creación de tokens. Solo en desarrollo local sin HTTPS, usaAPI_REQUIRE_HTTPS=false.API_ENABLED_SLICESyAPI_STAFF_PILOT_SLICES: bloques de la API habilitados y bloques limitados al personal durante un piloto. Ambos están vacíos por defecto, por lo que la API responde503; consulta Despliegue de la API autenticada.
La aplicación usa UTC-5 de forma predeterminada. En producción, usa HTTPS y no guardes secretos en el código. Si el TLS termina en un proxy, configura el servidor WSGI para comunicar el esquema HTTPS solo desde proxies de confianza; no confíes en encabezados reenviados arbitrarios.
Hoja de ruta del proyecto
Consulta la hoja de ruta para propuestas pendientes y las notas de despliegue de API para las etapas A0-A6 ya implementadas. Cada bloque de la API se habilita por configuración. Las páginas web públicas y exportaciones actuales continúan disponibles.
Desarrollo
Protege el hosting compartido: prioriza pruebas locales; como máximo tres GET de producción aprobados, secuenciales, separados por cinco segundos y con páginas pequeñas. Detén la tanda ante lentitud, timeout, 429 o 5xx; no reintentes automáticamente. No ejecutes benchmarks, replay de ratings ni pruebas de carga en el servidor activo: una base descartable no aísla CPU ni E/S. Consulta las reglas de validación de bajo impacto. Nunca guardes tokens ni contraseñas en notas o documentación.
Las guías se renderizan desde Markdown. Para exportar copias HTML estáticas:
python scripts/build_help_html.py
Ejecuta las pruebas desde la raíz:
python -m pip install -r requirements-test.txt
python -m pytest -q
CI ejecuta la suite completa en Python 3.10–3.13, incluidas las comprobaciones del contrato OpenAPI y de la documentación. Las pruebas de navegación en Chromium son opcionales y no forman parte de CI.
Las pruebas opcionales de navegación en Chromium requieren Playwright:
python -m pip install playwright
python -m playwright install chromium
python -m pytest tests\test_navigation_browser.py -q
Organización del código
Las rutas de la aplicación están en routes/, la lógica compartida en services/ y las pruebas en tests/. Los archivos de ejemplo necesarios para las pruebas están versionados.
Instalación en hosting Linux
Usa una versión incluida en la matriz de CI (Python 3.10–3.13), crea un entorno virtual e instala las dependencias:
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install --only-binary=Pillow -r requirements.txt
La aplicación de producción usa Passenger. Si Pillow no tiene wheels compatibles, revisa que la versión de Python y la plataforma del hosting sean compatibles. Para diagnosticar fallos comunes, revisa los registros del servidor, el entorno Python, las dependencias, el punto de entrada WSGI, los permisos y el enrutamiento. Hay herramientas de diagnóstico opcionales en scripts/dev_only/; no las incluyas en el despliegue normal.
En Passenger, las migraciones y limpiezas de esquema deben ejecutarse durante el inicio controlado, no en solicitudes de solo lectura como los informes. Para investigar CPU alta y fallos históricos de SQLite, consulta las notas operativas.
Copias programadas y pruebas de restauración
Programa scripts/scheduled_backup.py con el mismo Python, configuración y variables de entorno que usa la aplicación. La ubicación de la base se define en config.py; SCHEDULED_BACKUP_KEEP controla la retención. El trabajo verifica la copia y una restauración en una base temporal antes de aplicar la retención; termina con código 1 si falla. En Windows Task Scheduler, configura:
- Programa:
C:\ruta\glicko-db\.venv\Scripts\python.exe - Argumentos:
scripts\scheduled_backup.py - Iniciar en:
C:\ruta\glicko-db
En Linux, una entrada de cron diaria puede ser:
0 2 * * * cd /srv/glicko-db && .venv/bin/python scripts/scheduled_backup.py >> /var/log/glicko-db-backup.log 2>&1
Configura en el entorno del programador las mismas variables de producción; cron y Task Scheduler no necesariamente heredan el entorno del servidor web. Revisa /admin/backups como administrador para comprobar la frescura de ratings, la última copia y prueba de restauración, y los fallos operativos. Practica la restauración en una instancia desechable. Para sustituir la base activa, programa una ventana de mantenimiento, bloquea nuevas escrituras y espera a que terminen las solicitudes en curso durante el cambio final. Las copias SQLite no contienen uploads/sgf; protege y restaura esa carpeta por separado.
Con WAL, detén también lectores y nuevas conexiones durante el cambio final. La restauración verifica y vacía el WAL antes de reemplazar la base; si hay conexiones que lo bloquean, se cancela sin sustituir los datos. No borres manualmente -wal ni -shm. La base restaurada queda en modo DELETE; el siguiente inicio controlado vuelve a aplicar SQLITE_JOURNAL_MODE.
Para detectar un trabajo que nunca se ejecuta, programa scripts/check_backup_freshness.py por separado con el mismo intérprete, base y entorno, incluyendo SMTP y BACKUP_FRESHNESS_ENABLED=true. Elige la frecuencia del verificador independientemente de la copia; no se crea ningún horario automáticamente. Configura BACKUP_FRESHNESS_MAX_AGE_HOURS como entero positivo: 768 horas (32 días) permiten intervalos mensuales de 31 días y un día adicional. Ajusta el margen al horario real.
Por ejemplo, tras configurar las variables de producción y SMTP en el entorno de cron, esta entrada lo comprueba cada hora (ajusta ruta, frecuencia y registro):
0 * * * * cd /srv/glicko-db && BACKUP_FRESHNESS_ENABLED=true .venv/bin/python scripts/check_backup_freshness.py >> /var/log/glicko-db-freshness.log 2>&1
El verificador usa la última ejecución programada exitosa registrada en UTC. Si no existe una, concede el umbral completo desde la primera comprobación habilitada; un éxito antiguo ya vencido alerta de inmediato. Envía correo a administradores activos con direcciones válidas al vencer, repite como máximo cada 24 horas cuando se ejecute y envía recuperación cuando vuelve a estar vigente. Los fallos de entrega se registran y se reintentan en la siguiente comprobación. Código de salida: 0 vigente, en gracia o deshabilitado; 1 vencido; 2 error de configuración, base o entrega. Supervisa también estos errores. Para deshabilitar y reiniciar la gracia antes de volver a habilitar, ejecuta una vez el verificador con BACKUP_FRESHNESS_ENABLED=false.
El historial operativo tiene retención limitada; un éxito eliminado del historial y las marcas antiguas sin UTC no cuentan. El registro es evidencia de una ejecución, no garantiza que el archivo siga disponible o sea restaurable, ni incluye SGF. El estado vive en la base de la aplicación y puede retroceder al restaurarla. Un verificador en el mismo hosting no detecta su propio fallo ni la caída del host; usa supervisión externa si necesitas esa cobertura. Comprueba SMTP y destinatarios antes de depender de las alertas.
Despliegue de la API autenticada
La API /api/v1 se habilita por bloques independientes y está deshabilitada en una instalación nueva. Un bloque deshabilitado responde 503 (api_slice_disabled) sin afectar las páginas web, las sesiones ni las exportaciones.
API_ENABLED_SLICES: bloques habilitados, separados por comas (docs,reads,submissions,moderation,tournament_setup,tournament_participants,tournament_rounds), oall.API_STAFF_PILOT_SLICES: bloques habilitados que solo pueden usar organizadores, gestores y administradores; los demás reciben503(api_pilot_restricted).
Un nombre desconocido, o all junto con otros nombres, impide iniciar la aplicación. Reinicia la aplicación Passenger después de cambiar estas variables.
- Confirma una copia verificada, HTTPS y la configuración de proxies de confianza. Anota en las notas de versión los bloques que habilitas.
- Habilita
docs,reads, incluye los mismos bloques enAPI_STAFF_PILOT_SLICES, reinicia y ejecuta el cliente de prueba con un token piloto del personal. El cliente solo usa la biblioteca estándar, lee el token de una variable de entorno y no lo muestra:
powershell
$env:GLICKO_API_TOKEN = "<token piloto>"
python scripts/api_smoke_test.py --base-url https://ejemplo.org/glicko --expect-enabled docs,reads --expect-disabled submissions,moderation,tournament_setup,tournament_participants,tournament_rounds
- Quita
docs,readsdeAPI_STAFF_PILOT_SLICESpara abrirlos a los miembros. Después habilita, de uno en uno,submissions,moderation,tournament_setup,tournament_participantsytournament_rounds, primero como piloto del personal. Comprueba cada paso con el cliente de prueba y los registrosapi.request.completed, que incluyen el bloque, el estado y la duración.
Para revertir, quita los bloques afectados de API_ENABLED_SLICES, reinicia y ejecuta el cliente de prueba con --expect-disabled. Si hace falta, los titulares revocan los tokens piloto desde su perfil. Deshabilitar un bloque no deshace escrituras confirmadas: corrige los datos con los flujos web habituales y no restaures una base anterior para revertir un despliegue de la API. Los presupuestos medidos y los umbrales propuestos están en las notas operativas.
Verificación de producción (2026-11-06)
Las salidas comunicadas por el operador y las comprobaciones de lectura se consolidan en las observaciones de producción. Son capturas históricas: no verifican escrituras exitosas ni reversión en producción. El defecto de actividad y las comprobaciones pendientes están en la hoja de ruta.
La opción --write-draft-tournament del cliente de prueba crea además un torneo borrador; úsala solo con datos desechables. Para medir la API en una base nueva y desechable, que el script se niega a sobrescribir:
python scripts/benchmark_api.py --output $env:TEMP\glicko-api-benchmark.db
Licencia y atribución
Glicko-db fue originalmente desarrollado para la comunidad de Go en Colombia por Juan Felipe Samper en 2026.
El sistema Glicko-2 fue publicado por Mark E. Glickman en 2022 al dominio público. La implementación en Python es ©2009 Ryan Kirkman y BesoGo es ©2015-2018 Ye Wang. Ambas se distribuyen bajo la licencia MIT.
Este producto utiliza datos GeoLite creados por MaxMind y datos de GeoNames. Consulta la licencia GeoLite, CC BY 4.0 y CC BY-SA 4.0.