154 lines
4.4 KiB
Text
154 lines
4.4 KiB
Text
---
|
|
type: rule
|
|
name: consultar-banco-query-ia
|
|
description: Define como agentes devem consultar o banco de dados via rota dedicada /query-ia — proibindo acesso direto ao banco fora deste protocolo
|
|
scope: global
|
|
trigger: context_match
|
|
priority: alta
|
|
updatedAt: "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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"rows": [...],
|
|
"rowCount": 42
|
|
}
|
|
```
|
|
|
|
Em caso de erro SQL:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```typescript
|
|
// 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)
|