Baseline v2.0.0-dev: fork de ampmInsights_V1

- Copia integral de ampmInsights_V1/ (docs/ + sql/), que o usuário confirma
  ser exatamente o que foi usado para construir e implementar
  ampmInsights_V1_Cliente no cliente.
- Traz docs/10-carga-cmdb-vulnerabilidades.html de V1_Cliente (existia lá,
  faltava em V1 — gap de conteúdo, não só de tom).
- Rebrand mecânico 'Documentação V1' -> 'Documentação V2' nas 10 páginas de
  docs + link de navegação para o capítulo 10 adicionado onde faltava.
- ampmInsights_V1/ e ampmInsights_V1_Cliente/ ficam congelados a partir de
  agora (réplica validada, já implementada no cliente) — todo o trabalho de
  v2.0.0 (schema aditivo: ALTER/MERGE, sem DROP) acontece nesta pasta.
- Adiciona TASKS.md e CHANGELOG.md próprios desta geração.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-09 11:21:14 -03:00
commit 24a1c8bb6a
17 changed files with 82082 additions and 0 deletions

109
docs/02-arquitetura.html Normal file
View File

@@ -0,0 +1,109 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Arquitetura</title>
<meta name="description" content="Componentes, objetos de banco e PL/SQL do ambiente ampmInsights sobre Oracle AI Database 26ai.">
<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 V2 &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="active" 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="" 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">Arquitetura</p>
<h1>Como as peças se conectam</h1>
<p class="lede">Do dado bruto ao insight de IA vetorizado e pesquisável — os componentes técnicos do ambiente e o papel de cada objeto de banco.</p>
<div class="diagram">
<div class="node"><strong>CMDB</strong>Ativos/servidores</div>
<div class="node"><strong>Vulnerabilidades</strong>Export Tenable</div>
<div class="node"><strong>Syslog</strong>(opcional)</div>
</div>
<p>As três fontes acima chegam por <em>Data Load</em> da própria aplicação APEX (upload de planilha/CSV)
e alimentam as tabelas técnicas do schema <code>AMPMINSIGHTS</code>.</p>
<h2>Componentes principais</h2>
<div class="table-wrap">
<table>
<tr><th>Componente</th><th>Papel no fluxo</th></tr>
<tr><td>Autonomous Database 26ai</td><td>Hospeda o schema <code>AMPMINSIGHTS</code>: tabelas, view, PL/SQL, credencial OCI e o job de geração de insights.</td></tr>
<tr><td>AI Vector Search (<code>DBMS_VECTOR</code> / <code>DBMS_VECTOR_CHAIN</code>)</td><td>Gera embeddings (Cohere embed-v4, ou ONNX local opcional) e realiza a busca por similaridade usada no RAG.</td></tr>
<tr><td>OCI Generative AI</td><td>Modelo <code>meta.llama-4-maverick-17b-128e-instruct-fp8</code> para geração de texto/insight e <code>cohere.embed-v4.0</code> para embeddings.</td></tr>
<tr><td><code>DBMS_CLOUD_AI</code> (SELECT AI)</td><td>Permite perguntas em linguagem natural diretamente sobre <code>V_26AI_TECH</code> e <code>TB_26AI_TECH_CMDB</code>.</td></tr>
<tr><td>APEX &mdash; ampmInsights (app 100)</td><td>Interface web: cadastro/carga de dados, tabela de achados, chat RAG, disparo do job de geração de insights em lote.</td></tr>
<tr><td><code>DBMS_SCHEDULER</code></td><td>Job criado dinamicamente pela própria aplicação (botão "Gerar Insights em Lote") para processar os registros pendentes.</td></tr>
</table>
</div>
<h2>Objetos de banco (nomes preservados)</h2>
<p>Os nomes abaixo são referenciados diretamente, em dezenas de pontos, pelo export da aplicação
APEX (<code>02_ampminsights_apex_app.sql</code>). Por isso eles <strong>não foram renomeados</strong>
nesta versão V1 — apenas o schema/usuário que os contém mudou de nome.</p>
<div class="table-wrap">
<table>
<tr><th>Objeto</th><th>Tipo</th><th>Uso</th></tr>
<tr><td><code>TB_26AI_TECH_PARAMS</code></td><td>Tabela</td><td>Parâmetros (nome da credencial e OCID do compartimento) lidos por todo o PL/SQL e pelo job em lote.</td></tr>
<tr><td><code>TB_26AI_TECH_CMDB</code></td><td>Tabela</td><td>Ativos/servidores (CMDB).</td></tr>
<tr><td><code>TB_26AI_TECH_V2</code></td><td>Tabela</td><td>Achados de vulnerabilidade (fonte principal) + insight gerado.</td></tr>
<tr><td><code>TB_26AI_TECH</code></td><td>Tabela</td><td>Tabela legada, ainda usada por uma carga/página mais antiga da aplicação.</td></tr>
<tr><td><code>TB_26AI_TECH_SYS</code></td><td>Tabela</td><td>Eventos de syslog (opcional) + insight gerado.</td></tr>
<tr><td><code>TB_26AI_TECH_CHAT</code></td><td>Tabela</td><td>Histórico de interações do chat "fale com os dados".</td></tr>
<tr><td><code>TB_26AI_TECH_VECTOR</code></td><td>Tabela</td><td>Vetores/chunks usados na busca semântica (RAG).</td></tr>
<tr><td><code>V_26AI_TECH</code></td><td>View</td><td>Junta vulnerabilidades + CMDB; usada pela aplicação e pelo profile de SELECT AI.</td></tr>
<tr><td><code>SEQ_26AI_TECH</code> / <code>BIU_TB_26AI_TECH_V2</code></td><td>Sequence / Trigger</td><td>Gera o identificador sequencial de insight (<code>ID_INSIGHT</code>).</td></tr>
</table>
</div>
<h2>PL/SQL de geração de insights e RAG</h2>
<div class="table-wrap">
<table>
<tr><th>Rotina</th><th>Função</th></tr>
<tr><td><code>fnc_26ai_embed</code></td><td>Gera o embedding de um texto (COHERE via OCI Generative AI, ONNX local, ou vLLM self-hosted opcional).</td></tr>
<tr><td><code>fnc_26ai_tech_rag</code></td><td>Busca os trechos mais similares em <code>TB_26AI_TECH_VECTOR</code> e monta a resposta aumentada (RAG) via Llama 4.</td></tr>
<tr><td><code>FNC_26AI_TECH_MCP_V1</code></td><td>Wrapper de <code>fnc_26ai_tech_rag</code> pensado para exposição como ferramenta MCP a um agente externo.</td></tr>
<tr><td><code>FNC_26ai_rag</code></td><td>Chamada genérica ao OCI Generative AI (chat) usada tanto pelo RAG quanto pela geração de insight.</td></tr>
<tr><td><code>prc_26ai_tech</code></td><td>Gera o insight (análise/diagnóstico/recomendações/plano de ação) para um registro e cria o vetor correspondente.</td></tr>
</table>
</div>
<div class="callout info">
<div class="callout-title">Sobre o "job de banco"</div>
<p>Não existe um <code>DBMS_SCHEDULER.CREATE_JOB</code> estático no script de setup: o job
(<code>JOB_26AI_TECH_VULNERABILIDADE</code> / equivalente para syslog) é criado <strong>em tempo de
execução</strong> pela própria aplicação APEX, quando o usuário aciona o botão de processamento em
lote. O job lê o nome da credencial e o OCID do compartimento diretamente de
<code>TB_26AI_TECH_PARAMS</code> — por isso preencher essa tabela corretamente (SEÇÃO 2 do script 1,
a tabela de configuração) é o passo mais crítico de toda a configuração.</p>
</div>
<div class="pillnav"><a class="prev" href="index.html">&larr; Visão geral</a><a class="next" href="03-pre-requisitos-credenciais.html">Pré-requisitos & credenciais &rarr;</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>

View File

@@ -0,0 +1,114 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Pré-requisitos & credenciais</title>
<meta name="description" content="Checklist de pré-requisitos e passo a passo para criar a chave de API OCI usada pelo ampmInsights.">
<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 V2 &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="active" 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="" 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">Antes de começar</p>
<h1>Pré-requisitos e criação de credenciais</h1>
<p class="lede">Nenhuma habilidade prévia é assumida: este é o roteiro completo para gerar, do zero, tudo que os scripts pedem como <SUBSTITUA_...>.</p>
<h2>Checklist de pré-requisitos</h2>
<div class="grid">
<div class="card"><h4>Autonomous Database 26ai</h4><p>Provisionado (ATP/ADW), com acesso ADMIN e AI Vector Search disponível.</p></div>
<div class="card"><h4>Acesso ao Console OCI</h4><p>Usuário com permissão para criar API Signing Key no compartimento correto.</p></div>
<div class="card"><h4>Política IAM</h4><p>Uso do Generative AI e leitura de objetos no bucket do modelo ONNX (se for usar).</p></div>
<div class="card"><h4>Região com Generative AI</h4><p>Confirme que a região do seu tenancy oferece o OCI Generative AI (ex.: us-chicago-1 ou sa-saopaulo-1, conforme disponibilidade).</p></div>
<div class="card"><h4>Cliente SQL</h4><p>Database Actions (SQL Worksheet), SQL Developer ou SQLcl para rodar os scripts.</p></div>
<div class="card"><h4>Workspace APEX</h4><p>Um workspace disponível (ou permissão para criar um) para instalar a aplicação.</p></div>
</div>
<div class="callout info">
<div class="callout-title">Você preenche cada valor uma única vez</div>
<p>Todo OCID/região/bucket coletado nesta página é digitado <strong>uma única vez</strong>, na
tabela de configuração criada na Seção 2 do <code>01_ampminsights_db_setup.sql</code>. Os blocos
seguintes do script (credencial, modelo ONNX, SELECT AI) leem esses valores automaticamente — você
não precisa repetir nenhum OCID em vários lugares do arquivo.</p>
</div>
<h2>Passo a passo: criar a chave de API da OCI</h2>
<p>Esta chave autentica o banco de dados para chamar o OCI Generative AI (e, opcionalmente, o Object
Storage). É o único pré-requisito "manual" fora do banco de dados.</p>
<ol class="steps">
<li><h4>Abrir "User settings"</h4><p>No Console OCI, clique no seu avatar/usuário (canto superior direito) e selecione "User settings" — ou peça a um administrador OCI para gerar a chave para o usuário/service account que a aplicação vai usar.</p></li>
<li><h4>Adicionar API key</h4><p>No menu lateral, clique em "API keys" e depois em "Add API key".</p></li>
<li><h4>Gerar o par de chaves</h4><p>Selecione "Generate API key pair", clique em "Download private key" (baixa um arquivo <code>.pem</code>) e depois em "Add".</p></li>
<li><h4>Guardar os 4 valores</h4><p>A tela final mostra um "Configuration file preview" com <code>user</code>, <code>fingerprint</code>, <code>tenancy</code> e <code>region</code>. Guarde esses 4 valores — eles vão para a tabela de configuração (Seção 2 do script 1).</p></li>
<li><h4>Obter o OCID do compartimento</h4><p>Identity &amp; Security &rarr; Compartments &rarr; abra o compartimento do banco &rarr; copie o OCID no topo da página.</p></li>
<li><h4>Obter o namespace do Object Storage</h4><p>Console OCI &rarr; Storage &rarr; Buckets &rarr; o "Namespace" aparece no topo da página, independente de qual bucket você abrir. Só necessário se for usar o modelo ONNX (Seção 4 do script 1).</p></li>
<li><h4>Copiar o conteúdo da chave privada</h4><p>Abra o arquivo <code>.pem</code> em um editor de texto simples e copie todo o conteúdo, incluindo as linhas <code>BEGIN/END PRIVATE KEY</code> e as quebras de linha originais. Este é o único valor que <strong>não</strong> vai para a tabela de configuração — ele é colado direto no bloco da Seção 3, na hora de criar a credencial.</p></li>
</ol>
<div class="callout danger">
<div class="callout-title">Trate a chave privada como uma senha</div>
<p>Não envie o arquivo <code>.pem</code> por e-mail ou chat, não o suba para repositórios de código
e restrinja a política IAM do usuário ao mínimo necessário. Depois de criar a credencial no banco
(script 1, Seção 3), o arquivo local pode ser apagado com segurança — o Autonomous Database guarda a
chave de forma criptografada e ela não aparece em nenhuma consulta.</p>
</div>
<h2>Exemplo de política IAM mínima</h2>
<div class="code-block">
<div class="code-bar">
<span class="code-label">Política IAM</span>
<button class="copy-btn" type="button">Copiar</button>
</div>
<pre><code class="lang-sql">Allow group ampminsights-app to use generative-ai-family in compartment &lt;nome-do-compartimento&gt;
Allow group ampminsights-app to read objects in compartment &lt;nome-do-compartimento&gt; where target.bucket.name=&#x27;&lt;seu-bucket-onnx&gt;&#x27;</code></pre>
</div>
<h2>Onde cada valor da tabela de configuração é preenchido</h2>
<div class="table-wrap">
<table>
<tr><th>Campo (PARAM_NAME)</th><th>Onde obter</th></tr>
<tr><td><code>EMBEDDING_COMPARTMENT</code></td><td>Passo 5 acima (OCID do compartimento do banco).</td></tr>
<tr><td><code>OCI_TENANCY_OCID</code></td><td>Passo 4 acima (campo <code>tenancy</code>).</td></tr>
<tr><td><code>OCI_USER_OCID</code></td><td>Passo 4 acima (campo <code>user</code>).</td></tr>
<tr><td><code>OCI_FINGERPRINT</code></td><td>Passo 4 acima (campo <code>fingerprint</code>).</td></tr>
<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>
</div>
<div class="pillnav"><a class="prev" href="02-arquitetura.html">&larr; Arquitetura</a><a class="next" href="04-passo-a-passo-banco.html">Passo a passo: banco de dados &rarr;</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,79 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Passo a passo da aplicação APEX</title>
<meta name="description" content="Como importar e configurar a aplicação APEX ampmInsights (app 100).">
<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 V2 &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="active" 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="" 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">Script 2 de 2</p>
<h1>Passo a passo: aplicação APEX</h1>
<p class="lede">Importação, configuração de credenciais do APEX e primeira carga de dados da aplicação ampmInsights.</p>
<ol class="steps">
<li><h4>Criar (ou reutilizar) um workspace APEX</h4><p>No serviço APEX do Autonomous Database, crie um workspace e associe o schema <code>AMPMINSIGHTS</code> criado no script 1.</p></li>
<li><h4>Acessar o workspace</h4><p>Faça login no App Builder com um usuário de desenvolvedor do workspace.</p></li>
<li><h4>Importar o app</h4><p>App Builder &rarr; Import &rarr; selecione <code>sql/02_ampminsights_apex_app.sql</code>.</p></li>
<li><h4>Instalar</h4><p>Na tela de instalação, confirme que o <strong>parsing schema</strong> é <code>AMPMINSIGHTS</code> e finalize com "Run and Build".</p></li>
<li><h4>Preencher credenciais/remote servers do APEX</h4><p>Em Shared Components &rarr; Credentials, edite <code>apex_cred</code> e <code>RAG_CRED</code> com o OCID do tenancy. Em Shared Components &rarr; Remote Servers, edite <code>apex_genai</code> e ajuste o <code>compartmentId</code> em "AI Attributes" para o OCID real do compartimento.</p></li>
<li><h4>Executar a aplicação</h4><p>Abra a aplicação 100 (ampmInsights) pela primeira vez.</p></li>
<li><h4>Carregar CMDB</h4><p>Use a tela de Data Load de CMDB para subir a planilha/CSV de ativos.</p></li>
<li><h4>Carregar vulnerabilidades</h4><p>Use a tela de Data Load de vulnerabilidades (export do Tenable ou equivalente).</p></li>
<li><h4>Gerar insights em lote</h4><p>Acione o botão de processamento em lote — ele cria um job via <code>DBMS_SCHEDULER</code> que roda <code>PRC_26AI_TECH</code> para os registros pendentes.</p></li>
<li><h4>Testar o chat / RAG</h4><p>Use a tela de "fale com os dados" para validar que a busca semântica está retornando os relatórios corretos.</p></li>
</ol>
<div class="callout info">
<div class="callout-title">Login inicial</div>
<p>A tela de login gera uma senha inicial por usuário e exige troca no primeiro acesso (fluxo já
existente na aplicação). Ajuste o texto de contato exibido na tela de login (atualmente um
placeholder <code>admin@ampminsights.example.com</code>) para o e-mail real da equipe responsável
na AM/PM antes de publicar para os usuários finais.</p>
</div>
<div class="callout danger">
<div class="callout-title">Configurar o domínio de e-mail antes de liberar o cadastro</div>
<p>O fluxo de "solicitar acesso" só cria a conta e envia a senha inicial se o e-mail informado
bater com um domínio específico — no export original, esse domínio estava fixo em
<code>@oracle.com</code>. Foi substituído por
<code>@&lt;SUBSTITUA-PELO-DOMINIO-CORPORATIVO-DA-AMPM.COM.BR&gt;</code>. Antes de divulgar o app aos
usuários finais, edite essa regra (página de solicitação de acesso, ação
"NATIVE_EXECUTE_PLSQL_CODE") com o domínio de e-mail real da AM/PM — do contrário, ninguém
conseguirá se autoprovisionar.</p>
</div>
<div class="pillnav"><a class="prev" href="04-passo-a-passo-banco.html">&larr; Passo a passo: banco de dados</a><a class="next" href="06-validacao-testes.html">Validação & testes &rarr;</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>

