Status: Approved · v2.2 · SPEC-DOMAIN-FEED-001

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

used_by: IS-MVP-11.1, IS-MVP-11.2, IS-MVP-11.3, IS-POST-12.1

Feed e publicações

Feed inicial controlado por entidades e plataforma, sem posts livres de usuários comuns.

Objetivo e limites

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

Incluído no MVP

• Feed na aba Início.
• Posts oficiais de entidades.
• Sugestões geradas pela plataforma e aprovadas por gestor.
• Cards de plataforma inseridos com moderação.
• Ocultar post, silenciar entidade, deixar de seguir/torcer.
• Compartilhamento externo.

Fora do MVP

• Posts livres de usuários.
• Comentários.
• Curtidas e reações.
• Salvar posts.
• Compartilhamento interno.
• Recomendação por IA.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Pode ver posts em páginas públicas, não o feed personalizado.
Usuário	Recebe feed por follows, cheers e território; oculta e silencia.
Gestor de mídia	Cria posts oficiais e aprova sugestões.
Plataforma	Gera cards de ranking, jogos e destaques.
Operação	Remove conteúdo denunciado.

Conceitos canônicos

FeedPost

Conteúdo exibível no feed.

Source

entity_official, platform_generated ou platform_suggested.

Suggested Post

Rascunho preparado pela plataforma que exige aprovação.

Feed Reason

Motivo explicável pelo qual o usuário recebeu o conteúdo.

Mute

Supressão temporária ou indefinida de uma entidade.

Invariantes

• Usuário comum não cria post livre no MVP.
• Post suggested nunca é publicado automaticamente pela entidade.
• Conteúdo platform_generated pode ser publicado sem aprovação quando representa dado público canônico.
• Ocultar afeta somente o usuário.
• Mute não altera follow/cheer.
• Post removido por moderação não volta ao feed por paginação/cache.
• Conteúdo respeita visibilidade da entidade e dados de origem.
• Patrocínio não compra prioridade orgânica no feed.

Estados

Estado	Significado	Visibilidade/efeito
draft	Rascunho da entidade	Somente gestão.
suggested	Sugestão aguardando decisão	Somente gestão.
approved	Aprovado para publicação	Pode aguardar horário.
published	Público	Feed/página.
hidden	Oculto pela entidade	Não público.
removed	Removido por operação	Não público e auditado.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	create_official	draft/published	Gestor de mídia	Conforme opção publicar agora.
—	generate_suggestion	suggested	Plataforma	Notifica gestores.
suggested	approve	published	Gestor de mídia	Pode consumir crédito se ação paga.
suggested	reject	hidden	Gestor	Registra decisão.
draft	publish	published	Gestor	Valida dados públicos.
published	hide	hidden	Gestor/operação	Remove do feed.
published	moderate_remove	removed	Operação	Motivo e auditoria.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
feed.createOfficialPost	Media/Admin	Criar post	Sim
feed.approveSuggestion	Media/Admin	Aprovar/rejeitar	Sim
feed.hideEntityPost	Media/Admin	Ocultar	Sim
feed.moderate	Operação	Remover	Sim

Fluxos funcionais

Montagem do feed

1. Backend busca follows, cheers, preferências e território.
2. Prioriza entidades que o usuário torce/segue sem excluir recência.
3. Inclui cards de plataforma a cada 5–8 itens quando relevantes.
4. Aplica mutes, hides e status das entidades.
5. Retorna FeedReason para explicação.

Post oficial

1. Gestor escolhe template/tipo, escreve texto curto e anexa mídia opcional.
2. Preview usa identidade da entidade.
3. Publicação cria post e pode gerar share card.

Sugestão

1. Plataforma detecta resultado, próximo jogo, ranking ou marco.
2. Cria suggested post.
3. Gestor aprova/rejeita.
4. Aprovação publica sem editar o dado canônico; texto e mídia podem ser ajustados.

Controle do usuário

1. Usuário abre menu.
2. Pode ocultar post, silenciar 7/30 dias/até reativar, deixar de seguir ou deixar de torcer.
3. Ação atualiza feed imediatamente e permanece entre sessões.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Entidade suspensa	Remover posts do feed conforme política	ENTITY_SUSPENDED
Post aponta para partida contestada	Exibir status e evitar afirmação definitiva	SOURCE_NOT_FINAL
Suggestion já resolvida	Retornar estado atual	SUGGESTION_ALREADY_RESOLVED
Mute expirado	Voltar a incluir conteúdo	—
Usuário deixa de torcer	Exigir confirmação e manter follow opcional	CHEER_REMOVAL_CONFIRMATION

Privacidade e exposição pública

• Feed nunca transforma dado privado em conteúdo público.
• Motivo do conteúdo não expõe comportamento de terceiros.
• Preferências e mutes são privados.
• Posts podem ser públicos em páginas mesmo para visitante, conforme status.

Notificações e auditoria

• Sugestão nova para gestores.
• Post removido/moderado.
• Campanha paga de push separada do post.
• Auditoria de publicação, aprovação e remoção.

API relacionada

Método	Rota	Acesso	Finalidade
GET	/api/v1/feed	Autenticado	Feed personalizado
POST	/api/v1/feed/posts	Permissão de mídia	Criar
PATCH	/api/v1/feed/posts/:id	Permissão de mídia	Editar draft
POST	/api/v1/feed/posts/:id/publish	Permissão de mídia	Publicar
GET	/api/v1/feed/suggestions	Gestão	Listar sugestões
POST	/api/v1/feed/suggestions/:id/approve	Gestão	Aprovar
POST	/api/v1/feed/suggestions/:id/reject	Gestão	Rejeitar
POST	/api/v1/feed/posts/:id/hide	Autenticado	Ocultar para usuário
POST	/api/v1/feed/mutes	Autenticado	Silenciar
DELETE	/api/v1/feed/mutes/:entityType/:entityId	Autenticado	Reativar

Contratos compartilhados

• FeedPostDto
• FeedPostType
• FeedPostSource
• FeedPostStatus
• FeedReasonDto
• FeedPageResponse
• FeedPreferencesDto
• MuteEntityRequest
• ApproveSuggestedPostRequest

Requisitos de UX

• Home exibe Card Minha Gestão acima do feed para gestores e recolhe no scroll.
• Cada post deixa claro entidade, tempo, tipo, motivo e ação principal.
• Sem contadores de curtida/comentário no MVP.
• Menu oferece controles com consequência explícita.
• Feed vazio ensina seguir times, campeonatos e territórios.

Comportamento dos mocks

• Feed default, empty, rich e error.
• Posts de todos os tipos prioritários.
• Mute/hide in-memory.
• Suggestion approve/reject altera listas.
• Entidade suspensa e source contestada.

Critérios de aceite

• Sem posts livres.
• Suggested exige aprovação.
• Platform cards entram com frequência controlada.
• Mute/hide funcionam por usuário.
• Reason é retornado.
• Patrocínio não prioriza feed.

Testes obrigatórios

• Ordenação leve e filtros.
• Mute durations.
• Hide.
• Approval concurrency.
• Status da source.
• Paginação sem duplicatas.

Pós-MVP

• Curtidas, comentários, reações, salvar e posts livres.
• Recomendação mais avançada.
• Compartilhamento interno.
• Sugestões celebrativas de aniversário de jogador, time ou torcida e marco de campanha, sempre privadas até aprovação do usuário ou da entidade envolvida (IS-POST-12.1).
• Registro versionado de marcos, inicialmente com 5 vitórias validadas na campanha, 100º jogo validado e entrada no top 3 de qualquer ranking canônico; regras podem ser adicionadas, desativadas ou removidas sem apagar posts aprovados.
• A sugestão abre preview do card; somente Aprovar publicação cria o post. Ler a notificação não publica.

Decisões registradas

• Feed é principalmente cronológico com prioridade leve.
• Cards de plataforma a cada 5–8 posts quando relevantes.
• Nada é publicado automaticamente em nome da entidade sem aprovação ou regra explícita.
• Aniversários e marcos de campanha não usam publicação automática: são sugestões pós-MVP sujeitas à aprovação do próprio usuário ou de representante autorizado da entidade envolvida.

Machine summary

spec: SPEC-DOMAIN-FEED-001
domain: Feed e publicações
must_preserve:
  - Usuário comum não cria post livre no MVP.
  - Post suggested nunca é publicado automaticamente pela entidade.
  - Conteúdo platform_generated pode ser publicado sem aprovação quando representa dado público canônico.
  - Ocultar afeta somente o usuário.
  - Mute não altera follow/cheer.
  - Post removido por moderação não volta ao feed por paginação/cache.
  - Conteúdo respeita visibilidade da entidade e dados de origem.
  - Patrocínio não compra prioridade orgânica no feed.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation