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

depends_on: SPEC-DOMAIN-WALLET-001, SPEC-DOMAIN-PAYMENT-001

used_by: IS-MVP-10.1, IS-MVP-10.2

Patrocínios

Compra temporária de visibilidade em páginas públicas de time ou torcida, com slots limitados e moderação.

Objetivo e limites

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

Incluído no MVP

• Somente team e torcida.
• Até três slots ativos ou reservados.
• Pacotes 7, 30 e 90 dias.
• Pix simulado com reserva de slot por 30 min.
• Split 80/20.
• Exibição em grade, ordem randômica por sessão/request.

Fora do MVP

• Métricas de clique.
• Fila/agendamento.
• Auction de espaço.
• Patrocínio em cards.
• Sponsors de jogador/campeonato.

Atores e responsabilidades

Ator	Responsabilidade
Patrocinador	Informa marca, imagem, contato e paga.
Gestor financeiro	Inicia contratação e acompanha status.
Visitante	Visualiza sponsor ativo.
Operação	Suspende/remove conteúdo impróprio.

Conceitos canônicos

Sponsorship

Contrato temporal pago.

Sponsor

Marca/dados exibidos.

Slot Reservation

Reserva durante Pix pendente.

Display Window

Intervalo activeFrom-activeUntil.

Invariantes

• Máximo de três patrocínios ativos ou pending_payment por entidade.
• Slot pending expira com o Pix.
• Imagem/logo é obrigatória.
• Pagamento confirmado ativa exatamente uma vez.
• Gestor não pode remover ou pausar sponsor ativo no MVP; operação pode moderar.
• Patrocínio não altera busca, ranking ou feed orgânico.
• Entidade suspensa não inicia novos sponsors.

Estados

Estado	Significado	Visibilidade/efeito
pending_payment	Slot reservado e Pix aberto	Não público.
active	Exibição ativa	Público.
expired	Janela encerrada	Histórico privado.
suspended	Ocultado temporariamente	Operação.
removed	Removido por decisão	Não público; auditado.
cancelled	Pagamento cancelado/expirado	Libera slot.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	create_checkout	pending_payment	Gestor financeiro	Reserva slot.
pending_payment	payment_confirmed	active	Provider/webhook	Crédito e janela.
pending_payment	expire_payment	cancelled	Job/provider	Libera slot.
active	expire_window	expired	Job	Remove da página.
active	suspend	suspended	Operação	Oculta.
active/suspended	remove	removed	Operação	Decisão final.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
sponsor.create	Financial/Admin/Owner	Contratar	Sim
sponsor.editVisual	Financial/Admin/Owner	Editar visual/contato ativo	Sim
sponsor.viewHistory	Financial/Admin/Owner	Histórico	Não
sponsor.moderate	Operação	Suspender/remover	Sim

Fluxos funcionais

Contratação

1. Gestor escolhe pacote e entidade.
2. Sistema verifica slot.
3. Informa marca, imagem, texto curto e contato.
4. Valida conteúdo e cria Pix por 30 minutos.
5. Confirmação ativa e credita 80% na wallet.

Exibição

1. Página pública busca ativos dentro da janela.
2. Retorna até três itens.
3. Ordem é randômica sem favorecer pagamento maior.
4. Clique abre contato/link externo com segurança.

Moderação

1. Usuário denuncia sponsor.
2. Operação analisa.
3. Pode suspender imediatamente em caso grave.
4. Decisão registra motivo e não altera automaticamente o ledger já efetivado sem fluxo financeiro separado.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Três slots ocupados	Bloquear checkout	SPONSOR_LIMIT_REACHED
Imagem ausente/inválida	Rejeitar	SPONSOR_IMAGE_REQUIRED
Pix expira	Cancelar e liberar slot	PAYMENT_EXPIRED
Confirmação duplicada	Retornar sponsorship existente	IDEMPOTENCY_REPLAY
Entidade deixa de ser approved/active	Suspender exibição conforme política	ENTITY_NOT_ELIGIBLE

Privacidade e exposição pública

• Dados de contato publicados são os fornecidos para campanha.
• Dados de pagamento não são públicos.
• Denúncias e decisões são privadas.

Notificações e auditoria

• Checkout criado, pago, expirado.
• Sponsor prestes a expirar.
• Suspensão/remoção.
• Crédito recebido na wallet.

API relacionada

Método	Rota	Acesso	Finalidade
POST	/api/v1/sponsorships/checkout	sponsor.create	Criar checkout
GET	/api/v1/sponsorships/:id	Gestão	Detalhe
PATCH	/api/v1/sponsorships/:id/visual	sponsor.editVisual	Editar
GET	/api/v1/entities/:type/:id/sponsors	Público	Ativos
GET	/api/v1/entities/:type/:id/sponsorships	sponsor.viewHistory	Histórico

Contratos compartilhados

• SponsorDto
• SponsorshipEntity
• SponsorshipPackage
• SponsorshipStatus
• CreateSponsorshipCheckoutRequest/Response
• UpdateSponsorVisualRequest

Requisitos de UX

• Página pública mostra grade discreta, não carrossel agressivo.
• Checkout explica prazo, período, taxa e impossibilidade de pausa pelo gestor.
• Lotação mostra mensagem clara sem criar fila.
• Identidade visual não pode parecer anúncio de bet por padrão.

Comportamento dos mocks

• Slots 0/1/2/3 ocupados.
• Pix paid/expired.
• Active/expired/suspended.
• Ordem randômica determinística por seed de cenário.

Critérios de aceite

• Limite inclui pending_payment.
• Slot libera ao expirar.
• Split 80/20.
• Ativo aparece apenas na janela.
• Sem boost de ranking/busca.

Testes obrigatórios

• Concorrência de último slot.
• Expiração.
• Idempotência.
• Moderação.
• Janela temporal.
• Split e wallet.

Pós-MVP

• Métricas.
• Agendamento.
• Cards patrocinados moderados.
• Pacotes customizados.

Decisões registradas

• Patrocínio apenas em time e torcida.
• Máximo três.
• Sem fila.
• Gestor não pausa/remove ativo no MVP.
• Patrocínio em card fica pós-MVP.

Machine summary

spec: SPEC-DOMAIN-SPONSOR-001
domain: Patrocínios
must_preserve:
  - Máximo de três patrocínios ativos ou pending_payment por entidade.
  - Slot pending expira com o Pix.
  - Imagem/logo é obrigatória.
  - Pagamento confirmado ativa exatamente uma vez.
  - Gestor não pode remover ou pausar sponsor ativo no MVP; operação pode moderar.
  - Patrocínio não altera busca, ranking ou feed orgânico.
  - Entidade suspensa não inicia novos sponsors.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation