diff --git a/memory/registro-otimizacoes-sessao-2026-08-11-aprimorar-ia.md b/memory/registro-otimizacoes-sessao-2026-08-11-aprimorar-ia.md new file mode 100644 index 0000000..206c87f --- /dev/null +++ b/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