Query Builder Avançado

O Query Builder é o motor de extração e manipulação de dados do Manager City. Ele permite a construção visual de consultas dinâmicas de banco de dados, sendo utilizado em integrações com o Form Builder, Workflow Engine, relatórios analíticos e exportação de dados.

Visão Geral

O módulo foi projetado para:

• Oferecer uma interface amigável aos usuários, suportando um modo visual (react-querybuilder) e um modo avançado com editor JSON manual.
• Processar schemas de formulários para extração inteligente de campos, resolvendo dependências hierárquicas (com maxDepth=4).
• Permitir uma integração de payloads de entrada/saída extremamente flexível via Schemas padronizados, atuando como o "contrato" de dados entre módulos diferentes (como Workflow e API Routes).

Capacidades

1. Variáveis Globais e Parametrização Dinâmica

O Query Builder aceita Variáveis Globais e Parâmetros Dinâmicos injetados em tempo de execução via params.

• Isso significa que você pode desenhar uma query visual que filtra dados baseada em respostas de um formulário anterior ou do contexto global do usuário.
• O mapeamento é definido pelo esquema InputParamSchema, permitindo validar as variáveis exigidas.

2. Output Formatado

Os resultados das consultas raramente precisam de manipulação adicional do lado do cliente porque a consulta especifica o OutputFieldSchema.

• Cada campo selecionado pode ser processado e formatado dinamicamente (ex: máscaras de CURRENCY, agregações de COUNT, etc.).
• Isso garante que qualquer módulo consumidor da Query (seja a UI, o Engine ou uma API) receba os dados limpos, formatados e prontos.

3. Integração Cross-Module

A query resultante possui um esquema de entrada (inputPayload) e um de saída (outputPayload). Esses esquemas servem como documentação interativa para que módulos de fora consumam e gerem a requisição.

• Em um Workflow, um nó de ação (Action Node) sabe exatamente que tipo de input enviar e o que esperar na resposta, tudo validado por Zod em runtime.

4. Consultas Altamente Performáticas

Para executar as queries de forma rápida:

• A engine executa no modelo Dual-Mode (Prisma Nativo + $queryRaw).
• Para queries simples em JSON, usamos as APIs eficientes do Prisma (path, equals, string_contains) otimizadas por índices GIN do PostgreSQL (idx_form_records_data_gin), tornando a pesquisa textual dentro do JSON relâmpago.
• Quando as operações envolvem agregações complexas, subqueries, ou GROUP BY, o motor decodifica as regras do QueryBuilder gerando Raw SQL perfeitamente ajustado com escape para prevenir SQL Injection, sem overhead de ORM.

Integração Técnica

Para executar uma query, qualquer parte do código (ou uma interface mobile) pode chamar a action:

import { executeSavedQueryAction } from '@/server/actions/saved-query.actions';

// O "slug" identifica a query, os params injetam as variáveis dinâmicas ou do formulário.
const response = await executeSavedQueryAction('estatisticas-rh', {
  tenantId: 'abc-123', 
  statusFilter: 'ATIVO', 
  dataCorte: '2026-05-01'
});

if (response.success) {
   console.log("Métricas da Query:", response.data.metrics);
   console.log("Dados Prontos:", response.data.data);
}

Estrutura do Banco de Dados

A tabela SavedQuery no PostgreSQL armazena todo o estado. O queryDefinition é salvo em JSONB mantendo total flexibilidade estrutural e permitindo rollbacks versionados na evolução do query builder.