Módulo:Temporada/Estatisticas

De Clube Atletico Mineiro - Enciclopedia Galo Digital
Ir para navegação Ir para pesquisar

Predefinição:Documentation

Módulo:Temporada/Estatisticas

O Módulo:Temporada/Estatisticas é responsável pela consolidação estatística das partidas de uma temporada no projeto Wiki Galo Digital.

Ele processa os dados brutos de partidas, aplica regras de validação e cálculo e retorna estatísticas agregadas, que podem ser consumidas por outros módulos ou renderizadas por templates.

---

Escopo e responsabilidades

Este módulo é responsável por:

  • Consolidar estatísticas gerais da temporada
  • Processar partidas válidas (não anuladas e contabilizáveis)
  • Separar desempenho como mandante e visitante
  • Calcular:
    • Jogos
    • Vitórias, empates e derrotas
    • Gols pró e contra
    • Saldo de gols
    • Aproveitamento
  • Fornecer renderização tabular para uso editorial

Predefinição:Aviso

---

Dependências

Este módulo depende diretamente de:

  • Module:Temporada/Utils
  • Module:Temporada/Partidas

E carrega dinamicamente os dados de cada temporada a partir de:

  • Module:Temporada/Dados/ANO

---

Estrutura de dados

Estrutura base

A função interna de criação da estrutura estatística gera os seguintes campos:

  • Estatísticas gerais
    • jogos
    • vitorias
    • empates
    • derrotas
    • gols_pro
    • gols_contra
    • saldo
    • aproveitamento
  • Estatísticas como mandante
  • Estatísticas como visitante

Cada subestrutura mantém seus próprios totais.

---

Funções internas

processarPartida(stats, partida)

Processa uma partida individual e acumula seus dados na estrutura estatística.

  • Ignora partidas:
    • Anuladas
    • Marcadas como não contabilizáveis
  • Identifica se o Atlético atuou como:
    • Mandante
    • Visitante
  • Atualiza:
    • Contadores de jogos
    • Gols pró e contra
    • Resultado (V, E, D)

Predefinição:Nota

---

Funções públicas

calcularPorAno(ano)

Calcula todas as estatísticas da temporada informada.

  • Parâmetro
    • ano (number)
  • Fluxo de execução
  1. Cria estrutura estatística vazia
  2. Carrega dinamicamente o módulo de dados do ano
  3. Processa cada partida
  4. Calcula saldos e aproveitamento
  • Retorno
    • Tabela Lua com estatísticas consolidadas

Predefinição:Aviso

---

render(frame)

Função pública de renderização da tabela de estatísticas gerais.

  • Uso
    • Template:EstatisticasTemporada
  • Parâmetro
    • frame.args.ano
  • Saída
    • Tabela wiki com:
      • Totais gerais
      • Mandante
      • Visitante

Predefinição:Aviso

---

Regras de validação

O módulo aplica validações defensivas:

  • Ano inválido retorna erro controlado
  • Partidas inválidas são ignoradas
  • Campos ausentes são tratados como zero
  • Aproveitamento é calculado apenas ao final

---

Boas práticas e manutenção

  • Não adicionar lógica editorial neste módulo
  • Manter separação clara entre cálculo e apresentação
  • Não alterar estrutura de retorno sem revisar dependências
  • Novos campos estatísticos devem ser documentados
  • Dados históricos devem ser adicionados apenas em Módulo:Temporada/Dados/ANO

---

Páginas relacionadas

---

Histórico

  • Módulo criado para consolidação estatística centralizada
  • Estruturado para evitar repetição de cálculos entre templates
  • Preparado para expansão futura de indicadores
-- Module:Temporada/Estatisticas
-- Consolidação estatística das partidas de uma temporada
-- Projeto Wiki Galo Digital
--
-- ETAPA 3 – Estatísticas Gerais
--
-- Dependências:
--  - Module:Temporada/Utils
--  - Module:Temporada/Partidas

local Utils = require("Module:Temporada/Utils")
local Partidas = require("Module:Temporada/Partidas")

local Estatisticas = {}

--------------------------------------------------
-- Estrutura base de estatísticas
--------------------------------------------------
local function novaEstrutura()
	return {
		jogos = 0,
		vitorias = 0,
		empates = 0,
		derrotas = 0,
		gols_pro = 0,
		gols_contra = 0,
		saldo = 0,
		aproveitamento = "-",

		mandante = {
			jogos = 0,
			vitorias = 0,
			empates = 0,
			derrotas = 0,
			gols_pro = 0,
			gols_contra = 0,
			saldo = 0
		},

		visitante = {
			jogos = 0,
			vitorias = 0,
			empates = 0,
			derrotas = 0,
			gols_pro = 0,
			gols_contra = 0,
			saldo = 0
		}
	}
end

--------------------------------------------------
-- Processa uma partida individual
--------------------------------------------------
local function processarPartida(stats, partida)
	-- Ignora partidas inválidas
	if partida.anulada or not partida.conta then
		return
	end

	local lado
	if Utils.isAtletico(partida.mandante) then
		lado = "mandante"
	elseif Utils.isAtletico(partida.visitante) then
		lado = "visitante"
	else
		return
	end

	stats.jogos = stats.jogos + 1
	stats[lado].jogos = stats[lado].jogos + 1

	local golsPro, golsContra, resultado

	if lado == "mandante" then
		golsPro = partida.gols_mandante or 0
		golsContra = partida.gols_visitante or 0
		resultado = partida.resultado_mandante
	else
		golsPro = partida.gols_visitante or 0
		golsContra = partida.gols_mandante or 0
		resultado = partida.resultado_visitante
	end

	stats.gols_pro = stats.gols_pro + golsPro
	stats.gols_contra = stats.gols_contra + golsContra
	stats[lado].gols_pro = stats[lado].gols_pro + golsPro
	stats[lado].gols_contra = stats[lado].gols_contra + golsContra

	if resultado == "V" then
		stats.vitorias = stats.vitorias + 1
		stats[lado].vitorias = stats[lado].vitorias + 1
	elseif resultado == "E" then
		stats.empates = stats.empates + 1
		stats[lado].empates = stats[lado].empates + 1
	elseif resultado == "D" then
		stats.derrotas = stats.derrotas + 1
		stats[lado].derrotas = stats[lado].derrotas + 1
	end
end

--------------------------------------------------
-- Calcula estatísticas a partir do módulo de dados da temporada
--------------------------------------------------
function Estatisticas.calcularPorAno(ano)
	local stats = novaEstrutura()

	local ok, Dados = pcall(require, "Module:Temporada/Dados/" .. ano)
	if not ok or not Dados or not Dados.partidas then
		return stats
	end

	for _, args in ipairs(Dados.partidas) do
		local partida = Partidas.criar(args)
		processarPartida(stats, partida)
	end

	stats.saldo = stats.gols_pro - stats.gols_contra
	stats.mandante.saldo = stats.mandante.gols_pro - stats.mandante.gols_contra
	stats.visitante.saldo = stats.visitante.gols_pro - stats.visitante.gols_contra

	stats.aproveitamento = Utils.aproveitamento(
		stats.vitorias,
		stats.jogos * 3
	)

	return stats
end

--------------------------------------------------
-- Renderização pública (Template:EstatisticasTemporada)
--------------------------------------------------
function Estatisticas.render(frame)
	local ano = tonumber(frame.args.ano)

	if not ano then
		return "Erro: parâmetro <code>ano</code> não informado ou inválido."
	end

	local stats = Estatisticas.calcularPorAno(ano)

	return string.format([[
{| class="wikitable gd-table gd-estatisticas"
|+ Estatísticas Gerais – Temporada %d
! !! Jogos !! Vitórias !! Empates !! Derrotas !! Gols pró !! Gols contra !! Saldo !! Aproveitamento
|-
! Total
| %d
| %d
| %d
| %d
| %d
| %d
| %d
| %s
|-
! Mandante
| %d
| %d
| %d
| %d
| %d
| %d
| %d
| –
|-
! Visitante
| %d
| %d
| %d
| %d
| %d
| %d
| %d
| –
|}
]],
		ano,

		-- TOTAL
		stats.jogos,
		stats.vitorias,
		stats.empates,
		stats.derrotas,
		stats.gols_pro,
		stats.gols_contra,
		stats.saldo,
		stats.aproveitamento,

		-- MANDANTE
		stats.mandante.jogos,
		stats.mandante.vitorias,
		stats.mandante.empates,
		stats.mandante.derrotas,
		stats.mandante.gols_pro,
		stats.mandante.gols_contra,
		stats.mandante.saldo,

		-- VISITANTE
		stats.visitante.jogos,
		stats.visitante.vitorias,
		stats.visitante.empates,
		stats.visitante.derrotas,
		stats.visitante.gols_pro,
		stats.visitante.gols_contra,
		stats.visitante.saldo
	)
end

return Estatisticas
Disponível em “http://www.galodigital.com.br/w/index.php?title=Módulo:Temporada/Estatisticas&oldid=154179”