# PRD — Palpite e prazo

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

---

## 1. Problema

Hoje o palpite é mandado no grupo do WhatsApp e conferido à mão numa
planilha. Isso quebra em três pontos, todos com custo real:

- **O palpite se perde.** A mensagem afunda no meio de 200 outras e vira
  "eu mandei sim" contra "não chegou". Não existe registro confiável.
- **Não há prazo verificável.** Palpite que chega dois minutos depois do
  apito passa como válido, porque ninguém sabe a hora exata em que
  chegou. Isso gera a desconfiança de que alguém palpitou já sabendo do
  gol.
- **Não há sigilo.** Quem consolida a planilha vê o palpite de todos
  antes do jogo. Na Fase 1 o competitivo classificou isso como a pior de
  todas as dores: sem sigilo, o bolão perde a graça e ele não joga.

O admin, que faz esse trabalho manual, é quem desiste primeiro — e quando
ele desiste, o bolão morre.

## 2. Objetivo e métrica de sucesso

_Aceitas em 03/08/2026, com a revisão abaixo._

- **≥ 90% dos palpites** de participantes ativos enviados antes do prazo
  **sem o admin cobrar individualmente** no grupo.
- **Zero palpite digitado e perdido** por falha de rede.
- **Zero palpite aceito depois do horário oficial de início** do jogo.

⚠️ **Métrica removida em 03/08: "ver o ponto logo após o apito".** O projeto é
uma PoC e ficou no tier gratuito da `football-data.org`, que entrega **placar
atrasado por design** (ver `docs/spikes/fonte-de-dados.md`). O resultado e o
ponto chegam com atraso, e **a interface precisa deixar isso claro ao
participante** em vez de parecer que travou.

Consequência para a Fase 1: a necessidade do casual — *"preciso ver o resultado
e meu ponto logo depois do apito"* — **não é atendida nesta versão.** É a única
necessidade priorizada como essencial que fica descoberta.

## 3. Personas afetadas

| Persona           | O que muda                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| **Administrador** | Para de conferir palpite à mão e de cobrar um por um; passa a ver quem falta palpitar            |
| **Casual**        | Ganha a maior janela possível para palpitar, confirmação de que salvou, e lembrete antes de fechar |
| **Competitivo**   | Ganha sigilo garantido e a possibilidade de ajustar o palpite até o apito                        |

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

- **Sigilo × diversão (o competitivo contra si mesmo).** Na Fase 1 ele
  pediu duas coisas incompatíveis: sigilo absoluto e ver o palpite de
  todos "depois que fecha, porque é metade da graça". **Ganhou o sigilo:**
  os palpites só são revelados quando o jogo termina, não no apito.
  Integridade da competição vale mais que a conversa durante o jogo.
  _Custo aceito:_ perde-se o "e você, quanto botou?" enquanto a bola
  rola. **Vigiar se isso esfria o uso durante o jogo.**
- **Poder do admin × confiança do competitivo.** O admin queria ver
  palpites para conferir, e queria poder reabrir palpite. **Ganhou o
  competitivo:** o admin não vê palpite de ninguém antes do jogo
  terminar, e a reabertura por adiamento é **automática, disparada pela
  mudança do horário oficial** — nunca uma ação discricionária do admin.
  Isso resolve os dois lados: o palpite reabre quando precisa, sem que
  ninguém possa acusar o admin de favorecer alguém.
- **Notificação: casual × competitivo.** O casual quer quase nenhuma, o
  competitivo quer todas. **Ganhou o casual neste épico:** entra só o
  lembrete de prazo, e só para quem ainda não palpitou. Se o lembrete de
  prazo vier junto com avisos de ranking e comentário, o casual desliga
  tudo — e volta a perder rodada, que é o problema nº 1 deste PRD.

## 4. Escopo

- Palpitar e editar o placar de cada jogo enquanto o prazo daquele jogo
  estiver aberto
