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>
Adiciona TASKS.md: tracking de sprint v1.4.0 via Git, substitui Kanban DB/APEX
2026-09-09 11:21:20 -03:00 · 2026-09-09 11:05:14 -03:00 · 2026-08-12 09:55:42 -03:00 · 2026-07-31 17:11:18 -03:00 · 2026-07-24 17:39:39 -03:00 · 2026-07-24 15:20:32 -03:00
15 changed files with 685 additions and 61 deletions
--- a/.gitignore
+++ b/.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
--- a/Artefatos/template_limpo_ampm/DL_TECH_CMDB_V1_AMPM.xlsx
+++ b/Artefatos/template_limpo_ampm/DL_TECH_CMDB_V1_AMPM.xlsx
--- a/Artefatos/template_limpo_ampm/DL_TECH_VULNERABILIDADE_V2_AMPM.xlsx
+++ b/Artefatos/template_limpo_ampm/DL_TECH_VULNERABILIDADE_V2_AMPM.xlsx
--- a/CHANGELOG.md
+++ b/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.
+
--- a/docs/02-arquitetura.html
+++ b/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>
--- a/docs/03-pre-requisitos-credenciais.html
+++ b/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>
@@ -98,6 +99,8 @@ Allow group ampminsights-app to read objects in compartment &lt;nome-do-comparti
 <tr><td><code>OCI_REGION</code></td><td>Passo 4 acima (campo <code>region</code>), ex.: <code>sa-saopaulo-1</code>.</td></tr>
 <tr><td><code>OS_NAMESPACE</code></td><td>Passo 6 acima. Só necessário se for usar o modelo ONNX (Seção 4 do script 1).</td></tr>
 <tr><td><code>OS_BUCKET</code></td><td>Nome que você escolher para o bucket que vai criar na Seção 4 do script 1.</td></tr>
+<tr><td><code>GENAI_REGION</code></td><td>Região do OCI Generative AI (Seção 5+) — pode ser diferente de <code>OCI_REGION</code>. Padrão <code>us-chicago-1</code>; troque se sua tenancy não alcançar essa região (ver <a href="09-operacao-observabilidade.html">Operação &amp; observabilidade</a>).</td></tr>
+<tr><td><code>AI_LOG_RETENTION_DAYS</code></td><td>Preenchido automaticamente (90 dias) — dias de retenção do log de chamadas de IA/embeddings.</td></tr>
 <tr><td>Chave privada (.pem)</td><td>Passo 7 acima — colada direto na Seção 3 do script 1, nunca na tabela de configuração.</td></tr>
 <tr><td>Credenciais do export APEX (<code>apex_cred</code>, <code>RAG_CRED</code>, compartimento no remote server <code>apex_genai</code>)</td><td>Mesmos valores de tenancy/compartimento acima — preenchidos na importação do app (ver <a href="05-passo-a-passo-apex.html">Passo a passo: aplicação APEX</a>).</td></tr>
 </table>
--- a/docs/04-passo-a-passo-banco.html
+++ b/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>
@@ -112,9 +113,15 @@ GRANT CREATE CREDENTIAL TO AMPMINSIGHTS;
 GRANT CREATE JOB TO AMPMINSIGHTS;

 -- 1.6) Regras de rede (ACL) para o schema poder chamar o endpoint do OCI
--      Generative AI usado neste script (regiao us-chicago-1). Se voce for
--      usar outra regiao de Generative AI, ajuste o host abaixo (e repita
--      este bloco para cada host adicional que for necessario).
+--      Generative AI usado neste script (regiao us-chicago-1 por padrao - o
+--      mesmo valor que vai para o parametro GENAI_REGION da SECAO 2, que
+--      ainda nao existe neste ponto do script, por isso o host aqui e
+--      digitado direto). Nem toda tenancy alcanca us-chicago-1 (ex.: algumas
+--      tenancies com escopo regional restrito, como America Latina, podem
+--      so alcancar sa-saopaulo-1) - se for o seu caso, troque o host abaixo
+--      pela regiao que a sua tenancy alcanca, E use o mesmo valor no
+--      parametro GENAI_REGION da SECAO 2 (repita este bloco para cada host
+--      adicional que for necessario).
 BEGIN
    DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host       =&gt; &#x27;inference.generativeai.us-chicago-1.oci.oraclecloud.com&#x27;,
@@ -147,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
@@ -217,11 +233,38 @@ INSERT INTO TB_26AI_TECH_PARAMS (PARAM_NAME, PARAM_VALUE, DESCRIPTION) VALUES
  (&#x27;OS_BUCKET&#x27;, &#x27;&lt;SUBSTITUA_PELO_NOME_DO_BUCKET_QUE_VOCE_VAI_CRIAR&gt;&#x27;,
   &#x27;Nome do bucket de Object Storage onde o modelo ONNX sera armazenado (ver SECAO 4).&#x27;);

+INSERT INTO TB_26AI_TECH_PARAMS (PARAM_NAME, PARAM_VALUE, DESCRIPTION) VALUES
+  (&#x27;AI_LOG_RETENTION_DAYS&#x27;, &#x27;90&#x27;,
+   &#x27;Dias de retencao do log de chamadas de IA/embeddings (TB_26AI_TECH_LOG) - ver docs/09-operacao-observabilidade.html para a query de purga.&#x27;);
+
+INSERT INTO TB_26AI_TECH_PARAMS (PARAM_NAME, PARAM_VALUE, DESCRIPTION) VALUES
+  (&#x27;GENAI_REGION&#x27;, &#x27;us-chicago-1&#x27;,
+   &#x27;Regiao do OCI Generative AI usada pelo RAG/insights/embeddings (SECAO 5+). Pode ser diferente da OCI_REGION (que e a regiao &quot;de casa&quot; do seu tenancy/bucket) - o Generative AI so roda em regioes especificas. Se a sua tenancy nao alcancar us-chicago-1 (comum em tenancies com escopo regional restrito, ex. America Latina), troque para uma regiao que a sua tenancy alcance (ex. sa-saopaulo-1) E repita a ACL da SECAO 1.6 para o novo host - confirme antes com &quot;oci generative-ai model-collection list-models&quot; ou o Console OCI que o modelo usado (meta.llama-4-maverick-17b-128e-instruct-fp8) ainda esta ativo para uso on-demand na regiao escolhida, ja que a disponibilidade de modelos varia por regiao e muda com o tempo.&#x27;);
+
 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
@@ -297,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
@@ -532,14 +584,15 @@ criação de um profile de SELECT AI (que já lê região e compartimento da tab
  <pre><code class="lang-sql">-- Rode os 3 blocos abaixo para confirmar que a credencial e a rede estao OK
 -- antes de seguir para as tabelas e o PL/SQL da aplicacao.

-- 5.1) Teste de embedding (Cohere, via OCI Generative AI)
+-- 5.1) Teste de embedding (Cohere, via OCI Generative AI). A URL usa a
+--      regiao configurada em GENAI_REGION (SECAO 2), nao um valor fixo.
 SELECT VECTOR_SERIALIZE(
    DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING(
        TO_CLOB(&#x27;Teste simples para gerar um embedding.&#x27;),
        JSON(&#x27;{
            &quot;provider&quot;: &quot;ocigenai&quot;,
            &quot;credential_name&quot;: &quot;OCI_CRED&quot;,
-            &quot;url&quot;: &quot;https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText&quot;,
+            &quot;url&quot;: &quot;https://inference.generativeai.&#x27; || (SELECT param_value FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;GENAI_REGION&#x27;) || &#x27;.oci.oraclecloud.com/20231130/actions/embedText&quot;,
            &quot;model&quot;: &quot;cohere.embed-v4.0&quot;
        }&#x27;)
    )
@@ -547,13 +600,14 @@ SELECT VECTOR_SERIALIZE(
 ) AS embedding
 FROM dual;

-- 5.2) Teste de geracao de texto (Llama 4, via OCI Generative AI)
+-- 5.2) Teste de geracao de texto (Llama 4, via OCI Generative AI). Mesma
+--      logica: a URL usa a regiao configurada em GENAI_REGION (SECAO 2).
 SELECT DBMS_VECTOR_CHAIN.UTL_TO_GENERATE_TEXT(
    TO_CLOB(&#x27;Responda somente com a palavra: sucesso&#x27;),
    JSON(&#x27;{
        &quot;provider&quot;: &quot;ocigenai&quot;,
        &quot;credential_name&quot;: &quot;OCI_CRED&quot;,
-        &quot;url&quot;: &quot;https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat&quot;,
+        &quot;url&quot;: &quot;https://inference.generativeai.&#x27; || (SELECT param_value FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;GENAI_REGION&#x27;) || &#x27;.oci.oraclecloud.com/20231130/actions/chat&quot;,
        &quot;model&quot;: &quot;meta.llama-4-maverick-17b-128e-instruct-fp8&quot;,
        &quot;chatRequest&quot;: {
            &quot;temperature&quot;: 0.1,
@@ -565,27 +619,28 @@ SELECT DBMS_VECTOR_CHAIN.UTL_TO_GENERATE_TEXT(
 FROM dual;

 -- 5.3) Teste de SELECT AI (perguntas em linguagem natural sobre as views/
--      tabelas do schema). O bloco abaixo le EMBEDDING_COMPARTMENT da tabela
--      de configuracao (SECAO 2). As tabelas/view referenciadas abaixo sao
--      criadas na SECAO 6 - rode este bloco depois de criar V_26AI_TECH e
--      TB_26AI_TECH_CMDB.
+--      tabelas do schema). O bloco abaixo le EMBEDDING_COMPARTMENT e
+--      GENAI_REGION da tabela de configuracao (SECAO 2). As tabelas/view
+--      referenciadas abaixo sao criadas na SECAO 6 - rode este bloco depois
+--      de criar V_26AI_TECH e TB_26AI_TECH_CMDB.
 --
--      A regiao do OCI Generative AI abaixo (us-chicago-1) e fixa de
--      proposito, igual nos testes 5.1/5.2 e na ACL da SECAO 1.6 - nao
--      precisa (nem deve) ser trocada pelo valor de OCI_REGION da tabela de
--      configuracao, ja que o servico so esta disponivel em algumas regioes
--      especificas da OCI.
+--      A regiao do OCI Generative AI abaixo vem do parametro GENAI_REGION -
+--      nao precisa (nem deve) ser trocada pelo valor de OCI_REGION da tabela
+--      de configuracao (sao coisas diferentes de proposito), ja que o
+--      servico so esta disponivel em algumas regioes especificas da OCI.
 DECLARE
-  v_compartment TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
+  v_compartment   TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
+  v_genai_region  TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
 BEGIN
-  SELECT param_value INTO v_compartment FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;EMBEDDING_COMPARTMENT&#x27;;
+  SELECT param_value INTO v_compartment  FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;EMBEDDING_COMPARTMENT&#x27;;
+  SELECT param_value INTO v_genai_region FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;GENAI_REGION&#x27;;

  DBMS_CLOUD_AI.CREATE_PROFILE(
    profile_name =&gt; &#x27;OCI_CRED2&#x27;,
    attributes   =&gt; &#x27;{
      &quot;provider&quot;: &quot;oci&quot;,
      &quot;credential_name&quot;: &quot;OCI_CRED&quot;,
-      &quot;region&quot;: &quot;us-chicago-1&quot;,
+      &quot;region&quot;: &quot;&#x27; || v_genai_region || &#x27;&quot;,
      &quot;model&quot;: &quot;meta.llama-4-maverick-17b-128e-instruct-fp8&quot;,
      &quot;temperature&quot;: 0,
      &quot;comments&quot;: true,
@@ -835,19 +890,89 @@ LEFT OUTER JOIN
                     GROUP BY nome
                     HAVING count(1) = 1 )
      ) c
-ON  ( upper(v.ASSET_NAME) = upper(c.nome) AND c.AMBIENTE IS NOT NULL );</code></pre>
+ON  ( upper(v.ASSET_NAME) = upper(c.nome) AND c.AMBIENTE IS NOT NULL );
+
+-- Log de chamadas de IA/embeddings (sucesso e erro) - nao guarda prompt/
+-- resposta completos, so metadados de uso. Ver docs/09-operacao-observabilidade.html.
+CREATE TABLE &quot;TB_26AI_TECH_LOG&quot;
+   (	&quot;LOG_ID&quot; NUMBER GENERATED ALWAYS AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER  NOCYCLE  NOKEEP  NOSCALE  NOT NULL ENABLE,
+	&quot;LOG_TS&quot; TIMESTAMP(6) WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL ENABLE,
+	&quot;CALLING_OBJECT&quot; VARCHAR2(128),
+	&quot;OPERATION&quot; VARCHAR2(30),
+	&quot;SOURCE_TYPE&quot; VARCHAR2(10),
+	&quot;SOURCE_ID&quot; VARCHAR2(200),
+	&quot;PROVIDER&quot; VARCHAR2(30),
+	&quot;MODEL_NAME&quot; VARCHAR2(100),
+	&quot;APP_USER&quot; VARCHAR2(100),
+	&quot;STATUS&quot; VARCHAR2(10),
+	&quot;ERROR_CODE&quot; NUMBER,
+	&quot;ERROR_MESSAGE&quot; VARCHAR2(4000),
+	&quot;DURATION_MS&quot; NUMBER,
+	&quot;PROMPT_CHARS&quot; NUMBER,
+	&quot;RESPONSE_CHARS&quot; NUMBER,
+	 CONSTRAINT &quot;TB_26AI_TECH_LOG_PK&quot; PRIMARY KEY (&quot;LOG_ID&quot;) USING INDEX ENABLE
+   );
+
+CREATE INDEX &quot;TB_26AI_TECH_LOG_TS_IX&quot; ON &quot;TB_26AI_TECH_LOG&quot; (&quot;LOG_TS&quot;);
+CREATE INDEX &quot;TB_26AI_TECH_LOG_ST_IX&quot; ON &quot;TB_26AI_TECH_LOG&quot; (&quot;STATUS&quot;,&quot;LOG_TS&quot;);
+
+COMMENT ON TABLE &quot;TB_26AI_TECH_LOG&quot; IS &#x27;Log de cada chamada a Generative AI/embeddings feita pelo ampmInsights (sucesso ou erro) - nao guarda prompt/resposta completos, so metadados de uso (modelo, duracao, tamanho, status, erro). Usada para troubleshooting e monitoramento de consumo - ver docs/09-operacao-observabilidade.html.&#x27;;</code></pre>
 </div>
 <h2>Seção 7 &middot; PL/SQL de geracao de embeddings, RAG e insights (ampmInsights)</h2>
-<p>Cria as funções e a procedure descritas em <a href="02-arquitetura.html">Arquitetura</a>:
-<code>fnc_26ai_embed</code>, <code>fnc_26ai_tech_rag</code>, <code>FNC_26AI_TECH_MCP_V1</code>,
-<code>FNC_26ai_rag</code> e <code>prc_26ai_tech</code>. É um bloco longo (a maior parte é o texto dos
-prompts de IA) — copie e cole inteiro de uma vez.</p>
+<p>Cria <code>PRC_26AI_TECH_LOG</code> (log de cada chamada de IA/embedding — ver
+<a href="09-operacao-observabilidade.html">Operação &amp; observabilidade</a>) e as funções e a
+procedure descritas em <a href="02-arquitetura.html">Arquitetura</a>: <code>fnc_26ai_embed</code>,
+<code>fnc_26ai_tech_rag</code>, <code>FNC_26AI_TECH_MCP_V1</code>, <code>FNC_26ai_rag</code> e
+<code>prc_26ai_tech</code>. É um bloco longo (a maior parte é o texto dos prompts de IA) — copie e
+cole inteiro de uma vez.</p>
 <div class="code-block">
  <div class="code-bar">
    <span class="code-label">Seção 7 — copiar e colar</span>
    <button class="copy-btn" type="button">Copiar</button>
  </div>
-  <pre><code class="lang-sql">CREATE OR REPLACE FUNCTION fnc_26ai_embed( p_string      IN VARCHAR2,
+  <pre><code class="lang-sql">CREATE OR REPLACE PROCEDURE PRC_26AI_TECH_LOG (
+  p_calling_object  IN VARCHAR2,
+  p_operation       IN VARCHAR2,
+  p_status          IN VARCHAR2,
+  p_source_type     IN VARCHAR2 DEFAULT NULL,
+  p_source_id       IN VARCHAR2 DEFAULT NULL,
+  p_provider        IN VARCHAR2 DEFAULT NULL,
+  p_model_name      IN VARCHAR2 DEFAULT NULL,
+  p_error_code      IN NUMBER   DEFAULT NULL,
+  p_error_message   IN VARCHAR2 DEFAULT NULL,
+  p_duration_ms     IN NUMBER   DEFAULT NULL,
+  p_prompt_chars    IN NUMBER   DEFAULT NULL,
+  p_response_chars  IN NUMBER   DEFAULT NULL
+) AS
+  PRAGMA AUTONOMOUS_TRANSACTION;
+/*
+  Projeto: ampmInsights
+  Objetivo: registrar em TB_26AI_TECH_LOG cada chamada a Generative AI/
+            embeddings (sucesso ou erro), para troubleshooting e
+            monitoramento de consumo (ver docs/09-operacao-observabilidade.html).
+  Autonomous transaction: pode ser chamada de dentro de functions invocadas
+  em contexto SQL sem interferir na transacao do chamador; nunca propaga erro
+  (uma falha ao logar nao pode derrubar a chamada real de IA).
+*/
+BEGIN
+  INSERT INTO TB_26AI_TECH_LOG (
+    calling_object, operation, source_type, source_id, provider, model_name,
+    app_user, status, error_code, error_message, duration_ms, prompt_chars,
+    response_chars
+  ) VALUES (
+    p_calling_object, p_operation, p_source_type, p_source_id, p_provider,
+    p_model_name, NVL(V(&#x27;APP_USER&#x27;), SYS_CONTEXT(&#x27;USERENV&#x27;,&#x27;SESSION_USER&#x27;)),
+    p_status, p_error_code, SUBSTR(p_error_message, 1, 4000), p_duration_ms,
+    p_prompt_chars, p_response_chars
+  );
+  COMMIT;
+EXCEPTION
+  WHEN OTHERS THEN
+    NULL; -- logging nunca pode quebrar a chamada real
+END;
+/
+
+CREATE OR REPLACE FUNCTION fnc_26ai_embed( p_string      IN VARCHAR2,
                                            p_emb_type    IN VARCHAR2 DEFAULT &#x27;COHERE&#x27;,
                                            p_credential  IN VARCHAR2 DEFAULT &#x27;OCI_CRED&#x27;)
 RETURN CLOB
@@ -891,7 +1016,7 @@ BEGIN
                        dbms_vector_chain.utl_to_text( v_string ),
 					     json(&#x27;{    &quot;provider&quot;: &quot;ocigenai&quot;,
                                &quot;credential_name&quot;: &quot;&#x27; || p_credential || &#x27;&quot;,
-                                &quot;url&quot;: &quot;https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText&quot;,
+                                &quot;url&quot;: &quot;https://inference.generativeai.&#x27; || (SELECT param_value FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;GENAI_REGION&#x27;) || &#x27;.oci.oraclecloud.com/20231130/actions/embedText&quot;,
                                &quot;model&quot;: &quot;cohere.embed-v4.0&quot;
                            }&#x27;)
                )
@@ -929,12 +1054,34 @@ BEGIN
 				EXCEPTION
 					WHEN OTHERS THEN
 					   DBMS_OUTPUT.PUT_LINE(&#x27;Erro: &#x27; || SQLCODE || &#x27; - &#x27; || SQLERRM);
+					   PRC_26AI_TECH_LOG(
+					     p_calling_object =&gt; &#x27;FNC_26AI_EMBED&#x27;,
+					     p_operation      =&gt; &#x27;EMBEDDING&#x27;,
+					     p_status         =&gt; &#x27;ERROR&#x27;,
+					     p_provider       =&gt; &#x27;vLLM&#x27;,
+					     p_error_code     =&gt; SQLCODE,
+					     p_error_message  =&gt; SQLERRM
+					   );
 				END;

    END IF;

 	RETURN v_embedding;

+EXCEPTION
+  WHEN OTHERS THEN
+    -- Cobre os ramos ONNX/COHERE (o vLLM ja trata e loga o proprio erro
+    -- acima e nao propaga). Loga e repropaga sem mudar o comportamento
+    -- existente.
+    PRC_26AI_TECH_LOG(
+      p_calling_object =&gt; &#x27;FNC_26AI_EMBED&#x27;,
+      p_operation      =&gt; &#x27;EMBEDDING&#x27;,
+      p_status         =&gt; &#x27;ERROR&#x27;,
+      p_provider       =&gt; p_emb_type,
+      p_error_code     =&gt; SQLCODE,
+      p_error_message  =&gt; SQLERRM
+    );
+    RAISE;
 END;
 /

@@ -959,9 +1106,12 @@ RETURN CLOB IS
   output        CLOB;
   query_vec     VECTOR;
   v_llm         VARCHAR2(20) := &#x27;LLAMA4&#x27;; -- [ LLAMA4 | OPENAI ]
+   v_genai_region TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;

 BEGIN

+  SELECT param_value INTO v_genai_region FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;GENAI_REGION&#x27;;
+
  -- embedding da pergunta do usuario
  query_vec := to_vector( fnc_26ai_embed ( p_string =&gt; p_query, p_emb_type =&gt; &#x27;COHERE&#x27; ) ) ;

@@ -987,7 +1137,7 @@ BEGIN
    params_genai := &#x27;{
 		&quot;provider&quot; : &quot;ocigenai&quot;,
     	&quot;credential_name&quot; : &quot;&#x27; || p_credential || &#x27;&quot;,
-		&quot;url&quot; : &quot;https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat&quot;,
+		&quot;url&quot; : &quot;https://inference.generativeai.&#x27; || v_genai_region || &#x27;.oci.oraclecloud.com/20231130/actions/chat&quot;,
 		&quot;model&quot;: &quot;meta.llama-4-maverick-17b-128e-instruct-fp8&quot;}&#x27;;

  ELSIF v_llm = &#x27;OPENAI&#x27; THEN
@@ -1055,6 +1205,20 @@ Formato obrigatorio de saida:

   RETURN output;

+EXCEPTION
+  WHEN OTHERS THEN
+    -- Nao havia handler antes; loga e repropaga (comportamento de
+    -- propagar o erro ao chamador continua o mesmo).
+    PRC_26AI_TECH_LOG(
+      p_calling_object =&gt; &#x27;FNC_26AI_TECH_RAG&#x27;,
+      p_operation      =&gt; &#x27;RAG&#x27;,
+      p_status         =&gt; &#x27;ERROR&#x27;,
+      p_source_type    =&gt; p_source_type,
+      p_provider       =&gt; &#x27;ocigenai&#x27;,
+      p_error_code     =&gt; SQLCODE,
+      p_error_message  =&gt; SQLERRM
+    );
+    RAISE;
 END;
 /

@@ -1087,10 +1251,16 @@ RETURN CLOB AS
  Objetivo: funcao global de chamada ao LLM (Llama 4, via OCI Generative AI)
            usada pelo RAG e pela geracao de insights.
 */
-      v_gen_ai_endpoint VARCHAR2(500) := &#x27;https://inference.generativeai.us-chicago-1.oci.oraclecloud.com&#x27;;
+      v_gen_ai_endpoint VARCHAR2(500);
      v_gen_ai_model    VARCHAR2(500) := &#x27;meta.llama-4-maverick-17b-128e-instruct-fp8&#x27;;
      resp DBMS_CLOUD_TYPES.RESP;
+      v_t0     PLS_INTEGER := DBMS_UTILITY.GET_TIME;
+      v_result CLOB;
 BEGIN
+    SELECT &#x27;https://inference.generativeai.&#x27; || param_value || &#x27;.oci.oraclecloud.com&#x27;
+      INTO v_gen_ai_endpoint
+      FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;GENAI_REGION&#x27;;
+
    resp := dbms_cloud.send_request(
        credential_name =&gt; p_oci_cred,
        uri =&gt; v_gen_ai_endpoint || &#x27;/20231130/actions/chat&#x27;,
@@ -1119,10 +1289,34 @@ BEGIN
                        ))
        ))
    );
-    RETURN json_value( dbms_cloud.get_response_text(resp) , &#x27;$.chatResponse.choices[0].message.content[0].text&#x27;) ;
+    v_result := json_value( dbms_cloud.get_response_text(resp) , &#x27;$.chatResponse.choices[0].message.content[0].text&#x27;) ;
+
+    PRC_26AI_TECH_LOG(
+      p_calling_object =&gt; &#x27;FNC_26AI_RAG&#x27;,
+      p_operation      =&gt; &#x27;CHAT&#x27;,
+      p_status         =&gt; &#x27;OK&#x27;,
+      p_provider       =&gt; &#x27;ocigenai&#x27;,
+      p_model_name     =&gt; v_gen_ai_model,
+      p_duration_ms    =&gt; (DBMS_UTILITY.GET_TIME - v_t0) * 10,
+      p_prompt_chars   =&gt; LENGTH(p_ai_prompt),
+      p_response_chars =&gt; LENGTH(v_result)
+    );
+
+    RETURN v_result;

 EXCEPTION
 WHEN OTHERS THEN
+     PRC_26AI_TECH_LOG(
+       p_calling_object =&gt; &#x27;FNC_26AI_RAG&#x27;,
+       p_operation      =&gt; &#x27;CHAT&#x27;,
+       p_status         =&gt; &#x27;ERROR&#x27;,
+       p_provider       =&gt; &#x27;ocigenai&#x27;,
+       p_model_name     =&gt; v_gen_ai_model,
+       p_error_code     =&gt; SQLCODE,
+       p_error_message  =&gt; SQLERRM,
+       p_duration_ms    =&gt; (DBMS_UTILITY.GET_TIME - v_t0) * 10,
+       p_prompt_chars   =&gt; LENGTH(p_ai_prompt)
+     );
     RETURN &#x27;Nao foi possivel gerar um texto com base nas informacoes.&#x27;;
 END;
 /
@@ -1167,8 +1361,11 @@ AS
  v_response        CLOB;
  v_json            CLOB;
  v_error           CLOB;
+  v_genai_region    TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
 BEGIN

+  SELECT param_value INTO v_genai_region FROM TB_26AI_TECH_PARAMS WHERE param_name = &#x27;GENAI_REGION&#x27;;
+
 IF p_source_type = &#x27;VUL&#x27; THEN -- vulnerabilidades

    v_pre_prompt :=&#x27;Voce e um analista senior de dados e operacoes.
@@ -1565,7 +1762,7 @@ Retorne um JSON valido (sem comentarios), espelhando o relatorio:
                           (  v_response ) ,
                        json(&#x27;{ &quot;provider&quot;: &quot;ocigenai&quot;,
                                &quot;credential_name&quot;: &quot;&#x27; || p_oci_cred || &#x27;&quot;,
-                                &quot;url&quot;: &quot;https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText&quot;,
+                                &quot;url&quot;: &quot;https://inference.generativeai.&#x27; || v_genai_region || &#x27;.oci.oraclecloud.com/20231130/actions/embedText&quot;,
                                &quot;model&quot;: &quot;cohere.embed-v4.0&quot;
                            }&#x27;)
                    )
@@ -1579,27 +1776,73 @@ Retorne um JSON valido (sem comentarios), espelhando o relatorio:
                    )
                ) AS et;

+       PRC_26AI_TECH_LOG(
+         p_calling_object =&gt; &#x27;PRC_26AI_TECH&#x27;,
+         p_operation      =&gt; &#x27;EMBEDDING&#x27;,
+         p_status         =&gt; &#x27;OK&#x27;,
+         p_source_type    =&gt; p_source_type,
+         p_source_id      =&gt; p_rowid,
+         p_provider       =&gt; &#x27;ocigenai&#x27;,
+         p_model_name     =&gt; &#x27;cohere.embed-v4.0&#x27;,
+         p_prompt_chars   =&gt; LENGTH(v_response)
+       );
+
    END IF;

+    PRC_26AI_TECH_LOG(
+      p_calling_object =&gt; &#x27;PRC_26AI_TECH&#x27;,
+      p_operation      =&gt; &#x27;INSIGHT_PIPELINE&#x27;,
+      p_status         =&gt; &#x27;OK&#x27;,
+      p_source_type    =&gt; p_source_type,
+      p_source_id      =&gt; p_rowid
+    );
+
    COMMIT;

 EXCEPTION
  WHEN OTHERS THEN
    v_error := sqlerrm;
+    PRC_26AI_TECH_LOG(
+      p_calling_object =&gt; &#x27;PRC_26AI_TECH&#x27;,
+      p_operation      =&gt; &#x27;INSIGHT_PIPELINE&#x27;,
+      p_status         =&gt; &#x27;ERROR&#x27;,
+      p_source_type    =&gt; p_source_type,
+      p_source_id      =&gt; p_rowid,
+      p_error_code     =&gt; SQLCODE,
+      p_error_message  =&gt; v_error
+    );
+    -- Antes, o erro tecnico (sqlerrm) era gravado direto em insight_report e
+    -- ficava visivel pro usuario de negocio no modal. Agora o erro completo
+    -- vai so pro log (TB_26AI_TECH_LOG); o usuario ve uma mensagem amigavel.
    IF p_source_type = &#x27;VUL&#x27; THEN
        UPDATE TB_26AI_TECH_v2
-           SET insight_report = v_error,
+           SET insight_report = &#x27;Nao foi possivel gerar o insight para este registro no momento.&#x27;,
               insight_json =  null
           WHERE rowid = p_rowid;
    ELSIF p_source_type = &#x27;SYS&#x27; THEN
        UPDATE TB_26AI_TECH_SYS
-           SET insight_report = v_error,
+           SET insight_report = &#x27;Nao foi possivel gerar o insight para este registro no momento.&#x27;,
               insight_json =  null
           WHERE rowid = p_rowid;
    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
--- a/docs/05-passo-a-passo-apex.html
+++ b/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>
--- a/docs/06-validacao-testes.html
+++ b/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>
--- a/docs/07-seguranca-boas-praticas.html
+++ b/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>
--- a/docs/08-glossario-roadmap.html
+++ b/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>
--- a/docs/09-operacao-observabilidade.html
+++ b/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>
@@ -50,7 +51,10 @@ rapidamente qualquer problema, e o checklist abaixo para os casos mais comuns.</
 <tr><td><code>ORA-00942</code> em qualquer objeto <code>TB_26AI_TECH_*</code></td><td>Conectado como <code>ADMIN</code> em vez de <code>AMPMINSIGHTS</code>.</td><td>Rode <code>SELECT USER FROM DUAL;</code> — tem que voltar <code>AMPMINSIGHTS</code>. Reconecte e repita a seção que falhou.</td></tr>
 <tr><td>"AI Insight"/chat sempre retorna um texto genérico de indisponibilidade</td><td>Credencial <code>OCI_CRED</code> ausente ou quebrada.</td><td><code>SELECT credential_name FROM user_credentials WHERE credential_name = 'OCI_CRED';</code> — se não retornar linha, refaça a Seção 3 conectado como <code>AMPMINSIGHTS</code>. Depois, confira o motivo exato na consulta de "Erros recentes" abaixo.</td></tr>
 <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 em vez da região do Generative AI.</td><td>A região do Generative AI já vem fixa (<code>us-chicago-1</code>) na Seção 5.3 do <a href="04-passo-a-passo-banco.html">Passo a passo: banco de dados</a> — não troque pelo valor de <code>OCI_REGION</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>

@@ -126,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>
@@ -144,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>
--- a/docs/10-carga-cmdb-vulnerabilidades.html
+++ b/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>
--- a/docs/index.html
+++ b/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>
--- a/sql/01_ampminsights_db_setup.sql
+++ b/sql/01_ampminsights_db_setup.sql
@@ -103,9 +103,15 @@ GRANT CREATE CREDENTIAL TO AMPMINSIGHTS;
 GRANT CREATE JOB TO AMPMINSIGHTS;

 -- 1.6) Regras de rede (ACL) para o schema poder chamar o endpoint do OCI
--      Generative AI usado neste script (regiao us-chicago-1). Se voce for
--      usar outra regiao de Generative AI, ajuste o host abaixo (e repita
--      este bloco para cada host adicional que for necessario).
+--      Generative AI usado neste script (regiao us-chicago-1 por padrao - o
+--      mesmo valor que vai para o parametro GENAI_REGION da SECAO 2, que
+--      ainda nao existe neste ponto do script, por isso o host aqui e
+--      digitado direto). Nem toda tenancy alcanca us-chicago-1 (ex.: algumas
+--      tenancies com escopo regional restrito, como America Latina, podem
+--      so alcancar sa-saopaulo-1) - se for o seu caso, troque o host abaixo
+--      pela regiao que a sua tenancy alcanca, E use o mesmo valor no
+--      parametro GENAI_REGION da SECAO 2 (repita este bloco para cada host
+--      adicional que for necessario).
 BEGIN
    DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host       => 'inference.generativeai.us-chicago-1.oci.oraclecloud.com',
@@ -139,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.



@@ -201,12 +216,35 @@ INSERT INTO TB_26AI_TECH_PARAMS (PARAM_NAME, PARAM_VALUE, DESCRIPTION) VALUES
  ('AI_LOG_RETENTION_DAYS', '90',
   'Dias de retencao do log de chamadas de IA/embeddings (TB_26AI_TECH_LOG) - ver docs/09-operacao-observabilidade.html para a query de purga.');

+INSERT INTO TB_26AI_TECH_PARAMS (PARAM_NAME, PARAM_VALUE, DESCRIPTION) VALUES
+  ('GENAI_REGION', 'us-chicago-1',
+   'Regiao do OCI Generative AI usada pelo RAG/insights/embeddings (SECAO 5+). Pode ser diferente da OCI_REGION (que e a regiao "de casa" do seu tenancy/bucket) - o Generative AI so roda em regioes especificas. Se a sua tenancy nao alcancar us-chicago-1 (comum em tenancies com escopo regional restrito, ex. America Latina), troque para uma regiao que a sua tenancy alcance (ex. sa-saopaulo-1) E repita a ACL da SECAO 1.6 para o novo host - confirme antes com "oci generative-ai model-collection list-models" ou o Console OCI que o modelo usado (meta.llama-4-maverick-17b-128e-instruct-fp8) ainda esta ativo para uso on-demand na regiao escolhida, ja que a disponibilidade de modelos varia por regiao e muda com o tempo.');
+
 COMMIT;

 -- Confira: nenhuma linha abaixo deve ainda mostrar um valor "<SUBSTITUA...>"
 -- 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');
+


 --------------------------------------------------------------------------------
@@ -271,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.
+


 --------------------------------------------------------------------------------
@@ -340,14 +387,15 @@ WHERE  model_name = 'CLIP_VIT_LARGE_PATCH14_TXT';
 -- Rode os 3 blocos abaixo para confirmar que a credencial e a rede estao OK
 -- antes de seguir para as tabelas e o PL/SQL da aplicacao.

-- 5.1) Teste de embedding (Cohere, via OCI Generative AI)
+-- 5.1) Teste de embedding (Cohere, via OCI Generative AI). A URL usa a
+--      regiao configurada em GENAI_REGION (SECAO 2), nao um valor fixo.
 SELECT VECTOR_SERIALIZE(
    DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING(
        TO_CLOB('Teste simples para gerar um embedding.'),
        JSON('{
            "provider": "ocigenai",
            "credential_name": "OCI_CRED",
-            "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText",
+            "url": "https://inference.generativeai.' || (SELECT param_value FROM TB_26AI_TECH_PARAMS WHERE param_name = 'GENAI_REGION') || '.oci.oraclecloud.com/20231130/actions/embedText",
            "model": "cohere.embed-v4.0"
        }')
    )
@@ -355,13 +403,14 @@ SELECT VECTOR_SERIALIZE(
 ) AS embedding
 FROM dual;

-- 5.2) Teste de geracao de texto (Llama 4, via OCI Generative AI)
+-- 5.2) Teste de geracao de texto (Llama 4, via OCI Generative AI). Mesma
+--      logica: a URL usa a regiao configurada em GENAI_REGION (SECAO 2).
 SELECT DBMS_VECTOR_CHAIN.UTL_TO_GENERATE_TEXT(
    TO_CLOB('Responda somente com a palavra: sucesso'),
    JSON('{
        "provider": "ocigenai",
        "credential_name": "OCI_CRED",
-        "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat",
+        "url": "https://inference.generativeai.' || (SELECT param_value FROM TB_26AI_TECH_PARAMS WHERE param_name = 'GENAI_REGION') || '.oci.oraclecloud.com/20231130/actions/chat",
        "model": "meta.llama-4-maverick-17b-128e-instruct-fp8",
        "chatRequest": {
            "temperature": 0.1,
@@ -373,27 +422,28 @@ SELECT DBMS_VECTOR_CHAIN.UTL_TO_GENERATE_TEXT(
 FROM dual;

 -- 5.3) Teste de SELECT AI (perguntas em linguagem natural sobre as views/
--      tabelas do schema). O bloco abaixo le EMBEDDING_COMPARTMENT da tabela
--      de configuracao (SECAO 2). As tabelas/view referenciadas abaixo sao
--      criadas na SECAO 6 - rode este bloco depois de criar V_26AI_TECH e
--      TB_26AI_TECH_CMDB.
+--      tabelas do schema). O bloco abaixo le EMBEDDING_COMPARTMENT e
+--      GENAI_REGION da tabela de configuracao (SECAO 2). As tabelas/view
+--      referenciadas abaixo sao criadas na SECAO 6 - rode este bloco depois
+--      de criar V_26AI_TECH e TB_26AI_TECH_CMDB.
 --
--      A regiao do OCI Generative AI abaixo (us-chicago-1) e fixa de
--      proposito, igual nos testes 5.1/5.2 e na ACL da SECAO 1.6 - nao
--      precisa (nem deve) ser trocada pelo valor de OCI_REGION da tabela de
--      configuracao, ja que o servico so esta disponivel em algumas regioes
--      especificas da OCI.
+--      A regiao do OCI Generative AI abaixo vem do parametro GENAI_REGION -
+--      nao precisa (nem deve) ser trocada pelo valor de OCI_REGION da tabela
+--      de configuracao (sao coisas diferentes de proposito), ja que o
+--      servico so esta disponivel em algumas regioes especificas da OCI.
 DECLARE
-  v_compartment TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
+  v_compartment   TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
+  v_genai_region  TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
 BEGIN
-  SELECT param_value INTO v_compartment FROM TB_26AI_TECH_PARAMS WHERE param_name = 'EMBEDDING_COMPARTMENT';
+  SELECT param_value INTO v_compartment  FROM TB_26AI_TECH_PARAMS WHERE param_name = 'EMBEDDING_COMPARTMENT';
+  SELECT param_value INTO v_genai_region FROM TB_26AI_TECH_PARAMS WHERE param_name = 'GENAI_REGION';

  DBMS_CLOUD_AI.CREATE_PROFILE(
    profile_name => 'OCI_CRED2',
    attributes   => '{
      "provider": "oci",
      "credential_name": "OCI_CRED",
-      "region": "us-chicago-1",
+      "region": "' || v_genai_region || '",
      "model": "meta.llama-4-maverick-17b-128e-instruct-fp8",
      "temperature": 0,
      "comments": true,
@@ -752,7 +802,7 @@ BEGIN
                        dbms_vector_chain.utl_to_text( v_string ),
 					     json('{    "provider": "ocigenai",
                                "credential_name": "' || p_credential || '",
-                                "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText",
+                                "url": "https://inference.generativeai.' || (SELECT param_value FROM TB_26AI_TECH_PARAMS WHERE param_name = 'GENAI_REGION') || '.oci.oraclecloud.com/20231130/actions/embedText",
                                "model": "cohere.embed-v4.0"
                            }')
                )
@@ -842,9 +892,12 @@ RETURN CLOB IS
   output        CLOB;
   query_vec     VECTOR;
   v_llm         VARCHAR2(20) := 'LLAMA4'; -- [ LLAMA4 | OPENAI ]
+   v_genai_region TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;

 BEGIN

+  SELECT param_value INTO v_genai_region FROM TB_26AI_TECH_PARAMS WHERE param_name = 'GENAI_REGION';
+
  -- embedding da pergunta do usuario
  query_vec := to_vector( fnc_26ai_embed ( p_string => p_query, p_emb_type => 'COHERE' ) ) ;

@@ -870,7 +923,7 @@ BEGIN
    params_genai := '{
 		"provider" : "ocigenai",
     	"credential_name" : "' || p_credential || '",
-		"url" : "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat",
+		"url" : "https://inference.generativeai.' || v_genai_region || '.oci.oraclecloud.com/20231130/actions/chat",
 		"model": "meta.llama-4-maverick-17b-128e-instruct-fp8"}';

  ELSIF v_llm = 'OPENAI' THEN
@@ -984,12 +1037,16 @@ RETURN CLOB AS
  Objetivo: funcao global de chamada ao LLM (Llama 4, via OCI Generative AI)
            usada pelo RAG e pela geracao de insights.
 */
-      v_gen_ai_endpoint VARCHAR2(500) := 'https://inference.generativeai.us-chicago-1.oci.oraclecloud.com';
+      v_gen_ai_endpoint VARCHAR2(500);
      v_gen_ai_model    VARCHAR2(500) := 'meta.llama-4-maverick-17b-128e-instruct-fp8';
      resp DBMS_CLOUD_TYPES.RESP;
      v_t0     PLS_INTEGER := DBMS_UTILITY.GET_TIME;
      v_result CLOB;
 BEGIN
+    SELECT 'https://inference.generativeai.' || param_value || '.oci.oraclecloud.com'
+      INTO v_gen_ai_endpoint
+      FROM TB_26AI_TECH_PARAMS WHERE param_name = 'GENAI_REGION';
+
    resp := dbms_cloud.send_request(
        credential_name => p_oci_cred,
        uri => v_gen_ai_endpoint || '/20231130/actions/chat',
@@ -1090,8 +1147,11 @@ AS
  v_response        CLOB;
  v_json            CLOB;
  v_error           CLOB;
+  v_genai_region    TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
 BEGIN

+  SELECT param_value INTO v_genai_region FROM TB_26AI_TECH_PARAMS WHERE param_name = 'GENAI_REGION';
+
 IF p_source_type = 'VUL' THEN -- vulnerabilidades

    v_pre_prompt :='Voce e um analista senior de dados e operacoes.
@@ -1488,7 +1548,7 @@ Retorne um JSON valido (sem comentarios), espelhando o relatorio:
                           (  v_response ) ,
                        json('{ "provider": "ocigenai",
                                "credential_name": "' || p_oci_cred || '",
-                                "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText",
+                                "url": "https://inference.generativeai.' || v_genai_region || '.oci.oraclecloud.com/20231130/actions/embedText",
                                "model": "cohere.embed-v4.0"
                            }')
                    )
@@ -1555,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;
+


 --------------------------------------------------------------------------------
Author	SHA1	Message	Date
Antonio Sergio Rodrigues Figueiredo	caf43a9d7d	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>	2026-09-09 11:21:20 -03:00
Antonio Sergio Rodrigues Figueiredo	16aca0a657	Adiciona TASKS.md: tracking de sprint v1.4.0 via Git, substitui Kanban DB/APEX - Migra o board de tarefas de TB_26AI_TECH_SPRINT_KANBAN (tabela ADB, dropada) + tentativa de região Kanban no App Builder para um checklist versionado neste repo. - Replaneja as 13 tarefas substantivas do sprint v1.4.0 (nenhuma entregue no ciclo anterior de 13/08-02/09) a partir de 09/09. - Registra como concluído/abandonado o experimento de export de página via SQLcl (f100_page_11.sql/.zip, removidos, nunca commitados). - Lista separadamente as pendências de carga v1.3.0 ainda abertas no CHANGELOG (não fazem parte do escopo v1.4.0). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-09-09 11:05:14 -03:00
Antonio Sergio Rodrigues Figueiredo	7a1bbbcb68	Adiciona CHANGELOG.md formalizando as versoes v1.0.0-v1.3.0 e abre v1.4.0 Consolida em um so lugar o que mudou em cada tag ja existente. Abre a secao "Nao lancado / v1.4.0 em andamento" com o escopo combinado: fechar a validacao da carga de CMDB/Vulnerabilidades (uploads, checagem visual, e os 4 pontos em aberto - registros #DUP, colunas sem fonte no export, ativos sem match) antes de repetir a carga no ambiente real do cliente. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-12 09:55:42 -03:00
Antonio Sergio Rodrigues Figueiredo	32b3c23362	Adiciona guia de carga de CMDB/Vulnerabilidades + templates sanitizados Nova pagina docs/10-carga-cmdb-vulnerabilidades.html documentando como filtrar e mapear novas cargas de CMDB (ServiceNow) e vulnerabilidades (Tenable) pra manter o ambiente com dados exclusivos da AM/PM - o export bruto do grupo Ultrapar traz Ipiranga/Ultrapar/Iconic misturados, e a coluna "company"/"empresa" do export nao e confiavel (~40% das linhas marcadas AMPM tinham nome de servidor de outra empresa); o criterio usado e o prefixo do nome do servidor (AM...). Inclui os dois templates finais ja sanitizados e com cabecalho mapeado pro formato esperado pelos perfis de carga do APEX (DL_TECH_CMDB_V1 e DL_TECH_VULNERABILIDADE_V2): Artefatos/template_limpo_ampm/_AMPM.xlsx. .gitignore atualizado pra nunca versionar os exports brutos/intermediarios (contem dados reais de outras empresas do grupo) - so os _AMPM.xlsx finais sao rastreados. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-31 17:11:18 -03:00
Antonio Sergio Rodrigues Figueiredo	1c607f3f72	Adiciona criterios de validacao apos cada etapa critica Depois de uma sessao de troubleshooting real (schema errado, tipo de OCID errado, credencial com valor velho, Application Settings do APEX desincronizadas da tabela de config), formaliza cada um desses pontos como uma checagem que roda imediatamente apos a etapa correspondente, em vez de so aparecer como sintoma bem mais tarde: - Entre Secao 1 e 2: confirma que a sessao trocou para AMPMINSIGHTS (SELECT USER FROM DUAL) antes de continuar. - Fim da Secao 2: confere que EMBEDDING_COMPARTMENT/OCI_TENANCY_OCID/ OCI_USER_OCID tem o PREFIXO de OCID certo (nao so que foram preenchidos) - pega o caso real de hoje onde o OCID do Autonomous Database foi colado no lugar do compartimento. - Fim da Secao 3: lembrete de que a credencial precisa ser recriada se EMBEDDING_COMPARTMENT mudar depois dela ja existir. - Fim da Secao 7: confere STATUS = VALID dos 6 objetos novos antes de seguir pra instalacao do APEX. - docs/09: nova secao explicando que a lupa "AI Insight" le credencial/ compartimento/regiao das Application Settings do APEX (Shared Components), nao da TB_26AI_TECH_PARAMS - as duas fontes precisam ser mantidas em sincronia manualmente. Duas linhas novas no checklist de erros comuns. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-24 17:39:39 -03:00
Antonio Sergio Rodrigues Figueiredo	1e9af90582	Torna a regiao do Generative AI configuravel (GENAI_REGION) Region estava fixa em us-chicago-1 em varios pontos (ACL, testes 5.1/5.2/5.3, FNC_26ai_rag, fnc_26ai_tech_rag, fnc_26ai_embed, PRC_26AI_TECH). Tenancies com escopo regional restrito (ex. America Latina) podem nao alcancar essa regiao, mesmo com credencial/ACL/compartimento corretos - o sintoma e ORA-20404 "Object not found" com uma URL bem formada. Novo parametro GENAI_REGION em TB_26AI_TECH_PARAMS (default us-chicago-1, editavel) substitui o valor fixo em todos os pontos de chamada. Seção 1.6 (ACL) continua com host fixo por rodar antes da tabela de config existir, mas o comentario agora aponta para o parametro. docs/09 ganhou uma entrada de checklist nova: ORA-20404 com URL correta pode ser modelo aposentado para uso on-demand na regiao (verificavel via `oci generative-ai model-collection list-models`), nao so credencial/ACL. Seções 6 e 7 de docs/04-passo-a-passo-banco.html tambem foram resincronizadas com o sql/01_ampminsights_db_setup.sql atual (estavam desatualizadas desde a adição do TB_26AI_TECH_LOG). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-24 15:20:32 -03:00