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

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

used_by: IS-MVP-01.3, IS-MVP-06.1, IS-MVP-06.3, IS-MVP-06.5

Partidas e súmulas

Registro público de confrontos, escalações, eventos, resultado, validação, contestação e estatísticas.

Objetivo e limites

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

Incluído no MVP

• Partidas com ou sem campeonato.
• Data definida ou pendente.
• Campo cadastrado ou local livre.
• Resultado informado, validado, contestado e retificado.
• Súmula com titulares, banco, entradas, tempo, gols, assistências, cartões e substituições.
• Convidados cadastrados ou não.
• Auto-validação em amistosos após prazo.

Fora do MVP

• Tempo real confiável.
• Streaming.
• Arbitragem digital avançada.
• VAR comunitário.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Consulta partida, placar, escalações públicas e histórico.
Gestor de time	Cria partidas, informa resultado, escala elenco e valida/contesta.
Gestor de campeonato	Cria e governa partidas da competição.
Jogador	Aparece em escalações e histórico conforme confirmação/privacidade.
Operação	Modera disputas fora de campeonato quando necessário.

Conceitos canônicos

Match

Confronto esportivo entre pelo menos dois times.

Match Report

Súmula estruturada.

Validation

Confirmação do resultado pela contraparte ou autoridade do campeonato.

Retification

Correção auditada após validação.

Match Event

Gol, assistência, cartão, substituição ou evento administrativo.

Invariantes

• Partida possui ao menos dois participantes distintos.
• Partida não pode terminar antes de começar.
• Resultado validado só muda por retificação auditada.
• Partida contestada não consolida ranking ou stats definitivas.
• Partida de campeonato respeita autoridade e regras da edição.
• Convidado não confirmado pode constar na partida sem criar histórico público pessoal.
• Eventos que afetam stats devem estar associados a participante elegível.
• Campo cadastrado e local livre são alternativas; ao menos um contexto de local deve existir quando a data for confirmada.

Estados

Estado	Significado	Visibilidade/efeito
draft	Rascunho	Somente gestão.
date_pending	Confronto sem data	Público opcional conforme campeonato.
scheduled	Agendada	Página pública completa.
in_progress	Em andamento	Atualizações controladas.
waiting_result	Encerrada sem placar informado	Gestores acionados.
result_reported	Placar informado	Aguardando validação.
waiting_validation	Aguardando contraparte/autoridade	Prazo ativo.
contested	Resultado contestado	Stats/ranking pendentes.
validated	Resultado confirmado	Stats e ranking consolidados.
finished	Encerrada administrativamente	Histórico final.
cancelled	Cancelada	Sem stats esportivas.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
draft/date_pending	schedule	scheduled	Gestor autorizado	Define data/local e notifica.
scheduled	start	in_progress	Gestor/autoridade	Registra início.
scheduled/in_progress	finish_without_result	waiting_result	Gestor/autoridade	Solicita placar.
waiting_result/in_progress	report_result	waiting_validation	Gestor/autoridade	Salva placar e súmula.
waiting_validation	validate	validated	Oponente/autoridade	Consolida stats/ranking.
waiting_validation	contest	contested	Oponente/time	Abre disputa com motivo/evidência.
waiting_validation	auto_validate	validated	Job	Somente tipos elegíveis após prazo.
contested	resolve	validated/cancelled	Autoridade/operação	Decide e consolida ou anula.
validated	request_retification	contested	Autoridade	Reabre de forma auditada.
any non-final	cancel	cancelled	Autoridade	Registra motivo.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
match.create	Sports/Admin/Championship manager	Criar partida	Sim
match.editSchedule	Sports/Admin/Championship manager	Data/local	Sim
match.manageLineup	Squad/Sports	Escalação	Sim
match.reportResult	Sports/Admin/Championship manager	Resultado/súmula	Sim
match.validateResult	Gestor autorizado da contraparte	Validar	Sim
match.contestResult	Gestor autorizado	Contestar	Sim
match.retifyResult	Championship authority/operação	Retificar validado	Sim

Fluxos funcionais

Criação de amistoso

1. Gestor escolhe dois times e tipo de partida.
2. Informa categoria, data opcional, campo ou local livre.
3. Contraparte recebe convite/aviso conforme política.
4. Partida fica scheduled ou date_pending.

Informação de resultado

1. Gestor autorizado informa placar e súmula.
2. Sistema valida participantes, gols e cartões.
3. Status vira waiting_validation.
4. Oponente recebe notificação e prazo.

Validação e auto-validação

1. Oponente revisa placar e súmula.
2. Pode validar ou contestar com motivo/evidências.
3. Se não agir e a partida for elegível, job valida após 72h.
4. Stats e rankings são recalculados somente após validated.

Contestação

1. Contestante descreve divergência e anexa evidências.
2. Autoridade recebe caso.
3. Outra parte pode responder.
4. Autoridade corrige, mantém ou anula.
5. Todas as alterações ficam auditadas.

