Remove TASKS.md: tracking da v2.0.0 migrou para ampmInsights_V2/

Esta pasta fica congelada como réplica validada, já implementada no
cliente — nenhuma mudança funcional/estrutural a partir de agora. O board
de sprint da v2.0.0 (nova geração) vive em ampmInsights_V2/TASKS.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitignore

@@ -5,3 +5,14 @@
 # Continua no pacote (zip de entrega); ver docs/04-passo-a-passo-banco.html para
 # como gerar/obter o arquivo caso precise recriar esta pasta do zero.
 modelo-onnx/*.onnx
+
+# Exports brutos/intermediarios de CMDB e vulnerabilidades - contem dados
+# reais de OUTRAS empresas do grupo Ultrapar (Ipiranga, Ultrapar, Iconic)
+# antes da sanitizacao por nome de servidor (ver docs/10-carga-cmdb-vulnerabilidades.html).
+# So os arquivos finais _AMPM.xlsx dentro de template_limpo_ampm/ sao
+# rastreados - nunca remova este bloco sem confirmar que os brutos nao vao
+# entrar no historico.
+Artefatos/*.csv
+Artefatos/*.xlsx
+Artefatos/template_limpo_ampm/*.csv
+!Artefatos/template_limpo_ampm/*_AMPM.xlsx

CHANGELOG.md

@@ -0,0 +1,99 @@
+# 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.
+

docs/02-arquitetura.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>

docs/03-pre-requisitos-credenciais.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>

docs/04-passo-a-passo-banco.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>
@@ -153,7 +154,16 @@ WHERE  principal = &#x27;AMPMINSIGHTS&#x27;;
 
 --------------------------------------------------------------------------------
 -- A partir daqui, conecte-se como o usuario AMPMINSIGHTS (nao mais como ADMIN)
---------------------------------------------------------------------------------</code></pre>
+--------------------------------------------------------------------------------
+--
+-- VALIDACAO (rode antes de continuar - erro mais comum deste script):
+SELECT USER FROM DUAL;
+-- Tem que retornar AMPMINSIGHTS. Se retornar ADMIN, voce ainda nao trocou de
+-- usuario/sessao - troque agora, senao a SECAO 2 (e tudo depois) vai falhar
+-- com ORA-00942 (table or view &quot;ADMIN&quot;.&quot;TB_26AI_TECH_PARAMS&quot; does not exist).
+-- No Database Actions/SQL Developer Web, trocar o &quot;schema&quot; num seletor do
+-- Worksheet NAO basta - precisa fazer login de novo com o usuario/senha do
+-- AMPMINSIGHTS.</code></pre>
 </div>
 <h2>Seção 2 &middot; Tabela de configuracao (preencha os valores UMA UNICA VEZ aqui)</h2>
 <p>Agora conecte como o usuário <strong>AMPMINSIGHTS</strong> que você acabou de criar (não mais
@@ -235,7 +245,26 @@ COMMIT;
 
 -- Confira: nenhuma linha abaixo deve ainda mostrar um valor &quot;&lt;SUBSTITUA...&gt;&quot;
 -- antes de voce seguir para a SECAO 3.
-SELECT param_name, param_value, description FROM TB_26AI_TECH_PARAMS ORDER BY param_name;</code></pre>
+SELECT param_name, param_value, description FROM TB_26AI_TECH_PARAMS ORDER BY param_name;
+
+-- VALIDACAO EXTRA: confere que cada OCID e do TIPO certo, nao so que foi
+-- preenchido. Ja aconteceu de EMBEDDING_COMPARTMENT ser preenchido com o
+-- OCID do proprio Autonomous Database (ocid1.autonomousdatabase...) em vez
+-- do compartimento (ocid1.compartment...) - o valor &quot;parece&quot; um OCID valido
+-- e passa despercebido, mas quebra silenciosamente mais tarde (Generative AI
+-- retorna ORA-20404 &quot;Object not found&quot;, dificil de associar a este campo).
+SELECT param_name, param_value,
+       CASE
+         WHEN param_name = &#x27;EMBEDDING_COMPARTMENT&#x27; AND param_value NOT LIKE &#x27;ocid1.compartment.%&#x27;
+           THEN &#x27;ERRO: deveria comecar com ocid1.compartment. - confira se nao colou o OCID do banco/Autonomous Database por engano&#x27;
+         WHEN param_name = &#x27;OCI_TENANCY_OCID&#x27; AND param_value NOT LIKE &#x27;ocid1.tenancy.%&#x27;
+           THEN &#x27;ERRO: deveria comecar com ocid1.tenancy.&#x27;
+         WHEN param_name = &#x27;OCI_USER_OCID&#x27; AND param_value NOT LIKE &#x27;ocid1.user.%&#x27;
+           THEN &#x27;ERRO: deveria comecar com ocid1.user.&#x27;
+         ELSE &#x27;OK&#x27;
+       END AS validacao
+FROM TB_26AI_TECH_PARAMS
+WHERE param_name IN (&#x27;EMBEDDING_COMPARTMENT&#x27;, &#x27;OCI_TENANCY_OCID&#x27;, &#x27;OCI_USER_OCID&#x27;);</code></pre>
 </div>
 <h2>Seção 3 &middot; Credencial de acesso a OCI (Generative AI + Object Storage)</h2>
 <p>Cria a credencial <code>OCI_CRED</code>, usada pelo banco para chamar o OCI Generative AI e o
@@ -311,7 +340,16 @@ END;
 -- Conferir que a credencial foi criada (nao mostra a chave privada)
 SELECT credential_name, username, comments
 FROM   user_credentials
-WHERE  credential_name = &#x27;OCI_CRED&#x27;;</code></pre>
+WHERE  credential_name = &#x27;OCI_CRED&#x27;;
+
+-- VALIDACAO/LEMBRETE: esta credencial grava tenancy/user/compartment por
+-- dentro, NO MOMENTO em que e criada. Se voce corrigir qualquer valor da
+-- SECAO 2 (principalmente EMBEDDING_COMPARTMENT) DEPOIS de ja ter rodado
+-- este bloco, a credencial antiga continua com o valor velho - corrigir a
+-- tabela sozinho NAO conserta. Nesse caso, rode:
+--   BEGIN DBMS_VECTOR_CHAIN.DROP_CREDENTIAL(credential_name =&gt; &#x27;OCI_CRED&#x27;); END;
+--   /
+-- e este bloco de novo, nesta ordem.</code></pre>
 </div>
 <h2>Seção 4 &middot; Modelo de embeddings ONNX</h2>
 <p>Opcional — só necessária se você for usar embeddings de imagem/texto combinados (CLIP). O
@@ -1789,7 +1827,22 @@ EXCEPTION
     END IF;
     COMMIT;
 END;
-/</code></pre>
+/
+
+-- VALIDACAO: confere que todos os objetos desta secao compilaram sem erro
+-- antes de seguir para a instalacao do APEX. Nao vale so olhar se o CREATE
+-- &quot;rodou sem erro na tela&quot; - PL/SQL pode compilar um objeto que chama outro
+-- ainda inexistente sem acusar erro na hora (resolucao adiada de nomes); o
+-- STATUS aqui e a fonte de verdade.
+SELECT object_name, object_type, status
+FROM   user_objects
+WHERE  object_name IN (&#x27;TB_26AI_TECH_LOG&#x27;,&#x27;PRC_26AI_TECH_LOG&#x27;,&#x27;FNC_26AI_EMBED&#x27;,
+                        &#x27;FNC_26AI_TECH_RAG&#x27;,&#x27;FNC_26AI_RAG&#x27;,&#x27;PRC_26AI_TECH&#x27;)
+ORDER  BY object_name;
+-- As 6 linhas tem que aparecer com STATUS = VALID. Se alguma faltar, o
+-- CREATE dela nao rodou (role a secao de novo); se aparecer INVALID, rode
+-- para descobrir o motivo:
+--   SELECT line, position, text FROM user_errors WHERE name = &#x27;&lt;NOME_DO_OBJETO&gt;&#x27; ORDER BY sequence;</code></pre>
 </div>
 <h2>Seção 8 &middot; Instalar a aplicacao APEX (ampmInsights)</h2>
 <p>Últimos passos, agora fora do SQL Worksheet: instalar a aplicação APEX. Detalhado em

docs/05-passo-a-passo-apex.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>

docs/06-validacao-testes.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>

docs/07-seguranca-boas-praticas.html

@@ -26,6 +26,7 @@
 <li><a class="active" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>

docs/08-glossario-roadmap.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="active" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>

docs/09-operacao-observabilidade.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="active" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>
@@ -52,6 +53,8 @@ rapidamente qualquer problema, e o checklist abaixo para os casos mais comuns.</
 <tr><td>Erro de rede/timeout ao chamar o Generative AI</td><td>ACL de rede (Seção 1.6) não cobre o host correto.</td><td><code>SELECT host, privilege FROM dba_host_aces WHERE principal = 'AMPMINSIGHTS';</code> — deve listar <code>inference.generativeai.us-chicago-1.oci.oraclecloud.com</code> com <code>RESOLVE</code> e <code>CONNECT</code>.</td></tr>
 <tr><td><code>ORA-20404</code> ("Object not found", domínio <code>oci.my$cloud_domain</code>)</td><td>Perfil de SELECT AI usando a região "de casa" do tenancy (<code>OCI_REGION</code>) em vez da região do Generative AI.</td><td>Use o valor de <code>GENAI_REGION</code> (Seção 2), não <code>OCI_REGION</code> — ver Seção 5.3 do <a href="04-passo-a-passo-banco.html">Passo a passo: banco de dados</a>.</td></tr>
 <tr><td><code>ORA-20404</code> com URL bem formada (região correta no domínio)</td><td>A tenancy não alcança a região configurada em <code>GENAI_REGION</code>, ou o modelo não está mais disponível para uso on-demand nessa região (a disponibilidade de modelos varia por região e muda com o tempo).</td><td>Rode <code>oci generative-ai model-collection list-models --compartment-id &lt;seu-compartimento&gt; --region &lt;regiao-candidata&gt; --capability CHAT --all</code> (ou o Console OCI) e confirme que o modelo usado está <code>ACTIVE</code> e sem <code>time-on-demand-retired</code> preenchido nessa região; ajuste <code>GENAI_REGION</code> (e a ACL da Seção 1.6 para o novo host) para uma região que sua tenancy alcance e que ainda sirva o modelo on-demand.</td></tr>
+<tr><td><code>ORA-20404</code> mesmo com credencial/ACL/região corretos</td><td><code>EMBEDDING_COMPARTMENT</code> preenchido com o OCID errado (ex.: do Autonomous Database em vez do compartimento — os dois "parecem" um OCID válido).</td><td>Confira o prefixo: tem que ser <code>ocid1.compartment....</code>, nunca <code>ocid1.autonomousdatabase....</code>. Se corrigir, recrie a credencial (<code>OCI_CRED</code>) — ela grava o compartimento internamente na criação.</td></tr>
+<tr><td>Lupa do "AI Insight" falha mesmo com tudo certo em <code>TB_26AI_TECH_PARAMS</code></td><td><code>COMPARTMENT_ID</code>/<code>OCI_CREDENTIAL</code>/<code>REGION</code> nas Application Settings do APEX (config separada, ver seção abaixo) desatualizados em relação à tabela.</td><td>App Builder → Shared Components → Application Settings — compare com <code>TB_26AI_TECH_PARAMS</code>.</td></tr>
 </table>
 </div>
 
@@ -127,6 +130,27 @@ END;
 /</code></pre>
 </div>
 
+<h2>Application Settings do APEX — uma segunda fonte de configuração</h2>
+<p>A funcionalidade "AI Insight" (lupa na lista de vulnerabilidades) não lê
+<code>EMBEDDING_COMPARTMENT</code> direto de <code>TB_26AI_TECH_PARAMS</code> — o processo da página
+usa <code>apex_app_setting.get_value('OCI_CREDENTIAL')</code> e
+<code>apex_app_setting.get_value('COMPARTMENT_ID')</code>, valores configurados dentro do próprio
+APEX (App Builder → Shared Components → Application Settings), separados da tabela de configuração
+do banco.</p>
+<div class="table-wrap">
+<table>
+<tr><th>Application Setting (APEX)</th><th>Deve bater com</th></tr>
+<tr><td><code>OCI_CREDENTIAL</code></td><td><code>OCI_CRED</code> (nome da credencial da Seção 3)</td></tr>
+<tr><td><code>COMPARTMENT_ID</code></td><td>o mesmo valor de <code>EMBEDDING_COMPARTMENT</code> em <code>TB_26AI_TECH_PARAMS</code></td></tr>
+<tr><td><code>REGION</code></td><td>o mesmo valor de <code>GENAI_REGION</code> em <code>TB_26AI_TECH_PARAMS</code></td></tr>
+</table>
+</div>
+<p>Confira direto no App Builder: abra a aplicação → <strong>Shared Components</strong> →
+<strong>Application Settings</strong>, e compare os três valores acima com a
+<code>TB_26AI_TECH_PARAMS</code> atual. Sempre que corrigir <code>EMBEDDING_COMPARTMENT</code> ou
+<code>GENAI_REGION</code> no banco, atualize também aqui — são dois lugares de armazenamento
+independentes, corrigir um não corrige o outro.</p>
+
 <h2>Ferramentas nativas — sem código novo</h2>
 <div class="grid">
   <div class="card"><h4>ADB Performance Hub</h4><p>Saúde do banco (CPU, I/O, sessões, SQL Monitor) direto no Console OCI, sem instrumentação extra.</p></div>
@@ -145,7 +169,7 @@ END;
   — não deve retornar linha depois que o processamento terminar.</p>
 </div>
 
-    <div class="pillnav"><a class="prev" href="08-glossario-roadmap.html">&larr; Glossário & roadmap</a></div>
+    <div class="pillnav"><a class="prev" href="08-glossario-roadmap.html">&larr; Glossário & roadmap</a><a class="next" href="10-carga-cmdb-vulnerabilidades.html">Carga: CMDB & Vulnerabilidades &rarr;</a></div>
   </main>
 </div>
 <script src="assets/main.js"></script>

docs/10-carga-cmdb-vulnerabilidades.html

@@ -0,0 +1,162 @@
+<!DOCTYPE html>
+<html lang="pt-BR">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ampmInsights &middot; Carga de dados: CMDB e Vulnerabilidades</title>
+<meta name="description" content="Como preparar e subir novas cargas de CMDB (ServiceNow) e vulnerabilidades (Tenable) só com dados da AM/PM.">
+<link rel="stylesheet" href="assets/main.css">
+</head>
+<body>
+<div class="layout">
+  <aside class="sidebar">
+    <div class="brand">
+      <span class="oracle">ORACLE</span>
+      <span class="name">ampmInsights</span>
+    </div>
+    <button class="menu-toggle" type="button">Menu &#9776;</button>
+    <div class="kicker">Documentação V1 &middot; AM/PM</div>
+    <ul class="nav-list">
+      <li><a class="" href="index.html"><span class="step-no">1</span>Visão geral</a></li>
+<li><a class="" href="02-arquitetura.html"><span class="step-no">2</span>Arquitetura</a></li>
+<li><a class="" href="03-pre-requisitos-credenciais.html"><span class="step-no">3</span>Pré-requisitos & credenciais</a></li>
+<li><a class="" href="04-passo-a-passo-banco.html"><span class="step-no">4</span>Passo a passo: banco de dados</a></li>
+<li><a class="" href="05-passo-a-passo-apex.html"><span class="step-no">5</span>Passo a passo: aplicação APEX</a></li>
+<li><a class="" href="06-validacao-testes.html"><span class="step-no">6</span>Validação & testes</a></li>
+<li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
+<li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
+<li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="active" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
+    </ul>
+    <div class="sidebar-footer">
+      Vulnerability &amp; Audit AI Insights<br>
+      Oracle AI Database 26ai &middot; AI Vector Search<br>
+      Versão V1 &middot; ambiente reprodutível do cliente
+    </div>
+  </aside>
+  <main class="content">
+    <p class="page-kicker">Carga de dados</p>
+    <h1>Carga de dados: CMDB e Vulnerabilidades</h1>
+    <p class="lede">Guia rápido para preparar e subir novas cargas de CMDB (ServiceNow) e de vulnerabilidades (Tenable), garantindo que só entram dados da AM/PM.</p>
+
+<div class="callout danger">
+  <div class="callout-title">Por que filtrar antes de subir</div>
+  <p>O ServiceNow e o Tenable do grupo Ultrapar são compartilhados entre todas as empresas
+  (Ipiranga, Ultrapar, Iconic, AM/PM). Um export "bruto" do CMDB ou do Tenable traz ativos de
+  <strong>todas</strong> essas empresas misturados — sem filtrar antes de subir, o ambiente da
+  AM/PM passa a exibir servidores e vulnerabilidades de outras empresas do grupo. Siga os passos
+  abaixo em toda carga nova, não só na primeira.</p>
+</div>
+
+<h2>1. Como identificar o que é da AM/PM</h2>
+<p>O campo "Empresa"/"company" do export <strong>não é totalmente confiável</strong> — em uma
+carga real, cerca de 40% das linhas marcadas como AM/PM na verdade tinham nome de servidor no
+padrão de outra empresa do grupo. O critério que funciona é o <strong>nome do servidor</strong>:</p>
+<div class="table-wrap">
+<table>
+<tr><th>Prefixo do nome</th><th>Empresa</th></tr>
+<tr><td><code>AM...</code></td><td>AM/PM — manter</td></tr>
+<tr><td><code>IP...</code> / <code>I2...</code></td><td>Ipiranga — remover</td></tr>
+<tr><td><code>U2...</code></td><td>Ultragaz — remover</td></tr>
+<tr><td>outros/genéricos (ex.: endereço IP, hash, <code>SERV-*</code>)</td><td>revisar manualmente antes de decidir</td></tr>
+</table>
+</div>
+<p><strong>Regra prática no Excel:</strong> filtre a coluna de nome do servidor pra manter só
+linhas que <em>começam com</em> <code>AM</code> (não importa o que a coluna "Empresa" diga) e
+apague o restante. Revise manualmente linhas com nome fora desse padrão antes de decidir incluir
+ou não — nunca confie só na coluna "Empresa".</p>
+
+<h2>2. Mapeamento de colunas — CMDB</h2>
+<p>O arquivo de CMDB do ServiceNow vem com nomes de coluna em inglês; a carga no ampmInsights
+espera um <strong>XLSX</strong> com os cabeçalhos exatamente como na tabela abaixo (renomeie as
+colunas no Excel antes de subir):</p>
+<div class="table-wrap">
+<table>
+<tr><th>Coluna no export ServiceNow</th><th>Renomear para (cabeçalho esperado)</th></tr>
+<tr><td><code>name</code></td><td><code>NOME</code></td></tr>
+<tr><td><code>operational_status</code></td><td><code>STATUS_OPERACIONAL</code></td></tr>
+<tr><td><code>short_description</code></td><td><code>DESCRIÇÃO</code></td></tr>
+<tr><td><code>environment</code></td><td><code>AMBIENTE</code></td></tr>
+<tr><td><code>company</code></td><td><code>EMPRESA</code> (revise pelo nome do servidor, não copie direto)</td></tr>
+<tr><td><code>managed_by_group</code></td><td><code>GERENCIADO_PELO_GRUPO</code></td></tr>
+<tr><td><code>assignment_group</code></td><td><code>GRUPO_RESPONSÁVEL</code></td></tr>
+<tr><td><code>u_safe_box</code></td><td><code>COFRE</code> (converter Verdadeiro/Falso(a) para 1/0)</td></tr>
+<tr><td><code>u_sox</code></td><td><code>SOX</code> (converter Verdadeiro/Falso(a) para 1/0)</td></tr>
+<tr><td><code>u_tipo_de_rede</code></td><td><code>TIPO_DE_REDE</code></td></tr>
+<tr><td><code>u_grupo_resp_assignment_group</code></td><td><code>GRUPOS_RESPONSÁVEIS</code></td></tr>
+<tr><td><code>u_tenable</code></td><td><code>TENABLE</code> (converter Verdadeiro/Falso(a) para 1/0)</td></tr>
+<tr><td><code>u_siem</code></td><td><code>SIEM</code> (converter Verdadeiro/Falso(a) para 1/0)</td></tr>
+<tr><td><em>sem equivalente no export</em></td><td><code>É_VIRTUAL</code>, <code>APPLIANCE</code>, <code>EDR</code> — deixe em branco</td></tr>
+</table>
+</div>
+
+<h2>3. Mapeamento de colunas — Vulnerabilidades</h2>
+<p>O export do Tenable também precisa ter os cabeçalhos renomeados. Use só as colunas abaixo —
+o restante do export do Tenable (CVE, CVSS, solução, etc.) não é usado nesta carga:</p>
+<div class="table-wrap">
+<table>
+<tr><th>Coluna no export Tenable</th><th>Renomear para (cabeçalho esperado)</th></tr>
+<tr><td><code>age_in_days</code></td><td><code>AGE_IN_DAYS</code></td></tr>
+<tr><td><code>asset.display_ipv4_address</code></td><td><code>ASSET_DISPLAY_IPV4_ADDRESS</code></td></tr>
+<tr><td><code>asset.id</code></td><td><code>ASSET_ID</code></td></tr>
+<tr><td><code>asset.name</code></td><td><code>ASSET_NAME</code></td></tr>
+<tr><td><code>asset.tags</code></td><td><code>ASSET_TAGS</code></td></tr>
+<tr><td><code>definition.exploitability_ease</code></td><td><code>DEFINITION_EXPLOITABILITY_EASE</code></td></tr>
+<tr><td><code>definition.family</code></td><td><code>DEFINITION_FAMILY</code></td></tr>
+<tr><td><code>definition.id</code></td><td><code>DEFINITION_ID</code></td></tr>
+<tr><td><code>definition.name</code></td><td><code>DEFINITION_NAME</code></td></tr>
+<tr><td><code>definition.vpr.score</code></td><td><code>DEFINITION_VPR_SCORE</code></td></tr>
+<tr><td><code>first_observed</code></td><td><code>FIRST_OBSERVED</code></td></tr>
+<tr><td><code>id</code></td><td><code>ID</code></td></tr>
+<tr><td><code>last_seen</code></td><td><code>LAST_SEEN</code></td></tr>
+<tr><td><code>output</code></td><td><code>OUTPUT</code></td></tr>
+<tr><td><code>protocol</code></td><td><code>PROTOCOL</code></td></tr>
+<tr><td><code>resurfaced_date</code></td><td><code>RESURFACED_DATE</code></td></tr>
+<tr><td><code>severity</code></td><td><code>SEVERITY</code></td></tr>
+<tr><td><code>state</code></td><td><code>STATE</code></td></tr>
+</table>
+</div>
+<div class="callout warning">
+  <div class="callout-title">Filtre as vulnerabilidades pelo mesmo critério do CMDB</div>
+  <p>Depois de filtrar o CMDB, filtre também o arquivo de vulnerabilidades: mantenha só as linhas
+  cujo <code>ASSET_NAME</code> começa com <code>AM</code> — mesmo critério do passo 1, aplicado
+  aqui pelo nome do ativo em vez do nome do servidor.</p>
+</div>
+
+<h2>4. Passo a passo da carga</h2>
+<ol>
+  <li><strong>Exportar</strong> o CMDB (ServiceNow) e as vulnerabilidades (Tenable) em CSV, como de costume.</li>
+  <li><strong>Filtrar</strong> as duas planilhas pelo critério do passo 1 (nome começa com <code>AM</code>).</li>
+  <li><strong>Renomear as colunas</strong> conforme as tabelas dos passos 2 e 3, e salvar cada planilha como <code>.xlsx</code>.</li>
+  <li><strong>Se for recarregar dados já existentes</strong> (não uma carga inicial), limpe as tabelas antes — peça ao time técnico para rodar:
+    <div class="code-block">
+      <div class="code-bar">
+        <span class="code-label">Limpeza antes de recarregar (time técnico)</span>
+        <button class="copy-btn" type="button">Copiar</button>
+      </div>
+      <pre><code class="lang-sql">DELETE FROM TB_26AI_TECH_VECTOR WHERE source_type = 'VUL';
+DELETE FROM TB_26AI_TECH_V2;
+DELETE FROM TB_26AI_TECH_CMDB;
+COMMIT;</code></pre>
+    </div>
+  </li>
+  <li><strong>Suba o CMDB primeiro</strong>, pelo menu <strong>Upload CMDB</strong> da aplicação.</li>
+  <li><strong>Suba as vulnerabilidades em seguida</strong> (depois do CMDB, pra já aparecer nome/empresa corretos nos insights).</li>
+  <li><strong>Valide</strong>: confira no CMDB que o total de linhas bate com o esperado e que o filtro "Empresa" só mostra AM/PM; confira na tela de Insights que os nomes de servidor são todos padrão <code>AM...</code>.</li>
+</ol>
+
+<div class="callout info">
+  <div class="callout-title">Casos que sempre merecem revisão manual</div>
+  <ul>
+    <li>Nomes com sufixo <code>#DUP</code> — o ServiceNow já marcou como duplicata pendente de revisão.</li>
+    <li>Nomes duplicados exatos na planilha de CMDB — mantenha a linha com status "Operacional" e descarte a outra.</li>
+    <li>Ativos de vulnerabilidade sem correspondência no CMDB filtrado — ficam sem nome/empresa preenchidos nos insights, mas os dados de vulnerabilidade continuam sendo carregados normalmente.</li>
+  </ul>
+</div>
+
+    <div class="pillnav"><a class="prev" href="09-operacao-observabilidade.html">&larr; Operação & observabilidade</a></div>
+  </main>
+</div>
+<script src="assets/main.js"></script>
+</body>
+</html>

docs/index.html

@@ -26,6 +26,7 @@
 <li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
 <li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
 <li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
+<li><a class="" href="10-carga-cmdb-vulnerabilidades.html"><span class="step-no">10</span>Carga: CMDB & Vulnerabilidades</a></li>
     </ul>
     <div class="sidebar-footer">
       Vulnerability &amp; Audit AI Insights<br>

sql/01_ampminsights_db_setup.sql

@@ -145,6 +145,15 @@ WHERE  principal = 'AMPMINSIGHTS';
 --------------------------------------------------------------------------------
 -- A partir daqui, conecte-se como o usuario AMPMINSIGHTS (nao mais como ADMIN)
 --------------------------------------------------------------------------------
+--
+-- VALIDACAO (rode antes de continuar - erro mais comum deste script):
+SELECT USER FROM DUAL;
+-- Tem que retornar AMPMINSIGHTS. Se retornar ADMIN, voce ainda nao trocou de
+-- usuario/sessao - troque agora, senao a SECAO 2 (e tudo depois) vai falhar
+-- com ORA-00942 (table or view "ADMIN"."TB_26AI_TECH_PARAMS" does not exist).
+-- No Database Actions/SQL Developer Web, trocar o "schema" num seletor do
+-- Worksheet NAO basta - precisa fazer login de novo com o usuario/senha do
+-- AMPMINSIGHTS.
 
 
 
@@ -217,6 +226,25 @@ COMMIT;
 -- antes de voce seguir para a SECAO 3.
 SELECT param_name, param_value, description FROM TB_26AI_TECH_PARAMS ORDER BY param_name;
 
+-- VALIDACAO EXTRA: confere que cada OCID e do TIPO certo, nao so que foi
+-- preenchido. Ja aconteceu de EMBEDDING_COMPARTMENT ser preenchido com o
+-- OCID do proprio Autonomous Database (ocid1.autonomousdatabase...) em vez
+-- do compartimento (ocid1.compartment...) - o valor "parece" um OCID valido
+-- e passa despercebido, mas quebra silenciosamente mais tarde (Generative AI
+-- retorna ORA-20404 "Object not found", dificil de associar a este campo).
+SELECT param_name, param_value,
+       CASE
+         WHEN param_name = 'EMBEDDING_COMPARTMENT' AND param_value NOT LIKE 'ocid1.compartment.%'
+           THEN 'ERRO: deveria comecar com ocid1.compartment. - confira se nao colou o OCID do banco/Autonomous Database por engano'
+         WHEN param_name = 'OCI_TENANCY_OCID' AND param_value NOT LIKE 'ocid1.tenancy.%'
+           THEN 'ERRO: deveria comecar com ocid1.tenancy.'
+         WHEN param_name = 'OCI_USER_OCID' AND param_value NOT LIKE 'ocid1.user.%'
+           THEN 'ERRO: deveria comecar com ocid1.user.'
+         ELSE 'OK'
+       END AS validacao
+FROM TB_26AI_TECH_PARAMS
+WHERE param_name IN ('EMBEDDING_COMPARTMENT', 'OCI_TENANCY_OCID', 'OCI_USER_OCID');
+
 
 
 --------------------------------------------------------------------------------
@@ -281,6 +309,15 @@ SELECT credential_name, username, comments
 FROM   user_credentials
 WHERE  credential_name = 'OCI_CRED';
 
+-- VALIDACAO/LEMBRETE: esta credencial grava tenancy/user/compartment por
+-- dentro, NO MOMENTO em que e criada. Se voce corrigir qualquer valor da
+-- SECAO 2 (principalmente EMBEDDING_COMPARTMENT) DEPOIS de ja ter rodado
+-- este bloco, a credencial antiga continua com o valor velho - corrigir a
+-- tabela sozinho NAO conserta. Nesse caso, rode:
+--   BEGIN DBMS_VECTOR_CHAIN.DROP_CREDENTIAL(credential_name => 'OCI_CRED'); END;
+--   /
+-- e este bloco de novo, nesta ordem.
+
 
 
 --------------------------------------------------------------------------------
@@ -1578,6 +1615,21 @@ EXCEPTION
 END;
 /
 
+-- VALIDACAO: confere que todos os objetos desta secao compilaram sem erro
+-- antes de seguir para a instalacao do APEX. Nao vale so olhar se o CREATE
+-- "rodou sem erro na tela" - PL/SQL pode compilar um objeto que chama outro
+-- ainda inexistente sem acusar erro na hora (resolucao adiada de nomes); o
+-- STATUS aqui e a fonte de verdade.
+SELECT object_name, object_type, status
+FROM   user_objects
+WHERE  object_name IN ('TB_26AI_TECH_LOG','PRC_26AI_TECH_LOG','FNC_26AI_EMBED',
+                        'FNC_26AI_TECH_RAG','FNC_26AI_RAG','PRC_26AI_TECH')
+ORDER  BY object_name;
+-- As 6 linhas tem que aparecer com STATUS = VALID. Se alguma faltar, o
+-- CREATE dela nao rodou (role a secao de novo); se aparecer INVALID, rode
+-- para descobrir o motivo:
+--   SELECT line, position, text FROM user_errors WHERE name = '<NOME_DO_OBJETO>' ORDER BY sequence;
+
 
 
 --------------------------------------------------------------------------------