Módulo:Temporada/Utils/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 '<noinclude> {{Documentação de módulo}} </noinclude> = Module:Temporada/Utils = Este módulo reúne **funções utilitárias reutilizáveis** para a automação das páginas de temporada da Wiki Galo Digital, com foco em: * simplicidade de código * segurança contra erros de parâmetros * performance * padronização de cálculos e regras O módulo **não gera nenhuma saída visual direta**. Ele deve ser utilizado exclusivamente como dependência de outros módu...'
 
Sem resumo de edição
 
Linha 1: Linha 1:
<noinclude>
{{Documentation}}
{{Documentação de módulo}}
</noinclude>


= Module:Temporada/Utils =
= Módulo:Temporada/Utils =


Este módulo reúne **funções utilitárias reutilizáveis** para a automação das páginas de temporada da Wiki Galo Digital, com foco em:
O '''Módulo:Temporada/Utils''' concentra funções utilitárias reutilizáveis utilizadas pelos módulos de temporada do projeto '''Wiki Galo Digital'''.


* simplicidade de código
Este módulo **não gera saída visual** e existe para:
* segurança contra erros de parâmetros
* Evitar repetição de código
* performance
* Padronizar cálculos e validações
* padronização de cálculos e regras
* Centralizar regras simples e transversais
 
O módulo **não gera nenhuma saída visual direta**. 
Ele deve ser utilizado exclusivamente como dependência de outros módulos Scribunto.


---
---


== Finalidade ==
== Escopo e responsabilidades ==


O '''Module:Temporada/Utils''' funciona como a **camada de fundação lógica** do sistema de temporadas, centralizando operações comuns que seriam repetidas em diversos módulos, como:
Este módulo é responsável por:


* comparação de placares
* Conversões seguras de tipos (string, número, boolean)
* normalização de valores
* Normalização básica de valores vindos da wiki
* cálculo de resultados
* Cálculos genéricos utilizados em estatísticas e campanhas
* cálculo de aproveitamento
* Regras auxiliares de comparação de resultados
* interpretação de parâmetros booleanos vindos do wikitexto
* Apoio à padronização visual indireta (classes CSS)


Ele é utilizado, ou será utilizado, pelos seguintes módulos:
{{Aviso|texto=Este módulo não deve conter lógica de domínio específica de competições, estatísticas ou campanhas.}}


* Module:Temporada/Partidas
---
* Module:Temporada/Estatisticas
* Module:Temporada/Campanha
* Module:Temporada/Artilharia
* Module:Temporada


---
== Dependências ==


== Princípios de implementação ==
Este módulo utiliza funções nativas do MediaWiki:


O módulo foi desenvolvido seguindo os seguintes princípios:
* <code>mw.text.trim</code>
* <code>mw.ustring.lower</code>


* funções pequenas e legíveis
Não possui dependência direta de outros módulos do projeto.
* nenhuma dependência externa
* nenhuma chamada a mw.title.new()
* comportamento defensivo (nunca quebra a renderização da página)
* retorno de valores simples e previsíveis


---
---


== Funções disponíveis ==
== Funções públicas ==


=== toNumber(value, default) ===
=== toNumber(value, default) ===


Converte um valor em número de forma segura.
Converte um valor para número de forma defensiva.


; Parâmetros
* '''Parâmetros'''
* <code>value</code> – valor a ser convertido
** <code>value</code> – valor a ser convertido
* <code>default</code> – valor retornado caso a conversão falhe (opcional)
** <code>default</code> (opcional) – valor padrão em caso de falha


; Retorno
* '''Retorno'''
* Número (integer ou float)
** Número convertido ou valor padrão
** Retorna <code>0</code> caso nenhum padrão seja informado


; Observações
* '''Uso típico'''
* Se <code>value</code> for nulo ou inválido, retorna <code>default</code> ou <code>0</code>
* Tratamento de parâmetros vindos de templates
* Cálculos estatísticos


---
---


=== normalizeString(value) ===
=== normalizeString(valor) ===


Normaliza uma string, removendo espaços extras e aplicando trim.
Normaliza uma string removendo espaços excedentes.


; Parâmetros
* '''Parâmetro'''
* <code>value</code> – string de entrada
** <code>valor</code> (string)


; Retorno
* '''Retorno'''
* String normalizada
** String normalizada
* String vazia caso o valor seja nulo
** Retorna string vazia se o valor não for string


---
---
Linha 82: Linha 72:
=== isAtletico(nome) ===
=== isAtletico(nome) ===


Verifica se o nome informado corresponde ao Clube Atlético Mineiro, independentemente de grafia ou acentuação básica.
Verifica se um nome se refere ao Clube Atlético Mineiro.