Súmula e convidados

1. Gestor relaciona jogadores ativos e convidados.
2. Define titulares/banco e eventos.
3. Convidados cadastrados recebem confirmação se necessário.
4. Participação não confirmada conta para o time e a partida, não para histórico pessoal público.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Mesmo time nos dois lados	Rejeitar	MATCH_TEAMS_MUST_DIFFER
Placar incompatível com eventos	Bloquear ou exigir justificativa administrativa	MATCH_REPORT_INCONSISTENT
Resultado informado duas vezes	Usar idempotência ou conflito	MATCH_RESULT_ALREADY_REPORTED
Validação por gestor do mesmo time que informou	Bloquear quando exigida contraparte	MATCH_VALIDATOR_NOT_ALLOWED
Prazo de auto-validação durante contestação	Não validar	MATCH_CONTESTED
Jogador suspenso em campeonato	Bloquear ou exigir override auditado conforme regras	PLAYER_INELIGIBLE
Partida cancelada recebe evento	Rejeitar	MATCH_CANCELLED

Privacidade e exposição pública

• Página pública exibe participantes, contexto, placar e eventos permitidos.
• Escalação pode ocultar convidado não confirmado conforme política.
• Evidências de contestação são privadas para partes e operação.
• Dados pessoais de convidado nunca aparecem.

Notificações e auditoria

• Criação/alteração/cancelamento.
• Prazo de resultado e validação.
• Contestação, resposta e resolução.
• Convite de convidado para confirmar participação.
• Retificação que altera stats.
• Todas as mudanças sensíveis entram em audit log.

API relacionada

Método	Rota	Acesso	Finalidade
POST	/api/v1/matches	Gestão	Criar
GET	/api/v1/matches/:id	Público	Página pública
PATCH	/api/v1/matches/:id	Gestão	Editar agenda/contexto
POST	/api/v1/matches/:id/result	match.reportResult	Informar resultado
POST	/api/v1/matches/:id/validate	match.validateResult	Validar
POST	/api/v1/matches/:id/contest	match.contestResult	Contestar
POST	/api/v1/matches/:id/retification	match.retifyResult	Retificar
PUT	/api/v1/matches/:id/report	match.manageLineup	Salvar súmula
POST	/api/v1/matches/:id/events	match.manageLineup	Adicionar evento
POST	/api/v1/matches/:id/guest-players	match.manageLineup	Adicionar convidado

Contratos compartilhados

• MatchEntity
• PublicMatchDto
• MatchManagementDto
• MatchStatus
• MatchType
• MatchParticipantDto
• MatchReportDto
• MatchPlayerDto
• MatchEventDto
• ReportMatchResultRequest
• ContestMatchRequest
• RetificationRequest

Requisitos de UX

• Página pública com escudos, placar/status, data, campo, competição, escalações, timeline, histórico do confronto e galeria.
• Gestão usa etapas claras: contexto, elenco, eventos, placar, revisão e envio.
• Status waiting_validation e contested explicam o que falta.
• Ações de compartilhar e gerar card ficam próximas ao placar.
• Tela não simula tempo real no MVP.

Comportamento dos mocks

• Partidas em todos os estados.
• Relatórios consistentes e inconsistentes.
• Auto-validação simulável por relógio controlado.
• Mutations alteram stats apenas após validate.
• Contestação com evidências fake e resolução.

Critérios de aceite

• Resultado não consolida antes de validação.
• Auto-validação só ocorre em partidas elegíveis e sem contestação.
• Retificação de validado é auditada.
• Súmula suporta titulares, banco, eventos e convidados.
• Página pública funciona sem login.

Testes obrigatórios

• State machine completa.
• Permissões por parte.
• Consistência placar/eventos.
• Auto-validação 72h.
• Contestação e resolução.
• Retificação e recálculo.
• Convidados e privacidade.
• Idempotência de resultado.

Pós-MVP

• Atualização ao vivo.
• Arbitragem digital.
• Streaming e placar externo.
• Integração com wearables.

Decisões registradas

• Partida pública é entidade central de registro.
• Amistosos possuem auto-validação sugerida de 72h.
• Campeonato define autoridade de suas partidas.
• Sem evidência suficiente, disputa pode anular o resultado.

Machine summary

spec: SPEC-DOMAIN-MATCH-001
domain: Partidas e súmulas
must_preserve:
  - Partida possui ao menos dois participantes distintos.
  - Partida não pode terminar antes de começar.
  - Resultado validado só muda por retificação auditada.
  - Partida contestada não consolida ranking ou stats definitivas.
  - Partida de campeonato respeita autoridade e regras da edição.
  - Convidado não confirmado pode constar na partida sem criar histórico público pessoal.
  - Eventos que afetam stats devem estar associados a participante elegível.
  - Campo cadastrado e local livre são alternativas; ao menos um contexto de local deve existir quando a data for confirmada.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation