Módulo:Temporada/Utils/doc

Module:Temporada/Utils

Este módulo reúne **funções utilitárias reutilizáveis** para a automação das páginas de temporada da Wiki Galo Digital, com foco em:

• simplicidade de código
• segurança contra erros de parâmetros
• performance
• padronização de cálculos e regras

O módulo **não gera nenhuma saída visual direta**. Ele deve ser utilizado exclusivamente como dependência de outros módulos Scribunto.

---

Finalidade

O Module:Temporada/Utils funciona como a **camada de fundação lógica** do sistema de temporadas, centralizando operações comuns que seriam repetidas em diversos módulos, como:

• comparação de placares
• normalização de valores
• cálculo de resultados
• cálculo de aproveitamento
• interpretação de parâmetros booleanos vindos do wikitexto

Ele é utilizado, ou será utilizado, pelos seguintes módulos:

• Module:Temporada/Partidas
• Module:Temporada/Estatisticas
• Module:Temporada/Campanha
• Module:Temporada/Artilharia
• Module:Temporada

---

Princípios de implementação

O módulo foi desenvolvido seguindo os seguintes princípios:

• funções pequenas e legíveis
• nenhuma dependência externa
• nenhuma chamada a mw.title.new()
• comportamento defensivo (nunca quebra a renderização da página)
• retorno de valores simples e previsíveis

---

Funções disponíveis

toNumber(value, default)

Converte um valor em número de forma segura.

Parâmetros

• value – valor a ser convertido
• default – valor retornado caso a conversão falhe (opcional)

Retorno

• Número (integer ou float)

Observações

• Se value for nulo ou inválido, retorna default ou 0

---

normalizeString(value)

Normaliza uma string, removendo espaços extras e aplicando trim.

Parâmetros

• value – string de entrada

Retorno

• String normalizada
• String vazia caso o valor seja nulo

---

isAtletico(nome)

Verifica se o nome informado corresponde ao Clube Atlético Mineiro, independentemente de grafia ou acentuação básica.

Parâmetros

• nome – nome do time

Retorno

• true se for Atlético
• false caso contrário

Uso típico

Identificar automaticamente se o Atlético é mandante ou visitante em uma partida.

---

resultadoPartida(golsTime, golsAdversario)

Compara os gols de uma partida e retorna o resultado padrão.

Parâmetros

• golsTime
• golsAdversario

Retorno

• "V" – vitória
• "E" – empate
• "D" – derrota

---

cssResultado(resultado)

Retorna a classe CSS correspondente ao resultado da partida.

Parâmetros

• resultado – valor retornado por resultadoPartida

Retorno

• gd-result-win
• gd-result-draw
• gd-result-loss
• String vazia se inválido

---

pontosResultado(resultado)

Retorna a pontuação padrão associada ao resultado da partida.

Parâmetros

• resultado – "V", "E" ou "D"

Retorno

• 3 para vitória
• 1 para empate
• 0 para derrota

---

aproveitamento(pontosObtidos, pontosPossiveis)

Calcula o percentual de aproveitamento.

Parâmetros

• pontosObtidos
• pontosPossiveis

Retorno

• String formatada com uma casa decimal e símbolo de porcentagem
• Retorna "-" caso pontosPossiveis seja zero

Exemplo de retorno

37.5%

---

toBoolean(value)

Converte parâmetros textuais do wikitexto em booleano.

Valores interpretados como true

• sim
• true
• 1

Retorno

• true ou false

Uso típico

Leitura de parâmetros como:

• jogo anulado
• W.O
• jogo fora das estatísticas

---

Observações finais

• Este módulo **não deve ser chamado diretamente via #invoke em páginas de conteúdo**
• Toda lógica específica de temporada deve ficar nos módulos especializados
• Alterações neste módulo afetam todo o sistema de temporadas e devem ser feitas com cautela

---

Histórico

• Criado no contexto do projeto Wiki Galo Digital
• Desenvolvido para sustentar a automação das páginas de temporadas históricas
• Primeira aplicação prática: Futebol – Temporada 1919