📋 Documentação

Personas

Jogador — usuário cadastrado que paga ingresso (PIX), joga as partidas e recebe premiação (PIX).
(Admin é fora deste backlog — painel administrativo já existe à parte.)

Convenções

IDs locais (E# épico, E#-H# história) só para referência neste doc — o Jira gera os dele.
Estimativa em story points (Fibonacci) é sugestão — refinar com o time.
Toda história assume o padrão de resposta da API e mensagens em PT-BR.

Definition of Ready (resumo)

Critérios de aceitação claros · endpoints/eventos mapeados · design/fluxo definido · sem dependência bloqueante aberta.

Definition of Done (resumo)

Critérios de aceitação atendidos · responsivo/PWA · estados de erro/carregamento tratados · testado em dispositivo real · texto em PT-BR · telemetria básica (se aplicável).

🟦 E1 — Autenticação e Conta

Objetivo: permitir que o jogador crie conta, entre e recupere acesso com segurança.

E1-H1 — Cadastro 3

Como visitante, quero criar uma conta com nome, e-mail e senha, para poder jogar.

Critérios de aceitação:

campos nome, e-mail, senha; validação de senha mín. 8 caracteres.
e-mail duplicado mostra erro amigável (não cria conta).
ao concluir, o usuário já entra logado (recebe token) e vai para a Home.
erros de validação exibidos por campo.

Técnico: POST /auth/register.

E1-H2 — Login 2

Como jogador, quero entrar com e-mail e senha, para acessar minha conta.

Critérios de aceitação:

credenciais inválidas → mensagem genérica (sem revelar se o e-mail existe).
conta bloqueada → mensagem de conta suspensa, sem acesso.
token persistido com segurança; reabrir o app mantém a sessão.

Técnico: POST /auth/login, bootstrap com GET /auth/me.

E1-H3 — Recuperação de senha 3

Como jogador que esqueceu a senha, quero solicitar a recuperação por e-mail, para voltar a acessar.

Critérios de aceitação:

informo o e-mail e vejo sempre a mesma mensagem de sucesso (anti-enumeração).
recebo e-mail com link; o link abre a página web de redefinição (fora do PWA).
após redefinir, consigo entrar com a nova senha.

Técnico: POST /auth/send-recovery-email (redefinição é página web do backend).

E1-H4 — Logout 1

Como jogador, quero sair da conta, para proteger meu acesso no dispositivo.

Critérios de aceitação:

logout revoga o token no servidor e volta para a tela de login.

Técnico: POST /auth/logout.

🟦 E2 — Home / Lobby ("Jogar")

Objetivo: ponto de partida com chamada para jogar e o pulso da plataforma ao vivo.

E2-H1 — Ver a Home com info da rodada 3

Como jogador, quero ver o valor do ingresso, o prêmio estimado e o tamanho da partida, para decidir jogar.

Critérios de aceitação:

exibe ingresso (R$), prêmio estimado (% do pote) e jogadores por partida.
botão "Jogar agora" em destaque.

Técnico: GET /home (ticket_price em reais, prize_percentage, players_per_game).

E2-H2 — Pulso ao vivo (social proof) 2

Como jogador, quero ver quantos estão na fila e quantas salas ativas, para sentir o movimento e me animar a entrar.

Critérios de aceitação:

mostra "N jogadores na fila" e "M salas ativas agora".
atualiza ao focar/abrir a Home.

Técnico: GET /home (queue_size, active_games).

E2-H3 — Retomar fluxo em andamento 3

Como jogador que já entrou numa fila/partida, quero voltar direto ao ponto onde parei, para não perder o ingresso/partida.

Critérios de aceitação:

se há ticket ativo (aguardando pagamento, na fila ou em partida), a Home leva ao passo correto.

Técnico: GET /home (active_ticket), GET /matchmaking/status.

E2-H4 — Aviso de prêmio pendente 2

Como jogador que venceu mas não cadastrou PIX, quero ser avisado na Home, para cadastrar e receber antes de perder o prêmio.

Critérios de aceitação:

se há prêmio "Aguardando PIX" e sem chave cadastrada, exibe banner com valor e CTA para cadastrar PIX.
o banner some após o cadastro da chave.

Técnico: GET /home (pending_prize, has_bank_account).

🟦 E3 — Entrada na partida e Pagamento PIX

Objetivo: entrar na fila pagando o ingresso via PIX, com confirmação confiável.

E3-H1 — Entrar e gerar cobrança 3

Como jogador, quero tocar em "Jogar" e receber a cobrança PIX do ingresso, para pagar e disputar.

Critérios de aceitação:

"Jogar" cria a reserva e exibe QR Code + copia-e-cola e o valor.
mostra contador de expiração da cobrança.
se já tenho ticket ativo/partida em andamento, sou levado ao fluxo atual (sem duplicar).

Técnico: POST /matchmaking/join.

E3-H2 — Confirmar pagamento 3

Como jogador, quero que o app reconheça meu pagamento automaticamente, para entrar na fila sem ação manual.

Critérios de aceitação:

o app acompanha o status e, quando pago, avança para a fila.
a entrada só é validada após a confirmação (não confia em "paguei").

Técnico: GET /payments/{payment}/status (confirmação real via webhook do gateway).

E3-H3 — Sair da fila / reembolso 3

Como jogador, quero poder desistir antes de a partida formar, para não ficar preso — e ser reembolsado se já paguei.

Critérios de aceitação:

posso sair enquanto aguardo; volto à Home.
se a fila não encher no tempo limite, o ingresso expira e é reembolsado.
se eu pagar após sair, o valor é reembolsado automaticamente.

Técnico: DELETE /matchmaking/leave; reembolso é automático no backend.

E3-H4 — Aguardar a sala encher 2

Como jogador pago, quero ver que estou na fila aguardando jogadores, para saber que vai começar.

Critérios de aceitação:

tela "procurando jogadores…"; quando enche (até 10), a partida inicia automaticamente.

Técnico: GET /matchmaking/status; transição por evento da partida.

🟦 E4 — Partida ao vivo (tempo real)

Objetivo: jogar os 60 segundos julgando afirmações "Verdadeiro/Falso", com cronômetro e ranking ao vivo.

E4-H1 — Conectar ao canal da partida 5

Como jogador, quero conectar ao tempo real da minha partida, para ver cronômetro, placar e ranking ao vivo.

Critérios de aceitação:

assina o canal privado da partida autenticando com meu token.
ao reconectar, recupero o estado (questão atual + placar).

Técnico: POST /broadcasting/auth, canal private-game.{gameId}; eventos GameStarted, ScoreUpdated, RankingUpdated, GameEnded. (Cronômetro derivado de ends_at; não há tick periódico.)

E4-H2 — Cronômetro sincronizado 2

Como jogador, quero um cronômetro de 60s igual para todos, para uma disputa justa.

Critérios de aceitação:

o tempo é derivado do servidor (ends_at), não do relógio local.
ao zerar, não consigo mais responder.

E4-H3 — Responder afirmações 5

Como jogador, quero julgar afirmações como "Verdadeiro/Falso" e receber a próxima, para pontuar no meu ritmo.

Critérios de aceitação:

vejo o enunciado da afirmação (ex.: "De acordo com a Bíblia, o primeiro homem foi Adão.") e dois botões Verdadeiro/Falso.
ao responder, recebo feedback e a próxima questão (ou "fim").
todas as partidas usam as mesmas afirmações na mesma ordem; avanço é individual.
o tempo de resposta é medido no servidor (não enviado pelo app).
resposta após o fim do tempo é rejeitada.

Técnico: GET /games/{game}/current-question, POST /games/{game}/answers.

E4-H4 — Placar e ranking ao vivo 3

Como jogador, quero ver pontuação e classificação parcial em tempo real, para acompanhar a disputa.

Critérios de aceitação:

placar/ranking atualizam ao longo da partida.

Técnico: eventos ScoreUpdated, RankingUpdated.

🟦 E5 — Resultado e Transparência

Objetivo: mostrar o desfecho da partida com transparência total.

E5-H1 — Tela de resultado 3

Como jogador, quero ver o resultado final ao encerrar, para saber se venci e quanto.

Critérios de aceitação:

exibe vencedor(es), classificação final, acertos e tempo de cada um.
em empate, mostra os vencedores e o prêmio dividido.
CTAs "Jogar de novo" e "Ver histórico".

Técnico: GET /games/{game}/result; evento GameEnded.

E5-H2 — Transparência da premiação 2

Como vencedor, quero ver o status da transferência PIX e um identificador da transação, para confiar no pagamento.

Critérios de aceitação:

exibe valor, status (Aguardando PIX/Processando/Pago/Cancelado) e id mascarado da transação. (A chave PIX não é exposta no resultado — privacidade; fica no Perfil.)

Técnico: dados em GET /games/{game}/result.

🟦 E6 — Histórico e Estatísticas

Objetivo: o jogador acompanha suas partidas e desempenho (sem telas separadas de premiações/pagamentos).

E6-H1 — Estatísticas do jogador 3

Como jogador, quero ver minhas partidas jogadas, vitórias e winrate, para acompanhar meu desempenho.

Critérios de aceitação:

cabeçalho com partidas · vitórias · winrate (e total ganho).

Técnico: GET /me/stats.

E6-H2 — Lista de partidas 3

Como jogador, quero ver a lista das partidas que joguei, para revisitar resultados.

Critérios de aceitação:

lista paginada, por padrão todas; cada item leva ao detalhe.
filtro "Vencidas".

Técnico: GET /games, GET /games?won=1.

E6-H3 — Detalhe da partida 3

Como jogador, quero abrir uma partida e ver tudo dela, para conferir resultado e premiação/pagamento.

Critérios de aceitação:

classificação, minha posição/acertos, e — se venci — o prêmio (valor, status PIX, id mascarado).
mostra também o status do ingresso pago.

Técnico: GET /games/{game}, GET /games/{game}/result.

🟦 E7 — Premiação e Dados Bancários (PIX)

Objetivo: garantir que o jogador receba o prêmio cadastrando sua chave PIX.

E7-H1 — Cadastrar/atualizar chave PIX 3

Como jogador, quero cadastrar minha chave PIX e dados do titular, para receber premiações.

Critérios de aceitação:

campos chave, tipo (CPF/e-mail/telefone/aleatória), titular, documento.
ao salvar, prêmios "Aguardando PIX" são liberados automaticamente para pagamento.

Técnico: GET /bank-accounts, PUT /bank-accounts.

E7-H2 — Prazo de reivindicação 2

Como jogador, quero ser alertado de que prêmios sem PIX expiram, para não perder o dinheiro.

Critérios de aceitação:

aviso de que o prêmio é cancelado se a chave não for cadastrada no prazo (30 dias).
reforço do aviso na Home e no detalhe da partida vencida.

🟦 E8 — Perfil e Institucional

Objetivo: gerenciar conta e acessar informações institucionais.

E8-H1 — Editar conta 2

Como jogador, quero editar meu nome e e-mail, para manter meus dados atualizados.

Critérios de aceitação:

GET/edição do perfil; e-mail único validado.

Técnico: GET /auth/me, PUT /me.

E8-H2 — Trocar senha 2

Como jogador logado, quero trocar minha senha informando a atual, para manter a conta segura.

Critérios de aceitação:

exige current_password correta + nova senha (mín. 8).

Técnico: PUT /me.

E8-H3 — Termos e Privacidade 1

Como jogador, quero ler os termos de uso e a política de privacidade, para entender as regras.

Critérios de aceitação:

abre o conteúdo HTML servido pelo backend.

Técnico: GET /pagina/terms-of-use, GET /pagina/privacy-policy.

E8-H4 — Sobre o app 1

Como jogador, quero ver a versão e os créditos, para identificar o app.

Critérios de aceitação:

tela "Sobre" com versão + "Desenvolvido com ♥ por Phurshell.com".

🟦 E9 — PWA, Estados e Resiliência (transversal)

Objetivo: experiência de app instalável, resiliente e segura.

E9-H1 — App instalável (PWA) 3

Como jogador, quero instalar o app na tela inicial, para acesso rápido.

Critérios de aceitação:

manifest (nome, ícones, tema), splash; "adicionar à tela inicial".

E9-H2 — Estados de conexão e erro 3

Como jogador, quero mensagens claras quando estou sem conexão ou algo falha, para saber o que fazer.

Critérios de aceitação:

tela/aviso de "sem conexão"; erros da API em PT-BR amigável.
reconexão automática ao WebSocket retoma a partida.

E9-H3 — Conta bloqueada 2

Como sistema, quero impedir acesso de conta bloqueada, para conter fraude.

Critérios de aceitação:

ao detectar bloqueio (401/403), o app mostra tela de conta suspensa e encerra a sessão.

📌 Notas para o PO

Dependências externas: confirmação de pagamento e payout dependem do gateway PIX (webhooks). O app reage ao status; não há "marcar como pago" manual.
Regras de negócio centrais (servidor): ingresso e prêmio configuráveis; vencedor = mais acertos, desempate por tempo; empate divide; partida de 60s com N questões; tudo apurado server-side.
Fora do escopo (PWA): push notifications, publicação em lojas, e qualquer módulo não previsto → alteração de escopo.