Status: Approved · v2.1 · SPEC-DOMAIN-NOTIFICATION-001

depends_on: SPEC-DOMAIN-AUTH-001, SPEC-DOMAIN-PERMISSION-001, SPEC-DOMAIN-WALLET-001

used_by: IS-MVP-11.4, IS-MVP-11.5, IS-POST-12.1

Notificações e pendências

Central interna para eventos pessoais e de gestão, com push reservado a itens importantes ou campanhas pagas.

Objetivo e limites

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

Incluído no MVP

• Central interna.
• Separação pessoal/gestão e agrupamento por entidade.
• Notificações acionáveis.
• Configuração por categoria.
• Push simulado e campanhas pagas com créditos.

Fora do MVP

• E-mail completo.
• Push real.
• Digest inteligente.
• Preferências granulares por entidade.

Atores e responsabilidades

Ator	Responsabilidade
Usuário	Recebe e configura notificações pessoais.
Gestor	Recebe notificações por entidade e permissão.
Sistema	Cria notificações por eventos de domínio.
Operação	Envia avisos críticos e trata falhas.
Gestor financeiro/mídia	Cria campanha de push paga quando autorizado.

Conceitos canônicos

Notification

Evento entregue a um usuário.

Pending Action

Notificação que exige decisão/ação.

Scope

personal ou management.

Category

Agrupamento funcional.

Delivery Channel

in_app, push ou email preparado.

Invariantes

• Usuário sem permissão não recebe conteúdo de gestão correspondente.
• Revogar permissão impede novas notificações e pode ocultar conteúdo sensível antigo.
• Toda notificação possui targetRoute ou ação segura quando acionável.
• Marcar como lida não executa ação.
• Campanha paga exige saldo, permissão e confirmação.
• Push não é enviado automaticamente para eventos de baixa prioridade.
• Dados financeiros privados não aparecem no texto de push em tela bloqueada.

Estados

Estado	Significado	Visibilidade/efeito
unread	Não lida	Conta em badge.
read	Lida	Permanece no histórico.
archived	Arquivada	Fora da lista padrão.
expired	Ação não mais disponível	Mantém contexto histórico.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	deliver	unread	Sistema	Atualiza contadores.
unread	read	read	Usuário	Remove badge.
read/unread	archive	archived	Usuário	Oculta da lista.
unread/read	expire_action	expired	Sistema	Desabilita CTA.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
notification.readOwn	Próprio usuário	Central	Não
notification.manageSettings	Próprio usuário	Preferências	Sim leve
notification.createPaidPush	Media/Financial/Admin	Campanha	Sim

Fluxos funcionais

Entrega por evento

1. Caso de uso conclui ação.
2. Publisher gera evento interno.
3. Resolver identifica destinatários por papel/permissão/preferência.
4. Cria in_app; push apenas se prioridade/configuração permitir.

Pendência acionável

1. Notificação carrega actionType e resourceVersion.
2. Usuário abre detalhes.
3. Ao aprovar/rejeitar, endpoint do domínio revalida estado.
4. Notificação é marcada como resolvida/expirada conforme resultado.

Campanha paga

1. Gestor escolhe entidade, audiência permitida e mensagem/template.
2. Preview mostra custo em créditos e alcance estimado não garantido.
3. Confirmação consome créditos idempotentemente.
4. Provider mock registra envio.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Permissão revogada	Não entregar e ocultar detalhe sensível	PERMISSION_REQUIRED
Ação já resolvida	Abrir contexto com CTA desabilitado	ACTION_ALREADY_RESOLVED
Créditos insuficientes	Não criar campanha	INSUFFICIENT_CREDITS
Notificação duplicada	Deduplicar por event key	NOTIFICATION_DUPLICATE
Target removido	Mostrar contexto mínimo	TARGET_NOT_AVAILABLE

Privacidade e exposição pública

