# PRD — Pontuação e ranking

**Dono:** Igor · **Status:** rascunho · **Data:** 03/08/2026
**Origem:** Fase 1 do `bolao-usuario` (03/08/2026)

---

## 1. Problema

A conta dos pontos é feita à mão numa planilha, e isso custa caro:

- **Um erro de conta vira briga que dura o campeonato inteiro.** Ninguém
  consegue auditar a planilha do admin, então "confia" é a única resposta
  disponível — e ela não resolve discussão.
- **Ninguém sabe explicar como o ponto saiu.** O competitivo pediu a conta
  jogo por jogo; hoje ela não existe em lugar nenhum.
- **Empate no fim do campeonato não tem critério definido.** Dois
  empatados no topo geram briga justamente na hora que mais importa.
- **Placar corrigido pela federação** obriga o admin a refazer a planilha à
  mão, ou a ignorar a correção e deixar alguém injustiçado.
- **Quem entrou na rodada 5** não sabe com quantos pontos começa, e isso
  também é decidido no improviso.

É o trabalho manual que faz o admin desistir na terceira rodada — e
quando ele desiste, o bolão morre.

## 2. Objetivo e métrica de sucesso

_Métricas propostas, a validar com o dono._

- **Zero cálculo manual de pontos** pelo admin durante o campeonato.
- **100% dos pontos rastreáveis até o jogo** que os gerou, visível ao
  participante sem pedir para o admin.
- **Zero discussão sobre pontuação** que precise do admin como árbitro.

## 3. Personas afetadas

| Persona           | O que muda                                                                    |
| ----------------- | ----------------------------------------------------------------------------- |
| **Administrador** | Sai do papel de calculadora e de árbitro de discussão sobre ponto             |
| **Casual**        | Vê se subiu ou caiu num lugar só, e quanto falta para passar quem está à frente |
| **Competitivo**   | Vê a conta jogo por jogo, o desempate aplicado, e é avisado quando o ponto muda |

**Onde as personas discordam, e quem ganha:**

- **Prêmio por rodada.** O competitivo pediu premiação por rodada para
  segurar quem está em 15º na rodada 10; o admin achou que complica a
  divisão do dinheiro. **A discussão ficou vazia por outro motivo:** não
  há dinheiro nesta versão. Fica só o **ranking da rodada** separado do
  geral — resolve o problema de motivação do competitivo sem tocar em
  premiação.
- **Estabilidade do ranking × placar oficial.** O casual quer um ranking
  que não mude sozinho; o competitivo quer que o app use sempre o placar
  oficial. **Ganhou o competitivo:** correção recalcula o passado. _Custo
  aceito:_ o ranking pode mudar depois de fechado, então **a comunicação
  da mudança é obrigatória** — sem ela, o casual lê como bug e sai.

## 4. Escopo

- Cálculo do ponto por jogo segundo a tabela 10 / 5 / 3
- Extrato do ponto por jogo, visível a cada participante
- Ranking geral e ranking da rodada, separados
- Aplicação e exibição dos critérios de desempate
- Recálculo retroativo quando um placar oficial é corrigido, com aviso aos
  afetados
- Jogo pendente de apuração não pontua e não altera o total da rodada — não
  existe anulação, todo jogo não realizado fica aguardando (ver seção 6)
- Correção manual de placar pelo admin quando a fonte oficial falhar, visível
  a todos como intervenção humana

## 5. Fora de escopo

- Registro do palpite, prazo, edição e sigilo → épico _Palpite e prazo_
- Premiação, valor de entrada, cobrança → **sem dinheiro nesta versão**
  (ver `docs/prd/premiacao-e-cobranca.md`)
- Criação do bolão e escolha da tabela de pontos na criação → épico
  _Criação e convite_
- Encerramento do campeonato e ranking final definitivo → épico
  _Ciclo de vida do bolão_
- Gráfico de evolução por rodada e histórico de temporadas (desejável na
  Fase 1, não essencial)
- Comentários sobre o ranking

## 6. Regras de domínio decididas

| Regra                          | Decisão                                                                                                                                                                                              | Status                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Pontuação                      | **10** placar exato · **5** acertar o vencedor **e** o saldo de gols · **3** acertar só o vencedor · **0** errar. Empate acertado com placar exato vale 10; acertar que foi empate sem o placar vale **3** — **confirmado pelo dono em 07/08**, porque todo empate tem saldo 0 e não existe faixa de saldo para empate | decidido e confirmado |
| Desempate                      | 1º **mais placares exatos** → 2º **mais acertos de vencedor** → 3º persistindo o empate, **os empatados dividem a posição** (co-campeões). O critério aplicado fica visível ao participante              | decidido                            |
| Placar corrigido após apuração | **Recalcula retroativamente** com o placar oficial, mesmo em rodada fechada. **Todo participante cujo ponto ou posição mudou é avisado, com o motivo** — aviso não é opcional                            | decidido                            |
| Jogo cancelado / W.O.          | **Não existem: todo jogo não realizado é adiado** (decidido 03/08, revisa a proposta anterior de anular). **Nenhum jogo é anulado** e o total da rodada nunca muda — o jogo fica pendente até ser apurado. W.O. real: o admin lança o placar oficial à mão (`PR-10`). **A story `PR-8` foi cancelada** | decidido                            |
| Palpite não enviado            | **Zero pontos naquele jogo, sem penalidade adicional.** Não pontuar já é a consequência                                                                                                                | proposta a validar — Igor            |
| Entrada no meio do campeonato  | não se aplica — **não é possível entrar atrasado** (decidido 03/08, épico _Criação e convite_). Todos os participantes disputam desde o primeiro jogo, então não há pontuação inicial a definir        | não se aplica                       |
| Prazo do palpite               | não se aplica — decidido no épico _Palpite e prazo_ (fecha no apito de cada jogo)                                                                                                                      | não se aplica                       |
| Jogo adiado                    | não se aplica — decidido no épico _Palpite e prazo_ (prazo e palpite reabrem no novo horário)                                                                                                          | não se aplica                       |
| Sigilo dos palpites            | não se aplica — decidido no épico _Palpite e prazo_ (libera quando o jogo termina)                                                                                                                     | não se aplica                       |
| Dinheiro                       | **não se aplica — sem dinheiro nesta versão** (decisão de 03/08/2026). A regra de divisão de prêmio em caso de empate está registrada para quando o dinheiro entrar                                     | não se aplica                       |

## 7. Fluxo principal

1. O jogo termina e o placar oficial entra.
2. Vejo meu ponto daquele jogo aparecer, com a conta: o que eu palpitei, o
   que deu, e por que valeu 10, 5, 3 ou 0.
3. Vejo minha posição no ranking da rodada e no geral, e se subi ou caí.
4. Se eu estou empatado com alguém, vejo qual critério está me colocando
   à frente ou atrás.
5. Se a federação corrigir um placar depois, recebo o aviso de que meu
   ponto mudou, com o motivo, e o ranking já reflete a correção.

## 8. Requisitos não funcionais

- **O cálculo é do servidor.** O app exibe o ponto que o servidor mandou;
  qualquer conta local só pode aparecer rotulada como parcial/não oficial.
- **Mudança retroativa precisa ser explicável**, não só aplicada — o
  aviso tem que dizer qual jogo mudou e qual era o placar anterior.
- **Fuso e rodada:** "rodada fechada" é determinado pelo servidor, não
  pela data no device.
- **Ranking com muitos participantes** precisa carregar sem travar e
  mostrar minha posição sem eu ter que rolar até achar.

## 9. Riscos e dependências

- **Fonte oficial de placar.** Todo o épico depende dela. Se ela errar ou
  ficar fora, o ranking inteiro fica errado — e é a mesma dependência
  crítica do épico _Palpite e prazo_.
- **Recálculo retroativo é a maior fonte de desconfiança do produto.** Um
  ranking que muda sem explicação clara é lido como bug, não como
  correção.
- **Correção manual de placar pelo admin** (pedido na Fase 1 para quando a
  fonte falhar) precisa ficar visível a todos como intervenção humana —
  senão reintroduz a suspeita que o sigilo resolveu.
- Depende de o épico _Palpite e prazo_ já registrar palpite e prazo.

## 10. Perguntas abertas

| Pergunta                                                                          | Dono | Prazo      |
| --------------------------------------------------------------------------------- | ---- | ---------- |
_Nenhuma pergunta aberta neste épico._

**Respondidas em 03/08/2026:**

- **Jogo cancelado ou W.O.: anula para todos.** Confirmado — ninguém pontua e
  o jogo sai do total da rodada (story `PR-8`).
- **Palpite não enviado: zero, sem penalidade.** Confirmado.
- **Entrada no meio: deixou de existir** — não é possível entrar atrasado,
  então não há pontuação inicial a definir. **A story `PR-9` foi cancelada.**

- **O admin pode corrigir placar à mão.** Vira capacidade nova (story
  `PR-10`), com duas condições que a decisão do PRD já impõe: a correção
  **recalcula tudo como qualquer correção oficial** (PR-6), e **fica visível
  a todos como intervenção humana**, com autor e placar anterior. ⚠️ Sem isso
  a correção manual reintroduz a suspeita que o sigilo (PP-7) eliminou.
- **Fonte oficial de placar:** a gratuita — `football-data.org` tier Free,
  provisória até o spike. **O tier Free tem placar atrasado**, o que conflita
  com a necessidade de ver o ponto logo após o apito.

### Consequência da decisão sobre encerramento

O épico _Ciclo de vida_ decidiu que **correção de placar após o encerramento
troca o campeão**. Isso muda o alcance de PR-6: o recálculo se aplica também
a bolão já encerrado, e o ranking final não é congelado.

## 11. Stories derivadas

Os Given/When/Then vivem no cartão de cada story (`docs/stories/`), não aqui.

- [ ] `PR-1` Calcular o ponto de cada palpite pela tabela 10 / 5 / 3
- [ ] `PR-2` Extrato do ponto por jogo, com a conta visível ao participante
- [ ] `PR-3` Ranking geral do bolão
- [ ] `PR-4` Ranking da rodada, separado do geral
- [ ] `PR-5` Aplicar e exibir os critérios de desempate
- [ ] `PR-6` Recalcular pontos e ranking quando um placar oficial é corrigido
- [ ] `PR-7` Avisar os participantes afetados por um recálculo, com o motivo
- [ ] Correção manual de placar pelo admin (`PR-10`)

**Stories canceladas em 03/08:**

- ~~Pontuação de quem entra com o campeonato em andamento~~ (`PR-9`) — não é
  possível entrar atrasado, a regra deixou de existir.
- ~~Anular jogo cancelado / W.O. no cálculo da rodada~~ (`PR-8`) — não existem
  cancelado nem W.O.: todo jogo não realizado é adiado e aguarda. Sem
  anulação, não há nada a implementar. W.O. real vira `PR-10`.

---

## Bloqueios

**Nenhuma story deste épico está bloqueada por decisão de produto.** Todas as
regras da seção 6 estão fechadas, e as duas que estavam em aberto acabaram
cancelando suas stories (`PR-8` e `PR-9`) em vez de destravá-las.

**Mas duas stories têm risco técnico não verificado**, que só o spike da fonte
de dados resolve:

- `PR-1` (cálculo do ponto) — depende de quanto o tier Free da
  `football-data.org` atrasa o placar. Atraso grande contraria a métrica
  aceita na seção 2.
- `PR-6` (recálculo por correção) — depende de a fonte informar correção de
  placar de jogo já apurado. Se ela apenas sobrescrever sem sinalizar, a
  detecção tem que ser feita por comparação no nosso backend.
