Módulo:Temporada/Estatisticas/doc: mudanças entre as edições

De Clube Atletico Mineiro - Enciclopedia Galo Digital
Ir para navegação Ir para pesquisar
Admin (discussão | contribs)
Burocratas, Administradores
1 029 edições
Criou página com '== Módulo:Temporada/Estatisticas == Este módulo é responsável pela **consolidação estatística das partidas de uma temporada**, a partir dos dados estruturados fornecidos pelo {{tl|Partida}} e processados pelo módulo {{code|Module:Temporada/Partidas}}. Ele **não gera saída visual**. Seu papel é exclusivamente lógico, servindo como base para: * Estatísticas gerais da temporada * Campanhas por competição * Infobox da temporada * Relatórios e agregações...'
 
Sem resumo de edição
 
Linha 1: Linha 1:
== Módulo:Temporada/Estatisticas ==
{{Documentation}}


Este módulo é responsável pela **consolidação estatística das partidas de uma temporada**, a partir dos dados estruturados fornecidos pelo {{tl|Partida}} e processados pelo módulo {{code|Module:Temporada/Partidas}}.
= Módulo:Temporada/Estatisticas =


Ele **não gera saída visual**. Seu papel é exclusivamente lógico, servindo como base para:
O '''Módulo:Temporada/Estatisticas''' é responsável pela consolidação estatística das partidas de uma temporada no projeto '''Wiki Galo Digital'''.


* Estatísticas gerais da temporada
Ele processa os dados brutos de partidas, aplica regras de validação e cálculo e retorna estatísticas agregadas, que podem ser consumidas por outros módulos ou renderizadas por templates.
* Campanhas por competição
* Infobox da temporada
* Relatórios e agregações futuras


---
---


== Dependências ==
== Escopo e responsabilidades ==


Este módulo depende obrigatoriamente de:
Este módulo é responsável por:


* {{code|Module:Temporada/Utils}}
* Consolidar estatísticas gerais da temporada
* {{code|Module:Temporada/Partidas}}
* Processar partidas válidas (não anuladas e contabilizáveis)
* Separar desempenho como mandante e visitante
* Calcular:
** Jogos
** Vitórias, empates e derrotas
** Gols pró e contra
** Saldo de gols
** Aproveitamento
* Fornecer renderização tabular para uso editorial


Caso qualquer uma dessas dependências seja alterada, este módulo deve ser revisado.
{{Aviso|texto=Este módulo concentra lógica estatística. Ele não deve conter regras editoriais nem decisões de apresentação fora do escopo estatístico.}}


---
---


== Responsabilidades ==
== Dependências ==
 
Este módulo depende diretamente de:
 
* <code>Module:Temporada/Utils</code>
* <code>Module:Temporada/Partidas</code>


O módulo é responsável por:
E carrega dinamicamente os dados de cada temporada a partir de:


* Contabilizar apenas partidas válidas
* <code>Module:Temporada/Dados/ANO</code>
* Ignorar automaticamente:
** Jogos anulados
** Jogos marcados como “não conta”
* Identificar corretamente se o Atlético atuou como:
** Mandante
** Visitante
* Consolidar:
** Jogos
** Vitórias
** Empates
** Derrotas
** Gols pró
** Gols contra
** Saldo de gols
** Aproveitamento
* Gerar estatísticas separadas para:
** Total
** Mandante
** Visitante


---
---


== O que este módulo NÃO faz ==
== Estrutura de dados ==
 
=== Estrutura base ===
 
A função interna de criação da estrutura estatística gera os seguintes campos:


* Não gera HTML
* Estatísticas gerais
* Não aplica CSS
** <code>jogos</code>
* Não renderiza tabelas
** <code>vitorias</code>
* Não acessa páginas da wiki
** <code>empates</code>
* Não possui lógica editorial ou visual
** <code>derrotas</code>
* Não conhece ano, competição ou contexto da página
** <code>gols_pro</code>
** <code>gols_contra</code>
** <code>saldo</code>
** <code>aproveitamento</code>
* Estatísticas como mandante
* Estatísticas como visitante