• Push usa texto neutro quando contém finanças ou denúncia.
• Central de gestão só mostra entidades acessíveis.
• Preferências são privadas.
• Campanha não permite upload de lista arbitrária de destinatários.

Notificações e auditoria

• O próprio domínio é esta camada; auditoria registra campanhas e mudanças de preferência sensíveis.
• Falhas de provider geram observabilidade, não duplicação infinita.

API relacionada

Método	Rota	Acesso	Finalidade
GET	/api/v1/notifications	Autenticado	Listar
GET	/api/v1/notifications/counts	Autenticado	Contadores
POST	/api/v1/notifications/:id/read	Autenticado	Ler
POST	/api/v1/notifications/read-all	Autenticado	Ler todas no escopo
POST	/api/v1/notifications/:id/archive	Autenticado	Arquivar
GET	/api/v1/notification-settings	Autenticado	Preferências
PATCH	/api/v1/notification-settings	Autenticado	Atualizar
POST	/api/v1/paid-push-campaigns	Permissão	Criar
POST	/api/v1/paid-push-campaigns/:id/confirm	Permissão	Confirmar

Contratos compartilhados

• NotificationDto
• NotificationScope
• NotificationCategory
• NotificationPriority
• NotificationAction
• NotificationSettingsDto
• PaidPushCampaignDto
• CreatePaidPushCampaignRequest

Requisitos de UX

• Aba Notificações separa Pessoal e Gestão.
• Gestão agrupa por entidade, não por lista global confusa.
• Pendências mostram prazo e contexto.
• Badge diferencia crítico, alto e normal sem depender só de cor.
• Campanha paga fica dentro da gestão da entidade, não na central pessoal.

Comportamento dos mocks

• Notificações unread/read/archived/expired.
• Ações resolvidas e permission denied.
• Paid push com saldo suficiente/insuficiente e provider failure.

Critérios de aceite

• Permissões filtram gestão.
• In-app é canal base.
• Push importante/pago apenas.
• Ações revalidam domínio.
• Contadores consistentes.

Testes obrigatórios

• Resolver destinatários.
• Deduplicação.
• Revogação de permissão.
• Read/archive.
• Action expired.
• Paid push idempotente.

Pós-MVP

• Push real.
• E-mail/digest.
• Preferências por entidade.
• Resumo inteligente.
• Sugestão celebrativa acionável: aniversário de jogador/time/torcida ou marco de campanha abre preview do card e permite aprovar publicação, rejeitar ou arquivar.
• A sugestão celebrativa não expira automaticamente por tempo. Permanece unread/read até decisão ou arquivamento; publicação sempre revalida permissão, privacidade e snapshot.
• O recipient resolver entrega aniversário de jogador ao próprio jogador e eventos de time/torcida aos usuários que podem publicar pela entidade. Marco de ranking usa o sujeito do marco para resolver destinatários.

Decisões registradas

• Toda informação relevante entra na central.
• Nem toda notificação vira push.
• Push pago usa créditos.
• Pendência é notificação acionável, não módulo separado.
• Abrir ou marcar uma sugestão como lida nunca publica; somente a confirmação explícita no preview cria o post.
• A retenção da sugestão segue o padrão de central persistente: sem TTL automático, com leitura, resolução e arquivamento controlados pelo usuário.

Machine summary

spec: SPEC-DOMAIN-NOTIFICATION-001
domain: Notificações e pendências
must_preserve:
  - Usuário sem permissão não recebe conteúdo de gestão correspondente.
  - Revogar permissão impede novas notificações e pode ocultar conteúdo sensível antigo.
  - Toda notificação possui targetRoute ou ação segura quando acionável.
  - Marcar como lida não executa ação.
  - Campanha paga exige saldo, permissão e confirmação.
  - Push não é enviado automaticamente para eventos de baixa prioridade.
  - Dados financeiros privados não aparecem no texto de push em tela bloqueada.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation