API Reference: Comunicados

Base URL: /api/comunicados. CRUD completo para comunicados do nucleo com suporte a foto/video, push seletivo, email opcional e integracao com IA.

POST /api/comunicados

Cria um novo comunicado no nucleo.

Permissao: COORDENADOR / ADMINISTRADOR

Body

Campo	Tipo	Obrigatorio	Descricao
`titulo`	string	Sim	Titulo do comunicado
`conteudo`	string	Sim	Texto do comunicado (suporta HTML)
`fotoUrl`	string	Nao	URL da foto (upload via Supabase Storage bucket `comunicados`)
`videoUrl`	string	Nao	URL do video (YouTube)
`segmentoAlvo`	object	Nao	Filtros `{ cargo?, plano? }` para segmentacao
`dataAgendamento`	string (ISO)	Nao	Data/hora para publicacao agendada (se omitido, publica imediatamente)
`enviarPush`	boolean	Nao	Enviar push notification (default: true)
`enviarEmail`	boolean	Nao	Enviar email para membros (default: false)
`pushDestinatarios`	string \| object	Nao	Controle seletivo de push: 'todos', { cargo: [] } ou { membroIds: [] }

Exemplo de body

{
  "titulo": "Acao de sabado confirmada",
  "conteudo": "<p>A acao no centro de Vitoria esta confirmada para sabado as 9h.</p>",
  "fotoUrl": "https://storage.supabase.co/.../foto.jpg",
  "videoUrl": "https://www.youtube.com/watch?v=abc123",
  "enviarPush": true,
  "enviarEmail": true,
  "pushDestinatarios": "todos",
  "segmentoAlvo": { "cargo": "MEMBRO" }
}

Response 201

{
  "id": "uuid",
  "titulo": "Acao de sabado confirmada",
  "status": "PUBLICADO",
  "criado_em": "2026-03-30T10:00:00Z"
}

PATCH /api/comunicados/:id

Atualiza um comunicado existente. Aceita os mesmos campos do POST (todos opcionais).

Permissao: COORDENADOR / ADMINISTRADOR

DELETE /api/comunicados/:id

Remove um comunicado.

Permissao: COORDENADOR / ADMINISTRADOR

Response 200

{ "message": "Comunicado removido com sucesso" }

GET /api/comunicados

Lista comunicados publicados visiveis para o usuario logado (respeita segmentacao).

Permissao: Qualquer usuario autenticado

Response 200

[
  {
    "id": "uuid",
    "titulo": "Acao de sabado confirmada",
    "conteudo": "<p>...</p>",
    "fotoUrl": "https://...",
    "videoUrl": "https://...",
    "status": "PUBLICADO",
    "criado_em": "2026-03-30T10:00:00Z",
    "autor": { "id": "uuid", "nome": "Joao Silva" }
  }
]

GET /api/comunicados/admin

Lista todos os comunicados do nucleo (incluindo agendados) para a tela de administracao.

Permissao: COORDENADOR / ADMINISTRADOR

GET /api/comunicados/:id

Retorna detalhes de um comunicado especifico.

Permissao: Qualquer usuario autenticado

Midia (Foto e Video)

Foto

Upload feito pelo frontend para o Supabase Storage no bucket comunicados
A URL publica e enviada no campo fotoUrl ao criar/editar
Foto e exibida no topo do comunicado no feed e na pagina de detalhe

Video

Apenas URLs do YouTube sao suportadas
O frontend renderiza um player embed a partir da URL
Video aparece abaixo da foto (se ambos presentes) ou no topo

Push Seletivo

O campo pushDestinatarios permite controlar quem recebe a push notification:

Valor	Tipo	Descricao
`'todos'`	string	Envia push para todos os membros ativos do nucleo (padrao)
`{ cargo: string[] }`	object	Envia push apenas para membros com cargos especificados
`{ membroIds: string[] }`	object	Envia push apenas para membros especificos por ID

UI no Frontend

O formulario de criacao/edicao exibe radio buttons para selecao do tipo de destinatario:

Todos: Opcao padrao, envia para todos os membros ativos
Por cargo: Checkboxes para cada cargo (MEMBRO, LIDER_PROJETO, COORDENADOR, ADMINISTRADOR, PORTA_VOZ)
Membros especificos: Campo de busca por nome com chips removiveis

Email Opcional

Quando enviarEmail: true, o backend chama MailService.sendToSegment() com tipo comunicado:

Usa o template HTML de comunicado com branding do nucleo
Respeita segmentacao por cargo e plano (se configurado)
Respeita preferencias individuais de email (email_comunicado)

Feed com Midia

Ao criar um comunicado com status PUBLICADO, o backend insere automaticamente um registro na tabela feed_atividades:

Tipo: COMUNICADO
O campo conteudo (JSONB) inclui fotoUrl e videoUrl quando presentes
O feed renderiza a midia inline — foto como imagem e video como embed do YouTube
O feed e exibido no dashboard principal para todos os membros

Comunicados Nacional

Comunicados do nivel Nacional (sem nucleo_id) sao exibidos no feed de todos os nucleos:

Criados pelo super admin via painel nacional
Aparecem no feed de todos os nucleos com badge "Nacional"
Push e email sao enviados para todos os nucleos quando habilitados

IA: Melhorar com IA

O formulario de criacao/edicao possui um botao "Melhorar com IA" que:

Envia o texto do conteudo para o endpoint /api/ia/melhorar-texto
Recebe uma versao melhorada do texto (mais claro, corrigido, formatado)
O usuario pode aceitar ou descartar a sugestao

Segmentacao

O campo segmentoAlvo permite filtrar quem recebe e ve o comunicado:

cargo — filtra por cargo do membro (ex: COORDENADOR, MEMBRO)
plano — filtra por plano ativo (ex: APOIADOR, MILITANTE)

Comunicados sem segmento sao visiveis para todos os membros ativos do nucleo.

Status do Comunicado

Status	Descricao
`PUBLICADO`	Comunicado visivel no feed e listagem
`AGENDADO`	Comunicado criado mas aguardando `dataAgendamento` para ser publicado