API Reference: IA (Inteligencia Artificial)

Base URL: /api/ia. Todos os endpoints requerem papel COORDENADOR ou ADMINISTRADOR.

Provider: OpenAI GPT-4o-mini. Arquitetura baseada em Function Calling com 27 ferramentas (19 leitura + 8 escrita).

Arquitetura: Function Calling

O sistema utiliza Function Calling da OpenAI para interagir com o banco de dados de forma segura e estruturada. O fluxo e:

1. Usuario envia pergunta pelo chat
2. OpenAI recebe a mensagem junto com o historico da conversa e decide quais ferramentas chamar (tool_calls)
3. Backend executa as queries no banco de dados via ferramentas
4. Resultados sao enviados de volta para a OpenAI
5. OpenAI gera a resposta final em linguagem natural com rich content types

Ferramentas de Leitura (19)

Disponiveis para COORDENADOR e ADMINISTRADOR.

Ferramentas de Escrita (8)

Disponiveis apenas para ADMINISTRADOR. Todas requerem confirmacao do usuario antes da execucao.

Rich Content Types

A IA retorna conteudo rico estruturado no chat. O campo tipo na resposta determina como o frontend renderiza:

Quick Replies

Os botoes de quick reply sao contextuais — variam de acordo com a ferramenta chamada pela IA:

• Apos listarMembros: "Ver detalhes", "Exportar CSV", "Enviar email para esses"
• Apos estatisticasGerais: "Comparar com mes anterior", "Detalhar por cargo"
• Apos criarTarefa: "Criar outra tarefa", "Ver tarefas pendentes"
• Clicar em um quick reply envia o texto como nova mensagem do usuario

Endpoints

POST /api/ia/chat

Endpoint principal do chat com IA. Recebe o historico completo de mensagens para manter contexto conversacional.

Body

{
  "messages": [
    { "role": "user", "content": "Quantos membros ativos temos?" },
    { "role": "assistant", "content": "O nucleo possui 47 membros ativos." },
    { "role": "user", "content": "E quantos sao coordenadores?" }
  ]
}

Response 200

{
  "resposta": "Dos 47 membros ativos, 5 possuem o cargo de Coordenador.",
  "tool_calls": ["contarMembros"],
  "tipo": "text",
  "quick_replies": ["Listar coordenadores", "Ver ranking", "Estatisticas gerais"]
}

O campo tipo pode ser: text, member_cards, quick_replies, task_preview, email_preview, action_confirm ou success.

POST /api/ia/chat/action

Executa uma acao previamente confirmada pelo usuario no chat.

Body

{
  "action": "push",
  "payload": {
    "titulo": "Evento confirmado!",
    "mensagem": "O evento de sabado esta confirmado. Nos vemos as 9h no centro.",
    "destinatarios": "todos"
  }
}

Acoes suportadas

Response 200

{
  "success": true,
  "message": "Push enviado para 47 membros."
}

POST /api/ia/consulta-membros

Chat com IA sobre dados dos membros do nucleo (endpoint legado, mantido para compatibilidade).

Body

{ "pergunta": "Quantos membros temos de cada cidade? Monte uma tabela." }

Response 200

{
  "resposta": "## Membros por Cidade\n\n| Cidade | Quantidade |\n|---|---|\n| Vitoria | 15 |\n| Vila Velha | 8 |..."
}

POST /api/ia/matching

Encontra membros que melhor se encaixam em uma necessidade especifica.

Body

{ "prompt": "Preciso de 3 pessoas com experiencia em design para criar material de campanha" }

Response 200

{
  "membros": [
    { "id": "uuid", "nome": "Maria Silva", "cargo": "MEMBRO", "competencias": ["design", "photoshop"] }
  ],
  "justificativa": "Maria possui competencias em design e ferramentas visuais..."
}

POST /api/ia/resumo-semanal

Gera um resumo semanal de engajamento do nucleo usando IA.

Response 200

{
  "dados": {
    "novosMembros": 5,
    "tarefasConcluidas": 23,
    "eventosFinalizados": 3
  },
  "resumo": "Semana produtiva para o nucleo! 5 novos membros se juntaram ao time..."
}

Cache no frontend

O resumo e armazenado no localStorage com TTL de 1 hora.

POST /api/ia/melhorar-texto

Reescreve um texto com tom profissional e claro.

Body

{ "texto": "vamos fazer um evento la no centro pra galera se encontrar e tal" }

Response 200

