melhorias na ia

global/rules/consultar-banco-query-ia

@@ -0,0 +1,154 @@
+---
+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)