Glicko DB

Glicko BD

Documentação: Español | English | Português

Glicko BD é uma aplicação Flask e SQLite para gerenciar jogadores, ratings, partidas e torneios de uma comunidade de Go. Ela oferece classificações e estatísticas públicas, além de telas administrativas protegidas para importações, configuração do rating, cópias de segurança e operações de torneios.

Índice

Recursos

Ajuda do usuário

Procedimentos de implantação e observações estão resumidos nas notas operacionais (inglês); o roadmap reúne o trabalho pendente. Consulte a matriz de permissões para conhecer as funções e suas operações.

O guia da interface é a referência para as tarefas diárias. Ele também está disponível pelo botão ? na barra superior ou em /help?lang=pt. Em navegadores móveis compatíveis, você pode adicionar o Glicko BD à tela inicial como aplicativo.

Requisitos

Execução local

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
$env:APP_SECRET_KEY = "substitua-por-um-valor-aleatorio-longo"
$env:ADMIN_PASSWORD = "escolha-uma-senha-segura"
python app.py

macOS ou Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
export APP_SECRET_KEY="substitua-por-um-valor-aleatorio-longo"
export ADMIN_PASSWORD="escolha-uma-senha-segura"
python app.py

Abra http://127.0.0.1:5000 no navegador. A aplicação cria o banco SQLite em data/acg_ratings.db na primeira inicialização.

Apenas para dados de exemplo locais, defina LOAD_SAMPLE_DATA=1 antes de iniciar. Não use dados de exemplo em um banco de produção.

Configuração

Configure as variáveis de ambiente necessárias; a maioria dos valores padrão está em config.py.

O fuso padrão é UTC-5. Em produção, use HTTPS e mantenha os segredos fora do código-fonte. Se o TLS terminar em um proxy, configure o servidor WSGI para informar o esquema HTTPS somente a partir de proxies confiáveis; não confie em cabeçalhos encaminhados arbitrários.

Plano do projeto

Consulte o roteiro do projeto para propostas pendentes e as notas de implantação da API para as etapas A0-A6 implementadas. Cada bloco da API é habilitado por configuração. As páginas públicas e exportações existentes permanecem disponíveis.

Desenvolvimento

Proteja o hosting compartilhado: prefira testes locais; no máximo três GET de produção aprovados, sequenciais, separados por cinco segundos e com páginas pequenas. Pare diante de lentidão, timeout, 429 ou 5xx; não repita automaticamente. Não execute benchmarks, replay de ratings ou testes de carga no servidor ativo: um banco descartável não isola CPU nem E/S. Siga as regras de validação de baixo impacto. Nunca guarde tokens ou senhas em notas ou documentação.

As páginas de ajuda são renderizadas a partir do Markdown. Para exportar cópias HTML estáticas:

python scripts/build_help_html.py

Execute os testes a partir da raiz:

python -m pip install -r requirements-test.txt
python -m pytest -q

O CI executa a suite completa no Python 3.10–3.13, incluindo as verificações do contrato OpenAPI e da documentação. Os testes de navegação no Chromium são opcionais e não fazem parte do CI.

Os testes opcionais de navegação no Chromium exigem Playwright:

python -m pip install playwright
python -m playwright install chromium
python -m pytest tests\test_navigation_browser.py -q

Organização do código

As rotas ficam em routes/, a lógica compartilhada em services/ e os testes em tests/. Os arquivos de exemplo dos testes estão versionados.

Instalação em hospedagem Linux

Use uma versão incluída na matriz do CI (Python 3.10–3.13), crie um ambiente virtual e instale as dependências:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install --only-binary=Pillow -r requirements.txt

A aplicação de produção usa Passenger. Se o Pillow não tiver um wheel compatível, verifique se a versão do Python e a plataforma da hospedagem são compatíveis. Para problemas comuns, consulte os logs do servidor, o ambiente Python, as dependências, o ponto de entrada WSGI, as permissões e o roteamento. Há ferramentas opcionais de diagnóstico em scripts/dev_only/; não as inclua na implantação normal.

No Passenger, migrações e limpezas de esquema devem ocorrer durante uma inicialização controlada, não em solicitações somente de leitura, como relatórios. Para investigar CPU alta e falhas históricas do SQLite, consulte as notas operacionais.

Backups agendados e testes de restauração

Agende scripts/scheduled_backup.py com o mesmo Python, configuração e ambiente usados pela aplicação. O caminho do banco é definido em config.py; SCHEDULED_BACKUP_KEEP controla a retenção. O job verifica o backup e uma restauração em um banco temporário antes de aplicar a retenção; termina com código 1 se falhar. No Agendador de Tarefas do Windows, configure:

No Linux, uma entrada diária do cron pode ser:

0 2 * * * cd /srv/glicko-db && .venv/bin/python scripts/scheduled_backup.py >> /var/log/glicko-db-backup.log 2>&1

Defina no agendador as mesmas variáveis de ambiente de produção; cron e Agendador de Tarefas talvez não herdem o ambiente do servidor web. Como administrador, confira /admin/backups para verificar a atualização dos ratings, o backup e o teste de restauração mais recentes e as falhas operacionais. Faça testes de restauração em uma instância descartável. Antes de substituir o banco ativo, agende uma janela de manutenção, bloqueie novas gravações e aguarde a conclusão das solicitações em andamento durante a troca final. Os backups SQLite não incluem uploads/sgf; proteja e restaure essa pasta separadamente.

Com WAL, interrompa também leitores e novas conexões durante a troca final. A restauração verifica e esvazia o WAL antes de substituir o banco; conexões que o bloqueiam fazem a operação abortar sem substituir os dados. Nunca apague -wal ou -shm manualmente. O banco restaurado usa DELETE; a próxima inicialização controlada reaplica SQLITE_JOURNAL_MODE.

Para detectar um job que nunca é executado, agende scripts/check_backup_freshness.py separadamente com o mesmo interpretador, banco e ambiente, incluindo SMTP e BACKUP_FRESHNESS_ENABLED=true. Escolha a frequência do verificador independentemente do backup; nenhum horário é criado automaticamente. Defina BACKUP_FRESHNESS_MAX_AGE_HOURS como inteiro positivo: 768 horas (32 dias) permitem um intervalo mensal de 31 dias e um dia adicional. Ajuste a margem ao horário real.

Por exemplo, após configurar as variáveis de produção e SMTP no ambiente do cron, esta entrada verifica a cada hora (ajuste caminho, frequência e log):

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

O verificador usa o último sucesso registrado em UTC do backup agendado. Se não houver um, concede o limite completo desde a primeira verificação habilitada; um sucesso antigo já vencido gera alerta imediatamente. Envia e-mail aos administradores ativos com endereços válidos quando vencido, repete no máximo a cada 24 horas quando executado e envia recuperação quando estiver atualizado. Falhas de envio são registradas e a próxima verificação tenta novamente. Código de saída: 0 atualizado, em tolerância ou desabilitado; 1 vencido; 2 erro de configuração, banco ou envio. Monitore esses erros também. Para desabilitar e reiniciar a tolerância antes de reabilitar, execute uma vez o verificador com BACKUP_FRESHNESS_ENABLED=false.

O histórico operacional tem retenção limitada; um sucesso removido do histórico e timestamps antigos sem UTC não contam. O registro é evidência de uma execução, não garante que o arquivo ainda exista ou possa ser restaurado, nem inclui SGFs. O estado fica no banco da aplicação e pode retroceder em uma restauração. Um verificador no mesmo host não detecta sua própria falha nem uma queda do host; use monitoração externa se precisar dessa cobertura. Verifique o SMTP e os destinatários antes de depender dos alertas.

Implantação da API autenticada

A API /api/v1 é habilitada em blocos independentes e fica desabilitada em uma instalação nova. Um bloco desabilitado retorna 503 (api_slice_disabled) sem afetar as páginas web, as sessões ou as exportações.

Um nome desconhecido, ou all combinado com outros nomes, impede o início da aplicação. Reinicie a aplicação Passenger depois de alterar essas variáveis.

  1. Confirme um backup verificado, HTTPS e a configuração de proxies confiáveis. Registre nas notas de versão os blocos habilitados.
  2. Habilite docs,reads, inclua os mesmos blocos em API_STAFF_PILOT_SLICES, reinicie e execute o cliente de teste com um token piloto da equipe. O cliente usa apenas a biblioteca padrão, lê o token de uma variável de ambiente e nunca o exibe:

powershell $env:GLICKO_API_TOKEN = "<token piloto>" python scripts/api_smoke_test.py --base-url https://exemplo.org/glicko --expect-enabled docs,reads --expect-disabled submissions,moderation,tournament_setup,tournament_participants,tournament_rounds

  1. Remova docs,reads de API_STAFF_PILOT_SLICES para abri-los aos membros. Depois habilite, um por vez, submissions, moderation, tournament_setup, tournament_participants e tournament_rounds, primeiro como piloto da equipe. Verifique cada etapa com o cliente de teste e os registros api.request.completed, que incluem o bloco, o status e a duração.

Para reverter, remova os blocos afetados de API_ENABLED_SLICES, reinicie e execute o cliente de teste com --expect-disabled. Se necessário, os titulares revogam os tokens piloto no próprio perfil. Desabilitar um bloco não desfaz gravações confirmadas: corrija os dados pelos fluxos web habituais e não restaure um banco anterior para reverter uma implantação da API. Os orçamentos medidos e os limites propostos estão nas notas operacionais.

Verificação em produção (2026-11-06)

As saídas informadas pelo operador e as verificações de leitura estão consolidadas nas observações de produção. Esses registros históricos não verificam gravações bem-sucedidas nem reversão em produção. O defeito de atividade e as verificações pendentes estão no roteiro.

A opção --write-draft-tournament do cliente de teste também cria um torneio rascunho; use-a somente com dados descartáveis. Para medir a API em um banco novo e descartável, que o script se recusa a sobrescrever:

python scripts/benchmark_api.py --output $env:TEMP\glicko-api-benchmark.db

Licença e atribuição

Glicko BD foi originalmente desenvolvido para a comunidade de Go na Colômbia por Juan Felipe Samper em 2026.

O sistema Glicko-2 foi publicado por Mark Glickman em 2022 no domínio público. A implementação em Python é ©2009 Ryan Kirkman e o BesoGo é ©2015-2018 Ye Wang. Ambos são distribuídos sob a licença MIT.

Este produto utiliza dados GeoLite criados pela MaxMind e dados do GeoNames. Consulte a licença GeoLite, CC BY 4.0 e CC BY-SA 4.0.

^