; Parâmetros
* '''Parâmetro'''
* <code>nome</code> – nome do time
** <code>nome</code> (string)


; Retorno
* '''Retorno'''
* <code>true</code> se for Atlético
** <code>true</code> se identificar “atlético” ou “atletico”
* <code>false</code> caso contrário
** <code>false</code> caso contrário


; Uso típico
{{Nota|texto=Função auxiliar simples, pensada para normalizações futuras mais robustas.}}
Identificar automaticamente se o Atlético é mandante ou visitante em uma partida.


---
---
Linha 98: Linha 87:
=== resultadoPartida(golsTime, golsAdversario) ===
=== resultadoPartida(golsTime, golsAdversario) ===


Compara os gols de uma partida e retorna o resultado padrão.
Compara o placar de uma partida.


; Parâmetros
* '''Parâmetros'''
* <code>golsTime</code>
** <code>golsTime</code>
* <code>golsAdversario</code>
** <code>golsAdversario</code>


; Retorno
* '''Retorno'''
* <code>"V"</code> – vitória
** <code>"V"</code> – vitória
* <code>"E"</code> – empate
** <code>"E"</code> – empate
* <code>"D"</code> – derrota
** <code>"D"</code> – derrota


---
---
Linha 113: Linha 102:
=== cssResultado(resultado) ===
=== cssResultado(resultado) ===


Retorna a classe CSS correspondente ao resultado da partida.
Retorna a classe CSS associada ao resultado da partida.


; Parâmetros
* '''Parâmetro'''
* <code>resultado</code> – valor retornado por <code>resultadoPartida</code>
** <code>resultado</code> (<code>V</code>, <code>E</code>, <code>D</code>)


; Retorno
* '''Retorno'''
* <code>gd-result-win</code>
** Classe CSS correspondente
* <code>gd-result-draw</code>
** String vazia se inválido
* <code>gd-result-loss</code>
 
* String vazia se inválido
* '''Classes utilizadas'''
** <code>gd-result-win</code>
** <code>gd-result-draw</code>
** <code>gd-result-loss</code>


---
---


=== pontosResultado(resultado) ===
=== aproveitamento(pontosObtidos, pontosPossiveis) ===
 
Calcula o aproveitamento percentual.


Retorna a pontuação padrão associada ao resultado da partida.
* '''Parâmetros'''
** <code>pontosObtidos</code>
** <code>pontosPossiveis</code>


; Parâmetros
* '''Retorno'''
* <code>resultado</code> – "V", "E" ou "D"
** Número percentual (0 a 100)
** Retorna <code>0</code> se <code>pontosPossiveis</code> for zero


; Retorno
{{Aviso|texto=Esta função retorna um número puro. A formatação deve ser feita fora do módulo.}}
* <code>3</code> para vitória
* <code>1</code> para empate
* <code>0</code> para derrota


---
---


=== aproveitamento(pontosObtidos, pontosPossiveis) ===
=== pontosResultado(resultado) ===
 
Calcula o percentual de aproveitamento.


; Parâmetros
Converte o resultado da partida em pontuação padrão (3-1-0).
* <code>pontosObtidos</code>
* <code>pontosPossiveis</code>


; Retorno
* '''Parâmetro'''
* String formatada com uma casa decimal e símbolo de porcentagem
** <code>resultado</code> (<code>V</code>, <code>E</code>, <code>D</code>)
* Retorna "-" caso <code>pontosPossiveis</code> seja zero


; Exemplo de retorno
* '''Retorno'''
<code>37.5%</code>
** <code>3</code>, <code>1</code> ou <code>0</code>


---
---
Linha 159: Linha 148:
=== toBoolean(value) ===
=== toBoolean(value) ===


Converte parâmetros textuais do wikitexto em booleano.
Converte parâmetros vindos da wiki ou Lua para booleano real.


; Valores interpretados como <code>true</code>
* '''Parâmetro'''
* <code>sim</code>
** <code>value</code>
* <code>true</code>
 
* <code>1</code>
* '''Reconhece como verdadeiro'''
** <code>true</code> (boolean)
** <code>"sim"</code>
** <code>"true"</code>
** <code>"1"</code>
 
* '''Retorno'''
** <code>true</code> ou <code>false</code>
 
---


; Retorno
== Boas práticas ==
* <code>true</code> ou <code>false</code>


; Uso típico
* Não adicionar renderização visual
Leitura de parâmetros como:
* Não incluir lógica específica de domínio
* jogo anulado
* Manter funções pequenas e previsíveis
* W.O
* Centralizar aqui regras simples reutilizáveis
* jogo fora das estatísticas
* Documentar qualquer nova função adicionada


---
---


== Observações finais ==
== Páginas relacionadas ==


* Este módulo **não deve ser chamado diretamente via #invoke em páginas de conteúdo**
* [[Módulo:Temporada]]
* Toda lógica específica de temporada deve ficar nos módulos especializados
* [[Módulo:Temporada/Estatisticas]]
* Alterações neste módulo afetam todo o sistema de temporadas e devem ser feitas com cautela
* [[Módulo:Temporada/Campanha]]
* [[Módulo:Temporada/Partidas]]


---
---
Linha 187: Linha 185:
== Histórico ==
== Histórico ==


* Criado no contexto do projeto '''Wiki Galo Digital'''
* Módulo criado como base utilitária do sistema de temporadas
* Desenvolvido para sustentar a automação das páginas de temporadas históricas
* Projetado para reduzir duplicação de código e facilitar manutenção
* Primeira aplicação prática: '''Futebol – Temporada 1919'''

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

Predefinição:Documentation

Módulo:Temporada/Utils

O Módulo:Temporada/Utils concentra funções utilitárias reutilizáveis utilizadas pelos módulos de temporada do projeto Wiki Galo Digital.

Este módulo **não gera saída visual** e existe para:

  • Evitar repetição de código
  • Padronizar cálculos e validações
  • Centralizar regras simples e transversais

---

Escopo e responsabilidades

Este módulo é responsável por:

  • Conversões seguras de tipos (string, número, boolean)
  • Normalização básica de valores vindos da wiki
  • Cálculos genéricos utilizados em estatísticas e campanhas
  • Regras auxiliares de comparação de resultados
  • Apoio à padronização visual indireta (classes CSS)

Predefinição:Aviso

---

Dependências

Este módulo utiliza funções nativas do MediaWiki:

  • mw.text.trim
  • mw.ustring.lower

Não possui dependência direta de outros módulos do projeto.

---

Funções públicas

toNumber(value, default)

Converte um valor para número de forma defensiva.

  • Parâmetros
    • value – valor a ser convertido
    • default (opcional) – valor padrão em caso de falha
  • Retorno
    • Número convertido ou valor padrão
    • Retorna 0 caso nenhum padrão seja informado
  • Uso típico
  • Tratamento de parâmetros vindos de templates
  • Cálculos estatísticos

---

normalizeString(valor)

Normaliza uma string removendo espaços excedentes.

  • Parâmetro
    • valor (string)
  • Retorno
    • String normalizada
    • Retorna string vazia se o valor não for string

---

isAtletico(nome)

Verifica se um nome se refere ao Clube Atlético Mineiro.

  • Parâmetro
    • nome (string)
  • Retorno
    • true se identificar “atlético” ou “atletico”
    • false caso contrário

Predefinição:Nota

---

resultadoPartida(golsTime, golsAdversario)

Compara o placar de uma partida.

  • Parâmetros
    • golsTime
    • golsAdversario
  • Retorno
    • "V" – vitória
    • "E" – empate
    • "D" – derrota

---

cssResultado(resultado)

Retorna a classe CSS associada ao resultado da partida.

  • Parâmetro
    • resultado (V, E, D)
  • Retorno
    • Classe CSS correspondente
    • String vazia se inválido
  • Classes utilizadas
    • gd-result-win
    • gd-result-draw
    • gd-result-loss

---

aproveitamento(pontosObtidos, pontosPossiveis)

Calcula o aproveitamento percentual.

  • Parâmetros
    • pontosObtidos
    • pontosPossiveis
  • Retorno
    • Número percentual (0 a 100)
    • Retorna 0 se pontosPossiveis for zero

Predefinição:Aviso

---

pontosResultado(resultado)

Converte o resultado da partida em pontuação padrão (3-1-0).

  • Parâmetro
    • resultado (V, E, D)
  • Retorno
    • 3, 1 ou 0

---

toBoolean(value)

Converte parâmetros vindos da wiki ou Lua para booleano real.

  • Parâmetro
    • value
  • Reconhece como verdadeiro
    • true (boolean)
    • "sim"
    • "true"
    • "1"
  • Retorno
    • true ou false

---

Boas práticas

  • Não adicionar renderização visual
  • Não incluir lógica específica de domínio
  • Manter funções pequenas e previsíveis
  • Centralizar aqui regras simples reutilizáveis
  • Documentar qualquer nova função adicionada

---

Páginas relacionadas

---

Histórico

  • Módulo criado como base utilitária do sistema de temporadas
  • Projetado para reduzir duplicação de código e facilitar manutenção
Disponível em “http://www.galodigital.com.br/w/index.php?title=Módulo:Temporada/Utils/doc&oldid=154208”