{
  "original": "vamos fazer um evento la no centro pra galera se encontrar e tal",
  "melhorado": "Estamos organizando um evento presencial no centro da cidade, voltado para promover a integracao entre os membros do nucleo."
}

AI Chat Widget (Flutuante)

Widget flutuante de chat com IA integrado ao dashboard.

• Botao flutuante: Posicionado no canto inferior direito da tela (icone Sparkles), tamanho compacto
• Visibilidade: Apenas para usuarios com cargo COORDENADOR ou ADMINISTRADOR
• Painel de chat: 360px de largura, com historico de mensagens, sugestoes de perguntas e campo de input
• Rich content: Renderiza todos os 6 tipos de conteudo rico (member_cards, quick_replies, task_preview, email_preview, action_confirm, success)
• Historico: Mensagens da sessao sao mantidas no estado do componente e salvas automaticamente via ia_conversas

Pagina Fullscreen: /dashboard/ia

Experiencia fullscreen dedicada de IA com sidebar de conversas:

• Sidebar de conversas: Lista todas as conversas do usuario com titulo e data, permitindo retomar conversas anteriores
• Area de chat: Ocupa toda a area principal com mais espaco para mensagens longas, tabelas e previews
• Nova conversa: Botao para iniciar uma conversa do zero
• Responsivo: No mobile, a sidebar de conversas fica oculta com toggle

Historico de Conversas (ia_conversas)

Todas as conversas com a IA sao salvas automaticamente na tabela ia_conversas:

• Auto-save: A cada mensagem enviada/recebida, a conversa e atualizada no banco automaticamente
• Titulo automatico: O titulo da conversa e gerado automaticamente a partir da primeira mensagem do usuario
• Compartilhar: Administradores podem compartilhar uma conversa, tornando-a visivel para coordenadores do nucleo (campo compartilhada + compartilhada_em)
• Retomar: O usuario pode retomar qualquer conversa anterior com todo o historico preservado

Contexto da Conversa

A IA utiliza o historico completo da conversa (enviado via array messages) para manter contexto:

• Nao re-pergunta informacoes ja mencionadas pelo usuario na mesma conversa
• Referencia dados de mensagens anteriores (ex: "Envie um email para os membros que voce listou")
• O array messages enviado ao endpoint inclui todo o historico da sessao
• Permite conversas multi-turno naturais sem repeticao

Tarefas sem Projeto via IA

A IA pode criar tarefas avulsas (standalone) sem vinculo a um projeto:

• O campo projeto_id na tabela tarefas e nullable
• Permite criar tarefas rapidas pelo chat sem precisar selecionar/criar um projeto
• Tarefas avulsas aparecem na listagem geral de tarefas do nucleo
• A acao criar_tarefa_aberta no endpoint /api/ia/chat/action utiliza esse recurso
• A IA exibe um task_preview com titulo, descricao, dificuldade e recompensa CC antes de confirmar a criacao

Credito de Moedas via IA

A ferramenta creditarMoedas nao auto-credita — sempre exibe um action_confirm com os detalhes (membro, valor, motivo) e requer confirmacao explicita do administrador antes de executar a transacao no ledger.

Email via Chat

Administradores podem criar e enviar emails diretamente pelo chat com IA:

1. O admin descreve o email desejado (ex: "Crie um email sobre o evento de sabado")
2. A IA chama prepararEmail e gera um preview com assunto e conteudo HTML
3. O preview e exibido no chat como mensagem do tipo email_preview com botoes Confirmar/Editar
4. O admin revisa e confirma o envio
5. A IA chama enviarEmail para disparar o email via Resend

Push Preview

Quando a IA prepara um push notification, o widget exibe um formulario de preview antes do envio:

• Titulo: Campo editavel com o titulo sugerido pela IA
• Mensagem: Campo editavel com o corpo do push sugerido pela IA
• Destinatarios: Indicacao de quem recebera (todos, por cargo, membros especificos)
• O usuario pode editar ambos os campos antes de confirmar o envio

Seguranca

• Ferramentas de escrita sao restritas ao cargo ADMINISTRADOR
• Todas as acoes de escrita (creditar moedas, alterar cargo, enviar email) exigem confirmacao explicita do usuario no chat antes da execucao
• Dados sao filtrados por nucleo_id (multi-tenant) — a IA so acessa dados do nucleo do usuario
• Tokens JWT sao validados em todos os endpoints

Variaveis de Ambiente

Arquivos Principais