Módulo:Temporada/Artilharia/doc

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.)