- Prazo por jogo, com contagem de tempo restante visível
- Rascunho preservado localmente e enviado quando a conexão voltar
- Sincronização recorrente com a fonte oficial: horário, status e placar dos
  jogos — é o único ponto de entrada de dado externo do sistema
- Reabertura automática do palpite quando o horário oficial do jogo muda
- Sigilo do palpite até o jogo terminar
- Lembrete de prazo apenas para quem ainda não palpitou
- Visão do admin de **quem** ainda não palpitou (sem ver o que foi palpitado)

## 5. Fora de escopo

- Cálculo de pontuação, ranking e desempate → épico _Pontuação e ranking_
- Placar corrigido retroativamente pela federação → épico _Pontuação e ranking_
- Dinheiro: entrada, premiação, confirmação de pagamento → **sem dinheiro
  nesta versão** (ver `docs/prd/premiacao-e-cobranca.md`)
- Criação do bolão, convite e remoção de participante → épico _Criação e convite_
- Comentários e zoeira dentro do app
- Palpite rápido copiando o favorito de cada jogo (sugestão da Fase 1)
- Participar de vários bolões ao mesmo tempo

## 6. Regras de domínio decididas

| Regra                          | Decisão                                                                                                                                                     | Status                              |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Prazo do palpite               | Fecha **no horário oficial de início de cada jogo, individualmente** (não por rodada). **A fonte do horário é sempre o servidor, nunca o relógio do device.** | decidido                            |
| Edição do palpite              | **Livre**, quantas vezes quiser, até o prazo daquele jogo fechar                                                                                             | decidido                            |
| Sigilo dos palpites            | **Ninguém vê o palpite de ninguém — o admin incluído — até o jogo terminar.** Nem no apito                                                                   | decidido                            |
| Jogo adiado                    | Prazo passa para o novo horário oficial e **o palpite reabre para todos, automaticamente**. Nunca por ação manual do admin                                   | decidido                            |
| Jogo cancelado / W.O.          | **Não existem no sistema: todo jogo não realizado é tratado como adiado** (decidido 03/08). Não há anulação — o jogo aguarda nova data e o palpite reabre quando ela chegar. W.O. real é resolvido pelo admin lançando o placar oficial à mão (`PR-10`) | decidido                            |
| Palpite não enviado            | Fica sem palpite e sem ponto naquele jogo, **sem penalidade adicional**                                                                                     | proposta a validar — Igor            |
| Entrada no meio do campeonato  | não se aplica — **não é possível entrar atrasado** (épico _Criação e convite_): a entrada fecha no início do primeiro jogo, então todo participante tem todos os jogos disponíveis | não se aplica                       |
| Pontuação                      | não se aplica — decidido no épico _Pontuação e ranking_                                                                                                     | não se aplica                       |
| Desempate                      | não se aplica — decidido no épico _Pontuação e ranking_                                                                                                     | não se aplica                       |
| Placar corrigido após apuração | não se aplica — decidido no épico _Pontuação e ranking_                                                                                                     | não se aplica                       |
| Dinheiro                       | **não se aplica — sem dinheiro nesta versão** (decisão de 03/08/2026, ver `premiacao-e-cobranca.md`)                                                          | não se aplica                       |

## 7. Fluxo principal

1. Abro o app e vejo os jogos com prazo aberto, cada um com quanto tempo
   falta para fechar.
2. Digito os placares dos jogos que quero, na sequência, sem sair da tela.
3. Vejo confirmação de que cada palpite foi salvo — sem precisar procurar.
4. Se eu estiver sem sinal, o que digitei fica guardado e é enviado sozinho
   quando a conexão volta; até lá eu vejo que ainda não foi enviado.
5. Voltando antes do apito, ajusto o palpite que quiser.
6. Perto de fechar, recebo um lembrete — só dos jogos em que ainda não
   palpitei.
7. No apito daquele jogo, meu palpite trava.
8. Quando o jogo termina, os palpites de todos ficam visíveis.

## 8. Requisitos não funcionais

