Status: Approved · v2 · SPEC-DOMAIN-RANKING-001

depends_on: SPEC-DOMAIN-MATCH-001, SPEC-DOMAIN-PLAYER-001

used_by: IS-MVP-12.1, IS-MVP-12.2

Rankings e estatísticas

Cálculos públicos derivados de partidas validadas, com peso por tipo, amostra mínima e recortes territoriais.

Objetivo e limites

Esta especificação define o comportamento canônico do domínio Rankings e estatísticas no RaizFC. Ela deve ser consultada antes de alterar contratos, mocks, endpoints, telas, permissões ou Increment Specifications relacionados.

Incluído no MVP

• Ranking de desempenho de times.
• Rankings territoriais de times e torcidas.
• Artilharia.
• Stats de time/jogador/campeonato.
• Períodos geral, 90 dias e campeonato atual.
• Provisório abaixo de três jogos validados.

Fora do MVP

• Elo avançado.
• Modelos preditivos.
• Rankings nacionais complexos.
• Prêmios automatizados.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Consulta rankings e stats.
Time/jogador/torcida	Aparece conforme dados validados e privacidade.
Gestor de campeonato	Consulta standings específicas da edição.
Sistema	Recalcula após eventos canônicos.

Conceitos canônicos

Ranking Snapshot

Resultado versionado de um cálculo.

Provisional

Amostra insuficiente.

Match Weight

Peso por tipo/importância.

Opponent Strength

Fator moderado baseado no desempenho do adversário.

Engagement Ranking

Ranking de torcida sem valor financeiro.

Invariantes

• Somente partidas validated entram em stats definitivas.
• Contestada é excluída até resolução.
• Patrocínio e valor de apoio não influenciam ranking.
• Amostra menor que três jogos recebe Provisório e penalização de confiança.
• Período e território aparecem claramente.
• Retificação invalida snapshots afetados.
• Stats do jogador respeitam privacidade e guest confirmation.
• Standing de campeonato segue regulamento da edição, não fórmula geral.

Estados

Estado	Significado	Visibilidade/efeito
pending_recalculation	Dados alterados	Snapshot antigo pode ser marcado stale.
current	Atual	Público.
stale	Desatualizado	Pode exibir timestamp/aviso.
invalidated	Retificação/disputa	Não usar.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	calculate	current	Job/service	Cria snapshot.
current	source_changed	pending_recalculation	Evento	Agenda.
current	invalidate	invalidated	Retificação	Remove uso.
pending_recalculation	recalculate	current	Job	Substitui.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
ranking.read	Público	Consultar	Não
ranking.recalculate	Sistema/operação	Recalcular	Sim
ranking.override	Não usado no ranking geral	—	—

Fluxos funcionais

Ranking de times

1. Seleciona times elegíveis por território/período.
2. Agrega pontos de resultado, aproveitamento, peso da partida, força do adversário, regularidade e confiabilidade.
3. Aplica fator de amostra.
4. Ordena e cria rows com score explicável.

Artilharia

1. Agrega gols de eventos validados e jogadores confirmados/elegíveis.
2. Desempate por jogos, média e regras do contexto.
3. Exibe time e período.

Ranking de torcida

1. Usa membros, seguidores/cheers permitidos, atividade e regularidade.
2. Não usa valor de apoio ou patrocínio.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Menos de três jogos	Marcar Provisório	RANKING_PROVISIONAL
Empate de score	Aplicar desempates documentados e posição compartilhada quando necessário	—
Partida retificada	Invalidar e recalcular	RANKING_STALE
Jogador privado	Excluir ranking público pessoal	PLAYER_PRIVATE
Adversário sem ranking	Usar fator neutro	—

Privacidade e exposição pública

• Ranking público usa somente métricas públicas.
• Não expõe valores financeiros.
• Stats privadas não são inferidas por totals agregados quando houver risco.

Notificações e auditoria

• Mudança de posição pode alimentar feed, não push automático por padrão.
• Retificação e erro de cálculo geram observabilidade.

API relacionada

Método	Rota	Acesso	Finalidade
GET	/api/v1/rankings	Público	Ranking por tipo/período/território
GET	/api/v1/rankings/top-scorers	Público	Artilharia
GET	/api/v1/teams/:id/stats	Público	Stats time
GET	/api/v1/players/:id/stats	Público	Stats jogador
GET	/api/v1/torcidas/:id/stats	Público	Stats torcida
GET	/api/v1/championships/:id/editions/:editionId/standings	Público	Standing competição

Contratos compartilhados

• RankingType
• RankingPeriod
• RankingDto
• RankingRowDto
• RankingBadge
• TeamStatsDto
• PlayerStatsDto
• TorcidaStatsDto
• TopScorerRowDto

Requisitos de UX

• Ranking sempre mostra escopo, período, atualização e explicação resumida.
• Badge Provisório é textual e acessível.
• Filtros por território/período ficam visíveis.
• Linha do usuário/time pode ser destacada sem alterar ordem.

Comportamento dos mocks

• Ranking current/stale/provisional.
• Retificação remove/reordena.
• Top scorers com privacy filtered.

Critérios de aceite

• Somente validated.
• Mínimo três para não provisório.
• Sem dinheiro/patrocínio.
• Período/território claros.
• Retificação recalcula.

Testes obrigatórios

• Fórmula e pesos.
• Amostra.
• Empates.
• Contestação/retificação.
• Privacy.
• Torcida sem valor financeiro.

Pós-MVP

• Elo, força regional, modelos preditivos e badges históricos.

Decisões registradas

• Ranking misto e explicável.
• Poucos jogos não superam histórico robusto sem aviso/fator.
• Ranking de torcida não usa dinheiro.

Machine summary

spec: SPEC-DOMAIN-RANKING-001
domain: Rankings e estatísticas
must_preserve:
  - Somente partidas validated entram em stats definitivas.
  - Contestada é excluída até resolução.
  - Patrocínio e valor de apoio não influenciam ranking.
  - Amostra menor que três jogos recebe Provisório e penalização de confiança.
  - Período e território aparecem claramente.
  - Retificação invalida snapshots afetados.
  - Stats do jogador respeitam privacidade e guest confirmation.
  - Standing de campeonato segue regulamento da edição, não fórmula geral.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation