Status: Approved · v2 · SPEC-DOMAIN-CHAMPIONSHIP-001
depends_on: SPEC-DOMAIN-MATCH-001, SPEC-DOMAIN-TEAM-001, SPEC-DOMAIN-PAYMENT-001
used_by: IS-MVP-01.4, IS-MVP-07.1, IS-MVP-07.4, IS-MVP-07.5
Campeonatos
Entidade independente para organizar competições, edições, regulamentos, inscrições, fases, partidas e disciplina.
Objetivo e limites
Esta especificação define o comportamento canônico do domínio Campeonatos no RaizFC. Ela deve ser consultada antes de alterar contratos, mocks, endpoints, telas, permissões ou Increment Specifications relacionados.
Incluído no MVP
- Rascunho gratuito e publicação paga por Pix simulado.
- Edições independentes.
- Regulamento em texto, regras estruturadas e PDF opcional.
- Convite, pedido ou ambos para inscrição.
- Pontos corridos, grupos+mata, mata direto, liga ida/volta e mata ida/volta.
- Fixtures automáticos sem datas ou manuais.
- Classificação, artilharia e disciplina.
Fora do MVP
- Sorteios transmitidos.
- Bilheteria.
- Premiação financeira.
- Integração com federações.
- Sistema completo de arbitragem.
Atores e responsabilidades
| Ator | Responsabilidade |
|---|---|
| Visitante | Consulta página, regulamento, tabela, classificação e artilharia. |
| Organizador | Cria rascunho, publica e gerencia edição. |
| Gestor de time | Solicita inscrição, envia atletas e contesta dados. |
| Jogador | Aparece em inscrições e stats conforme elegibilidade. |
| Operação | Modera publicação, pagamentos e disputas excepcionais. |
Conceitos canônicos
Championship
Marca/entidade duradoura.
Edition
Instância temporal com inscrições, fases e jogos.
Phase
Grupo, liga ou mata-mata dentro da edição.
Fixture
Confronto planejado; pode existir sem data.
Regulation
Texto e regras estruturadas bloqueáveis após marcos.
Eligibility Rule
Regra de participação de times e jogadores.
Invariantes
- Campeonato em draft não aparece na busca pública geral.
- Publicação exige pagamento confirmado e idempotente.
- Cada edição pertence a um campeonato.
- Formato e fases devem ser compatíveis.
- Classificação usa apenas partidas validadas.
- Alterações de regulamento após bloqueio exigem override auditado e aviso.
- Atleta não pode violar regra de exclusividade da edição.
- Campeonato não possui wallet nem sponsors no MVP.
Estados
| Estado | Significado | Visibilidade/efeito |
|---|---|---|
| draft | Rascunho privado | Configuração livre. |
| waiting_payment | Publicação solicitada | Pix pendente; permanece não público. |
| published | Publicado | Página e inscrições conforme janela. |
| registration_open | Inscrições abertas | Times podem entrar conforme modo. |
| in_progress | Competição em andamento | Regras críticas bloqueadas. |
| finished | Encerrado | Histórico e stats finais. |
| cancelled | Cancelado | Motivo público/administrativo. |
| suspended | Suspenso | Operação bloqueia ações. |
Transições permitidas
| Origem | Ação | Destino | Autoridade | Efeitos |
|---|---|---|---|---|
| — | create | draft | Usuário autenticado | Cria owner e edição opcional. |
| draft | request_publication | waiting_payment | Owner/financial | Gera Pix. |
| waiting_payment | payment_confirmed | published | Webhook/provider | Publica idempotentemente. |
| published | open_registration | registration_open | Gestor | Abre janela. |
| registration_open | close_registration | published/in_progress | Gestor/job | Bloqueia novas inscrições. |
| published/registration_open | start | in_progress | Gestor | Bloqueia formato/regra conforme política. |
| in_progress | finish | finished | Gestor | Finaliza após resultados. |
| any | cancel | cancelled | Owner/operação | Registra motivo. |
Permissões
| Permission key | Quem recebe por padrão | Ação protegida | Auditoria |
|---|---|---|---|
| championship.editProfile | Admin | Identidade e descrição | Sim |
| championship.manageEdition | Competition/Admin | Edições, formato e fases | Sim |
| championship.manageRegulation | Competition/Admin | Regulamento | Sim |
| championship.manageRegistrations | Registrations/Admin | Convites/pedidos/atletas | Sim |
| championship.manageFixtures | Competition/Admin | Confrontos e datas | Sim |
| championship.manageDiscipline | Discipline/Admin | Cartões, suspensões e overrides | Sim |
| championship.publish | Financial/Primary owner | Iniciar pagamento de publicação | Sim |
| championship.manageManagers | Admin/Owner | Acessos | Sim |
Fluxos funcionais
Criação e publicação
- Organizador cria campeonato draft.
- Define identidade, distrito, edição, formato e regulamento mínimo.
- Solicita publicação com Idempotency-Key.
- Pix simulado é criado por 30 minutos.
- Confirmação publica; expiração mantém draft.
Inscrição de time
- Edição abre janela e modo.
- Organizador convida ou time solicita.
- Parte oposta aprova quando necessário.
- Time escolhe categoria e envia lista preliminar conforme regras.
- Inscrição vira approved e aparece publicamente.
Geração de fixtures
- Gestor define participantes e formato.
- Sistema valida número mínimo e parâmetros.
- Gera confrontos sem data ou com regras básicas.
- Gestor revisa e confirma.
- Alterações após início exigem auditoria.
Disciplina
- Eventos validados alimentam cartões.
- Regra configurada calcula pendurados e suspensões.
- Escalação verifica elegibilidade.
- Override exige motivo e fica visível conforme política.
Contestação de dados
- Time contesta resultado, inscrição ou disciplina dentro do prazo.
- Organizador responde ou retifica.
- Se persistir, disputa formal registra evidências e decisão.
Casos-limite e erros
| Cenário | Comportamento esperado | Código/estado |
|---|---|---|
| Pix expira | Voltar/continuar draft sem publicar | PAYMENT_EXPIRED |
| Formato incompatível com participantes | Rejeitar geração | INVALID_CHAMPIONSHIP_FORMAT |
| Regulamento bloqueado | Exigir override e notificação | REGULATION_LOCKED |
| Atleta em outro time proibido | Bloquear inscrição/escalação | PLAYER_NOT_ELIGIBLE |
| Fixture duplicado | Rejeitar ou substituir com confirmação | DUPLICATE_FIXTURE |
| Classificação com partida contestada | Ignorar provisoriamente | STANDINGS_PENDING_MATCH |
Privacidade e exposição pública
- Regulamento publicado é público.
- Listas de atletas respeitam perfil/privacidade, mas elegibilidade pode exibir nome esportivo.
- Pagamentos e dados de gestão são privados.
- Evidências de disputa são restritas.
Notificações e auditoria
- Convites e pedidos de inscrição.
- Abertura/fechamento de janela.
- Pagamento e publicação.
- Alteração de regulamento.
- Fixtures/data.
- Cartões, pendurados e suspensão.
- Contestações e decisões.
API relacionada
| Método | Rota | Acesso | Finalidade |
|---|---|---|---|
| POST | /api/v1/championships | Autenticado | Criar draft |
| GET | /api/v1/championships/:slug | Público | Página |
| PATCH | /api/v1/championships/:id | Gestão | Editar |
| POST | /api/v1/championships/:id/publish | championship.publish | Criar Pix |
| POST | /api/v1/championships/:id/editions | championship.manageEdition | Criar edição |
| PUT | /api/v1/championships/:id/editions/:editionId/regulation | championship.manageRegulation | Regulamento |
| POST | /api/v1/championships/:id/editions/:editionId/registrations | Gestão/time | Inscrição |
| POST | /api/v1/championships/:id/editions/:editionId/fixtures/generate | championship.manageFixtures | Gerar |
| GET | /api/v1/championships/:id/editions/:editionId/standings | Público | Classificação |
| GET | /api/v1/championships/:id/editions/:editionId/top-scorers | Público | Artilharia |
Contratos compartilhados
- ChampionshipEntity
- PublicChampionshipDto
- ChampionshipEditionDto
- ChampionshipFormat
- ChampionshipPhaseDto
- RegulationDto
- RegistrationDto
- AthleteEligibilityRuleDto
- FixtureDto
- StandingsDto
- DisciplineRuleDto
Requisitos de UX
- Página pública apresenta edição ativa, regulamento, participantes, tabela, classificação, jogos, artilharia e disciplina.
- Painel usa sequência guiada: identidade → edição → regulamento → inscrições → formato/fases → fixtures → jogos → disciplina.
- Publish explica preço, prazo do Pix e consequência da expiração.
- Configuração avançada aparece progressivamente.
Comportamento dos mocks
- Campeonato draft, waiting_payment, published, registration_open, in_progress e finished.
- Pix fake pago/expirado.
- Geração determinística de fixtures.
- Standings recalculadas somente com validated.
- Elegibilidade e disciplina com erros previsíveis.
Critérios de aceite
- Draft gratuito e privado.
- Publicação somente após pagamento confirmado.
- Formatos MVP funcionam.
- Fixtures podem nascer sem datas.
- Standings ignoram partidas contestadas.
- Regulamento bloqueado exige override.
Testes obrigatórios
- Publicação idempotente e expiração.
- Inscrição por modos.
- Elegibilidade de atleta.
- Geração de formatos.
- Classificação e desempate.
- Disciplina e override.
- Lock de regulamento.
Pós-MVP
- Bilheteria e inscrições pagas.
- Premiação.
- Arbitragem e escalas.
- Sorteios públicos.
- Sponsors do campeonato.
Decisões registradas
- Campeonato é entidade independente.
- Publicação é paga por Pix separado e não usa wallet.
- Sem sponsors/wallet no MVP.
- Edições concentram operação competitiva.
Machine summary
spec: SPEC-DOMAIN-CHAMPIONSHIP-001
domain: Campeonatos
must_preserve:
- Campeonato em draft não aparece na busca pública geral.
- Publicação exige pagamento confirmado e idempotente.
- Cada edição pertence a um campeonato.
- Formato e fases devem ser compatíveis.
- Classificação usa apenas partidas validadas.
- Alterações de regulamento após bloqueio exigem override auditado e aviso.
- Atleta não pode violar regra de exclusividade da edição.
- Campeonato não possui wallet nem sponsors no MVP.
touches:
- contracts
- mocks
- api
- frontend
- backend
- tests
- documentation