# Changelog — ampmInsights (pacote cliente)

Todas as mudanças notáveis deste pacote (`ampmInsights_V1_Cliente`) ficam registradas aqui.
Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) e
[Versionamento Semântico](https://semver.org/lang/pt-BR/) (`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.