Módulo:Temporada/Campanha

Módulo:Temporada/Campanha

O Módulo:Temporada/Campanha é responsável pela consolidação da campanha do Clube Atlético Mineiro por competição em uma determinada temporada, no projeto Wiki Galo Digital.

Ele processa as partidas registradas no módulo de dados da temporada e apresenta os resultados agregados por competição, com recortes de desempenho total, como mandante e como visitante.

---

Escopo e responsabilidades

Este módulo é responsável por:

• Agrupar partidas por competição
• Calcular campanha do Atlético em cada competição
• Separar desempenho:
  • Total
  • Mandante
  • Visitante
• Calcular:
  • Jogos
  • Vitórias, empates e derrotas
  • Gols pró e contra
  • Saldo de gols
  • Aproveitamento
• Renderizar tabela consolidada por competição

---

Dependências

Este módulo depende diretamente de:

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

E consome dados exclusivamente de:

• Module:Temporada/Dados/ANO

---

Estrutura de dados

Estrutura base de campanha

Cada campanha por competição utiliza a seguinte estrutura:

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

Essa estrutura é inicializada por competição.

---

Funções internas

processarPartida(c, p)

Processa uma partida individual dentro da campanha da competição.

• Ignora partidas:
  • Anuladas
  • Não contabilizáveis
• Identifica se o Atlético atuou como:
  • Mandante
  • Visitante
• Atualiza:
  • Jogos
  • Resultados
  • Gols pró e contra

---

saldo(c)

Calcula o saldo de gols da estrutura informada.

• Retorno
  • gols_pro - gols_contra

---

aproveitamento(c)

Calcula o aproveitamento percentual da campanha.

• Regra
  • Pontuação padrão 3-1-0
• Retorno
  • Percentual formatado
  • Retorna “–” se não houver jogos

---

Função pública

render(frame)

Renderiza a tabela de campanha por competição da temporada.

• Parâmetro
  • frame.args.ano

• Fluxo de execução

1. Obtém partidas do ano
2. Agrupa por competição
3. Consolida campanha
4. Renderiza tabela com três linhas por competição:
   1. Total
   2. Mandante
   3. Visitante

• Saída
  • Tabela wiki estruturada

---

Regras de validação

• Ano inválido gera erro controlado
• Competições vazias são ignoradas
• Partidas anuladas não entram no cálculo
• Partidas não contabilizáveis são ignoradas

---

Boas práticas e manutenção

• Não misturar lógica editorial com lógica de campanha
• Alterações na estrutura exigem revisão da renderização
• Novos recortes devem ser documentados
• Dados históricos devem permanecer no módulo de dados do ano
• Evitar duplicação de cálculos já existentes em outros módulos

---

Páginas relacionadas

• Módulo:Temporada
• Módulo:Temporada/Partidas
• Módulo:Temporada/Estatisticas
• Módulo:Temporada/Dados/1919
• Predefinição:CampanhaTemporada

---

Histórico

• Módulo criado para consolidação da campanha por competição
• Centraliza recortes total, mandante e visitante
• Estruturado para facilitar expansão futura

---

-- Module:Temporada/Campanha
-- Campanha por competição da temporada
-- Projeto Wiki Galo Digital
--
-- Etapa 4.1 – Campanha por Competição
--
-- Dependências:
--  - Module:Temporada/Utils
--  - Module:Temporada/Partidas

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

local Campanha = {}

--------------------------------------------------
-- Estrutura base de campanha
--------------------------------------------------
local function novaCampanha()
	return {
		jogos = 0,
		vitorias = 0,
		empates = 0,
		derrotas = 0,
		gols_pro = 0,
		gols_contra = 0,

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

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

--------------------------------------------------
-- Processa uma partida dentro da campanha
--------------------------------------------------
local function processarPartida(c, p)
	if p.anulada or not p.conta then
		return
	end

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

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

	local golsPro, golsContra, resultado

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

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

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

--------------------------------------------------
-- Funções auxiliares
--------------------------------------------------
local function saldo(c)
	return c.gols_pro - c.gols_contra
end

local function aproveitamento(c)
	local pontos = (c.vitorias * 3) + c.empates
	local maximos = c.jogos * 3
	if maximos == 0 then
		return "–"
	end
	return string.format("%.1f%%", (pontos / maximos) * 100)
end

--------------------------------------------------
-- Renderização da Campanha por Competição
--------------------------------------------------
function Campanha.render(frame)
	local ano = tonumber(frame.args.ano)
	if not ano then
		return "Erro: parâmetro <code>ano</code> não informado."
	end

	local partidas = Partidas.obterPorAno(ano)
	local porComp = {}

	for _, args in ipairs(partidas) do
		local p = Partidas.criar(args)
		if p.competicao and p.competicao ~= "" then
			porComp[p.competicao] = porComp[p.competicao] or novaCampanha()
			processarPartida(porComp[p.competicao], p)
		end
	end

	local out = {}
	table.insert(out, '{| class="wikitable gd-table gd-campanha"')
	table.insert(out, '|+ Campanha por Competição – Temporada ' .. ano)
	table.insert(out, '! Competição !! Recorte !! Jogos !! Vitórias !! Empates !! Derrotas !! Gols pró !! Gols contra !! Saldo !! Aproveitamento')

	for nome, c in pairs(porComp) do
		-- TOTAL
		table.insert(out, "|-")
		table.insert(out, '| rowspan="3" | [[' .. nome .. ']]')
		table.insert(out, "| Total")
		table.insert(out, "| " .. c.jogos)
		table.insert(out, "| " .. c.vitorias)
		table.insert(out, "| " .. c.empates)
		table.insert(out, "| " .. c.derrotas)
		table.insert(out, "| " .. c.gols_pro)
		table.insert(out, "| " .. c.gols_contra)
		table.insert(out, "| " .. saldo(c))
		table.insert(out, "| " .. aproveitamento(c))

		-- MANDANTE
		table.insert(out, "|-")
		table.insert(out, "| Mandante")
		table.insert(out, "| " .. c.mandante.jogos)
		table.insert(out, "| " .. c.mandante.vitorias)
		table.insert(out, "| " .. c.mandante.empates)
		table.insert(out, "| " .. c.mandante.derrotas)
		table.insert(out, "| " .. c.mandante.gols_pro)
		table.insert(out, "| " .. c.mandante.gols_contra)
		table.insert(out, "| " .. saldo(c.mandante))
		table.insert(out, "| " .. aproveitamento(c.mandante))

		-- VISITANTE
		table.insert(out, "|-")
		table.insert(out, "| Visitante")
		table.insert(out, "| " .. c.visitante.jogos)
		table.insert(out, "| " .. c.visitante.vitorias)
		table.insert(out, "| " .. c.visitante.empates)
		table.insert(out, "| " .. c.visitante.derrotas)
		table.insert(out, "| " .. c.visitante.gols_pro)
		table.insert(out, "| " .. c.visitante.gols_contra)
		table.insert(out, "| " .. saldo(c.visitante))
		table.insert(out, "| " .. aproveitamento(c.visitante))
	end

	table.insert(out, "|}")

	return table.concat(out, "\n")
end

return Campanha