Merge remote-tracking branch 'origin/agent--qualifica'

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

@@ -0,0 +1,25 @@
+# Registro de Otimizações da Sessão — Aprimoramento da IA (Parte 2)
+
+**Data:** 11/08/2026  
+**Sessão / Contexto:** Eliminação de erros de consulta à tabela removida `usuarios` (`select "codigo", "nome", "categoria"` - `code 42703`) e padronização da integração via SSO (`e-licencie.drive`).
+
+---
+
+## 📌 Principais Aprendizados e Regras Consolidadas
+
+### 1. Gestão de Usuários e Perfis via `e-licencie.drive` (SSO)
+- A tabela `usuarios` **não existe** no banco de dados PostgreSQL local dos schemas dos inquilinos. A identificação, listagem e auditoria de usuários (operadores e usuários externos da categoria `externo`) são providas exclusivamente pelo pacote `p-e-licencie-drive` (`eliDrive`).
+- É **estritamente proibido** realizar chamadas `knex("usuarios")` ou `knex(enumTabelas.usuarios)`. Toda consulta de usuários em endpoints ou tarefas em segundo plano (CRON) deve invocar `eliDrive({ token }).listarUsuarios()`.
+
+### 2. Tratamento de Depreciação e Tabela Undefined no Knex
+- Ao chamar `knex(prop)` quando `prop` é `undefined`, o Knex executa `knex()` sem nome de tabela, emitindo o aviso de depreciação `calling knex without a tableName is deprecated. Use knex.queryBuilder() instead` e gerando queries SQL inválidas (`SELECT ...` sem cláusula `FROM`).
+- Qualquer utilitário ou tabela que tenha sido removida do esquema deve ter suas referências completamente limpas da biblioteca `qualifica-comuns` (em `_tabelas_registros.ts`) para evitar que a chave acesse propriedades `undefined` via Proxy.
+
+---
+
+## 🔍 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`, `npx tsx`)
+- [x] Padrão `eliDrive` unificado em todas as rotas de listagem de eventos e tarefas de envio de e-mail

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

@@ -0,0 +1,29 @@
+# Registro de Otimizações da Sessão — Aprimoramento da IA
+
+**Data:** 11/08/2026  
+**Sessão / Contexto:** Resolução de erro de "Acesso Negado — Você não possui permissão" ao acessar a rota pública `/publico/painel-empresa/:token/avaliacao/:id` do Qualifica.
+
+---
+
+## 📌 Principais Aprendizados e Regras Consolidadas
+
+### 1. Distinção entre Eventos Operacionais/Notificações e Eventos de Status Macro
+- A tabela `eventos` registra múltiplos tipos de eventos associados a uma avaliação (`tabela_origem = 'avaliacoes'`), incluindo tanto mudanças de **status macro** (`rascunho`, `aberta`, `correcao_solicitada`, `aprovada`, `aprovada_ressalvas`, `reprovada`, `vencida`, `cancelada`) quanto **notificações/auditorias operacionais** (`alerta_prazo`, `acesso_painel`, `acesso_formulario`).
+- Toda consulta SQL / Knex que determine o `statusAtual` de uma avaliação a partir da tabela `eventos` **DEVE** conter obrigatoriamente a restrição `.whereIn("status", zStatusAvaliacaoMacro.options)` (ou no SQL: `AND ev.status IN (...)`).
+
+### 2. Validação Estrita de Schemas Zod em Rotas Públicas (`zApiPublica`)
+- A rota pública `publico_painel_empresa_detalhe` e `publica_formulario_perguntas` utilizam o schema `zStatusAvaliacaoMacro` para validar o campo `status_avaliacao` no payload de resposta.
+- Caso a consulta ao banco retorne um evento operacional como `'alerta_prazo'`, a validação Zod falha com `ZodError`, forçando o wrapper da API a retornar `{ eErro: true }`. No frontend, isso se traduz no fallback de erro `token_invalido` ("Acesso Negado"), disfarçando um erro de schema do backend como uma falha de autenticação.
+- **Regra:** Todo valor retornado para o frontend em um campo validado por enum Zod DEVE ser sanitizado e validado defensivamente contra os membros do enum (`zStatusAvaliacaoMacro.options`) antes de ser montado no objeto de resposta.
+
+### 3. Tracing de Diagnóstico Prévia a Qualquer Modificação
+- Conforme a regra `diagnostico-antes-correcao.md`, o agente investigou a causa raiz testando os componentes isoladamente (Token JWT -> Zod schema `zTokenPublico` -> Query Knex -> Zod schema `zApiPublica`). Isso permitiu identificar exatamente a linha onde o `ZodError` ocorria (`zStatusAvaliacaoMacro`), evitando refatorações desnecessárias em autenticação ou rotas Vue Router.
+
+---
+
+## 🔍 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`, `npx tsx`)
+- [x] Contratos Zod preservados e validados estritamente

proxy

@@ -14,6 +14,8 @@ Abra o arquivo de configuração do seu shell (`~/.bashrc` ou `~/.zshrc`).
 nano ~/.bashrc  # ou ~/.zshrc
 ```
 
+
+
 ### Passo 2: Adicionar o Alias
 Adicione a seguinte instrução ao final do arquivo: