query-ia

memory/registro-otimizacoes-sessao-2026-08-10-aprimorar-ia-2.md

@@ -0,0 +1,39 @@
+# Registro de Otimizações da Sessão — Aprimoramento da IA
+
+**Data:** 10/08/2026  
+**Sessão / Contexto:** Resolução de inconsistências de histórico de eventos, consultas SQL de banco e formatação visual no módulo Qualifica (Empresa / Formulários / Avaliação).
+
+---
+
+## 📌 Principais Aprendizados e Regras Consolidadas
+
+### 1. Escopo e Filtragem de Histórico (Avaliação Pai vs Formulário)
+- O histórico da **Avaliação Pai** deve exibir estritamente eventos cujo `tabela_origem === 'avaliacoes'`.
+- O histórico de um **Formulário específico** deve exibir eventos do próprio formulário E de todos os seus campos associados (`ev.codigo_origem === formId || ev.codigo_resposta_formulario === formId`).
+
+### 2. Esquema do Banco PostgreSQL (`respostas_avaliacao`)
+- A tabela `respostas_avaliacao` **não possui** a coluna `codigo_resposta_formulario`.
+- Consultas Knex não devem selecionar nem filtrar diretamente por `codigo_resposta_formulario` nessa tabela (evita erro SQL `42703` `errorMissingColumn`).
+- O relacionamento entre respostas de campo e formulários deve ser resolvido via `codigo_avaliacao` e mapeado em memória usando a hierarquia de seções/perguntas de `todasPerguntas`.
+
+### 3. Cores Dinâmicas e Identidade Visual dos Status
+- Os badges e ícones de status em linhas do tempo devem consumir as propriedades de cores dinâmicas (`cor`, `textoCor`, `corVuetify`) exportadas por `qualifica-comuns` (`statusFormularioDetalhes`, `statusAvaliacaoMacroDetalhes`, `classificacaoRespostaDetalhes`).
+- Cores estáticas ou *hardcoded* (como fundo azul fixo `#EBF8FF` ou verde fallback `#688C00`) são proibidas para status com cores do domínio.
+
+### 4. Formatação de Textos de Eventos (Quebras de Linha e Nomes)
+- Textos de descrição e justificativa em cartões e timelines de eventos devem conter explicitamente as regras CSS:
+  `white-space: pre-wrap; word-break: break-word; line-height: 1.5;`
+- Nomes de autores devem ser sanitizados para remover marcas repetidas (ex: `(Sistema)` prefixado indevidamente).
+
+### 5. Botão de Histórico Universal por Campo
+- O componente `CampoRespostaBase.vue` (invocado por todos os tipos de entrada de campo) contém um botão universal `<History />` com tooltip `"Ver histórico do campo"`.
+- O modal `ModalHistoricoEventos.vue` aceita `:eventos-direct` para renderizar o histórico diretamente da memória do componente quando pre-carregado.
+
+---
+
+## 🔍 Checklist de Verificação de Artefatos
+
+- [x] Artefatos dependentes revisados
+- [x] Nenhuma regra ficou implícita
+- [x] Referências cruzadas e linters validados (`pnpm run biome`, `tsc --noEmit`)
+- [x] Nomes de funções e variáveis mantidos conforme contratos

rules/consultar-banco-query-ia.md

@@ -19,13 +19,14 @@ Essa rota é exclusiva para desenvolvimento e **nunca deve ser usada em produç
 ## 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
+GET  http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia   → retorna documentação da rota (texto plano)
+POST http://127.0.0.1:<porta-back>/<nome_modulo>/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
+> **`<porta-back>` e `<nome_modulo>` são definidos por módulo** — cada módulo do ecossistema usa uma porta e prefixo de rota específicos (ex: `http://127.0.0.1:5260/qualifica/query-ia`). Antes de usar a rota:
+> - O acesso **GET** retorna a documentação do endpoint.
+> - O acesso **POST** executa a consulta SQL e retorna os dados em JSON.
+> - Verificar `package.json` do `*-back` (campo `scripts.dev` ou `scripts.start`) ou o arquivo `.env` do módulo.
 
 ## Como usar
 
@@ -36,13 +37,13 @@ POST http://127.0.0.1:<porta-back>/query-ia   → executa consulta SQL e retorna
 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
+curl http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia
 ```
 
 ### Executar uma consulta SQL
 
 ```bash
-curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
+curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
   -H 'Content-Type: application/json' \
   -d '{
     "sql": "SELECT * FROM empresas LIMIT 10",
@@ -53,7 +54,7 @@ curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
 ### Consulta com parâmetros (binding seguro)
 
 ```bash
-curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
+curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
   -H 'Content-Type: application/json' \
   -d '{
     "sql": "SELECT * FROM avaliacoes WHERE empresa_id = ? AND status = ?",
@@ -107,7 +108,7 @@ O agente **NUNCA** deve:
 ### ✅ Correto — inspecionar registros via query-ia
 
 ```bash
-curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
+curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
   -d '{"sql": "SELECT codigo, nome, status FROM empresas ORDER BY criado_em DESC LIMIT 20"}' \
   -H 'Content-Type: application/json' | jq '.rows'
 ```
@@ -115,7 +116,7 @@ curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
 ### ✅ Correto — verificar schemas PostgreSQL disponíveis
 
 ```bash
-curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
+curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
   -d '{"sql": "SELECT schema_name FROM information_schema.schemata ORDER BY schema_name"}' \
   -H 'Content-Type: application/json' | jq '.rows'
 ```
@@ -123,7 +124,7 @@ curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
 ### ✅ Correto — contar registros por inquilino
 
 ```bash
-curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
+curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
   -d '{"sql": "SELECT inquilino, COUNT(*) as total FROM empresas GROUP BY inquilino"}' \
   -H 'Content-Type: application/json' | jq '.rows'
 ```
@@ -132,7 +133,7 @@ curl -s -X POST http://127.0.0.1:<porta-back>/query-ia \
 
 ```bash
 # Será bloqueado com status 400
-curl -X POST http://127.0.0.1:<porta-back>/query-ia \
+curl -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
   -d '{"sql": "UPDATE empresas SET status = ?", "parametros": ["ativo"]}'`
 ```