No bolão isto é regra, não polimento — palpite é feito na fila do almoço,
no ônibus e no estádio.

- **Offline / conexão ruim:** palpite digitado nunca é perdido. Fica em
  rascunho local, com o estado "ainda não enviado" visível, e sincroniza
  sozinho. Rejeição por prazo vencido é resposta esperada, não erro.
- **Horário:** a decisão de "ainda dá para palpitar?" é do servidor. O
  relógio do celular pode ser alterado pelo usuário e não pode ser fonte
  de verdade em nenhum ponto.
- **Fuso:** horário exibido no fuso local do device, com o fuso indicado
  quando for decisivo para o prazo.
- **Push:** permissão negada não pode travar nada; sem push, a contagem
  de tempo na tela continua sendo o aviso.

## 9. Riscos e dependências

- **Fonte oficial de calendário e horário dos jogos.** Todo este épico
  depende dela, incluindo a reabertura automática por adiamento. Se a
  mudança de horário não chegar ao app, o palpite fecha na hora errada.
- **Horário confiável no servidor**, independente do device.
- **Adiamento em cascata:** jogo adiado para depois de rodadas seguintes
  reabre um palpite muito tempo depois, com o participante já sabendo
  muito mais. A decisão foi aceitar isso; vale medir se gera reclamação.
- **Sigilo é requisito de segurança, não de UI.** Esconder na tela não
  basta se o dado for entregue ao app antes do jogo terminar.

## 10. Perguntas abertas

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

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

- **Jogo cancelado ou W.O.: anula para todos** — ninguém pontua e o jogo sai
  do total da rodada. Fecha a pendência da seção 6. Detalhamento no épico
  _Pontuação e ranking_ (story `PR-8`).
- **Palpite não enviado: zero pontos, sem penalidade.** Confirmado.
- **Não é possível entrar atrasado** — a entrada fecha no início do primeiro
  jogo, o que eliminou a regra de "entrada no meio" deste épico.

- **Fonte de calendário e horário:** a gratuita — `football-data.org`, tier
  Free (€0, 10 req/min, Brasileirão Série A incluído). **Escolha provisória
  até o spike técnico**, porque o tier Free tem **placar atrasado** e ainda
  não foi verificado se ele expõe status de jogo adiado/cancelado. Se não
  expuser mudança de horário, PP-6 não funciona.
- **Métricas da seção 2:** aceitas como definição de sucesso. ⚠️ A meta de
  ver o ponto logo após o apito conflita com o placar atrasado do tier Free
  — resolver no spike.

## 11. Stories derivadas

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

- [ ] `PP-1` Palpitar nos jogos com prazo aberto, em sequência, com confirmação de salvo
- [ ] `PP-2` Editar palpite enquanto o prazo do jogo estiver aberto
- [ ] `PP-3` Contagem de tempo restante por jogo, baseada no horário do servidor
- [ ] `PP-4` Rascunho offline com envio automático ao recuperar conexão
- [ ] `PP-5` Bloqueio do palpite no horário oficial de início do jogo
- [ ] Job de sincronização com a fonte de dados (`PP-10`) — serve também
  `PR-1`, `PR-6` e `CC-1`
- [ ] `PP-6` Reabertura automática do palpite quando o horário oficial muda
- [ ] `PP-7` Sigilo do palpite até o jogo terminar, e liberação depois
- [ ] `PP-8` Lembrete de prazo apenas para quem não palpitou
- [ ] `PP-9` Visão do admin de quem ainda não palpitou, sem ver o palpite

---

## Bloqueios

**Nada aqui bloqueia o início das stories.** As duas regras em aberto —
jogo cancelado/W.O. e a confirmação de "palpite não enviado sem
penalidade" — não afetam nenhuma das nove stories listadas, porque ambas
são sobre **pontuação**, não sobre prazo ou registro do palpite. As sete
decisões estruturais deste épico (prazo por jogo, edição livre, sigilo até
o fim do jogo, reabertura automática, fonte de horário no servidor) estão
fechadas.
