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
- Requisitos
- Execução local
- Configuração
- Plano do projeto
- Desenvolvimento
- Organização do código
- Instalação em hospedagem Linux
- Backups agendados e testes de restauração
- Implantação da API autenticada
- Licença e atribuição
Recursos
- Classificações públicas, busca, perfis, histórico de partidas e gráficos de rating
- Cálculo Glicko-2 configurável e interface em espanhol, inglês e português
- Importação de Excel, CSV e OpenGotha; envios de torneios OpenGotha são revisados e aprovados antes de aplicar alterações
- Sistemas suíço, suíço por categoria, suíço acelerado e McMahon
- Registro de membros, solicitações moderadas de vínculo com jogadores sem conta e envio de resultados para aprovação administrativa
- Relatórios filtráveis com exportação CSV/PDF, notícias e biblioteca pública de SGF
- Cópias de segurança, restauração protegida e migrações SQLite
- Classificações por país, região, idade e categoria feminina; a região padrão dos rankings web/API é configurável (inicialmente América Latina)
- Três níveis de acesso: global (administradores), regional e país; organizadores têm Operações de torneios (incluindo jogadores) e gestores também têm Gestão de dados
- Partidas com handicap, BYE e ausências
- Rascunhos permanecem ocultos e torneios cancelados não aparecem nas listas públicas; detalhes individuais cancelados continuam acessíveis por link direto. Torneios concluídos não pontuáveis exibem suas partidas sem afetar os ratings
- Torneios PairGo com dois jogadores por dupla e sem restrições de gênero; nunca são pontuáveis e não alteram estatísticas nem confrontos individuais
- Navegação acessível por teclado, suporte a movimento reduzido e filtros com controles nativos de fallback
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
- Python 3.10, 3.11, 3.12 ou 3.13 (versões incluídas na matriz do CI)
pip- Dependências Python: requirements.txt
- Dependências de desenvolvimento e teste: requirements-test.txt
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.
APP_SECRET_KEYeADMIN_PASSWORD: chave de sessão e senha de uso único para criar a conta administradora inicial. Use valores seguros em produção.APP_PUBLIC_ORIGIN: origem HTTPS pública para links de recuperação de senha.DB_PATHemconfig.py: caminho do banco SQLite; não é uma variável de ambiente.- A análise usa um arquivo separado ao lado de
DB_PATH, com sufixo.analytics.db(padrãodata/acg_ratings.analytics.db); backups e restaurações da aplicação não o incluem. A inicialização importa linhas históricas ausentes da tabela antiga sem alterá-la. SQLITE_JOURNAL_MODE=DELETE(padrão) ouWAL: modo de diário do banco principal, aplicado na inicialização. WAL exige um sistema de arquivos local compatível e validação em staging; todas as conexões da aplicação aguardam até 5000 ms por bloqueios. Veja o procedimento WAL.GEOIP_COUNTRY_DB: caminho do banco local GeoLite2 Country, por padrãodata/GeoLite2-Country.mmdb. Ele é usado para exibição de perfis e estatísticas agregadas do site. Não está incluído; obtenha-o conforme sua licença.MAIL_SERVER,MAIL_PORT,MAIL_USERNAME,MAIL_PASSWORD,MAIL_USE_TLSeMAIL_FROM: configuração SMTP para recuperação e alertas.RECAPTCHA_SITE_KEYeRECAPTCHA_SECRET_KEY: chaves reCAPTCHA v3 para o registro de membros.LOAD_SAMPLE_DATA=1: carrega dados de exemplo locais; não use em produção.AUDIT_RETENTION_DAYSeSCHEDULED_BACKUP_KEEP: retenção de auditoria e cópias agendadas.BACKUP_FRESHNESS_ENABLED(padrãofalse) eBACKUP_FRESHNESS_MAX_AGE_HOURS(padrão768): habilitam e configuram o verificador independente de backups.API_RATE_LIMIT_READS_PER_TOKEN=60,API_RATE_LIMIT_WRITES_PER_TOKEN=20eAPI_RATE_LIMIT_REQUESTS_PER_IP=120: limites da API por janela fixa de 60 segundos.API_MAX_REQUEST_BYTES=1048576: tamanho máximo do corpo de uma solicitação da API (1 MiB).API_REQUIRE_HTTPS=true: exige HTTPS para solicitações bearer e criação de tokens. UseAPI_REQUIRE_HTTPS=falsesomente no desenvolvimento local sem HTTPS.API_ENABLED_SLICESeAPI_STAFF_PILOT_SLICES: blocos da API habilitados e blocos limitados à equipe durante um piloto. Ambos ficam vazios por padrão, então a API retorna503; veja Implantação da API autenticada.
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:
- Programa:
C:\caminho\glicko-db\.venv\Scripts\python.exe - Argumentos:
scripts\scheduled_backup.py - Iniciar em:
C:\caminho\glicko-db
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.
API_ENABLED_SLICES: blocos habilitados, separados por vírgulas (docs,reads,submissions,moderation,tournament_setup,tournament_participants,tournament_rounds), ouall.API_STAFF_PILOT_SLICES: blocos habilitados que somente organizadores, gestores e administradores podem usar; as demais contas recebem503(api_pilot_restricted).
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.
- Confirme um backup verificado, HTTPS e a configuração de proxies confiáveis. Registre nas notas de versão os blocos habilitados.
- Habilite
docs,reads, inclua os mesmos blocos emAPI_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
- Remova
docs,readsdeAPI_STAFF_PILOT_SLICESpara abri-los aos membros. Depois habilite, um por vez,submissions,moderation,tournament_setup,tournament_participantsetournament_rounds, primeiro como piloto da equipe. Verifique cada etapa com o cliente de teste e os registrosapi.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.