Setup — Backend

Pré-requisitos

Node.js 18+ (ver engines.node no package.json)
MySQL 8+ acessível na rede
Qdrant rodando (padrão: http://localhost:6333)

Ollama rodando com os modelos necessários:

ollama pull nomic-embed-text
ollama pull llama3.1

Instalação

cd backend
npm install

Variáveis de ambiente

Crie o arquivo backend/.env com base nas variáveis abaixo:

Servidor

Variável	Descrição	Exemplo
`PORT`	Porta HTTP da API	`3001`
`CORS_ORIGIN`	Origem permitida pelo CORS	`http://localhost:5173`
`API_KEY`	Chave de API opcional	—
`RATE_LIMIT_PER_MINUTE`	Limite de requisições por minuto (`0` desativa)	`0`

Banco de dados (MySQL)

Variável	Descrição	Exemplo
`DB_HOST`	Host do MySQL	`localhost`
`DB_PORT`	Porta do MySQL	`3306`
`DB_USER`	Usuário do banco	`root`
`DB_PASS`	Senha do banco	`senha`
`DB_SCHEMA`	Nome do schema/database	`oracle`
`DB_SSL_REJECT_UNAUTHORIZED`	Ativa SSL na conexão MySQL e valida o certificado do servidor (setar sozinho já liga SSL, mesmo sem `DB_SSL_CA`)	—
`DB_SSL_CA`	Caminho de um certificado CA para validar o servidor MySQL (se ele não usar CA público)	`./certs/rds-ca.pem`

Qdrant (busca vetorial)

Variável	Descrição	Exemplo
`QDRANT_URL`	URL do Qdrant	`http://localhost:6333`
`QDRANT_COLLECTION`	Nome da collection (default no código: `oraculo_docs`)	`empresa_docs`
`QDRANT_API_KEY`	Chave de API do Qdrant (opcional)	—

Ollama (LLM local)

Variável	Descrição	Exemplo
`OLLAMA_URL`	URL do Ollama	`http://localhost:11434`
`OLLAMA_EMBEDDINGS_MODEL`	Modelo para embeddings	`nomic-embed-text`
`OLLAMA_CHAT_MODEL`	Modelo para chat	`llama3.1`
`OLLAMA_VISION_MODEL`	Modelo de visão (default `llava:latest`)	`llava:latest`
`OLLAMA_ATENDENTE_MODEL`	Modelo usado na sugestão de resposta ao atendente (default `star-atendente`)	`llama3.1`
`OLLAMA_TIMEOUT_MS`	Timeout (ms) para chamadas não-streaming ao Ollama (default `180000`)	`180000`
`OLLAMA_STREAM_IDLE_TIMEOUT_MS`	Timeout (ms) de inatividade no streaming do chat — reinicia a cada chunk recebido (default `60000`)	`60000`
`OLLAMA_EMBED_QUERY_PREFIX`	Prefixo prependado à query antes de gerar embedding (modelos assimétricos, ex.: e5)	—
`OLLAMA_EMBED_PASSAGE_PREFIX`	Prefixo prependado à passagem indexada antes de gerar embedding	—

RAG

Contexto do pipeline (rewrite, HyDE, rerank) em architecture.md.

Variável	Descrição	Exemplo
`RAG_QUERY_REWRITE`	Reescrever query antes da busca, considerando o histórico da conversa (resolve follow-ups tipo "e o segundo caso?")	`true`
`RAG_HISTORY_LIMIT`	Quantidade de mensagens recentes do histórico incluídas no prompt de rewrite/chat (default `6`)	`6`
`RAG_TOP_K`	Número de chunks recuperados (default `8`)	`8`
`RAG_MIN_SCORE`	Score mínimo de similaridade (default `0.40`)	`0.40`
`RAG_CHUNK_SIZE`	Tamanho de cada chunk (caracteres)	`900`
`RAG_CHUNK_OVERLAP`	Sobreposição entre chunks	`150`
`RAG_RERANK`	Reordenar os chunks recuperados por relevância via LLM antes de montar o contexto	`true`
`RAG_RERANK_TOP_N`	Quantos chunks manter após o reranking (default = `RAG_TOP_K`)	`8`
`RAG_HYDE`	HyDE: gera um trecho hipotético de resposta via LLM e usa ele para o embedding de busca (custa uma chamada LLM extra por pergunta)	`false`

LLM (parâmetros de geração)

Variável	Descrição	Exemplo
`LLM_TEMPERATURE`	Criatividade das respostas (0–1); baixo = mais fiel à fonte (default `0.2`)	`0.2`
`LLM_TOP_P`	Nucleus sampling	`0.9`
`LLM_NUM_PREDICT`	Máximo de tokens gerados	`2048`
`LLM_REPEAT_PENALTY`	Penalidade de repetição	`1.1`

Autenticação (JWT)

Fluxo completo e níveis de acesso em auth.md.

Variável	Descrição	Exemplo
`AUTH_MODE`	Modo de auth (`jwt` ou `none`)	`jwt`
`JWT_SECRET`	Chave secreta para assinar tokens	`trocar-em-producao`
`JWT_ISSUER`	Issuer do token	`oraculo-api`
`JWT_ACCESS_TTL_SECONDS`	Duração do access token em segundos	`900` (15 min)
`JWT_REFRESH_TTL_SECONDS`	Duração do refresh token em segundos	`2592000` (30 dias)
`JWT_REFRESH_TTL_SHORT_SECONDS`	Duração do refresh token quando `rememberMe=false`/ausente no login	`86400` (1 dia)

Atenção: AUTH_MODE=none desativa a autenticação completamente. Nunca usar em produção.

Ifbot (sincronização de atendimentos)

Variável	Descrição	Exemplo
`IFBOT_BASE_URL`	URL base da API do ifbot (default `https://star.ifbot.com.br/api`)	`https://star.ifbot.com.br/api`
`IFBOT_TOKEN`	Token de autenticação da API do ifbot	—
`IFBOT_AUTH_HEADER`	Nome do header de autenticação (default `Authorization`)	`Authorization`
`IFBOT_MEDIA_BASE_URL`	Base pública dos arquivos de mídia (`/data/img`, `/data/aud`); default é `IFBOT_BASE_URL` sem o sufixo `/api`	`https://star.ifbot.com.br`
`ATENDIMENTOS_SYNC_INTERVAL_MINUTES`	Intervalo (min) do job de sincronização de atendimentos (`0` desativa)	`30`

RAG de atendimentos

Ingestão de conversas no Qdrant, em uma collection separada da de documentos.

Variável	Descrição	Exemplo
`ATENDIMENTOS_RAG_SEARCH_ENABLED`	Habilita a busca vetorial no modo "atendimentos" do chat	`false`
`ATENDIMENTOS_RAG_COLLECTION`	Nome da collection no Qdrant	`atendimentos_rag`
`ATENDIMENTOS_RAG_INTERVAL_MINUTES`	Intervalo (min) do job de ingestão	`60`
`ATENDIMENTOS_RAG_BATCH`	Tamanho do lote por execução	`10`
`ATENDIMENTOS_RAG_CHUNK_SIZE`	Tamanho de cada chunk (caracteres)	`1800`
`ATENDIMENTOS_RAG_CHUNK_OVERLAP`	Sobreposição entre chunks	`200`
`ATENDIMENTOS_RAG_TOP_K`	Número de chunks recuperados	`20`
`ATENDIMENTOS_RAG_MIN_SCORE`	Score mínimo de similaridade	`0.5`
`ATENDIMENTOS_RAG_HYDE`	HyDE aplicado à busca de atendimentos	`false`

WhatsApp Cloud API (Meta)

Usada pelo chat de Atendimentos (/api/conversas) e pelo webhook em /webhooks/whatsapp (fora de /api, sem JWT — protegido por hub.verify_token na verificação e, opcionalmente, assinatura HMAC no recebimento). Valores vêm do painel da Meta (developers.facebook.com/apps/<seu-app>/whatsapp-business/wa-dev-console/).

Variável	Descrição	Exemplo
`WHATSAPP_API_VERSION`	Versão da API (default `v21.0`)	`v25.0`
`WHATSAPP_PHONE_NUMBER_ID`	ID do número, aba "API Setup"	—
`WHATSAPP_TOKEN`	Token de acesso, aba "API Setup" (o temporário expira em 24h; gerar um permanente em System Users antes de produção)	—
`WHATSAPP_VERIFY_TOKEN`	Valor arbitrário definido por você; colar o mesmo valor no painel da Meta em Webhook → "Verify token"	—
`WHATSAPP_APP_SECRET`	Aba "App settings → Basic", campo "App Secret"; valida a assinatura `X-Hub-Signature-256` (vazio desativa a validação)	—
`WHATSAPP_BUSINESS_ACCOUNT_ID`	Opcional, não usado ainda; reservado para gestão de templates/perfil de negócio	—

Integrador IXC (Alfred)

Usadas só pelo seed (npm run seed:run), que provisiona a linha na tabela integracao. Em runtime o service lê Url/Login/Senha/Token do banco, não do .env (o token sobrevive a restart). Rodar o seed de novo com Login/Senha diferentes força um novo login e invalida o token cacheado.

Variável	Descrição	Exemplo
`IXC_INTEGRADOR_BASE_URL`	URL base do integrador	`http://localhost:4001/`
`IXC_INTEGRADOR_LOGIN`	Login do integrador	—
`IXC_INTEGRADOR_SENHA`	Senha do integrador	—

Whisper (transcrição de áudio local)

Fallback usado quando o ifbot não traz a transcrição do áudio. Requer brew install whisper-cpp ffmpeg e o modelo baixado em WHISPER_MODEL_PATH.

Variável	Descrição	Exemplo
`WHISPER_TRANSCRICAO_ENABLED`	Liga a feature (default `false`)	`true`
`WHISPER_BINARY_PATH`	Caminho do binário `whisper-cli` (default `whisper-cli`)	`whisper-cli`
`WHISPER_FFMPEG_PATH`	Caminho do binário `ffmpeg` (default `ffmpeg`)	`ffmpeg`
`WHISPER_MODEL_PATH`	Caminho do modelo Whisper	`whisper_models/ggml-small.bin`
`WHISPER_VAD_MODEL_PATH`	Caminho do modelo VAD (detecção de voz)	`whisper_models/ggml-silero-vad.bin`
`WHISPER_TIMEOUT_MS`	Timeout (ms) da transcrição (default `60000`)	`60000`

Rodando localmente

# Criar as tabelas no banco (rodar uma vez ou após novas migrations)
npm run migrate:latest

# Modo desenvolvimento (hot reload)
npm run dev

# Modo produção
npm start

A API estará disponível em http://localhost:3001.

Para verificar o status dos serviços:

GET http://localhost:3001/health

Comandos disponíveis

Comando	Descrição
`npm run dev`	Inicia com hot reload (`node --watch`)
`npm start`	Inicia sem hot reload
`npm run migrate:latest`	Aplica todas as migrations pendentes
`npm run migrate:rollback`	Reverte a última migration
`npm run seed:run`	Executa os seeds do banco

setup.md 9.3 KB Historia Czysty