Módulo:Temporada/Artilharia

Módulo:Temporada/Artilharia

O Módulo:Temporada/Artilharia é responsável pela consolidação automática da artilharia de uma temporada no projeto Wiki Galo Digital.

Ele processa os dados das partidas, identifica os autores dos gols do Clube Atlético Mineiro e gera rankings ordenados, reutilizáveis por outros módulos e templates.

---

Escopo e responsabilidades

Este módulo é responsável por:

• Extrair autores de gols a partir dos dados das partidas
• Consolidar a quantidade de gols por atleta
• Gerar ranking ordenado de artilharia
• Retornar o artilheiro principal da temporada
• Fornecer renderização simples em lista vertical

---

Dependências

Este módulo depende diretamente de:

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

E consome dados exclusivamente de:

• Module:Temporada/Dados/ANO

---

Extração de autores de gols

extrairAutores(texto)

Função interna responsável por interpretar a string de autores de gols.

• Formato esperado
  • Nome (2); OutroNome

• Regras aplicadas
• Divide a string por ponto e vírgula
• Remove espaços excedentes
• Identifica quantidade explícita de gols
• Assume 1 gol quando não informado
• Ignora valores como:
  • Não identificado
  • Não houve

• Retorno
  • Tabela Lua no formato { nome = quantidade }

---

Funções públicas

calcularPorAno(ano)

Calcula o ranking completo de artilharia da temporada.

• Parâmetro
  • ano (number)

• Fluxo de execução

1. Carrega dados das partidas do ano
2. Cria objetos Partida
3. Ignora partidas anuladas ou não contabilizáveis
4. Consolida gols do Atlético como mandante e visitante
5. Converte para lista ordenável
6. Ordena por número de gols (decrescente)

• Retorno
  • Lista ordenada de artilheiros no formato:
    • { nome = "Jogador", gols = 10 }

---

artilheiro(ano)

Retorna o principal artilheiro da temporada.

• Parâmetro
  • ano

• Retorno
  • Tabela Lua com:
    • nome
    • gols

• Comportamento
  • Retorna valores padrão caso não existam gols registrados

---

render(frame)

Renderiza a lista vertical de artilharia.

• Uso
  • Templates editoriais
• Parâmetro
  • frame.args.ano

• Saída
  • Lista wiki no formato:
    • * Jogador – X gols

---

Regras de validação

• Partidas anuladas são ignoradas
• Partidas marcadas como não contabilizáveis são ignoradas
• Strings inválidas não geram registros
• Ano inválido gera lista vazia ou erro controlado

---

Boas práticas e manutenção

• Não incluir lógica de apresentação complexa
• Manter separação entre extração, cálculo e renderização
• Alterações no formato dos dados exigem revisão das funções
• Novos critérios de desempate devem ser documentados
• Dados históricos devem permanecer no módulo de dados do ano

---

Páginas relacionadas

• Módulo:Temporada
• Módulo:Temporada/Partidas
• Módulo:Temporada/Utils
• Módulo:Temporada/Dados/1919
• Predefinição:ArtilheirosTemporada

---

Histórico

• Módulo criado para automação da artilharia por temporada
• Centraliza consolidação individual de gols
• Preparado para expansão futura (ranking por competição, fase etc.)

---

-- Module:Temporada/Artilharia
-- Consolidação de artilharia por temporada
-- Projeto Wiki Galo Digital
--
-- ETAPA 5.1 – Artilharia automática
--
-- Dependências:
--  - Module:Temporada/Utils
--  - Module:Temporada/Partidas

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

local Artilharia = {}

--------------------------------------------------
-- Extrai autores e quantidades a partir da string
-- Exemplo:
-- "Gondim (2); Quetinho"
--------------------------------------------------
local function extrairAutores(texto)
	local autores = {}

	if not texto or texto == "" or texto == "Não identificado" or texto == "Não houve" then
		return autores
	end

	local lista = mw.text.split(texto, ";")
	for _, item in ipairs(lista) do
		item = mw.text.trim(item)

		local nome = mw.ustring.match(item, "^(.-)%s*%(") or item
		local qtd = mw.ustring.match(item, "%((%d+)%)")

		nome = mw.text.trim(nome)
		qtd = tonumber(qtd) or 1

		if nome ~= "" then
			autores[nome] = (autores[nome] or 0) + qtd
		end
	end

	return autores
end

--------------------------------------------------
-- Calcula ranking de artilharia por ano
--------------------------------------------------
function Artilharia.calcularPorAno(ano)
	local ranking = {}

	if not ano then
		return ranking
	end

	local Dados = require("Module:Temporada/Dados/" .. ano)

	for _, args in ipairs(Dados.partidas or {}) do
		local partida = Partidas.criar(args)

		-- Ignora partidas inválidas
		if not partida.anulada and partida.conta then

			-- Atlético como mandante
			if Utils.isAtletico(partida.mandante) then
				local autores = extrairAutores(partida.autores_mandante)
				for nome, qtd in pairs(autores) do
					ranking[nome] = (ranking[nome] or 0) + qtd
				end
			end

			-- Atlético como visitante
			if Utils.isAtletico(partida.visitante) then
				local autores = extrairAutores(partida.autores_visitante)
				for nome, qtd in pairs(autores) do
					ranking[nome] = (ranking[nome] or 0) + qtd
				end
			end

		end
	end

	-- Converte para lista ordenável
	local lista = {}
	for nome, gols in pairs(ranking) do
		table.insert(lista, {
			nome = nome,
			gols = gols
		})
	end

	table.sort(lista, function(a, b)
		if a.gols == b.gols then
			return a.nome < b.nome
		end
		return a.gols > b.gols
	end)

	return lista
end

--------------------------------------------------
-- Retorna o artilheiro da temporada
--------------------------------------------------
function Artilharia.artilheiro(ano)
	local lista = Artilharia.calcularPorAno(ano)

	if #lista == 0 then
		return {
			nome = "-",
			gols = 0
		}
	end

	return lista[1]
end

--------------------------------------------------
-- Renderização simples (lista vertical)
--------------------------------------------------
function Artilharia.render(frame)
	local ano = tonumber(frame.args.ano)

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

	local lista = Artilharia.calcularPorAno(ano)

	if #lista == 0 then
		return "Nenhum gol registrado."
	end

	local linhas = {}
	for _, item in ipairs(lista) do
		table.insert(linhas, string.format("* [[%s]] – %d gols", item.nome, item.gols))
	end

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

return Artilharia