Glicko DB

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

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

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.

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:

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.

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.

  1. Confirma una copia verificada, HTTPS y la configuración de proxies de confianza. Anota en las notas de versión los bloques que habilitas.
  2. Habilita docs,reads, incluye los mismos bloques en API_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

  1. Quita docs,reads de API_STAFF_PILOT_SLICES para abrirlos a los miembros. Después habilita, de uno en uno, submissions, moderation, tournament_setup, tournament_participants y tournament_rounds, primero como piloto del personal. Comprueba cada paso con el cliente de prueba y los registros api.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.

^