ampmInsights/CHANGELOG.md

Changelog — ampmInsights (pacote cliente)

Todas as mudanças notáveis deste pacote (ampmInsights_V1_Cliente) ficam registradas aqui. Formato baseado em Keep a Changelog e Versionamento Semântico (MAJOR.MINOR.PATCH).

Este pacote é a V1 do ambiente ampmInsights entregue à AM/PM — os números de versão abaixo (v1.x.x) versionam correções/evoluções dentro da V1, não uma nova geração da aplicação.

[Não lançado] — v1.4.0 em andamento

Fechamento da validação de carga de CMDB/Vulnerabilidades iniciada na v1.3.0.

Pendente

• Confirmar upload de DL_TECH_CMDB_V1_AMPM.xlsx no ambiente de teste (esperado: 109 linhas).
• Confirmar upload de DL_TECH_VULNERABILIDADE_V2_AMPM.xlsx (esperado: 1.724 linhas).
• Validar visualmente na tela "Insigths sobre Vulnerabilidades" que só aparecem nomes padrão AM....
• Decidir sobre AMPMOCIVWNSP01#DUP / AMPMOCIVWNSP02#DUP (sufixo #DUP do ServiceNow — duplicata pendente de revisão).
• Confirmar fonte de dados (se houver) para É_VIRTUAL, APPLIANCE, EDR — ficaram em branco por falta de campo equivalente no export do ServiceNow.
• Confirmar se amprotrib (vulnerabilidade sem match no CMDB) e aampmocivlfgap02 (excluído por não bater o padrão AM) são ativos AMPM reais.
• Depois de validado no ambiente de teste, repetir a carga no ambiente real do cliente (primeira carga — sem necessidade de limpeza prévia).

[v1.3.0] — 2026-07-31

Adicionado

• docs/10-carga-cmdb-vulnerabilidades.html: guia de como preparar e subir novas cargas de CMDB (ServiceNow) e vulnerabilidades (Tenable), incluindo o critério de sanitização (nome do servidor, não a coluna "Empresa" do export) e o mapeamento completo de colunas para os dois perfis de carga do APEX (DL_TECH_CMDB_V1, DL_TECH_VULNERABILIDADE_V2).
• Artefatos/template_limpo_ampm/DL_TECH_CMDB_V1_AMPM.xlsx e DL_TECH_VULNERABILIDADE_V2_AMPM.xlsx — templates finais, já filtrados e com cabeçalho no formato esperado pela carga.

Corrigido

• Export bruto do grupo Ultrapar (ServiceNow/Tenable compartilhados) misturava dados de outras empresas (Ipiranga, Ultrapar, Iconic) com os da AM/PM; a coluna "company"/"empresa" do export não é confiável sozinha (~40% das linhas marcadas AMPM tinham nome de servidor de outra empresa) — critério de sanitização definido e aplicado.

Segurança

• .gitignore reforçado para nunca versionar exports brutos/intermediários de CMDB/vulnerabilidades (contêm dados reais de outras empresas do grupo) — só os *_AMPM.xlsx finais são rastreados.

[v1.2.0] — 2026-07-24

Adicionado

• Critérios de validação após cada etapa crítica do 01_ampminsights_db_setup.sql, direto no script (não só documentados à parte):
  • Entre Seção 1→2: confirma troca de sessão para AMPMINSIGHTS antes de continuar.
  • Fim da Seção 2: confere o tipo de cada OCID pelo prefixo (ocid1.compartment. etc.), não só se foi preenchido.
  • Fim da Seção 3: lembrete de recriar a credencial OCI_CRED se o compartimento mudar depois dela já existir.
  • Fim da Seção 7: confere STATUS = VALID dos objetos novos antes de seguir para o APEX.
• docs/09: seção nova sobre as Application Settings do APEX (OCI_CREDENTIAL, COMPARTMENT_ID, REGION) como fonte de configuração separada da TB_26AI_TECH_PARAMS — as duas precisam ser mantidas em sincronia manualmente.

Motivação

Formalizado depois de uma sessão real de troubleshooting (schema errado, tipo de OCID errado, credencial desatualizada, Application Settings fora de sincronia) — cada causa raiz virou uma checagem que roda no momento da etapa, não só um sintoma que aparece bem mais tarde.

[v1.1.0] — 2026-07-24

Alterado

• Região do OCI Generative AI deixou de ser fixa (us-chicago-1) e passou a ser configurável via novo parâmetro GENAI_REGION em TB_26AI_TECH_PARAMS, usado em todos os pontos de chamada (FNC_26ai_rag, fnc_26ai_tech_rag, fnc_26ai_embed, PRC_26AI_TECH, testes 5.1/5.2/5.3). Necessário porque tenancies com escopo regional restrito (ex. América Latina) podem não alcançar us-chicago-1 mesmo com credencial/ACL/compartimento corretos.
• docs/04-passo-a-passo-banco.html (Seções 6 e 7) resincronizada com o .sql — estava desatualizada desde a adição do TB_26AI_TECH_LOG na v1.0.0.

Adicionado

• docs/09: entrada de checklist para ORA-20404 com URL bem formada (modelo aposentado para uso on-demand na região, não só problema de credencial/ACL) — verificável via oci generative-ai model-collection list-models.

[v1.0.0] — 2026-07-24

Baseline: primeira versão do pacote cliente sob controle de versão (git init — antes disso as mudanças não tinham histórico rastreável).

Corrigido

• ORA-54426 no LOAD_ONNX_MODEL_CLOUD: modelo ONNX CLIP convertido corretamente via OML4Py (oml.utils.ONNXPipeline), em vez de um export cru com eixos dinâmicos duplicados.
• ORA-20404 no SELECT AI (Seção 5.3): região do Generative AI corrigida.
• Vazamento de erro técnico (sqlerrm) direto na coluna insight_report, visível ao usuário de negócio — trocado por mensagem amigável, erro completo só no log.
• Job JOB_26AI_TECH_VULNERABILIDADE ("Gerar Insights em Lote") agora se autoencerra quando não há mais registros pendentes, em vez de rodar indefinidamente a cada 20s.

Adicionado

• Observabilidade de IA: tabela TB_26AI_TECH_LOG + procedure PRC_26AI_TECH_LOG, instrumentando todas as chamadas de IA/embeddings (sucesso e erro).
• docs/09-operacao-observabilidade.html: checklist de erros comuns e consultas prontas de troubleshooting/consumo.