Módulo:Temporada/Utils

Módulo:Temporada/Utils

O Módulo:Temporada/Utils concentra funções utilitárias reutilizáveis utilizadas pelos módulos de temporada do projeto Wiki Galo Digital.

Este módulo **não gera saída visual** e existe para:

• Evitar repetição de código
• Padronizar cálculos e validações
• Centralizar regras simples e transversais

---

Escopo e responsabilidades

Este módulo é responsável por:

• Conversões seguras de tipos (string, número, boolean)
• Normalização básica de valores vindos da wiki
• Cálculos genéricos utilizados em estatísticas e campanhas
• Regras auxiliares de comparação de resultados
• Apoio à padronização visual indireta (classes CSS)

---

Dependências

Este módulo utiliza funções nativas do MediaWiki:

• mw.text.trim
• mw.ustring.lower

Não possui dependência direta de outros módulos do projeto.

---

Funções públicas

toNumber(value, default)

Converte um valor para número de forma defensiva.

• Parâmetros
  • value – valor a ser convertido
  • default (opcional) – valor padrão em caso de falha

• Retorno
  • Número convertido ou valor padrão
  • Retorna 0 caso nenhum padrão seja informado

• Uso típico
• Tratamento de parâmetros vindos de templates
• Cálculos estatísticos

---

normalizeString(valor)

Normaliza uma string removendo espaços excedentes.

• Parâmetro
  • valor (string)

• Retorno
  • String normalizada
  • Retorna string vazia se o valor não for string

---

isAtletico(nome)

Verifica se um nome se refere ao Clube Atlético Mineiro.

• Parâmetro
  • nome (string)

• Retorno
  • true se identificar “atlético” ou “atletico”
  • false caso contrário

---

resultadoPartida(golsTime, golsAdversario)

Compara o placar de uma partida.

• Parâmetros
  • golsTime
  • golsAdversario

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

---

cssResultado(resultado)

Retorna a classe CSS associada ao resultado da partida.

• Parâmetro
  • resultado (V, E, D)

• Retorno
  • Classe CSS correspondente
  • String vazia se inválido

• Classes utilizadas
  • gd-result-win
  • gd-result-draw
  • gd-result-loss

---

aproveitamento(pontosObtidos, pontosPossiveis)

Calcula o aproveitamento percentual.

• Parâmetros
  • pontosObtidos
  • pontosPossiveis

• Retorno
  • Número percentual (0 a 100)
  • Retorna 0 se pontosPossiveis for zero

---

pontosResultado(resultado)

Converte o resultado da partida em pontuação padrão (3-1-0).

• Parâmetro
  • resultado (V, E, D)

• Retorno
  • 3, 1 ou 0

---

toBoolean(value)

Converte parâmetros vindos da wiki ou Lua para booleano real.

• Parâmetro
  • value

• Reconhece como verdadeiro
  • true (boolean)
  • "sim"
  • "true"
  • "1"

• Retorno
  • true ou false

---

Boas práticas

• Não adicionar renderização visual
• Não incluir lógica específica de domínio
• Manter funções pequenas e previsíveis
• Centralizar aqui regras simples reutilizáveis
• Documentar qualquer nova função adicionada

---

Páginas relacionadas

• Módulo:Temporada
• Módulo:Temporada/Estatisticas
• Módulo:Temporada/Campanha
• Módulo:Temporada/Partidas

---

Histórico

• Módulo criado como base utilitária do sistema de temporadas
• Projetado para reduzir duplicação de código e facilitar manutenção

---

-- Module:Temporada/Utils
-- Funções utilitárias reutilizáveis para automação de temporadas
-- Não gera saída visual
-- Projeto Wiki Galo Digital

local Utils = {}

--------------------------------------------------
-- Conversão segura para número
--------------------------------------------------
function Utils.toNumber(value, default)
	if value == nil then
		return default or 0
	end

	local n = tonumber(value)
	if n == nil then
		return default or 0
	end

	return n
end

--------------------------------------------------
-- Normalização simples de strings
--------------------------------------------------
function Utils.normalizeString(valor)
	if type(valor) ~= "string" then
		return ""
	end

	valor = mw.text.trim(valor)
	return valor
end


--------------------------------------------------
-- Normalização de nome do Atlético
--------------------------------------------------
function Utils.isAtletico(nome)
	if not nome then
		return false
	end

	nome = mw.ustring.lower(nome)

	if nome:find("atlético") or nome:find("atletico") then
		return true
	end

	return false
end

--------------------------------------------------
-- Comparação de placar
-- Retorna: "V", "E", "D"
--------------------------------------------------
function Utils.resultadoPartida(golsTime, golsAdversario)
	golsTime = Utils.toNumber(golsTime)
	golsAdversario = Utils.toNumber(golsAdversario)

	if golsTime > golsAdversario then
		return "V"
	elseif golsTime < golsAdversario then
		return "D"
	else
		return "E"
	end
end

--------------------------------------------------
-- Classe CSS do resultado
--------------------------------------------------
function Utils.cssResultado(resultado)
	if resultado == "V" then
		return "gd-result-win"
	elseif resultado == "E" then
		return "gd-result-draw"
	elseif resultado == "D" then
		return "gd-result-loss"
	end

	return ""
end

--------------------------------------------------
-- Cálculo de aproveitamento (retorna NÚMERO)
--------------------------------------------------
function Utils.aproveitamento(pontosObtidos, pontosPossiveis)
	pontosObtidos = Utils.toNumber(pontosObtidos)
	pontosPossiveis = Utils.toNumber(pontosPossiveis)

	if pontosPossiveis == 0 then
		return 0
	end

	return (pontosObtidos / pontosPossiveis) * 100
end

--------------------------------------------------
-- Pontuação padrão (3-1-0)
--------------------------------------------------
function Utils.pontosResultado(resultado)
	if resultado == "V" then
		return 3
	elseif resultado == "E" then
		return 1
	elseif resultado == "D" then
		return 0
	end

	return 0
end

--------------------------------------------------
-- Validação booleana a partir de parâmetros wiki OU Lua
--------------------------------------------------
function Utils.toBoolean(value)
	-- Boolean real (vindos de módulos de dados)
	if type(value) == "boolean" then
		return value
	end

	-- Nil ou vazio
	if value == nil or value == "" then
		return false
	end

	-- String (vindos de templates)
	if type(value) == "string" then
		value = mw.ustring.lower(mw.text.trim(value))

		if value == "sim" or value == "true" or value == "1" then
			return true
		end
	end

	return false
end

return Utils