Módulo:Temporada/doc

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