Módulo:Temporada

Módulo:Temporada

O Módulo:Temporada é o módulo central de orquestração dos dados de uma temporada esportiva no projeto Wiki Galo Digital. Ele atua como camada de alto nível, agregando informações provenientes de submódulos especializados e expondo APIs estáveis para uso em templates e páginas editoriais.

Escopo e responsabilidades

Este módulo tem como responsabilidades principais:

• Centralizar o acesso aos dados consolidados de uma temporada
• Orquestrar chamadas a submódulos especializados
• Expor funções de alto nível para:
  • Estatísticas gerais
  • Campanha por competição
  • Artilharia
  • Destaques automáticos
• Servir como base lógica para infoboxes e destaques editoriais

---

Arquitetura do módulo

O módulo segue uma arquitetura em camadas:

• Camada de orquestração
  • Módulo:Temporada (este módulo)
• Camada de domínio
  • Módulo:Temporada/Estatisticas
  • Módulo:Temporada/Campanha
  • Módulo:Temporada/Artilharia
• Camada de interface
  • Templates (Predefinições)
  • Infoboxes
  • Páginas editoriais

Essa separação garante:

• Código reutilizável
• Manutenção simplificada
• Evolução futura sem quebra de dependências

---

Dependências

Este módulo depende diretamente dos seguintes submódulos:

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

Todos devem retornar dados estruturados em tabelas Lua e **não renderizar saída HTML diretamente**.

---

Funções públicas

estatisticas(ano)

Retorna as estatísticas gerais da temporada informada.

• Parâmetro
  • ano (number) – ano da temporada

• Retorno
  • Tabela Lua com estatísticas consolidadas ou nil se o ano não for informado

• Origem dos dados
  • Module:Temporada/Estatisticas.calcularPorAno

---

campanha(ano)

Retorna os dados de campanha da temporada, organizados por competição.

• Parâmetro
  • ano (number)

• Retorno
  • Tabela Lua com campanhas ou nil

• Origem dos dados
  • Module:Temporada/Campanha.calcularPorAno

---

artilharia(ano)

Retorna o ranking de artilharia da temporada.

• Parâmetro
  • ano (number)

• Retorno
  • Lista ordenada de artilheiros ou nil

• Origem dos dados
  • Module:Temporada/Artilharia.calcularPorAno

---

destaques(ano)

Calcula automaticamente os principais destaques da temporada.

Os destaques incluem:

• Jogos
• Vitórias, empates e derrotas
• Gols pró e contra
• Saldo de gols
• Aproveitamento
• Artilheiro principal (se disponível)

• Parâmetro
  • ano (number)

• Retorno
  • Tabela Lua com os destaques consolidados

---

Funções internas

_infobox(frame)

Função interna responsável por renderizar a infobox da temporada.

• Uso
  • Chamada exclusivamente por templates
• Responsabilidade
  • Montagem básica da estrutura da infobox
• Observação
  • A lógica de dados permanece no módulo, mas a evolução visual deve ocorrer preferencialmente nos templates.

---

Tratamento de erros

O módulo aplica validações defensivas:

• Ano não informado retorna erro ou nil
• Falha no cálculo de dados interrompe a renderização
• Campos opcionais possuem valores padrão ("-" ou zero)

Isso evita erros fatais na renderização das páginas.

---

Boas práticas e manutenção

• Não adicionar renderização de tabelas extensas neste módulo
• Não misturar lógica estatística com lógica editorial
• Manter as funções pequenas e previsíveis
• Evitar dependências circulares entre submódulos
• Documentar qualquer nova função pública adicionada

---

Páginas relacionadas

• Módulo:Temporada/Estatisticas
• Módulo:Temporada/Campanha
• Módulo:Temporada/Artilharia
• Predefinição:Infortemporada
• Projeto:Galo_Digital/Padrões/Temporadas

---

Histórico

• Módulo criado no contexto da automação de temporadas do projeto Wiki Galo Digital
• Estruturado para permitir expansão futura (Cargo, Wiki Semântica), sem dependência atual dessas extensões

---

-- Module:Temporada
-- Módulo central de orquestração da temporada
-- Projeto Wiki Galo Digital
--
-- Responsabilidades:
--  - Centralizar acesso aos dados da temporada
--  - Expor APIs de alto nível
--  - Servir de base para Infobox e destaques
--
-- NÃO renderiza tabelas diretamente

local Temporada = {}

local Estatisticas = require("Module:Temporada/Estatisticas")
local Campanha = require("Module:Temporada/Campanha")
local Artilharia = require("Module:Temporada/Artilharia")

--------------------------------------------------
-- Retorna estatísticas gerais da temporada
--------------------------------------------------
function Temporada.estatisticas(ano)
	if not ano then
		return nil
	end

	return Estatisticas.calcularPorAno(tonumber(ano))
end

--------------------------------------------------
-- Retorna campanha por competição
--------------------------------------------------
function Temporada.campanha(ano)
	if not ano then
		return nil
	end

	return Campanha.calcularPorAno(tonumber(ano))
end

--------------------------------------------------
-- Retorna ranking de artilharia
--------------------------------------------------
function Temporada.artilharia(ano)
	if not ano then
		return nil
	end

	return Artilharia.calcularPorAno(tonumber(ano))
end

--------------------------------------------------
-- Destaques automáticos (base futura)
--------------------------------------------------
function Temporada.destaques(ano)
	if not ano then
		return nil
	end

	local stats = Temporada.estatisticas(ano)
	local artilharia = Temporada.artilharia(ano)

	if not stats then
		return nil
	end

	local destaques = {}

	destaques.jogos = stats.jogos
	destaques.vitorias = stats.vitorias
	destaques.empates = stats.empates
	destaques.derrotas = stats.derrotas
	destaques.gols_pro = stats.gols_pro
	destaques.gols_contra = stats.gols_contra
	destaques.saldo = stats.saldo
	destaques.aproveitamento = stats.aproveitamento

	-- Artilheiro principal (se existir)
	if artilharia and #artilharia > 0 then
		destaques.artilheiro = artilharia[1].nome
		destaques.gols_artilheiro = artilharia[1].gols
	end

	return destaques
end

--------------------------------------------------
-- Renderização da Infobox da Temporada
--------------------------------------------------
function Temporada._infobox(frame)
	local args = frame.args
	local ano = tonumber(args.ano)

	if not ano then
		return "Erro: ano da temporada não informado."
	end

	local destaques = Temporada.destaques(ano)
	if not destaques then
		return "Erro ao calcular dados da temporada."
	end

	return string.format([[
{| class="infobox infobox-temporada"
|-
! colspan="2" | Temporada %d
|-
| Clube
| %s
|-
| Jogos
| %d
|-
| Vitórias
| %d
|-
| Empates
| %d
|-
| Derrotas
| %d
|-
| Gols pró
| %d
|-
| Gols contra
| %d
|-
| Saldo
| %d
|-
| Aproveitamento
| %.1f%%
|-
| Artilheiro
| %s (%d gols)
|-
| Técnico
| %s
|-
| Presidente
| %s
|-
| Estádio
| %s
|}
]],
		ano,
		args.clube or "Clube Atlético Mineiro",
		destaques.jogos,
		destaques.vitorias,
		destaques.empates,
		destaques.derrotas,
		destaques.gols_pro,
		destaques.gols_contra,
		destaques.saldo,
		destaques.aproveitamento,
		destaques.artilheiro or "-",
		destaques.gols_artilheiro or 0,
		args.tecnico or "-",
		args.presidente or "-",
		args.estadio or "-"
	)
end


return Temporada