Skip to content

Controllers e Endpoints

A arquitetura HTTP do sistema é dividida entre endpoints de integração (APIs), endpoints de consumo interno (Busca) e painéis administrativos (Logs).

Motor de Busca Híbrida

Arquivo: SearchController.php

É o endpoint principal de consulta do front-end. Ele orquestra a inteligência artificial local com o Meilisearch utilizando a seguinte lógica: * Geração de Vetor (Embeddings): Antes de consultar o banco, o sistema envia o termo de busca para a API local do Ollama utilizando o modelo mxbai-embed-large:latest. * Mecanismo Anti-Falha: A requisição para a IA possui um timeout estrito de 2 segundos. Se o Ollama demorar a responder ou o túnel cair, o sistema absorve a exceção e define o vetor como nulo, garantindo que a tela do usuário não trave. * Busca Híbrida Dinâmica: A consulta via Laravel Scout (WakeProduct::search) só ativa as opções de busca híbrida (semanticRatio: 0.6) e injeta o embedder caso a IA tenha retornado um vetor de busca válido. Os resultados são retornados em JSON com paginação de 20 itens.

Webhooks e Integração (Wake/n8n)

Arquivo: WakeWebhookController.php

Responsável por receber os payloads disparados pela Wake ou roteados pelo n8n. * Auditoria Primária: Antes de aplicar qualquer regra, o payload completo é salvo na tabela utilizando o model WebhookLog para histórico e depuração. * Validação: Exige obrigatoriamente a presença da chave id. * Enfileiramento: Para não prender a requisição HTTP, delega a carga pesada para o job ProcessWakeProductUpdate, despachando-o para a fila default na conexão redis. Retorna imediatamente um status HTTP 200.

Sistema de Logs e Telemetria

A gravação e exibição do histórico de buscas é separada em dois controllers distintos para dividir a carga entre API pública e painel administrativo.

1. Gravação de Logs (API)

Arquivo: BuscaLogController.php

  • Função: Recebe telemetria do front-end sempre que uma busca é executada.
  • Execução: Valida os campos obrigatórios (termo, motivo) e insere os dados diretamente na tabela logs_busca utilizando a facade DB::table, otimizando a performance de escrita.

2. Painel Administrativo de Logs (Web)

Arquivo: LogBuscaController.php

  • Função: Gera a visualização agregada (logs-busca) para os administradores do sistema.
  • Lógica SQL: Utiliza agrupamento (groupBy) para consolidar termos repetidos, somando o total_buscas e identificando o momento da ultima_busca.
  • Filtros e Ordenação: Possui travas de segurança dinâmicas verificando um array de colunas permitidas antes de aplicar os parâmetros sort_by e sort_dir da URL, evitando injeção de SQL.