View File

@@ -0,0 +1,77 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Validação & testes</title>
<meta name="description" content="Checklist de 15 itens para validar o ambiente ampmInsights antes de enviar ao cliente.">
<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 V2 &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="active" 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="" 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">Antes de enviar ao cliente</p>
<h1>Validação & testes</h1>
<p class="lede">Checklist de ponta a ponta para confirmar que o pacote reproduz o ambiente do zero, sem depender de nada do ambiente original.</p>
<p>Use esta checklist para validar o pacote antes de encaminhá-lo à AM/PM ou à V8 Solution — ideal
para reproduzir tudo do zero em um tenancy/ambiente de teste.</p>
<div class="table-wrap">
<table>
<tr><th>#</th><th>Verificação</th><th>Como confirmar</th><th>Status</th></tr>
<tr><td>1</td><td>Usuário/schema criado</td><td><code>SELECT username FROM all_users WHERE username='AMPMINSIGHTS';</code></td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>2</td><td>ACL de rede liberada</td><td>Consulta da Seção 1.7 retorna o host do Generative AI.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>3</td><td>Credencial OCI_CRED criada</td><td><code>SELECT * FROM user_credentials WHERE credential_name='OCI_CRED';</code></td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>4</td><td>Teste de embedding (Seção 5.1)</td><td>Retorna um vetor sem erro.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>5</td><td>Teste de geração de texto (Seção 5.2)</td><td>Retorna a palavra "sucesso".</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>6</td><td>SELECT AI responde (Seção 5.3)</td><td>Retorna "CONECTADO".</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>7</td><td><code>TB_26AI_TECH_PARAMS</code> preenchida (Seção 2)</td><td><code>EMBEDDING_COMPARTMENT</code> e os demais campos têm valores reais (nenhum <code>&lt;SUBSTITUA...&gt;</code> restante).</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>8</td><td>Tabelas/view/PL·SQL criados sem erro</td><td>Seções 6 e 7 rodam do início ao fim sem <code>ORA-</code>.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>9</td><td>App APEX importado</td><td>Parsing schema = <code>AMPMINSIGHTS</code>, "Run and Build" concluído.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>10</td><td>Credenciais/remote server do APEX preenchidos</td><td><code>apex_cred</code>, <code>RAG_CRED</code>, <code>apex_genai</code> sem OCID de exemplo.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>11</td><td>Carga de CMDB</td><td>Linhas visíveis em <code>TB_26AI_TECH_CMDB</code>.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>12</td><td>Carga de vulnerabilidades</td><td>Linhas visíveis em <code>TB_26AI_TECH_V2</code>.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>13</td><td>Geração de insight em lote</td><td>Job criado, <code>INSIGHT_REPORT</code> preenchido em pelo menos 1 registro.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>14</td><td>Vetor gerado</td><td>Linha correspondente em <code>TB_26AI_TECH_VECTOR</code>.</td><td><span class="badge todo">a validar</span></td></tr>
<tr><td>15</td><td>Chat / RAG responde com evidências</td><td>Pergunta de teste retorna relatório com citação de fonte.</td><td><span class="badge todo">a validar</span></td></tr>
</table>
</div>
<div class="callout success">
<div class="callout-title">Sign-off</div>
<p>Depois de marcar os 15 itens como validados em um ambiente de teste, o pacote está pronto para
ser encaminhado ao cliente. Registre aqui a data e quem validou antes do envio.</p>
</div>
<div class="pillnav"><a class="prev" href="05-passo-a-passo-apex.html">&larr; Passo a passo: aplicação APEX</a><a class="next" href="07-seguranca-boas-praticas.html">Segurança & boas práticas &rarr;</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>

View File

@@ -0,0 +1,95 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Segurança & boas práticas</title>
<meta name="description" content="Recomendações de segurança para o ambiente ampmInsights, incluindo rotação das credenciais originais encontradas em texto puro.">
<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 V2 &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="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>
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">Segurança</p>
<h1>Segurança & boas práticas</h1>
<p class="lede">O que rotacionar do ambiente original, e como manter o novo ambiente do cliente com privilégio mínimo.</p>
<div class="callout danger">
<div class="callout-title">Ação recomendada — credenciais do ambiente original</div>
<p>O arquivo de origem (<code>demo_ampm.sql</code>, fora desta pasta) continha uma chave privada
OCI completa, uma senha de schema e OCIDs de usuário/tenancy/compartimento em texto puro. O export
original da aplicação (<code>VulnerabilityAI-myapp.sql</code>) também continha: dois OCIDs de
tenancy, um OCID de compartimento, e-mails pessoais, e <strong>dois links pré-autenticados (PAR)
do Object Storage</strong> apontando para vídeos de demonstração hospedados em um bucket interno da
Oracle (galeria de vídeos genérica "26ai Demo Hub", sem relação com a AM/PM). Nenhum desses valores
foi trazido para <code>ampmInsights_V1</code>, mas recomenda-se:</p>
<ul>
<li>Revogar/rotacionar, no Console OCI, a API key correspondente à chave privada que estava em <code>demo_ampm.sql</code>.</li>
<li>Trocar a senha do usuário de banco original (se o ambiente de origem continuar em uso).</li>
<li>Revogar/expirar os dois links PAR de Object Storage encontrados no export original (dão acesso de leitura a objetos do bucket sem outra autenticação).</li>
<li>Não incluir <code>demo_ampm.sql</code>, <code>VulnerabilityAI-myapp.sql</code>, <code>Connections.md</code> ou <code>Wallet_ADBJSON.zip</code> (pasta raiz do projeto) em nada que seja enviado ao cliente ou a terceiros — apenas os arquivos desta pasta <code>ampmInsights_V1</code>.</li>
</ul>
</div>
<h2>Boas práticas para o ambiente do cliente</h2>
<div class="grid">
<div class="card"><h4>Privilégio mínimo</h4><p>Restrinja a política IAM da API key ao compartimento e ao bucket estritamente necessários (ver exemplo em Pré-requisitos).</p></div>
<div class="card"><h4>Rotação periódica</h4><p>Defina um ciclo de rotação da API key e da senha do schema <code>AMPMINSIGHTS</code>.</p></div>
<div class="card"><h4>ACL de rede restrita</h4><p>A regra de rede liberada cobre apenas o host de Generative AI necessário — evite abrir hosts adicionais sem necessidade.</p></div>
<div class="card"><h4>Sem segredos em texto puro</h4><p>Nunca deixe a chave privada ou senha do schema em planilhas, chats ou repositórios compartilhados.</p></div>
</div>
<h2>Itens do export original que precisam de atenção do time funcional</h2>
<p>Além de segredos, o export da aplicação continha lógica e textos herdados de um template interno
genérico de demonstração ("26ai Demo Hub"), incompatíveis com a entrega deste ambiente à AM/PM.
Foram ajustados nesta versão, mas revise antes de liberar aos usuários finais:</p>
<ul>
<li><strong>Autoprovisionamento de acesso:</strong> o cadastro automático de novos usuários (com envio de senha inicial por e-mail) estava restrito a e-mails <code>@oracle.com</code>. Foi trocado por um marcador
<code>&lt;SUBSTITUA-PELO-DOMINIO-CORPORATIVO-DA-AMPM.COM.BR&gt;</code> — configure o domínio de e-mail real da AM/PM na página de cadastro antes de liberar o app, ou nenhum usuário da AM/PM conseguirá se autoprovisionar.</li>
<li><strong>Disclaimer de uso:</strong> o texto original dizia "uso restrito a colaboradores Oracle", "não enviar dados reais de clientes" e "nunca compartilhe com clientes" — o oposto do que se aplica aqui, já que este ambiente roda com dados reais da própria AM/PM. O texto foi reescrito para o contexto da AM/PM; revise a redação final com o time de compliance/segurança da informação do cliente.</li>
</ul>
<h2>Sobre a normalização de nome de marca na view</h2>
<p>A view <code>V_26AI_TECH</code> contém duas chamadas <code>REPLACE()</code> que padronizam
os valores de <code>NOME</code>/<code>EMPRESA</code> para "Company" quando o CMDB traz "Ipiranga" ou
"Ampm". Essa lógica veio do ambiente de demonstração original (provavelmente pensada para
apresentações a outros prospects). Como este ambiente V1 é o próprio ambiente da AM/PM, avalie com o
time de negócio se essa normalização ainda faz sentido ou se deve ser removida da view.</p>
<h2>Privacidade dos dados</h2>
<p>As tabelas de vulnerabilidade e CMDB carregam dados reais e sensíveis do ambiente da AM/PM
(inventário de ativos, severidade de vulnerabilidades, criticidade de sistemas). Trate a base
carregada com o mesmo nível de confidencialidade do relatório de origem (Tenable/CMDB), inclusive
em ambientes de teste/demonstração.</p>
<div class="pillnav"><a class="prev" href="06-validacao-testes.html">&larr; Validação & testes</a><a class="next" href="08-glossario-roadmap.html">Glossário & roadmap &rarr;</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>

View File

@@ -0,0 +1,84 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Glossário & roadmap</title>
<meta name="description" content="Glossário de termos técnicos e roadmap da jornada Agentic AI para o ambiente ampmInsights.">
<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 V2 &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="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>
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">Referência</p>
<h1>Glossário & roadmap</h1>
<p class="lede">Termos usados neste pacote, limitações conhecidas herdadas do ambiente original e como este V1 se encaixa na jornada Agentic AI.</p>
<h2>Glossário</h2>
<div class="table-wrap">
<table>
<tr><th>Termo</th><th>Significado</th></tr>
<tr><td>RAG</td><td>Retrieval-Augmented Generation — busca os trechos mais relevantes (por similaridade vetorial) e usa esse contexto para o LLM responder com evidências.</td></tr>
<tr><td>Embedding</td><td>Representação numérica (vetor) de um texto, usada para medir similaridade semântica.</td></tr>
<tr><td>Chunk</td><td>Trecho de texto em que um documento/relatório é dividido antes de ser vetorizado.</td></tr>
<tr><td>ONNX</td><td>Formato aberto de modelo de IA; usado aqui para carregar um modelo de embeddings local (opcional) no banco.</td></tr>
<tr><td>SELECT AI</td><td>Recurso do Autonomous Database (<code>DBMS_CLOUD_AI</code>) que traduz perguntas em linguagem natural para SQL sobre um conjunto de objetos aprovado.</td></tr>
<tr><td>MCP</td><td>Model Context Protocol — padrão para expor funções/dados como ferramentas de um agente de IA externo.</td></tr>
<tr><td>VPR</td><td>Vulnerability Priority Rating (Tenable) — pontuação de priorização de risco de uma vulnerabilidade.</td></tr>
<tr><td>CMDB</td><td>Configuration Management Database — inventário de ativos/servidores e seus atributos.</td></tr>
<tr><td>ACL de rede</td><td>Regra do Autonomous Database que autoriza um schema a chamar um host externo específico.</td></tr>
<tr><td>ORDS</td><td>Oracle REST Data Services — expõe o schema via REST.</td></tr>
</table>
</div>
<h2>Limitações conhecidas (herdadas do ambiente original)</h2>
<ul>
<li>Vetores em <code>TB_26AI_TECH_VECTOR</code> não são removidos automaticamente ao reprocessar um insight já existente — avaliar rotina de limpeza antes de reprocessar em massa.</li>
<li>A carga de dados atual é "append": recarregar um arquivo já carregado pode duplicar linhas e afetar contagens/indicadores. Um processo de MERGE/UPSERT é uma evolução recomendada.</li>
</ul>
<h2>Roadmap (jornada Agentic AI &mdash; documento em construção)</h2>
<p>O parceiro <strong>V8 Solution</strong> está estruturando a evolução deste ambiente como uma
jornada em movimentos, documentada em <em>Jornada_AgenticAI.pptx</em> (versão ainda em construção).
Este pacote V1 corresponde ao <strong>Level Zero</strong> dessa jornada: provisionar o Autonomous
Database 26ai, organizar schema/segurança/acesso e deixar o ambiente pronto para os movimentos
seguintes (novas integrações de fontes, agentes especialistas por stack e relatórios técnicos/gerenciais).</p>
<div class="callout info">
<div class="callout-title">Atenção a uma divergência de nome</div>
<p>O rascunho da jornada referencia o schema como <code>DEMO_AMPM</code>. Esta documentação e os
scripts desta pasta padronizaram o schema como <code>AMPMINSIGHTS</code>, conforme solicitado para
este pacote. Alinhe com a V8 Solution qual nome deve prevalecer antes de consolidar a versão final
da jornada.</p>
</div>
<div class="pillnav"><a class="prev" href="07-seguranca-boas-praticas.html">&larr; Segurança & boas práticas</a><a class="next" href="09-operacao-observabilidade.html">Operação & observabilidade &rarr;</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>

View File

@@ -0,0 +1,186 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Operação & observabilidade</title>
<meta name="description" content="Como monitorar consumo e depurar erros de IA/Generative AI no ambiente ampmInsights.">
<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 V2 &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="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>
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">Operação</p>
<h1>Operação & observabilidade</h1>
<p class="lede">Checklist de erros comuns, consultas prontas de troubleshooting/consumo de IA, e onde olhar ferramentas nativas que já vêm sem custo de desenvolvimento.</p>
<p>Esta seção nasceu de um incidente real: o recurso "AI Insight" ficava sempre retornando o texto
genérico de fallback, e não havia nenhum log que revelasse o motivo. Investigando, encontramos duas
causas encadeadas — a Seção 3 (credencial <code>OCI_CRED</code>) tinha sido rodada conectado como
<code>ADMIN</code> em vez de <code>AMPMINSIGHTS</code> (por isso a credencial nunca existiu), e a
função que chama o LLM engolia qualquer erro silenciosamente, sem logar nada. As duas coisas foram
corrigidas: a função agora loga cada chamada (sucesso ou erro) em <code>TB_26AI_TECH_LOG</code>, e
esta página documenta como usar esse log — junto com um checklist dos erros mais comuns — para
nunca mais operar "às cegas".</p>
<h2>Checklist de erros comuns</h2>
<div class="table-wrap">
<table>
<tr><th>Sintoma</th><th>Causa provável</th><th>Como confirmar/corrigir</th></tr>
<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> (aconteceu neste ambiente em 2026-07-24).</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 o texto genérico de fallback</td><td>Credencial <code>OCI_CRED</code> ausente ou quebrada (é o sintoma exato do incidente que originou esta página).</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 (<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, ex. <code>inference.generativeai.us-chicago-1.oci.oraclecloud.com</code>)</td><td>A tenancy não alcança essa região do Generative AI (comum em tenancies com escopo regional restrito, ex. América Latina), ou o modelo configurado não está mais ativo para uso on-demand nessa região — descoberto em 2026-07-24 com <code>meta.llama-4-maverick-17b-128e-instruct-fp8</code>, que estava aposentado on-demand em <code>sa-saopaulo-1</code> desde maio/2025 apesar de ainda aparecer no catálogo.</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 em <code>GENAI_REGION</code> está <code>ACTIVE</code> e sem <code>time-on-demand-retired</code> preenchido; 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>
<h2>O que <code>TB_26AI_TECH_LOG</code> guarda</h2>
<p>Toda chamada a Generative AI/embeddings feita pelas funções <code>FNC_26ai_rag</code>,
<code>fnc_26ai_tech_rag</code>, <code>fnc_26ai_embed</code> e <code>PRC_26AI_TECH</code> grava uma
linha nesta tabela — sucesso ou erro, sem exceção. Guarda metadados de uso (objeto/função de
origem, provider, modelo, duração, tamanho do prompt/resposta em caracteres, usuário, e o
<code>SQLCODE</code>/<code>SQLERRM</code> completo quando há erro) — <strong>deliberadamente não
guarda o prompt ou a resposta completos</strong>, só o tamanho, por privacidade e para não inchar a
tabela.</p>
<h2>Consultas prontas</h2>
<div class="code-block">
<div class="code-bar">
<span class="code-label">Erros recentes (últimas 24h)</span>
<button class="copy-btn" type="button">Copiar</button>
</div>
<pre><code class="lang-sql">SELECT log_ts, calling_object, operation, provider, model_name,
error_code, error_message
FROM TB_26AI_TECH_LOG
WHERE status = 'ERROR'
AND log_ts >= SYSTIMESTAMP - INTERVAL '24' HOUR
ORDER BY log_ts DESC;</code></pre>
</div>
<div class="code-block">
<div class="code-bar">
<span class="code-label">Taxa de erro por dia e por função/modelo</span>
<button class="copy-btn" type="button">Copiar</button>
</div>
<pre><code class="lang-sql">SELECT TRUNC(log_ts) AS dia, calling_object, model_name,
COUNT(*) AS total,
SUM(CASE WHEN status = 'ERROR' THEN 1 ELSE 0 END) AS erros,
ROUND(100 * SUM(CASE WHEN status = 'ERROR' THEN 1 ELSE 0 END) / COUNT(*), 1) AS pct_erro
FROM TB_26AI_TECH_LOG
GROUP BY TRUNC(log_ts), calling_object, model_name
ORDER BY dia DESC, pct_erro DESC;</code></pre>
</div>
<div class="code-block">
<div class="code-bar">
<span class="code-label">Chamadas mais lentas</span>
<button class="copy-btn" type="button">Copiar</button>
</div>
<pre><code class="lang-sql">SELECT log_ts, calling_object, operation, model_name, duration_ms, status
FROM TB_26AI_TECH_LOG
WHERE duration_ms IS NOT NULL
ORDER BY duration_ms DESC
FETCH FIRST 20 ROWS ONLY;</code></pre>
</div>
<div class="code-block">
<div class="code-bar">
<span class="code-label">Qual registro de negócio está falhando</span>
<button class="copy-btn" type="button">Copiar</button>
</div>
<pre><code class="lang-sql">SELECT l.log_ts, l.source_type, l.source_id, l.error_message,
v.asset_name, v.definition_name
FROM TB_26AI_TECH_LOG l
LEFT JOIN TB_26AI_TECH_v2 v ON v.rowid = CHARTOROWID(l.source_id)
WHERE l.status = 'ERROR'
AND l.source_id IS NOT NULL
ORDER BY l.log_ts DESC;</code></pre>
</div>
<div class="code-block">
<div class="code-bar">
<span class="code-label">Purga do log (usa AI_LOG_RETENTION_DAYS)</span>
<button class="copy-btn" type="button">Copiar</button>
</div>
<pre><code class="lang-sql">DECLARE
v_days TB_26AI_TECH_PARAMS.PARAM_VALUE%TYPE;
BEGIN
SELECT param_value INTO v_days FROM TB_26AI_TECH_PARAMS WHERE param_name = 'AI_LOG_RETENTION_DAYS';
DELETE FROM TB_26AI_TECH_LOG WHERE log_ts < SYSTIMESTAMP - NUMTODSINTERVAL(v_days, 'DAY');
COMMIT;
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) <strong>não</strong> lê
<code>EMBEDDING_COMPARTMENT</code> direto de <code>TB_26AI_TECH_PARAMS</code> — o processo da página
81 chama <code>apex_app_setting.get_value('OCI_CREDENTIAL')</code> e
<code>apex_app_setting.get_value('COMPARTMENT_ID')</code>, valores configurados
<strong>dentro do próprio APEX</strong> (App Builder → Shared Components → Application Settings),
totalmente separados da tabela de configuração do banco. Descobrimos isso em 2026-07-24 depois de
corrigir tudo no banco e a lupa continuar falhando — os dois lugares tinham valores diferentes.</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>Não há uma view SQL simples e confiável pra conferir isso via Database Actions (evite adivinhar o
nome — já tentamos <code>apex_application_settings</code> com colunas erradas e perdemos tempo);
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>
<div class="card"><h4>OCI Cost Analysis</h4><p>Custo real do Generative AI, filtrado por serviço/compartimento — complementa o <code>TB_26AI_TECH_LOG</code> (que dá contagem/latência, não valor faturado).</p></div>
<div class="card"><h4>Activity Reports (páginas 10020-10026)</h4><p>Atividade de usuário/sessão e erros não tratados do APEX, já vêm prontas na aplicação (<code>apex_activity_log</code>).</p></div>
</div>
<div class="callout warning">
<div class="callout-title">Job de geração em lote (JOB_26AI_TECH_VULNERABILIDADE)</div>
<p>O botão "Gerar Insights em Lote" cria um job que roda a cada 20 segundos. Antes desta versão,
ele nunca se auto-encerrava — ficava rodando indefinidamente até alguém clicar em "parar",
consumindo chamadas de IA mesmo sem linhas pendentes. Agora ele mesmo verifica, a cada execução,
se ainda há registros com <code>insight_report</code> nulo e se auto-remove
(<code>DBMS_SCHEDULER.stop_job</code>/<code>drop_job</code>) quando não sobra nada para processar.
Confirme isso rodando <code>SELECT job_name, state FROM dba_scheduler_jobs WHERE job_name = 'JOB_26AI_TECH_VULNERABILIDADE';</code>
depois de um lote — não deve mais retornar linha quando o processamento terminar.</p>
</div>
<div class="pillnav"><a class="prev" href="08-glossario-roadmap.html">&larr; Glossário & roadmap</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>

View File

@@ -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 V2 &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>

438
docs/assets/main.css Normal file
View File

@@ -0,0 +1,438 @@
/* ampmInsights V1 - documentation styles
Paleta derivada do Oracle_PPT-template_FY26.pptx (tema "Custom 43"):
accent3 #C74634 (Oracle Red), accent1 #04536F (deep teal),
dk1 #2A2F2F (charcoal), lt2 #FBF9F8 (warm off-white),
accent4 #F0CC71 (gold), accent5 #89B2B0, accent6 #86B596 */
:root {
--red: #C74634;
--red-dark: #a8382a;
--teal: #04536F;
--teal-dark: #063C4E;
--charcoal: #2A2F2F;
--paper: #FBF9F8;
--paper-alt: #F1ECE8;
--gold: #F0CC71;
--sage: #86B596;
--dusty-teal: #89B2B0;
--line: #E2DCD6;
--text: #201E1C;
--text-soft: #55524E;
--card-bg: #FFFFFF;
--code-bg: #22282B;
--code-text: #E7EEF0;
--radius: 10px;
--font-head: Georgia, "Oracle Sans", "Oracle Sans Tab", serif;
--font-body: "Oracle Sans", "Oracle Sans Tab", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
--font-mono: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
}
:root[data-theme="dark"] {
--paper: #1B1E1F;
--paper-alt: #14171A;
--card-bg: #24282A;
--text: #F1ECE8;
--text-soft: #C7C2BC;
--line: #3A3F40;
--code-bg: #101315;
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--paper: #1B1E1F;
--paper-alt: #14171A;
--card-bg: #24282A;
--text: #F1ECE8;
--text-soft: #C7C2BC;
--line: #3A3F40;
--code-bg: #101315;
}
}
* { box-sizing: border-box; }
body {
margin: 0;
font-family: var(--font-body);
background: var(--paper);
color: var(--text);
line-height: 1.55;
}
a { color: var(--teal); }
:root[data-theme="dark"] a, @media (prefers-color-scheme: dark) { }
a:hover { color: var(--red); }
.layout {
display: flex;
min-height: 100vh;
}
/* ---------- Sidebar ---------- */
.sidebar {
width: 272px;
flex: 0 0 272px;
background: var(--charcoal);
color: #EFECE8;
padding: 20px 16px 32px;
position: sticky;
top: 0;
height: 100vh;
overflow-y: auto;
}
.brand {
display: flex;
align-items: baseline;
gap: 8px;
padding: 6px 8px 18px;
border-bottom: 2px solid var(--red);
margin-bottom: 16px;
}
.brand .oracle {
font-weight: 700;
letter-spacing: 0.06em;
color: var(--red);
font-size: 13px;
}
.brand .name {
font-family: var(--font-head);
font-size: 19px;
color: #fff;
}
.sidebar .kicker {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.08em;
color: #9FB3B8;
padding: 14px 8px 6px;
}
.nav-list { list-style: none; margin: 0; padding: 0; }
.nav-list li { margin: 2px 0; }
.nav-list a {
display: block;
padding: 9px 10px;
border-radius: 8px;
color: #D8D4CF;
text-decoration: none;
font-size: 14.5px;
border-left: 3px solid transparent;
}
.nav-list a:hover { background: rgba(255,255,255,0.06); color: #fff; }
.nav-list a.active {
background: rgba(199,70,52,0.18);
color: #fff;
border-left-color: var(--red);
font-weight: 600;
}
.nav-list .step-no {
display: inline-block;
width: 20px;
color: var(--gold);
font-variant-numeric: tabular-nums;
}
.sidebar-footer {
margin-top: 24px;
padding: 12px 10px 0;
border-top: 1px solid rgba(255,255,255,0.12);
font-size: 11.5px;
color: #9C9793;
}
/* ---------- Main content ---------- */
.content {
flex: 1;
min-width: 0;
padding: 40px clamp(20px, 5vw, 64px) 80px;
max-width: 980px;
}
.page-kicker {
text-transform: uppercase;
letter-spacing: 0.10em;
font-size: 12px;
color: var(--red);
font-weight: 700;
margin: 0 0 6px;
}
h1 {
font-family: var(--font-head);
font-size: clamp(28px, 3.4vw, 38px);
margin: 0 0 10px;
color: var(--text);
}
h1 + .lede {
font-size: 17px;
color: var(--text-soft);
max-width: 68ch;
margin-bottom: 30px;
}
h2 {
font-family: var(--font-head);
font-size: 23px;
margin: 46px 0 14px;
padding-bottom: 8px;
border-bottom: 1px solid var(--line);
color: var(--teal-dark);
}
:root[data-theme="dark"] h2 { color: var(--dusty-teal); }
h3 {
font-size: 17.5px;
margin: 28px 0 10px;
color: var(--text);
}
p { color: var(--text); max-width: 74ch; }
.content ul, .content ol { max-width: 74ch; }
.content li { margin-bottom: 6px; }
code {
font-family: var(--font-mono);
background: var(--paper-alt);
border: 1px solid var(--line);
padding: 1px 5px;
border-radius: 4px;
font-size: 0.88em;
}
pre {
background: var(--code-bg);
color: var(--code-text);
border-radius: var(--radius);
padding: 16px 18px;
overflow-x: auto;
font-size: 13px;
line-height: 1.55;
margin: 14px 0 22px;
}
pre code { background: none; border: none; padding: 0; color: inherit; }
/* ---------- Copyable code blocks ---------- */
.code-block {
max-width: none;
margin: 14px 0 22px;
border-radius: var(--radius);
overflow: hidden;
border: 1px solid var(--line);
}
.code-block .code-bar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 10px;
background: #171b1d;
color: #B9C4C7;
padding: 8px 12px;
font-size: 12px;
}
.code-block .code-label {
font-weight: 700;
letter-spacing: 0.03em;
text-transform: uppercase;
font-size: 11px;
color: #9FB3B8;
}
.code-block pre {
margin: 0;
border-radius: 0;
}
.copy-btn {
border: 1px solid rgba(255,255,255,0.18);
background: rgba(255,255,255,0.06);
color: #EFECE8;
font-family: var(--font-body);
font-size: 12px;
font-weight: 600;
padding: 5px 12px;
border-radius: 999px;
cursor: pointer;
display: inline-flex;
align-items: center;
gap: 6px;
transition: background 0.15s ease;
}
.copy-btn:hover { background: rgba(255,255,255,0.14); }
.copy-btn:focus-visible { outline: 2px solid var(--gold); outline-offset: 2px; }
.copy-btn.copied { background: var(--sage); border-color: var(--sage); color: #10231a; }
/* ---------- Callouts ---------- */
.callout {
border-radius: var(--radius);
padding: 16px 18px;
margin: 18px 0 22px;
border: 1px solid var(--line);
background: var(--card-bg);
max-width: 74ch;
}
.callout .callout-title {
font-weight: 700;
font-size: 13px;
text-transform: uppercase;
letter-spacing: 0.05em;
margin-bottom: 6px;
display: flex;
align-items: center;
gap: 8px;
}
.callout.info { border-left: 4px solid var(--teal); }
.callout.info .callout-title { color: var(--teal-dark); }
.callout.warning { border-left: 4px solid var(--gold); background: color-mix(in srgb, var(--gold) 10%, var(--card-bg)); }
.callout.warning .callout-title { color: #8a6a10; }
.callout.danger { border-left: 4px solid var(--red); background: color-mix(in srgb, var(--red) 7%, var(--card-bg)); }
.callout.danger .callout-title { color: var(--red-dark); }
.callout.success { border-left: 4px solid var(--sage); }
.callout.success .callout-title { color: #2f6b45; }
/* ---------- Cards / grids ---------- */
.grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
gap: 14px;
margin: 18px 0 26px;
}
.card {
background: var(--card-bg);
border: 1px solid var(--line);
border-radius: var(--radius);
padding: 16px 18px;
}
.card h4 {
margin: 0 0 6px;
font-size: 15px;
color: var(--teal-dark);
}
:root[data-theme="dark"] .card h4 { color: var(--dusty-teal); }
.card p { font-size: 14px; color: var(--text-soft); margin: 0; }
.stat {
background: var(--charcoal);
color: #fff;
border-radius: var(--radius);
padding: 16px 14px;
text-align: center;
}
.stat .num { font-family: var(--font-head); font-size: 26px; color: var(--gold); display: block; }
.stat .lbl { font-size: 12px; color: #C9C5C0; }
/* ---------- Steps ---------- */
.steps { counter-reset: step; list-style: none; padding: 0; max-width: 74ch; }
.steps > li {
counter-increment: step;
position: relative;
padding: 4px 0 18px 42px;
border-left: 2px solid var(--line);
margin-left: 14px;
}
.steps > li:last-child { border-left-color: transparent; padding-bottom: 2px; }
.steps > li::before {
content: counter(step);
position: absolute;
left: -15px;
top: 0;
width: 28px;
height: 28px;
border-radius: 50%;
background: var(--red);
color: #fff;
font-weight: 700;
font-size: 13px;
display: flex;
align-items: center;
justify-content: center;
}
.steps h4 { margin: 0 0 4px; font-size: 15.5px; }
.steps p { margin: 0; font-size: 14px; color: var(--text-soft); }
/* ---------- Table ---------- */
.table-wrap { overflow-x: auto; margin: 16px 0 26px; }
table { border-collapse: collapse; width: 100%; min-width: 480px; font-size: 14px; }
th, td { text-align: left; padding: 9px 12px; border-bottom: 1px solid var(--line); }
th { background: var(--paper-alt); font-size: 12.5px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--text-soft); }
tr:last-child td { border-bottom: none; }
.badge {
display: inline-block;
font-size: 11.5px;
font-weight: 700;
padding: 2px 9px;
border-radius: 999px;
letter-spacing: 0.02em;
}
.badge.ok { background: rgba(134,181,150,0.22); color: #2f6b45; }
.badge.todo { background: rgba(240,204,113,0.28); color: #8a6a10; }
.badge.risk { background: rgba(199,70,52,0.16); color: var(--red-dark); }
.pillnav {
display: flex;
justify-content: space-between;
margin-top: 56px;
padding-top: 18px;
border-top: 1px solid var(--line);
font-size: 14px;
}
.pillnav a { text-decoration: none; font-weight: 600; }
.pillnav .next { margin-left: auto; }
/* ---------- Diagram (CSS/SVG based, self-contained) ---------- */
.diagram {
display: flex;
flex-wrap: wrap;
gap: 10px;
align-items: center;
margin: 20px 0 28px;
}
.diagram .node {
background: var(--card-bg);
border: 1px solid var(--line);
border-radius: 10px;
padding: 12px 14px;
font-size: 13px;
min-width: 150px;
text-align: center;
}
.diagram .node.accent { border-color: var(--red); }
.diagram .node strong { display: block; font-size: 13.5px; margin-bottom: 2px; }
.diagram .arrow { color: var(--text-soft); font-size: 20px; }
/* ---------- Mobile nav ---------- */
.menu-toggle { display: none; }
@media (max-width: 880px) {
.layout { flex-direction: column; }
.sidebar {
position: relative;
width: 100%;
flex-basis: auto;
height: auto;
max-height: none;
}
.menu-toggle {
display: block;
background: var(--red);
color: #fff;
border: none;
border-radius: 8px;
padding: 8px 12px;
font-size: 13px;
font-weight: 700;
margin-bottom: 12px;
}
.nav-list { display: none; }
.sidebar.open .nav-list { display: block; }
.content { padding: 28px 18px 60px; }
}

49
docs/assets/main.js Normal file
View File

@@ -0,0 +1,49 @@
document.addEventListener('DOMContentLoaded', function () {
var btn = document.querySelector('.menu-toggle');
var sidebar = document.querySelector('.sidebar');
if (btn && sidebar) {
btn.addEventListener('click', function () {
sidebar.classList.toggle('open');
});
}
document.querySelectorAll('.copy-btn').forEach(function (button) {
button.addEventListener('click', function () {
var block = button.closest('.code-block');
var code = block ? block.querySelector('pre code, pre') : null;
if (!code) return;
var text = code.textContent;
function showCopied() {
var original = button.textContent;
button.textContent = 'Copiado!';
button.classList.add('copied');
setTimeout(function () {
button.textContent = original;
button.classList.remove('copied');
}, 1800);
}
if (navigator.clipboard && navigator.clipboard.writeText) {
navigator.clipboard.writeText(text).then(showCopied, function () {
fallbackCopy(text, showCopied);
});
} else {
fallbackCopy(text, showCopied);
}
});
});
function fallbackCopy(text, done) {
var ta = document.createElement('textarea');
ta.value = text;
ta.style.position = 'fixed';
ta.style.opacity = '0';
document.body.appendChild(ta);
ta.focus();
ta.select();
try { document.execCommand('copy'); } catch (e) { /* no-op */ }
document.body.removeChild(ta);
done();
}
});

116
docs/index.html Normal file
View File

@@ -0,0 +1,116 @@
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ampmInsights &middot; Visão geral</title>
<meta name="description" content="Visão geral do ambiente ampmInsights: AI Vector Search e Agentic AI para gestão de vulnerabilidades sobre Oracle AI Database 26ai.">
<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 V2 &middot; AM/PM</div>
<ul class="nav-list">
<li><a class="active" 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="" 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">ampmInsights &middot; documentação V1</p>
<h1>AI Vector Search e Agentic AI aplicados a vulnerabilidades e auditoria técnica</h1>
<p class="lede">Ambiente de demonstração da AM/PM sobre Oracle AI Database 26ai, adaptado para reprodução independente no tenancy OCI do cliente — sem nenhuma credencial da Oracle.</p>
<div class="callout info">
<div class="callout-title">O que é este pacote (V1)</div>
<p>Esta pasta (<code>ampmInsights_V1</code>) é uma cópia reproduzível do ambiente de demonstração
construído para a AM/PM sobre <strong>Oracle AI Database 26ai</strong>, adaptada para que a própria
AM/PM — ou o parceiro <strong>V8 Solution</strong> — consiga recriar o ambiente do zero em seu
próprio tenancy OCI. Nenhuma credencial, senha, chave privada ou OCID do ambiente original foi
mantida: todo valor que precisa ser preenchido aparece como um marcador
<code>&lt;SUBSTITUA_...&gt;</code>, com instruções completas de como obtê-lo.</p>
</div>
<h2>O que este ambiente faz</h2>
<p>O fluxo, em uma frase: depois da carga dos dados técnicos (relatório de vulnerabilidades,
CMDB de ativos e, opcionalmente, syslog), o banco de dados gera automaticamente um <strong>insight
de IA</strong> para cada registro, cria um <strong>vetor (chunk)</strong> a partir desse insight e,
a partir daí, é possível <strong>"falar com os dados"</strong> em linguagem natural — tanto pela
aplicação APEX quanto via SELECT AI ou uma integração MCP.</p>
<div class="diagram">
<div class="node"><strong>Fontes de dados</strong>Vulnerabilidades (Tenable), CMDB, Syslog</div>
<div class="arrow">&rarr;</div>
<div class="node accent"><strong>Autonomous Database 26ai</strong>Tabelas + PL/SQL ampmInsights</div>
<div class="arrow">&rarr;</div>
<div class="node"><strong>OCI Generative AI</strong>Llama 4 Maverick + Cohere embed-v4</div>
<div class="arrow">&rarr;</div>
<div class="node"><strong>Vetores (RAG)</strong>TB_26AI_TECH_VECTOR</div>
<div class="arrow">&rarr;</div>
<div class="node accent"><strong>ampmInsights (APEX)</strong>Chat, relatórios, SELECT AI, MCP</div>
</div>
<h2>Resultados do PoC (contexto de negócio)</h2>
<p>Números do PoC "AI Insights" realizado com a AM/PM em abril de 2026, conforme apresentado na
jornada Agentic AI (documento de jornada ainda em construção pela V8 Solution). Servem de contexto
para dimensionar o valor do ambiente — não fazem parte da configuração técnica.</p>
<div class="grid">
<div class="stat"><span class="num">4.433</span><span class="lbl">vulnerabilidades reais (Tenable)</span></div>
<div class="stat"><span class="num">136</span><span class="lbl">servidores AM/PM no CMDB</span></div>
<div class="stat"><span class="num">96,2%</span><span class="lbl">match ativo &times; CMDB</span></div>
<div class="stat"><span class="num">594 / 1.395</span><span class="lbl">vulnerabilidades críticas</span></div>
</div>
<h2>O que mudou nesta versão V1</h2>
<div class="grid">
<div class="card"><h4>Schema renomeado</h4><p>O schema/usuário de banco passa a se chamar <code>AMPMINSIGHTS</code> de forma consistente nos dois scripts (o ambiente original usava nomes divergentes entre os dois arquivos).</p></div>
<div class="card"><h4>Zero credenciais herdadas</h4><p>Chave privada OCI, senha do schema, OCIDs de tenancy/compartimento/usuário e e-mails pessoais foram removidos e substituídos por marcadores <code>&lt;SUBSTITUA_...&gt;</code>.</p></div>
<div class="card"><h4>Passo a passo do zero</h4><p>Cada credencial tem instruções completas de como gerar, assumindo que quem for reproduzir nunca fez isso antes.</p></div>
<div class="card"><h4>Identidade ampmInsights</h4><p>Nome da aplicação, título de login e textos internos passam a referenciar o projeto como <strong>ampmInsights</strong>.</p></div>
<div class="card"><h4>Objetos de banco preservados</h4><p>Nomes de tabelas, view e PL/SQL (ex.: <code>TB_26AI_TECH_V2</code>, <code>V_26AI_TECH</code>, <code>PRC_26AI_TECH</code>) foram mantidos idênticos entre os dois scripts, já que a aplicação APEX referencia esses nomes centenas de vezes.</p></div>
<div class="card"><h4>Achados de segurança documentados</h4><p>O ambiente original continha uma chave privada e senha em texto puro — ver <a href="07-seguranca-boas-praticas.html">Segurança &amp; boas práticas</a> para o que precisa ser rotacionado.</p></div>
</div>
<h2>Estrutura da entrega</h2>
<div class="table-wrap">
<table>
<tr><th>Caminho</th><th>Conteúdo</th></tr>
<tr><td><code>sql/01_ampminsights_db_setup.sql</code></td><td>Schema, credencial OCI, modelo de embeddings, tabelas/view, PL/SQL de geração de insights.</td></tr>
<tr><td><code>sql/02_ampminsights_apex_app.sql</code></td><td>Export da aplicação APEX (100 &middot; ampmInsights), sanitizado.</td></tr>
<tr><td><code>docs/</code></td><td>Esta documentação navegável.</td></tr>
</table>
</div>
<h2>Antes de encaminhar ao cliente</h2>
<div class="callout warning">
<div class="callout-title">Checklist de validação</div>
<p>Percorra o roteiro de <a href="06-validacao-testes.html">Validação &amp; testes</a> reproduzindo
o ambiente do zero em um tenancy de teste antes de enviar este pacote para a AM/PM ou para a
V8 Solution. Isso confirma que nenhum passo ficou implícito e que os dois arquivos SQL realmente
não dependem de nada do ambiente original.</p>
</div>
<div class="pillnav"><span></span><a class="next" href="02-arquitetura.html">Arquitetura &rarr;</a></div>
</main>
</div>
<script src="assets/main.js"></script>
</body>
</html>