Ajuda da interface
Consulte as rotas e notas de integração e o README em português.
Você também pode abrir este guia pelo botão ? na barra superior ou em /help?lang=pt.
Acessibilidade e dispositivos
- Use Pular para o conteúdo para ignorar a navegação. Os menus funcionam com teclado e toque; pressione Esc para fechá-los.
- Os filtros de rating e as fórmulas de categoria continuam disponíveis se os controles aprimorados não carregarem. O registro usa Google reCAPTCHA.
- Os cartões de conteúdo, estatísticas, variáveis e navegação compartilham bordas, cantos e espaçamento responsivo. Os cartões do diretório de jogadores e da lista de torneios são links completos: ative o título, os dados ou o espaço interno, ou use o teclado. A borda e a sombra indicam interação, e o foco do teclado permanece visível. Na administração de jogadores, o cartão abre o perfil, enquanto Editar e Excluir mantêm ações independentes. Cartões com tabelas, formulários ou vários destinos não são convertidos em um único link. As cores do tema, o alinhamento de cada tela, os links completos do menu administrativo e o rating destacado são preservados.
Índice
- Acessibilidade e dispositivos
- Interface pública
- Interface de membros
- Painel administrativo
- Guia de solução de problemas
Interface pública
Não é necessária uma conta para /, /rankings, /players, /player/view?id=<player_id>, /matches, /tournaments, /tournaments/<tournament_id>, /reports, /category e /sgf-library. Essas páginas oferecem ranking, perfis, histórico de partidas, torneios públicos, classificações, informações de rating, relatórios e visualização ou download de SGF.
Clique em qualquer captura para ampliá-la sem sair deste guia. Feche a visualização com Esc, pelo botão de fechar ou clicando fora da imagem.
A página pública oferece navegação, controles de idioma e tema, ranking, estatísticas e links para o conteúdo público.
As páginas aceitam ?lang=es, ?lang=en ou ?lang=pt; use AAAA-MM-DD nos filtros e campos de data.
Ranking e diretório de jogadores
- Ranking (
/rankings): permite filtrar por país, região, sub-18 e categoria feminina. A região padrão definida pelo administrador é inicialmente América Latina e também se aplica ao ranking da página inicial e à API. Escolha Todas as regiões para incluir jogadores de qualquer país; os filtros se intersectam. O seletor de país mostra apenas países atribuídos a jogadores. Os grupos sub-18 e feminino podem ser selecionados juntos. Os países usam códigos ISO 3166-1 alpha-3 e os códigos alpha-2 antigos são normalizados. - Diretório de jogadores (
/players): busca por nome ou sobrenome, filtros por intervalo de rating mínimo e máximo, data da última atividade e ordenação por qualquer coluna com paginação configurável. - Perfil do jogador (
/player/view?id=<id>): - Administradores, gestores e organizadores veem Editar somente quando suas permissões e seu escopo geográfico permitem editar o jogador; abre o editor administrativo existente.
- Resumo de rating atual, RD, volatilidade e categoria.
- Conquistas na carreira: melhor rating histórico, maior sequência de vitórias, vitórias como brancas e como pretas.
- País com uma pequena bandeira, ano de nascimento e uma marca para jogadoras são públicos; perfis mostram conquistas das cinco primeiras posições nacionais, regionais, sub-18 e femininas quando aplicável. Perfis não exibem uma marca de posição global.
- Em perfis de Taiwan, visitantes da China continental veem Taipé Chinês sem bandeira; fora da China continental é exibida a bandeira de Taiwan. Quando a localização é desconhecida, usa-se o idioma preferido do navegador: chinês simplificado mostra a alternativa e os demais idiomas mostram a bandeira. A detecção depende do banco local GeoLite e do IP disponível, portanto pode ser imprecisa; consulte
GEOIP_COUNTRY_DBno README para configurá-lo. - As conquistas comparativas de atividade, vitórias, melhora e melhor rating seguem a região definida pelo administrador, independentemente dos filtros da página de ranking. Com América Latina, somente jogadores dessa região são comparados; partidas contra adversários de fora continuam contando. Jogadores de fora não recebem essas conquistas comparativas nem as de classificação nacional, regional, sub-18 ou feminina. Todas as regiões volta a comparar jogadores de todos os países. A marca de organizador para contas vinculadas com funções da equipe independe da região.
- A elegibilidade sub-18 usa anos calendário:
ranking_year - 18 <= birth_year <= ranking_year(por exemplo, de 2008 a 2026 durante 2026). O valor interno9999identifica um jogador sub-18 cujo ano é desconhecido; o perfil mostra essa condição, não o valor. O jogador continua elegível até a atualização do registro, portanto a equipe deve revisá-lo. - Histórico completo de partidas com data, cor, oponente, resultado, evento e link para o visualizador SGF quando disponível. As partidas PairGo aparecem no mesmo histórico, ordenadas por data, com as duas duplas, a marca PairGo e um link para a partida; não contam nas estatísticas nem nos confrontos diretos. Não são exibidas marcas de partida ou torneio sem rating; os controles e as regras de rating são preservados.
- Gráfico interativo de evolução do rating ao longo do tempo.
- Histórico de torneios com posição inicial e final. Torneios PairGo concluídos aparecem no histórico dos dois jogadores como qualquer outro resultado e levam apenas à página do torneio.
- Tabela de confrontos diretos (Head-to-Head) contra cada oponente.
Perfil público com rating atual, categoria e resumo da atividade do jogador selecionado.
Partidas e visualizador SGF
- Lista de partidas (
/matches): histórico global de partidas registradas, com filtros por período e jogador, e ordenação por data, jogador branco, jogador preto, resultado ou rodada. - Visualizador SGF (
/matches/<id>/recorde/sgf-library/<filename>): visualizador interativo BesoGo integrado. Permite reproduzir jogadas lance a lance, alternar entre os temas Claro (Simples) e Escuro e baixar o arquivo original pelo link direto (/matches/<id>/sgfou/sgf/<filename>).
Torneios públicos
Torneios individuais cancelados mantêm acesso público aos detalhes por link direto, embora não apareçam nas listas; a API autenticada também permite esses detalhes com tournaments:read. Páginas web de detalhes PairGo cancelados continuam exclusivas para o pessoal.
- Lista de torneios (
/tournaments): exibe torneios ativos e concluídos com data, local, sistema de jogo, número de rodadas e status. Torneios cancelados não aparecem nesta lista. Torneios em rascunho e suas partidas permanecem ocultos do público; organizadores, gestores e administradores podem incluir rascunhos com a opção Mostrar rascunhos. - Detalhes do torneio (
/tournaments/<id>): consulte emparelhamentos e resultados mesa por mesa de cada rodada disputada, além da tabela de classificação oficial atualizada com categoria Dan/Kyu, pontuação (Pts/MMS), SOS, SOSOS e SODOS. Em torneios concluídos, a classificação aparece antes dos emparelhamentos. A equipe com permissão de edição e escopo geográfico sobre o torneio vê Editar, que abre suas configurações administrativas. - Na classificação individual, a categoria usa o último rating calculado antes da data de início. Sem partidas válidas anteriores, usa o rating inicial; se a fotografia ou a data de início não estiver disponível, usa o rating de inscrição. Pendentes usam seu rating de inscrição e PairGo mantém a categoria da dupla. Partidas no mesmo dia não são consideradas anteriores porque a hora não é registrada; a categoria não altera o desempate pelo rating de inscrição.
Detalhes de um torneio com seletor de rodada, mesas emparelhadas, resultados e classificação.
Relatórios periódicos e exportação
- Tela de relatórios (
/reports): analisa o desempenho dos jogadores em períodos específicos: - Períodos predefinidos: Todo o período, Este ano, Este trimestre ou Intervalo personalizado.
- Filtro opcional por jogador para examinar o desempenho contra adversários, clubes e países no período.
- As datas
start_dateeend_datesão inclusivas e avaliadas no fuso horário fixo do servidor (UTC-5). - A tabela de jogadores mostra 25 resultados por página por padrão, com opções para 50 ou 100. A navegação preserva os filtros ativos. A paginação limita apenas as linhas HTML exibidas; os dados do relatório e as exportações continuam usando o período e os filtros completos.
- Partidas com datas ou resultados inválidos são excluídas e contabilizadas no resumo.
- Exportação CSV (
/reports/export.csv): gera uma planilha CSV com a tabela exata calculada na tela, mantendo os filtros aplicados. - Exportação PDF (
/reports/export.pdf): gera um relatório em PDF formatado com cabeçalhos centralizados, data de geração, idioma atual e o nome do jogador e período no arquivo.
Conversor de categoria
A página /category converte um rating Glicko em categoria Dan/Kyu e exibe a fórmula, as constantes configuradas e a escala completa.
Dois controles expansíveis, inicialmente fechados, mostram a fórmula de conversão de categorias e a fórmula Glicko-2 com seus parâmetros atuais; os valores configuráveis também são destacados em /admin/ratings.
A força aumenta de 30 kyu a 1 kyu e depois de 1 dan a 9 dan: em kyu um número menor é mais forte, mas em dan um número maior é mais forte. Os limites da escala interna contínua são -N para N kyu e N - 1 para N dan (não há 0 kyu nem 0 dan); a categoria inteira usa floor nesse valor. Uma exibição decimal arredondada pode parecer alcançar o próximo limite embora o valor sem arredondamento ainda esteja abaixo dele.
O campo Glicko ocupa toda a largura disponível do formulário. Em /admin/categories, os campos GLICKO_K e GLICKO_M são mais largos e centralizados; ficam empilhados quando não cabem lado a lado em telas estreitas.
Notícias públicas
A página /news/<article_id> exibe o artigo publicado e transforma tags de jogadores, torneios e partidas em links relacionados.
Biblioteca SGF
A biblioteca pública (/sgf-library) lista arquivos SGF em uploads/sgf, com ou sem partida vinculada, sujeitos às regras de visibilidade:
- Ao enviar arquivos, valida tamanho, codificação UTF-8 e estrutura básica SGF.
- Sincroniza automaticamente as propriedades do cabeçalho SGF (jogadores branco e preto, graduações, evento, data e resultado) com a partida associada no banco de dados.
- Se um arquivo desaparecer, a referência é mantida, mas o link não é exibido; ele volta a funcionar se o arquivo retornar com o mesmo nome de armazenamento.
- Desvincular um arquivo ou excluir a partida mantém o registro na biblioteca; apenas administradores podem excluir arquivos físicos definitivamente.
Administradores podem selecionar vários arquivos SGF e excluí-los em uma única ação. As partidas e os resultados pendentes vinculados são mantidos, e suas referências SGF são removidas antes da exclusão dos arquivos.
Interface de membros
Os jogadores da comunidade podem registrar uma conta pessoal para gerenciar preferências e enviar resultados de torneios e partidas de clube.
Registro e início de sessão
- Abra
/admin/registerpara criar uma conta com nome de usuário, e-mail e senha (mínimo de 8 caracteres). O formulário é protegido pelo Google reCAPTCHA v3. - Contas novas recebem automaticamente a função
member. - Entre em
/admin/login. Para reportar resultados, solicite o vínculo com seu registro em Reportar Resultados e aguarde a aprovação.
Gestão de perfil e preferências
O menu Usuário reúne Menu de administração (conforme as permissões), Reportar Resultados, Perfil e Sair. Abra-o com mouse, teclado ou toque; pressione Esc para fechar.
Em /admin/profile, o usuário autenticado pode:
- Atualizar o endereço de e-mail para notificações e recuperação.
- Escolher o idioma preferido da interface (Español, English, Português).
- Alternar entre o tema claro e o tema escuro.
- Selecionar seu fuso horário IANA entre opções estáveis, mesmo quando compartilham o ajuste UTC atual (como UTC e Europe/London no inverno). O ajuste exibido muda com o horário de verão; um fuso válido salvo fora da lista sugerida continua disponível ao editar o perfil.
- Alterar sua senha informando a senha atual e confirmando a nova.
- Em Tokens de acesso à API, criar e revogar tokens pessoais para a API autenticada após confirmar a senha atual. Cada token é exibido uma única vez e dura até 90 dias (30 por padrão). Administradores escolhem seus escopos; as demais contas recebem os escopos permitidos pelas funções atuais, mostrados no formulário. Um token nunca concede mais que as permissões atuais da função, e as operações da API só funcionam depois que um operador as habilita (veja o guia da API).
Configurações de perfil do usuário para gerenciar idioma, tema, fuso horário e senha.
Recuperação de senha
- Caso esqueça sua senha, clique em Esqueceu sua senha? em
/admin/loginou acesse/admin/forgot-password. - Informe seu e-mail cadastrado. Se existente, o sistema enviará um link de uso único com token hash criptográfico.
- O link expira conforme o tempo configurado em
PASSWORD_RESET_TTL_SECONDS(padrão: 3600 segundos / 1 hora). - Abra o link
/admin/reset-password/<token>e defina a nova senha. Por segurança, a resposta nunca revela se o e-mail está cadastrado.
Enviar resultados
Membros podem reportar resultados de partidas em /admin/report-results:
- Vínculo com jogador: se sua conta de membro não tiver jogador vinculado, selecione seu perfil entre os jogadores sem conta vinculada e use Solicitar vínculo nesta página. Só pode haver uma solicitação pendente por conta. Um gestor do país/região do jogador ou um administrador aprova ou rejeita em Moderação de resultados (
/admin/result-submissions), com nota opcional. A solicitação não vincula a conta nem habilita o envio até sua aprovação. Depois, entre novamente. O histórico e as notas ficam disponíveis aqui; após rejeição você pode solicitar outro vínculo. A disponibilidade é verificada novamente ao aprovar, impedindo duas contas de reivindicarem o mesmo jogador. Administradores ainda podem atribuir vínculos diretamente. - Formulário de envio:
- Oponente: selecione o jogador adversário na lista de jogadores ativos.
- Cor: indique se jogou de Brancas ou Pretas.
- Resultado: vitória de Brancas (
1-0), vitória de Pretas (0-1) ou Empate (1/2-1/2). - Data: data em que a partida foi disputada (
AAAA-MM-DD). - Evento e Local: nome do torneio ou clube e cidade da partida.
- Rodada: número da rodada, se aplicável.
- Pedras de handicap: quantidade de pedras (0 a 9) concedidas às Pretas.
- Arquivo SGF (opcional): envie o arquivo
.sgfcom o registro das jogadas.
- Fila de moderação: as partidas enviadas entram no estado Pendente na fila de moderação (
/admin/result-submissions). Elas não afetam rankings, ratings ou relatórios públicos até serem revisadas e aprovadas pela equipe administrativa.
A tela mostra a exigência de vincular um jogador e a área de envios pendentes.
Painel administrativo
Entre em /admin/login com uma conta administrativa. A navegação disponível se adapta à função da conta:
- member: configurações de perfil e envio de resultados do jogador vinculado.
- country_organizer / regional_organizer (Organizadores): gestão de jogadores e torneios, incluindo criação de jogadores em torneios, edição/exclusão de jogadores, partidas, vinculação SGF, importação de torneios, participantes, emparelhamentos, rodadas, resultados e exportações.
- country_manager / regional_manager (Gestores): ferramentas dos organizadores, além de importação de jogadores dentro do âmbito, notícias e moderação de resultados.
- administrator: controle total da plataforma, incluindo jogadores, configurações de rating/categorias, backups, gestão de usuários, auditoria e parâmetros do sistema.
Os três níveis de acesso são Global, Regional e País. Administradores têm acesso global. Funções de país exigem um país, que pode vir do jogador vinculado quando não há seleção explícita; funções regionais exigem uma região explícita suportada (atualmente América Latina, identificada como latam). Uma função de país não pode usar uma região, nem uma função regional um país. Sem âmbito válido compatível, as rotas geográficas negam acesso. A equipe pode gerenciar jogadores dentro do âmbito, partidas com pelo menos um jogador dentro do âmbito e torneios cujo país pertença ao âmbito.
| Ferramentas | Organizadores | Gestores | Administradores |
|---|---|---|---|
| Jogadores, torneios, partidas e registros SGF | País/região atribuído | País/região atribuído | Global |
| Importação de jogadores e moderação de resultados | Não | País/região atribuído | Global |
| Notícias | Não | Sim (notícias compartilhadas do site) | Sim |
| Backups, importações globais, recálculo de ratings e categorias | Não | Não | Somente global |
| Usuários, auditoria e configurações | Não | Não | Somente global |
O menu agrupa as tarefas em Jogadores e competição (jogadores, partidas, torneios e moderação de resultados), Importações e ratings (importação de jogadores, importação geral, ratings e categorias), Conteúdo e registros de partidas (notícias e biblioteca SGF) e Administração do site (usuários, configurações, backups, auditoria e estatísticas). Cada cartão completo é um link acessível por teclado, sem um link Abrir separado. Somente as ferramentas permitidas e as seções com cartões visíveis aparecem; a organização não altera as permissões.
Contas operator migram para regional_manager e tournament_director para regional_organizer; ambas recebem o âmbito da América Latina, substituindo qualquer país anterior. A migração invalida suas sessões e tokens existentes uma única vez.
Gestão de torneios
1. Criação e configuração de torneios (/admin/tournaments)
- Nome, local, país e datas: informe o título oficial, cidade/sede, país do torneio e datas de início e término. O país explícito determina o âmbito geográfico das operações do torneio.
- Número de rodadas: defina o total de rodadas planejadas.
- Modalidade PairGo: escolha PairGo ao criar o torneio para competir em duplas de jogadores ativos, sem restrições de gênero. Os quatro sistemas estão disponíveis; a média dos ratings determina a categoria e a posição inicial da dupla. A modalidade não pode ser alterada após a criação. PairGo nunca é pontuável.
- Sistema de emparelhamento:
- Suíço padrão (
swiss): emparelha participantes com pontuações próximas, evitando repetição de adversários e equilibrando as cores branca e preta. - Suíço por categoria (
swiss_cat): restringe emparelhamentos estritamente dentro da mesma categoria nas rodadas iniciais indicadas. - Suíço acelerado (
accelerated_swiss): divide os participantes em faixas de aceleração (esquema de 3 faixas Go ou limites de categoria personalizados) nas rodadas iniciais para acelerar a convergência. As bonificações usam pontos inteiros; valores decimais personalizados não são válidos. - McMahon (
mcmahon): atribui pontuação inicial (MMS) com base na graduação a partir da Barra McMahon (mm_bar), Piso McMahon (mm_floor) e Zero McMahon (mm_zero). Barra e piso usam seletores de categorias de9 dana30 kyunas configurações e revisões de importação, e etiquetas de categoria nos resumos; zero permanece numérico. Valores antigos fora desse intervalo são preservados como uma opção selecionada. Salvar preserva os valores e as regras de emparelhamento; a barra deve ficar acima do piso. - Pontuação de folgas (BYE) e ausências:
- Pontos por descanso (BYE): pontos atribuídos ao participante sem par quando o número for ímpar (padrão: 1.0 ponto).
- Pontos por ausência: pontos concedidos em partidas não jogadas por ausência (padrão: 0.0 pontos).
- Handicap automático: habilita ou desabilita a sugestão automática de pedras calculada pela diferença de categoria.
- Rating do torneio: a opção Torneio válido para rating fica marcada por padrão. Desmarque-a para que, quando concluídos, o torneio e suas partidas continuem públicos sem afetar os ratings; essas partidas são identificadas como não pontuáveis.
- Ações rápidas da lista: a lista de torneios, os filtros e os botões Copiar torneios selecionados e Excluir torneios selecionados aparecem antes dos formulários de criação e importação, sem botões de ações por linha. Use a caixa no cabeçalho para selecionar ou limpar todos os torneios da página atual.
- Copiar torneios em lote: selecione até 100 torneios e escolha Copiar torneios selecionados para criar um rascunho por torneio com suas configurações e participantes. Datas, emparelhamentos e resultados não são copiados. Se algum torneio for inválido ou estiver fora do seu âmbito, nenhum será copiado; repetir a mesma solicitação não duplica as cópias.
- Excluir torneios em lote: selecione torneios da página atual e confirme a exclusão. As rodadas, emparelhamentos, participantes e partidas vinculadas serão excluídos; os arquivos SGF serão mantidos.
2. Gestão de participantes
- Duplas PairGo: em Gerenciar duplas, selecione dois jogadores ativos distintos para cada dupla. Cada jogador pode integrar apenas uma dupla no torneio. Quando ainda houver rodadas, uma dupla adicionada após a conclusão de uma rodada participa a partir da próxima; se a rodada estiver em andamento, deve participar dela. Para editar ou remover uma dupla já emparelhada, confirme que todos os seus emparelhamentos e resultados serão excluídos; depois emparelhe novamente as mesas afetadas. Copiar um torneio mantém as duplas, mas não as rodadas ou os resultados.
- Adicionar participantes em lote: selecione vários jogadores disponíveis na página de gestão e adicione-os em uma única ação.
- Remover participantes em lote: selecione vários jogadores inscritos e confirme a remoção. A operação é atômica; se algum jogador não puder ser removido (por exemplo, porque já foi emparelhado), nenhum será removido.
- Inscrição de jogadores: adicione jogadores ativos existentes pelo seletor ou crie um jogador pendente no torneio. Ao detectar um nome parecido, um diálogo identifica o torneio, o nome informado e o candidato: use o jogador sugerido, revise a entrada ou crie o jogador mesmo assim. Para jogadores já pendentes, aceite o candidato ou mantenha-os pendentes. Esc fecha o diálogo; ninguém é vinculado sem uma ação explícita. Se JavaScript ou diálogos nativos não estiverem disponíveis, a sugestão e suas ações permanecem na página.
- Retirada de participantes: remova participantes antes do início da primeira rodada.
- Importação OpenGotha XML: envios diretos em
/admin/tournamentsabrem uma revisão das configurações, operações previstas, avisos e impacto nos ratings. Nenhum dado é alterado até a aprovação explícita. Você pode vincular participantes, aceitar uma sugestão, criar jogadores, deixá-los pendentes ou ignorá-los; atualize o resumo após alterar decisões e aprove novamente. O torneio é criado como rascunho, e a aprovação expira após 15 minutos.
3. Emparelhamentos, rodadas e registro de resultados
- Gerar rodada: o algoritmo emparelha os jogadores automaticamente respeitando o sistema escolhido, evitando repetições e alternando cores.
- Tratamento de folgas (BYE): quando o número for ímpar, um BYE é atribuído automaticamente. O histórico é registrado para não repetir o BYE em um jogador enquanto outros ainda não o receberam.
- Emparelhamento manual e assistido:
- Emparelhar selecionados: selecione dois jogadores livres e clique em Emparelhar selecionados.
- Desemparelhar / Desemparelhar tudo: desfaça uma mesa específica ou reinicie a rodada inteira.
- Ajuste de handicap por mesa: cada mesa exibe a sugestão de pedras calculada automaticamente; o organizador pode editar as pedras antes de salvar o resultado.
- Ciclo de 7 estados de resultados: clique no nome do vencedor ou no texto do resultado para avançar entre:
1.
-: Pendente (partida ainda não jogada). 2.1-0: Vitória das Brancas. 3.1/2-1/2: Empate. 4.0-1: Vitória das Pretas. 5.1-!0: Vitória das Brancas por ausência das Pretas. 6.!0-1: Vitória das Pretas por ausência das Brancas. 7.!0-0: Ausência de ambos os jogadores (dupla derrota). Clicar novamente no vencedor selecionado limpa o resultado de volta para pendente (-). - Categorias dos jogadores: cada mesa mostra a categoria abreviada (por exemplo,
5dou3k) ao lado do nome de cada jogador.
Painel de controle de rodada do torneio: emparelhamentos, mesas, seletor de resultados e classificação.
4. Processamento de rodadas e cálculo de rating
- Processar rodada (
Procesar ronda): - Converte automaticamente os resultados individuais jogados (
1-0,1/2-1/2,0-1) em partidas oficiais no banco de dados. Resultados PairGo permanecem como partidas de seus emparelhamentos, aparecem na lista pública e no histórico de partidas dos quatro jogadores; nunca entram no cálculo de ratings ou estatísticas individuais. - Ausências (
1-!0,!0-1,!0-0) contam para a classificação e desempates do torneio, mas nunca afetam ratings oficiais nem perfis de jogadores. - Aplica o ajuste logarítmico de rating por pedra quando a partida for com handicap.
- Em torneios individuais, dispara o recálculo incremental de ratings em ordem cronológica por data e rodada.
- Classificação e desempates: as posições são estritamente sequenciais e únicas. Empates em pontos ou MMS são resolvidos de forma determinística por SOS, SOSOS, SODOS, rating base e ordem alfabética.
- Ordem e migrações: no mesmo dia, as atualizações de rating respeitam a rodada e depois a ordem de inserção. As notas de rodada são armazenadas como inteiros quando possível; rodadas desconhecidas usam a rodada 1. As tabelas de torneios são migradas automaticamente na inicialização.
- Ciclo de vida do torneio:
- Rascunho (
draft): oculto do portal público durante a preparação. - Ativo (
active): publicado e visível com emparelhamentos e classificação em tempo real. - Concluído (
completed): torneio encerrado com classificação final. Se Torneio válido para rating estiver desmarcado, suas partidas aparecem nas listas públicas e nos perfis, mas não afetam os ratings. - Cancelado (
canceled): não aparece na lista pública e suas partidas não afetam os ratings. - Os perfis de jogadores listam apenas torneios concluídos. Partidas de torneios ativos não afetam os ratings até a conclusão; rascunhos e torneios cancelados ficam fora das listas públicas e suas partidas não afetam os ratings. Detalhes individuais cancelados continuam acessíveis por link direto.
- Exportação de resultados: a exportação OpenGotha está disponível para torneios individuais, não para PairGo.
Gestão de dados
1. Assistente de importação com prévia (/admin/import)
Importe planilhas históricas, partidas ou arquivos do OpenGotha:
- Formatos aceitos:
- Planilha Excel (.xlsx): substitui o conjunto de dados ativo com jogadores e partidas completos.
- XML do OpenGotha (.xml): importa metadados do torneio, participantes, emparelhamentos e pedras de handicap.
- Arquivo CSV (.csv): colunas date, white, black, result e opcional handicap (0 a 9).
- Crie um backup antes de importar uma planilha que substitua os dados ativos.
- As importações são limitadas a 10 MiB por arquivo, 100 MiB de conteúdo XLSX descompactado e 10.000 linhas por planilha, CSV ou conjunto combinado de participantes/partidas OpenGotha. A importação de jogadores em /admin/players mantém limites menores: 5 MiB e 1.000 jogadores.
- Os envios OpenGotha por /admin/import e /admin/tournaments usam o mesmo fluxo de revisão e aprovação por etapas. Revise ou edite as configurações do torneio, o resumo das operações, os avisos e as decisões dos participantes; a prévia não altera o banco. Use Aprovar e importar somente depois de revisar o resumo atualizado. Se jogadores ou torneios mudarem enquanto a prévia estiver aberta, envie o arquivo novamente.
- Reconciliação explícita de jogadores:
- A prévia classifica cada registro como Correspondência exata, Sugestão aproximada, Novo jogador ou Duplicado.
- A equipe autorizada decide para cada jogador: vincular ao existente, criar novo ou rejeitar a linha.
- Metadados do torneio podem ser revisados e editados antes da confirmação.
- O CSV é validado antes da gravação: datas, resultados (1-0, 0-1 ou 1/2-1/2), handicap, jogadores existentes e erros por linha/campo. Qualquer erro bloqueia toda a importação; as gravações no banco são transacionais.
- A prévia XLSX identifica a planilha e a linha com dados inválidos e não substitui os dados se houver erros. A substituição continua exigindo confirmação explícita e backup verificado antes da importação.
- A prévia OpenGotha avisa sobre partidas cujos jogadores não estão no XML. O recibo final informa quantidades, avisos e o estado dos ratings. O torneio importado permanece como rascunho e não afeta os ratings imediatamente; ao ser concluído, partidas elegíveis podem marcar a data afetada para recálculo.
- Se DEFER_RATING_REPLAY_ON_IMPORT estiver ativado, a importação será concluída, mas um aviso informará que os ratings podem ficar desatualizados até a execução do recálculo adiado.
Exemplo de prévia e reconciliação de importação. As importações de torneios OpenGotha usam uma tela específica de revisão e aprovação.
2. Administração de jogadores (/admin/players)
- Localizado em Jogadores e competição para organizadores, gestores e administradores. A importação separada de CSV/XLSX pertence a Importações e ratings e exige gestor ou administrador.
- Filtre jogadores por nome, faixa de rating e status ativo/inativo.
- Importar jogadores: envie um CSV ou XLSX com as colunas
Name,RankeCountry. Use classificações Go de30ka9d(por exemplo,5kou1d); o país pode ficar em branco. Revise a prévia e os erros por linha antes de confirmar. Nomes existentes ou repetidos e linhas inválidas bloqueiam toda a importação. - Editar jogador (
/admin/players/edit?id=<id>): atualize nome, nome de exibição, rating inicial, país, ano de nascimento opcional, uma caixa para indicar se é mulher e status ativo. Os dados demográficos são públicos; o ano de nascimento é usado no ranking sub-18. Se o jogador é sub-18 mas seu ano é desconhecido, deixe o ano vazio e marque Sub-18 (ano de nascimento desconhecido). Desmarque a opção para remover essa condição ou substituí-la por um ano conhecido; não é possível informar ambos. - Excluir jogador: modal de confirmação seguro que avisa sobre a exclusão do histórico e partidas associadas.
- Categoria inicial e rating inicial: escolha uma categoria na lista de 9 dan a 30 kyu para atualizar o rating inicial, ou edite o rating para atualizar a categoria selecionada. Ambos os campos permanecem editáveis, sem seletor de modo ou texto de ajuda. Ratings vazios ou fora da faixa de categorias deixam a seleção vazia, sem alterar o rating. A conversão base usa
rating = m * exp((c + 29) / k), comc = dan - 1ouc = -kyu, mais o deslocamento inicial configurado. Jogadores sem partidas também atualizam o rating atual; com histórico, usa-se o recálculo normal. A sincronização imediata exige JavaScript; sem ele, mudanças de categoria são aplicadas ao salvar se o rating não mudou; se ambos os campos mudarem, o rating prevalece.
Ao selecionar uma categoria inicial, o campo de rating mostra uma casa decimal; ao salvar, a conversão mantém sua precisão para não reduzir a categoria. Ratings inseridos manualmente preservam sua precisão.
3. Administração de partidas (/admin/matches)
- Lista paginada de todas as partidas com filtros de data e jogador.
- Adicionar partida (
/admin/matches/add): formulário com validação rigorosa de data (AAAA-MM-DD), jogadores distintos existentes, resultado válido (1-0,0-1,1/2-1/2), pedras de handicap (0-9) e envio opcional de SGF. - Editar partida (
/admin/matches/edit?id=<id>): permite corrigir jogadores, datas, resultados ou anotações de rodada. - Quando resultados de torneio viram partidas oficiais,
eventmantém o nome do torneio enotes(exibido comoRound) armazena a rodada como inteiro. Valores antigos são convertidos quando contêm um número; textos sem número são mantidos e tratados como rodada 0. - Vincular e desvincular SGF: vincule arquivos SGF da biblioteca ou envie novos registros sincronizados.
4. Configuração de ratings e categorias (/admin/ratings e /admin/categories)
- Parâmetros Glicko-2:
- Rating inicial padrão (ex.: 1500).
- Desvio de rating inicial (RD, ex.: 350).
- Volatilidade inicial ($\sigma$, ex.: 0.06).
- Constante de tempo do sistema ($\tau$, ex.: 0.5).
- Conversão de categorias Dan/Kyu:
- Constante de escala $k$ e deslocamento $m$.
- Deslocamento do rating inicial (padrão +5 pontos; 0 desativa). Aplica-se a categorias de novos jogadores importados, jogadores pendentes criados manualmente e edições da categoria inicial; se alcançaria a categoria seguinte, limita-se ao ponto médio da categoria selecionada. Ratings digitados diretamente e pendentes importados não são alterados. A migração e o salvamento das configurações atualizam pendentes manuais não vinculados cuja categoria é conhecida ou identificável sem ambiguidade; os demais e jogadores existentes não são atualizados automaticamente. Alterar a configuração não recria emparceiramentos existentes.
- Limites mínimos para níveis Dan e Kyu.
- Recálculo de ratings:
- Recálculo completo: reprocessa todo o histórico cronologicamente por data e rodada.
- Atualização incremental: recalcula instantâneos a partir da data modificada mais antiga (dirty date).
- Alterações de status que adicionam ou removem partidas de torneios concluídos marcam a data afetada mais antiga; os ratings são atualizados quando uma dessas ações é executada.
5. Fila de moderação de resultados (/admin/result-submissions)
- Revise partidas enviadas pelos membros da comunidade.
- Inspecione detalhes completos: remetente, oponente, cores, resultado, data, handicap e visualizador do SGF anexo.
- Aprovar: materializa a partida no banco de dados oficial e atualiza os ratings automaticamente.
- Rejeitar: descarta o envio permitindo registrar uma nota de revisão visível para auditoria.
Tarefas administrativas e de segurança
1. Backups e restauração (/admin/backups)
- Localizado em Administração do site; todas as operações de backup continuam reservadas a administradores.
- Criar backup: gera um backup SQLite verificado, com data e nome seguro, em
backups/. Os arquivos SGF permanecem emuploads/sgf; o backup guarda apenas os vínculos dos registros de partidas com eles. - Restaurar backup:
- Antes de restaurar, guarda um snapshot verificado do banco atual como
*-pre-restore-*.dbembackups/. - Prepara a cópia restaurada, executa sobre ela as migrações pendentes e a verifica antes de substituir o banco ativo. Se alguma etapa falhar, o banco ativo permanece inalterado.
- Reconstrói os artefatos e o índice de busca textual FTS5 (
players_fts). - Não altera
uploads/sgf. As referências a arquivos SGF ausentes são mantidas e ignoradas até que retornem com os mesmos nomes. - Restringe candidatos a arquivos gerenciados e ao backup
.bakdesignado. - Backups agendados: os backups criados pelo job
scripts/scheduled_backup.pyaparecem aqui junto com os manuais. O job mantém osSCHEDULED_BACKUP_KEEPbackups agendados mais recentes (padrão 14) e nunca exclui backups manuais, anteriores a importações ou anteriores a restaurações. - Status operacional (somente administradores): mostra desde quando os ratings estão pendentes, os resultados mais recentes do recálculo, do backup agendado e do teste de restauração, da retenção, das restaurações manuais e das ações administrativas com falha. Os novos eventos são limitados a 180 dias e 2.000 registros; os anteriores com fuso desconhecido são mantidos indefinidamente. Os novos horários são exibidos no fuso do usuário, e os anteriores como foram registrados. As páginas públicas mostram apenas se os ratings estão atualizados, pendentes ou se não foi possível determinar o estado; a data interna não é exibida.
- Teste de restauração: os backups agendados são restaurados e verificados em um banco temporário antes de remover backups antigos. Pratique uma restauração completa somente em uma instância descartável e verifique depois o banco e os arquivos SGF.
- Janela de manutenção: antes de substituir o banco ativo, bloqueie novas gravações e aguarde a conclusão das solicitações em andamento durante a troca final. Se não for possível pausar o tráfego da aplicação, programe a restauração para uma janela de manutenção; leitores SQLite abertos podem impedir a substituição atômica, especialmente no Windows.
- Proteção SGF: a aplicação nunca faz backup nem restaura
uploads/sgf; o SQLite guarda apenas nomes e vínculos. Caso deseje proteger os arquivos, o operador deve copiá-los e restaurá-los separadamente fora da aplicação. - Excluir backups: remove cópias antigas para liberar espaço de armazenamento.
- Execute
python scripts/check_legacy_players_state.pypara auditar o banco ativo e os backups gerenciados.
Lista de backups com ações de criar, restaurar e excluir.
2. Gestão de contas de usuários (/admin/users)
- Crie e edite contas com funções
administrator,country_organizer,regional_organizer,country_manager,regional_manageroumember. Atribua um país às funções de país e uma região às regionais; o país do jogador vinculado só serve de fallback para funções de país. Alterações de função ou âmbito invalidam sessões e tokens. - Atribua um país às funções de país ou a região suportada da América Latina (
latam) às regionais. Sem âmbito compatível não há acesso geográfico; o país do jogador vinculado só serve de fallback para funções de país. - Vincule contas de usuário a perfis de jogadores para habilitar o envio de resultados.
- Atribua fusos horários individuais a cada conta; ao editá-la, um fuso IANA válido salvo fora das opções sugeridas continua visível.
- Ative ou desative contas de usuário.
3. Publicação de notícias (/admin/news)
- Localizado em Conteúdo e registros de partidas, disponível a gestores e administradores. Notícias são conteúdo compartilhado do site, sem âmbito de país.
- Redija notícias com título, texto e status de publicação (Rascunho ou Publicada).
- Insira tags inteligentes no texto:
[player:12],[tournament:5],[match:104], renderizadas na visualização pública como links interativos e atalhos para o visualizador SGF.
4. Registro e revisão de auditoria (/admin/audit)
- Registro completo de todas as ações administrativas que alteram o estado do sistema: importações, ciclo de vida de torneios, partidas, alterações de rating/categorias, usuários e backups.
- Filtre por usuário autor, categoria de ação, busca livre de texto e período de datas.
- Resumo compacto em JSON limitado a 2 KiB por evento. Os novos eventos são exibidos e filtrados no fuso do usuário e descartados após 730 dias (
AUDIT_RETENTION_DAYS); os anteriores com fuso desconhecido são exibidos como registrados e mantidos indefinidamente. - Os novos eventos são ordenados pelo instante UTC; os anteriores aparecem depois, na ordem de registro, pois não é possível recuperar sua ordem cronológica exata.
5. Estatísticas do site (/admin/analytics)
- Relatório exclusivo para administradores de visualizações corretas de páginas HTML públicas e visitantes diários aproximados nos últimos 30 dias.
- Solicitações autenticadas, rotas administrativas e agentes de usuário que parecem bots são excluídos. A detecção de bots é aproximada.
- Um cookie temporário de 24 horas contém apenas a data e evita contar o mesmo navegador mais de uma vez por dia. Apagar ou bloquear cookies pode inflar os totais; visitas em dias diferentes são contadas novamente, portanto os totais do período são visitas-dia, não pessoas únicas.
- Quando o GeoLite2 está disponível, o IP da solicitação é usado somente em memória para obter o país no banco local; este recurso não o salva no banco de dados de análise. Os logs de acesso da hospedagem são independentes. Localizações indisponíveis são agrupadas como desconhecidas. IPs, identificadores de visitantes, caminhos, agentes de usuário e referentes não são armazenados por este recurso.
- Os agregados ficam em um arquivo SQLite separado com sufixo
.analytics.dbao lado do banco principal; backups/restaurações da aplicação não o incluem. Totais diários e países são mantidos por 400 dias e removidos na inicialização e na primeira gravação ou consulta administrativa de cada novo dia, sem reiniciar os workers.
6. Configurações de segurança da aplicação (/admin/settings)
- Ajuste o número máximo de tentativas de login falhas antes do bloqueio temporário por IP.
- Defina a janela de tempo da limitação de taxa (em segundos).
- Configura a duração (TTL) dos links de recuperação de senha.
- Define o formato do nome dos jogadores:
Sobrenome, Nome(padrão),Nome Sobrenomeou um modelo personalizado com{first_name}e{last_name}. Os nomes são exibidos conforme este formato; salvar uma mudança não altera os dados armazenados. Na edição de cada jogador, é possível informar um nome personalizado opcional. Nome e sobrenome não podem conter vírgulas. - Define a região padrão de rankings e conquistas: América Latina (padrão inicial) ou Todas as regiões. A mudança afeta o ranking da página inicial, rankings web e API e conquistas dos perfis, mas não restringe o diretório de jogadores.
- O botão de restauração restabelece os padrões da aplicação, inclusive a região América Latina.
- A revisão de outras configurações globais para administradores está em F24 do roteiro.
Guia de solução de problemas
- Acesso negado (403): verifique sua função de organizador, gestor ou administrador e seu âmbito geográfico compatível. Importação de jogadores, notícias e moderação exigem um gestor ou administrador; operações globais exigem um administrador.
- Não consigo enviar resultados como membro: confirme em
/admin/usersse sua conta está vinculada a um registro de jogador ativo. - Erros na importação de arquivos:
- Certifique-se de que o CSV use codificação UTF-8 e contenha os cabeçalhos obrigatórios
date,white,black,result. - Verifique se o formato de data éAAAA-MM-DDe os resultados são exclusivamente1-0,0-1ou1/2-1/2. - Verifique se as pedras de handicap estão no intervalo de 0 a 9. - Arquivos SGF não encontrados: a referência é mantida sem exibir um link quebrado. Se o operador devolver o arquivo a
uploads/sgfcom o nome de armazenamento original, o vínculo volta a funcionar; um novo envio recebe outro nome e deve ser vinculado explicitamente. - Restauração de banco de dados: após restaurar um backup, aguarde o término das migrações e da indexação FTS5 antes de iniciar operações.
- Segurança em produção: mantenha segredos (
APP_SECRET_KEY,ADMIN_PASSWORD, credenciais SMTP e chaves reCAPTCHA) em variáveis de ambiente do servidor, nunca no controle de versão.







