# Glicko BD

Documentación: Español | [English](README.en.md) | [Português](README.pt.md)

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](#funciones)
- [Ayuda para usuarios](#ayuda-para-usuarios)
- [Requisitos](#requisitos)
- [Ejecución local](#ejecución-local)
- [Configuración](#configuración)
- [Hoja de ruta del proyecto](#hoja-de-ruta-del-proyecto)
- [Desarrollo](#desarrollo)
  - [Organización del código](#organización-del-código)
  - [Instalación en hosting Linux](#instalación-en-hosting-linux)
  - [Copias programadas y pruebas de restauración](#copias-programadas-y-pruebas-de-restauración)
  - [Despliegue de la API autenticada](#despliegue-de-la-api-autenticada)
- [Licencia y atribución](#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)](docs/operations.md); el [roadmap](FUTURE_FEATURES.md) contiene el trabajo pendiente. Consulta la [matriz de permisos](docs/user_interface.md#panel-de-administración) 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.

- [Ayuda de la interfaz](docs/user_interface.md)
- [Rutas y notas de integración](docs/api_endpoints.md)

## Requisitos

- Python 3.10, 3.11, 3.12 o 3.13 (versiones incluidas en la matriz de CI)
- `pip`
- Dependencias de Python: [requirements.txt](requirements.txt)
- Dependencias de desarrollo y pruebas: [requirements-test.txt](requirements-test.txt)

## Ejecución local

Windows PowerShell:

```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:

```bash
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_KEY` y `ADMIN_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_PATH` en `config.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 defecto `data/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) o `WAL`: 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](docs/operations.md#sqlite-journals-analytics-and-restore-cutover).
- `GEOIP_COUNTRY_DB`: ruta de la base local GeoLite2 Country, por defecto `data/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](https://www.maxmind.com/en/geolite/eula).
- `MAIL_SERVER`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_USE_TLS` y `MAIL_FROM`: configuración SMTP para recuperación y alertas.
- `RECAPTCHA_SITE_KEY` y `RECAPTCHA_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_DAYS` y `SCHEDULED_BACKUP_KEEP`: retención de auditoría y copias programadas.
- `BACKUP_FRESHNESS_ENABLED` (predeterminado `false`) y `BACKUP_FRESHNESS_MAX_AGE_HOURS` (predeterminado `768`): habilitan y configuran el verificador independiente de copias.
- `API_RATE_LIMIT_READS_PER_TOKEN=60`, `API_RATE_LIMIT_WRITES_PER_TOKEN=20` y `API_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, usa `API_REQUIRE_HTTPS=false`.
- `API_ENABLED_SLICES` y `API_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 responde `503`; consulta [Despliegue de la API autenticada](#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](FUTURE_FEATURES.md) para propuestas pendientes y las [notas de despliegue de API](docs/operations.md#api-rollout-and-rollback) 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](docs/operations.md#low-impact-production-validation). Nunca guardes tokens ni contraseñas en notas o documentación.

Las guías se renderizan desde Markdown. Para exportar copias HTML estáticas:

```powershell
python scripts/build_help_html.py
```

Ejecuta las pruebas desde la raíz:

```powershell
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:

```powershell
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:

```bash
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](docs/operations.md#passenger-resource-investigation-and-report-read-regression).

### 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:

```cron
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):

```cron
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`), o `all`.
- `API_STAFF_PILOT_SLICES`: bloques habilitados que solo pueden usar organizadores, gestores y administradores; los demás reciben `503` (`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.

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
   ```

3. 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](docs/operations.md#api-benchmark-and-proposed-budgets).

#### 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](docs/operations.md#production-api-observations). 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](FUTURE_FEATURES.md#production-verification-and-operations).

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:

```powershell
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](https://www.glicko.net/glicko/glicko2.pdf) 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](./static/vendor/besogo/LICENSE).

Este producto utiliza datos GeoLite creados por [MaxMind](https://www.maxmind.com/) y datos de [GeoNames](https://www.geonames.org/). Consulta la [licencia GeoLite](https://www.maxmind.com/en/geolite/eula), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) y [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
