﻿# Glicko BD

Documentação: [Español](README.md) | [English](README.en.md) | 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](#recursos)
- [Ajuda do usuário](#ajuda-do-usuário)
- [Requisitos](#requisitos)
- [Execução local](#execução-local)
- [Configuração](#configuração)
- [Plano do projeto](#plano-do-projeto)
- [Desenvolvimento](#desenvolvimento)
  - [Organização do código](#organização-do-código)
  - [Instalação em hospedagem Linux](#instalação-em-hospedagem-linux)
  - [Backups agendados e testes de restauração](#backups-agendados-e-testes-de-restauração)
  - [Implantação da API autenticada](#implantação-da-api-autenticada)
- [Licença e atribuição](#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)](docs/operations.md); o [roadmap](FUTURE_FEATURES.md) reúne o trabalho pendente. Consulte a [matriz de permissões](docs/user_interface.pt.md#painel-administrativo) 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.

- [Ajuda da interface](docs/user_interface.pt.md)
- [Rotas e notas de integração](docs/api_endpoints.pt.md)

## 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](requirements.txt)
- Dependências de desenvolvimento e teste: [requirements-test.txt](requirements-test.txt)

## Execução local

Windows PowerShell:

```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:

```bash
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_KEY` e `ADMIN_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_PATH` em `config.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ão `data/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) ou `WAL`: 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](docs/operations.md#sqlite-journals-analytics-and-restore-cutover).
- `GEOIP_COUNTRY_DB`: caminho do banco local GeoLite2 Country, por padrão `data/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](https://www.maxmind.com/en/geolite/eula).
- `MAIL_SERVER`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_USE_TLS` e `MAIL_FROM`: configuração SMTP para recuperação e alertas.
- `RECAPTCHA_SITE_KEY` e `RECAPTCHA_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_DAYS` e `SCHEDULED_BACKUP_KEEP`: retenção de auditoria e cópias agendadas.
- `BACKUP_FRESHNESS_ENABLED` (padrão `false`) e `BACKUP_FRESHNESS_MAX_AGE_HOURS` (padrão `768`): habilitam e configuram o verificador independente de backups.
- `API_RATE_LIMIT_READS_PER_TOKEN=60`, `API_RATE_LIMIT_WRITES_PER_TOKEN=20` e `API_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. Use `API_REQUIRE_HTTPS=false` somente no desenvolvimento local sem HTTPS.
- `API_ENABLED_SLICES` e `API_STAFF_PILOT_SLICES`: blocos da API habilitados e blocos limitados à equipe durante um piloto. Ambos ficam vazios por padrão, então a API retorna `503`; veja [Implantação da API autenticada](#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](FUTURE_FEATURES.md) para propostas pendentes e as [notas de implantação da API](docs/operations.md#api-rollout-and-rollback) 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](docs/operations.md#low-impact-production-validation). 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:

```powershell
python scripts/build_help_html.py
```

Execute os testes a partir da raiz:

```powershell
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:

```powershell
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:

```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
```

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](docs/operations.md#passenger-resource-investigation-and-report-read-regression).

### 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:

```cron
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):

```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
```

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`), ou `all`.
- `API_STAFF_PILOT_SLICES`: blocos habilitados que somente organizadores, gestores e administradores podem usar; as demais contas recebem `503` (`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.

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
   ```

3. 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](docs/operations.md#api-benchmark-and-proposed-budgets).

#### 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](docs/operations.md#production-api-observations). 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](FUTURE_FEATURES.md#production-verification-and-operations).

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:

```powershell
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](https://www.glicko.net/glicko/glicko2.pdf) 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](./static/vendor/besogo/LICENSE).

Este produto utiliza dados GeoLite criados pela [MaxMind](https://www.maxmind.com/) e dados do [GeoNames](https://www.geonames.org/). Consulte a [licença GeoLite](https://www.maxmind.com/en/geolite/eula), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) e [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
