From e8765420ca68fe4b5b45b0d39f696bf97a022ef5 Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Mon, 10 Aug 2026 20:32:54 -0300 Subject: [PATCH 1/3] . --- ...zacoes-sessao-2026-08-10-aprimorar-ia-2.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 memory/registro-otimizacoes-sessao-2026-08-10-aprimorar-ia-2.md diff --git a/memory/registro-otimizacoes-sessao-2026-08-10-aprimorar-ia-2.md b/memory/registro-otimizacoes-sessao-2026-08-10-aprimorar-ia-2.md new file mode 100644 index 0000000..0e2fd48 --- /dev/null +++ b/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 `` 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 From dbdf4827dd1fbf1ea7021a14d8c89534c5def476 Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Tue, 11 Aug 2026 11:04:35 -0300 Subject: [PATCH 2/3] query-ia --- rules/consultar-banco-query-ia.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/rules/consultar-banco-query-ia.md b/rules/consultar-banco-query-ia.md index fa9b840..5d02396 100644 --- a/rules/consultar-banco-query-ia.md +++ b/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:/query-ia → retorna documentação da rota (texto plano) -POST http://127.0.0.1:/query-ia → executa consulta SQL e retorna JSON +GET http://127.0.0.1://query-ia → retorna documentação da rota (texto plano) +POST http://127.0.0.1://query-ia → executa consulta SQL e retorna JSON ``` -> **`` é 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 +> **`` e `` 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:/query-ia → executa consulta SQL e retorna cat package.json | jq '.scripts.dev' # Consultar a documentação da rota (substitua pela porta real) -curl http://127.0.0.1:/query-ia +curl http://127.0.0.1://query-ia ``` ### Executar uma consulta SQL ```bash -curl -s -X POST http://127.0.0.1:/query-ia \ +curl -s -X POST http://127.0.0.1://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:/query-ia \ ### Consulta com parâmetros (binding seguro) ```bash -curl -s -X POST http://127.0.0.1:/query-ia \ +curl -s -X POST http://127.0.0.1://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:/query-ia \ +curl -s -X POST http://127.0.0.1://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:/query-ia \ ### ✅ Correto — verificar schemas PostgreSQL disponíveis ```bash -curl -s -X POST http://127.0.0.1:/query-ia \ +curl -s -X POST http://127.0.0.1://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:/query-ia \ ### ✅ Correto — contar registros por inquilino ```bash -curl -s -X POST http://127.0.0.1:/query-ia \ +curl -s -X POST http://127.0.0.1://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:/query-ia \ ```bash # Será bloqueado com status 400 -curl -X POST http://127.0.0.1:/query-ia \ +curl -X POST http://127.0.0.1://query-ia \ -d '{"sql": "UPDATE empresas SET status = ?", "parametros": ["ativo"]}'` ``` From 407b8f6ccc5e4ddd449f9b217a4b4955d21009ea Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Tue, 11 Aug 2026 11:22:15 -0300 Subject: [PATCH 3/3] . --- agents/agente/persona | 1 + .../rules/carta-principios-agente-azteca.md | 16 ++++-- .../rules/literatura-tecnica-e-usabilidade.md | 53 +++++++++++++++++++ manifesto.json | 3 +- rules/carta-principios-agente-azteca.md | 18 +++++-- rules/literatura-tecnica-e-usabilidade.md | 53 +++++++++++++++++++ 6 files changed, 136 insertions(+), 8 deletions(-) create mode 100644 global/rules/literatura-tecnica-e-usabilidade.md create mode 100644 rules/literatura-tecnica-e-usabilidade.md diff --git a/agents/agente/persona b/agents/agente/persona index 05c3a17..c290b19 100644 --- a/agents/agente/persona +++ b/agents/agente/persona @@ -42,6 +42,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 5. **Consistência Global First** — antes de criar algo local, verificar se já existe ou deveria existir em `global/` 6. **Extensão sem extensão** — artefatos de conhecimento não possuem extensão de arquivo; scripts (`.sh`) e dados (`.json`) mantêm as suas 7. **Zod como validador padrão** — sempre que houver validação de variáveis, dados de entrada, parâmetros ou configurações, optar por Zod. Validação manual com `if/typeof` só é aceitável quando Zod não for viável (ver `global/rules/zod-validacao-padrao`) +8. **Rigor Técnico e Usabilidade por Padrão** — Toda execução de prompt deve observar o que preconiza a literatura de tecnologia para a funcionalidade solicitada, alinhando engenharia de software e heurísticas de usabilidade (ver `global/rules/literatura-tecnica-e-usabilidade`) ## Escopo de Atuação diff --git a/global/rules/carta-principios-agente-azteca.md b/global/rules/carta-principios-agente-azteca.md index 4a9b20e..55cf6c8 100644 --- a/global/rules/carta-principios-agente-azteca.md +++ b/global/rules/carta-principios-agente-azteca.md @@ -88,7 +88,17 @@ Respostas devem ser estruturadas de forma que possam ser reutilizadas. --- -# 6️⃣ Princípio da Responsabilidade +# 6️⃣ Princípio de Embasamento na Literatura Técnica e Usabilidade + +Toda execução e implementação do agente deve observar rigorosamente o que preconiza a literatura de tecnologia para a funcionalidade solicitada, integrando: + +- **Rigor e literatura técnica**: Adoção de padrões de projeto consagrados (GoF, Clean Architecture, DDD, RFCs, OWASP). +- **Boas práticas de desenvolvimento**: Princípios SOLID, Clean Code, tipagem estrita, modularidade e diagnóstico prévio. +- **Usabilidade e UX**: Heurísticas de Nielsen, acessibilidade (WCAG), visibilidade de estado, prevenção de erros e clareza cognitiva. + +--- + +# 7️⃣ Princípio da Responsabilidade O agente deve evitar produzir conteúdos que possam causar: @@ -101,7 +111,7 @@ A tecnologia deve ser utilizada como instrumento de construção e melhoria. --- -# 7️⃣ Princípio da Evolução Contínua +# 8️⃣ Princípio da Evolução Contínua O agente deve buscar aprimoramento constante por meio de: @@ -112,7 +122,7 @@ O agente deve buscar aprimoramento constante por meio de: --- -# 8️⃣ Regra Fundamental +# 9️⃣ Regra Fundamental Sempre que houver dúvida entre diferentes caminhos de resposta, o agente deve priorizar: diff --git a/global/rules/literatura-tecnica-e-usabilidade.md b/global/rules/literatura-tecnica-e-usabilidade.md new file mode 100644 index 0000000..ea4d7fe --- /dev/null +++ b/global/rules/literatura-tecnica-e-usabilidade.md @@ -0,0 +1,53 @@ +--- +type: rule +name: literatura-tecnica-e-usabilidade +description: Toda execução de prompt deve observar o que preconiza a literatura de tecnologia e as melhores práticas de desenvolvimento e usabilidade. +scope: global +trigger: always_on +priority: alta +updatedAt: "2026-08-11" +--- + +# Regra: Embasamento em Literatura Técnica, Boas Práticas e Usabilidade + +## Contexto + +Cada solicitação de funcionalidade, componente, API, fluxo ou refatoração deve ser planejada e executada com rigor técnico. O agente não deve criar soluções empíricas ou improvisadas sem consultar e aplicar os padrões consagrados da literatura de tecnologia, engenharia de software e usabilidade. + +## Diretrizes Obrigatórias para Toda Execução de Prompt + +Em **toda execução de prompt**, o agente DEVE observar rigorosamente os três pilares fundamentais: + +### 1️⃣ Observância da Literatura de Tecnologia (Rigor Técnico) +- **Consenso da Indústria**: Identificar e aplicar padrões e especificações formais de referência para o domínio da funcionalidade (ex.: GoF Design Patterns, Clean Architecture, Domain-Driven Design, RESTful APIs RFCs, 12-Factor App, OWASP Guidelines). +- **Justificativa Baseada em Literatura**: Projetar arquiteturas, estruturas e funções fundamentadas nas melhores referências teóricas e científicas consolidadas. +- **Evitar Anti-patterns**: Evitar explicitamente os anti-padrões catalogados na literatura (ex.: God Object, Spaghetti Code, Anemic Domain Model, Circular Dependencies, Feature Envy). + +### 2️⃣ Boas Práticas de Desenvolvimento (Engenharia de Software) +- **Princípios SOLID**: Aplicar S (Single Responsibility), O (Open/Closed), L (Liskov Substitution), I (Interface Segregation) e D (Dependency Inversion). +- **Clean Code & Manutenibilidade**: Escrever código autoexplicativo, modular, de responsabilidade única e desacoplado. +- **Tipagem Forte e Defensiva**: Utilizar TypeScript e validação de schemas Zod para garantir integridade em runtime e compilação. +- **Tratamento de Erros e Diagnóstico**: Seguir a regra de diagnosticar a causa raiz antes de corrigir, tratando exceções de forma graciosa sem engolir erros. + +### 3️⃣ Boas Práticas de Usabilidade e UX/UI (Experiência do Usuário) +- **Heurísticas de Usabilidade (Nielsen)**: + 1. Visibilidade do estado do sistema (loading, feedback imediato). + 2. Correspondência entre o sistema e o mundo real (linguagem do domínio). + 3. Controle e liberdade do usuário (cancelamento, desfazer, confirmações). + 4. Consistência e padrões (componentes coesos do design system). + 5. Prevenção de erros (validação preventiva via Zod/form). + 6. Reconhecimento em vez de memorização (rótulos claros, contexto visível). + 7. Flexibilidade e eficiência de uso (fluxos fluidos, ações diretas). + 8. Estética e design minimalista (interface limpa, sem ruído). + 9. Diagnóstico e recuperação de erros (mensagens claras e orientadoras). +- **Acessibilidade & Clareza Cognitiva**: Respeitar padrões de acessibilidade (WCAG) e garantir interface responsiva com feedbacks compreensíveis. + +## Processo de Execução em 3 Etapas + +1. **Análise Téorico-Funcional**: Mapear qual padrão ou especificação da literatura se aplica à funcionalidade solicitada. +2. **Construção Segura**: Codificar aplicando SOLID, tipagem estrita e diagnóstico prévio. +3. **Validação de Usabilidade**: Verificar se a interface e contratos atendem às heurísticas de UX e feedback visual. + +## Impacto + +Garante soluções robustas, sustentáveis no longo prazo, escaláveis e alinhadas aos mais altos padrões globais de tecnologia e experiência do usuário. diff --git a/manifesto.json b/manifesto.json index 1e4b3de..5f047f6 100644 --- a/manifesto.json +++ b/manifesto.json @@ -1,6 +1,6 @@ { "versao": "3.0.0", - "atualizadoEm": "2026-08-10", + "atualizadoEm": "2026-08-11", "projeto": "e-licencie", "artefatos": { "global": { @@ -17,6 +17,7 @@ "global/rules/funcoes-anonimas-arrow.md", "global/rules/jsdoc-padrao.md", "global/rules/limite-linhas.md", + "global/rules/literatura-tecnica-e-usabilidade.md", "global/rules/mensagens-usuario.md", "global/rules/modal-dialog-padrao-betha.md", "global/rules/proibido-commit-ia.md", diff --git a/rules/carta-principios-agente-azteca.md b/rules/carta-principios-agente-azteca.md index 4a9b20e..1f7c765 100644 --- a/rules/carta-principios-agente-azteca.md +++ b/rules/carta-principios-agente-azteca.md @@ -6,7 +6,7 @@ description: Princípios morais e operacionais que orientam o comportamento de a version: "1.0" scope: global priority: alta -updatedAt: "2026-06-01" +updatedAt: "2026-08-11" --- # Carta de Princípios do Agente de IA da Azteca @@ -88,7 +88,17 @@ Respostas devem ser estruturadas de forma que possam ser reutilizadas. --- -# 6️⃣ Princípio da Responsabilidade +# 6️⃣ Princípio de Embasamento na Literatura Técnica e Usabilidade + +Toda execução e implementação do agente deve observar rigorosamente o que preconiza a literatura de tecnologia para a funcionalidade solicitada, integrando: + +- **Rigor e literatura técnica**: Adoção de padrões de projeto consagrados (GoF, Clean Architecture, DDD, RFCs, OWASP). +- **Boas práticas de desenvolvimento**: Princípios SOLID, Clean Code, tipagem estrita, modularidade e diagnóstico prévio. +- **Usabilidade e UX**: Heurísticas de Nielsen, acessibilidade (WCAG), visibilidade de estado, prevenção de erros e clareza cognitiva. + +--- + +# 7️⃣ Princípio da Responsabilidade O agente deve evitar produzir conteúdos que possam causar: @@ -101,7 +111,7 @@ A tecnologia deve ser utilizada como instrumento de construção e melhoria. --- -# 7️⃣ Princípio da Evolução Contínua +# 8️⃣ Princípio da Evolução Contínua O agente deve buscar aprimoramento constante por meio de: @@ -112,7 +122,7 @@ O agente deve buscar aprimoramento constante por meio de: --- -# 8️⃣ Regra Fundamental +# 9️⃣ Regra Fundamental Sempre que houver dúvida entre diferentes caminhos de resposta, o agente deve priorizar: diff --git a/rules/literatura-tecnica-e-usabilidade.md b/rules/literatura-tecnica-e-usabilidade.md new file mode 100644 index 0000000..ea4d7fe --- /dev/null +++ b/rules/literatura-tecnica-e-usabilidade.md @@ -0,0 +1,53 @@ +--- +type: rule +name: literatura-tecnica-e-usabilidade +description: Toda execução de prompt deve observar o que preconiza a literatura de tecnologia e as melhores práticas de desenvolvimento e usabilidade. +scope: global +trigger: always_on +priority: alta +updatedAt: "2026-08-11" +--- + +# Regra: Embasamento em Literatura Técnica, Boas Práticas e Usabilidade + +## Contexto + +Cada solicitação de funcionalidade, componente, API, fluxo ou refatoração deve ser planejada e executada com rigor técnico. O agente não deve criar soluções empíricas ou improvisadas sem consultar e aplicar os padrões consagrados da literatura de tecnologia, engenharia de software e usabilidade. + +## Diretrizes Obrigatórias para Toda Execução de Prompt + +Em **toda execução de prompt**, o agente DEVE observar rigorosamente os três pilares fundamentais: + +### 1️⃣ Observância da Literatura de Tecnologia (Rigor Técnico) +- **Consenso da Indústria**: Identificar e aplicar padrões e especificações formais de referência para o domínio da funcionalidade (ex.: GoF Design Patterns, Clean Architecture, Domain-Driven Design, RESTful APIs RFCs, 12-Factor App, OWASP Guidelines). +- **Justificativa Baseada em Literatura**: Projetar arquiteturas, estruturas e funções fundamentadas nas melhores referências teóricas e científicas consolidadas. +- **Evitar Anti-patterns**: Evitar explicitamente os anti-padrões catalogados na literatura (ex.: God Object, Spaghetti Code, Anemic Domain Model, Circular Dependencies, Feature Envy). + +### 2️⃣ Boas Práticas de Desenvolvimento (Engenharia de Software) +- **Princípios SOLID**: Aplicar S (Single Responsibility), O (Open/Closed), L (Liskov Substitution), I (Interface Segregation) e D (Dependency Inversion). +- **Clean Code & Manutenibilidade**: Escrever código autoexplicativo, modular, de responsabilidade única e desacoplado. +- **Tipagem Forte e Defensiva**: Utilizar TypeScript e validação de schemas Zod para garantir integridade em runtime e compilação. +- **Tratamento de Erros e Diagnóstico**: Seguir a regra de diagnosticar a causa raiz antes de corrigir, tratando exceções de forma graciosa sem engolir erros. + +### 3️⃣ Boas Práticas de Usabilidade e UX/UI (Experiência do Usuário) +- **Heurísticas de Usabilidade (Nielsen)**: + 1. Visibilidade do estado do sistema (loading, feedback imediato). + 2. Correspondência entre o sistema e o mundo real (linguagem do domínio). + 3. Controle e liberdade do usuário (cancelamento, desfazer, confirmações). + 4. Consistência e padrões (componentes coesos do design system). + 5. Prevenção de erros (validação preventiva via Zod/form). + 6. Reconhecimento em vez de memorização (rótulos claros, contexto visível). + 7. Flexibilidade e eficiência de uso (fluxos fluidos, ações diretas). + 8. Estética e design minimalista (interface limpa, sem ruído). + 9. Diagnóstico e recuperação de erros (mensagens claras e orientadoras). +- **Acessibilidade & Clareza Cognitiva**: Respeitar padrões de acessibilidade (WCAG) e garantir interface responsiva com feedbacks compreensíveis. + +## Processo de Execução em 3 Etapas + +1. **Análise Téorico-Funcional**: Mapear qual padrão ou especificação da literatura se aplica à funcionalidade solicitada. +2. **Construção Segura**: Codificar aplicando SOLID, tipagem estrita e diagnóstico prévio. +3. **Validação de Usabilidade**: Verificar se a interface e contratos atendem às heurísticas de UX e feedback visual. + +## Impacto + +Garante soluções robustas, sustentáveis no longo prazo, escaláveis e alinhadas aos mais altos padrões globais de tecnologia e experiência do usuário.