Toda visualização deve ser feita por templates ou outros módulos consumidores.
Cada subestrutura mantém seus próprios totais.


---
---


== Estrutura de dados retornada ==
== Funções internas ==


A função principal retorna uma tabela Lua com a seguinte estrutura:
=== processarPartida(stats, partida) ===


<syntaxhighlight lang="lua">
Processa uma partida individual e acumula seus dados na estrutura estatística.
{
  jogos = number,
  vitorias = number,
  empates = number,
  derrotas = number,
  gols_pro = number,
  gols_contra = number,
  saldo = number,
  aproveitamento = number,


  mandante = {
* Ignora partidas:
    jogos = number,
** Anuladas
    vitorias = number,
** Marcadas como não contabilizáveis
    empates = number,
* Identifica se o Atlético atuou como:
    derrotas = number,
** Mandante
    gols_pro = number,
** Visitante
    gols_contra = number
* Atualiza:
  },
** Contadores de jogos
** Gols pró e contra
** Resultado (V, E, D)


  visitante = {
{{Nota|texto=Partidas onde o Atlético não participa são ignoradas automaticamente.}}
    jogos = number,
    vitorias = number,
    empates = number,
    derrotas = number,
    gols_pro = number,
    gols_contra = number
  }
}
</syntaxhighlight>


---
---
Linha 102: Linha 86:
== Funções públicas ==
== Funções públicas ==


=== <code>calcular(listaDePartidas)</code> ===
=== calcularPorAno(ano) ===
 
Calcula todas as estatísticas da temporada informada.
 
* '''Parâmetro'''
** <code>ano</code> (number)
 
* '''Fluxo de execução'''
# Cria estrutura estatística vazia
# Carrega dinamicamente o módulo de dados do ano
# Processa cada partida
# Calcula saldos e aproveitamento
 
* '''Retorno'''
** Tabela Lua com estatísticas consolidadas
 
{{Aviso|texto=Em caso de ausência de dados, a função retorna a estrutura vazia, evitando erro fatal.}}
 
---


Calcula as estatísticas gerais da temporada a partir de uma lista de partidas.
=== render(frame) ===


; Parâmetros
Função pública de renderização da tabela de estatísticas gerais.
* <code>listaDePartidas</code> – tabela Lua contendo listas de argumentos equivalentes aos parâmetros do {{tl|Partida}}


; Comportamento
* '''Uso'''
* Cada item da lista é convertido internamente em uma partida normalizada
** Template:EstatisticasTemporada
* Apenas partidas válidas são contabilizadas
* '''Parâmetro'''
* O resultado é acumulado em uma única estrutura estatística
** <code>frame.args.ano</code>


; Retorno
* '''Saída'''
* Tabela Lua contendo as estatísticas consolidadas
** Tabela wiki com:
*** Totais gerais
*** Mandante
*** Visitante
 
{{Aviso|texto=A renderização tabular deve ser chamada apenas por templates.}}


---
---


== Exemplo de uso (interno) ==
== Regras de validação ==


Este módulo é utilizado internamente por outros módulos, por exemplo:
O módulo aplica validações defensivas:


<syntaxhighlight lang="lua">
* Ano inválido retorna erro controlado
local Estatisticas = require("Module:Temporada/Estatisticas")
* Partidas inválidas são ignoradas
* Campos ausentes são tratados como zero
* Aproveitamento é calculado apenas ao final
 
---


local stats = Estatisticas.calcular(listaDePartidas)
== Boas práticas e manutenção ==
</syntaxhighlight>


A renderização desses dados deve ser feita externamente, por templates ou módulos de visualização.
* Não adicionar lógica editorial neste módulo
* Manter separação clara entre cálculo e apresentação
* Não alterar estrutura de retorno sem revisar dependências
* Novos campos estatísticos devem ser documentados
* Dados históricos devem ser adicionados apenas em <code>Módulo:Temporada/Dados/ANO</code>


---
---


== Convenções editoriais ==
== Páginas relacionadas ==


* Este módulo deve permanecer **genérico**
* [[Módulo:Temporada]]
* Não devem ser inseridas regras específicas de uma temporada isolada
* [[Módulo:Temporada/Utils]]
* Toda exceção histórica deve ser resolvida no nível da partida
* [[Módulo:Temporada/Partidas]]
* Alterações devem ser documentadas nesta página
* [[Módulo:Temporada/Dados/1919]]
* [[Predefinição:EstatisticasTemporada]]


---
---
Linha 144: Linha 158:
== Histórico ==
== Histórico ==


* Módulo criado no contexto da automação das páginas de temporada da Wiki Galo Digital
* Módulo criado para consolidação estatística centralizada
* Parte do checklist mestre de automação (Etapa 3.1)
* Estruturado para evitar repetição de cálculos entre templates
* Preparado para expansão futura de indicadores

Edição atual tal como às 07h23min de 25 de janeiro de 2026

Predefinição:Documentation

Módulo:Temporada/Estatisticas

O Módulo:Temporada/Estatisticas é responsável pela consolidação estatística das partidas de uma temporada no projeto Wiki Galo Digital.

Ele processa os dados brutos de partidas, aplica regras de validação e cálculo e retorna estatísticas agregadas, que podem ser consumidas por outros módulos ou renderizadas por templates.

---

Escopo e responsabilidades

Este módulo é responsável por:

  • Consolidar estatísticas gerais da temporada
  • Processar partidas válidas (não anuladas e contabilizáveis)
  • Separar desempenho como mandante e visitante
  • Calcular:
    • Jogos
    • Vitórias, empates e derrotas
    • Gols pró e contra
    • Saldo de gols
    • Aproveitamento
  • Fornecer renderização tabular para uso editorial

Predefinição:Aviso

---

Dependências

Este módulo depende diretamente de:

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

E carrega dinamicamente os dados de cada temporada a partir de:

  • Module:Temporada/Dados/ANO

---

Estrutura de dados

Estrutura base

A função interna de criação da estrutura estatística gera os seguintes campos:

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

Cada subestrutura mantém seus próprios totais.

---

Funções internas

processarPartida(stats, partida)

Processa uma partida individual e acumula seus dados na estrutura estatística.

  • Ignora partidas:
    • Anuladas
    • Marcadas como não contabilizáveis
  • Identifica se o Atlético atuou como:
    • Mandante
    • Visitante
  • Atualiza:
    • Contadores de jogos
    • Gols pró e contra
    • Resultado (V, E, D)

Predefinição:Nota

---

Funções públicas

calcularPorAno(ano)

Calcula todas as estatísticas da temporada informada.

  • Parâmetro
    • ano (number)
  • Fluxo de execução
  1. Cria estrutura estatística vazia
  2. Carrega dinamicamente o módulo de dados do ano
  3. Processa cada partida
  4. Calcula saldos e aproveitamento
  • Retorno
    • Tabela Lua com estatísticas consolidadas

Predefinição:Aviso

---

render(frame)

Função pública de renderização da tabela de estatísticas gerais.

  • Uso
    • Template:EstatisticasTemporada
  • Parâmetro
    • frame.args.ano
  • Saída
    • Tabela wiki com:
      • Totais gerais
      • Mandante
      • Visitante

Predefinição:Aviso

---

Regras de validação

O módulo aplica validações defensivas:

  • Ano inválido retorna erro controlado
  • Partidas inválidas são ignoradas
  • Campos ausentes são tratados como zero
  • Aproveitamento é calculado apenas ao final

---

Boas práticas e manutenção

  • Não adicionar lógica editorial neste módulo
  • Manter separação clara entre cálculo e apresentação
  • Não alterar estrutura de retorno sem revisar dependências
  • Novos campos estatísticos devem ser documentados
  • Dados históricos devem ser adicionados apenas em Módulo:Temporada/Dados/ANO

---

Páginas relacionadas

---

Histórico

  • Módulo criado para consolidação estatística centralizada
  • Estruturado para evitar repetição de cálculos entre templates
  • Preparado para expansão futura de indicadores
Disponível em “http://www.galodigital.com.br/w/index.php?title=Módulo:Temporada/Estatisticas/doc&oldid=154209”