.agent/global/rules/consultar-banco-query-ia.md

type	name	description	scope	trigger	priority	updatedAt
rule	consultar-banco-query-ia	Define como agentes devem consultar o banco de dados via rota dedicada /query-ia — proibindo acesso direto ao banco fora deste protocolo	global	context_match	alta	2026-07-01

Regra: Consultar Banco de Dados via /query-ia

Contexto

Quando um agente precisa inspecionar dados reais do banco de dados — para diagnóstico, auditoria, validação de registros ou investigação de bugs — existe uma rota dedicada e segura para isso no backend do projeto.

Essa rota é exclusiva para desenvolvimento e nunca deve ser usada em produção. Ela bloqueia automaticamente comandos destrutivos.

Rota

GET  http://127.0.0.1:<porta-back>/query-ia   → retorna documentação da rota (texto plano)
POST http://127.0.0.1:<porta-back>/query-ia   → executa consulta SQL e retorna JSON

<porta-back> é subjetiva — cada módulo do ecossistema usa uma porta diferente. Antes de usar a rota, descobrir a porta correta do projeto atual:

• Verificar package.json do *-back (campo scripts.dev ou scripts.start)
• Ou verificar a variável PORT no .env do módulo

Como usar

Descobrir a porta e consultar a documentação

# Verificar a porta no package.json do módulo back
cat package.json | jq '.scripts.dev'

# Consultar a documentação da rota (substitua <porta-back> pela porta real)
curl http://127.0.0.1:<porta-back>/query-ia

Executar uma consulta SQL

curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
  -H 'Content-Type: application/json' \
  -d '{
    "sql": "SELECT * FROM empresas LIMIT 10",
    "parametros": []
  }' | jq .

Consulta com parâmetros (binding seguro)

curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
  -H 'Content-Type: application/json' \
  -d '{
    "sql": "SELECT * FROM avaliacoes WHERE empresa_id = ? AND status = ?",
    "parametros": ["uuid-da-empresa", "aprovado"]
  }' | jq .

Comandos bloqueados

Os seguintes comandos são automaticamente rejeitados pela rota (retorno 400):

• DELETE
• UPDATE
• DROP
• ALTER
• TRUNCATE
• INSERT

Apenas leitura (SELECT, WITH, EXPLAIN, etc.) é permitida.

Retorno

{
  "rows": [...],
  "rowCount": 42
}

Em caso de erro SQL:

{
  "erro": "mensagem de erro",
  "stack": "stack trace (apenas em desenvolvimento)"
}

Regra

O agente DEVE usar esta rota sempre que precisar de dados reais do banco — diagnóstico, contagem de registros, verificação de estado, auditoria de dados.

O agente NUNCA deve:

• Tentar acessar o banco diretamente via código (modificar arquivos para adicionar logs de DB)
• Inventar dados ou assumir estado sem verificar
• Usar esta rota para comandos de escrita — use as APIs REST do módulo para isso

Exemplos

✅ Correto — inspecionar registros via query-ia

curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
  -d '{"sql": "SELECT codigo, nome, status FROM empresas ORDER BY criado_em DESC LIMIT 20"}' \
  -H 'Content-Type: application/json' | jq '.rows'

✅ Correto — verificar schemas PostgreSQL disponíveis

curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
  -d '{"sql": "SELECT schema_name FROM information_schema.schemata ORDER BY schema_name"}' \
  -H 'Content-Type: application/json' | jq '.rows'

✅ Correto — contar registros por inquilino

curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
  -d '{"sql": "SELECT inquilino, COUNT(*) as total FROM empresas GROUP BY inquilino"}' \
  -H 'Content-Type: application/json' | jq '.rows'

❌ Errado — tentar escrever via query-ia

# Será bloqueado com status 400
curl -X POST http://127.0.0.1:<porta-back>/query-ia \
  -d '{"sql": "UPDATE empresas SET status = ?", "parametros": ["ativo"]}'`

❌ Errado — modificar código para adicionar log de banco

// NÃO fazer isso para "ver os dados" — usar a rota query-ia
const debug = await dbKnex('empresas').select('*').limit(10)
console.log(debug)

Impacto

Sem esta regra, agentes podem modificar código de produção apenas para inspecionar dados, ou assumir estados do banco sem verificação — gerando diagnósticos incorretos e alterações desnecessárias.

Referências

• Implementação de referência: qualifica-back/src/utilitarios-IA/query-ia.ts
• Rule: global/rules/autonomia-agente (ações autônomas sem aprovação)