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>

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

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

docs/09-operacao-observabilidade.html

@@ -52,6 +52,8 @@ rapidamente qualquer problema, e o checklist abaixo para os casos mais comuns.</
 <tr><td>Erro de rede/timeout ao chamar o Generative AI</td><td>ACL de rede (Seção 1.6) não cobre o host correto.</td><td><code>SELECT host, privilege FROM dba_host_aces WHERE principal = 'AMPMINSIGHTS';</code> — deve listar <code>inference.generativeai.us-chicago-1.oci.oraclecloud.com</code> com <code>RESOLVE</code> e <code>CONNECT</code>.</td></tr>
 <tr><td><code>ORA-20404</code> ("Object not found", domínio <code>oci.my$cloud_domain</code>)</td><td>Perfil de SELECT AI usando a região "de casa" do tenancy (<code>OCI_REGION</code>) em vez da região do Generative AI.</td><td>Use o valor de <code>GENAI_REGION</code> (Seção 2), não <code>OCI_REGION</code> — ver Seção 5.3 do <a href="04-passo-a-passo-banco.html">Passo a passo: banco de dados</a>.</td></tr>
 <tr><td><code>ORA-20404</code> com URL bem formada (região correta no domínio)</td><td>A tenancy não alcança a região configurada em <code>GENAI_REGION</code>, ou o modelo não está mais disponível para uso on-demand nessa região (a disponibilidade de modelos varia por região e muda com o tempo).</td><td>Rode <code>oci generative-ai model-collection list-models --compartment-id &lt;seu-compartimento&gt; --region &lt;regiao-candidata&gt; --capability CHAT --all</code> (ou o Console OCI) e confirme que o modelo usado está <code>ACTIVE</code> e sem <code>time-on-demand-retired</code> preenchido nessa região; ajuste <code>GENAI_REGION</code> (e a ACL da Seção 1.6 para o novo host) para uma região que sua tenancy alcance e que ainda sirva o modelo on-demand.</td></tr>
+<tr><td><code>ORA-20404</code> mesmo com credencial/ACL/região corretos</td><td><code>EMBEDDING_COMPARTMENT</code> preenchido com o OCID errado (ex.: do Autonomous Database em vez do compartimento — os dois "parecem" um OCID válido).</td><td>Confira o prefixo: tem que ser <code>ocid1.compartment....</code>, nunca <code>ocid1.autonomousdatabase....</code>. Se corrigir, recrie a credencial (<code>OCI_CRED</code>) — ela grava o compartimento internamente na criação.</td></tr>
+<tr><td>Lupa do "AI Insight" falha mesmo com tudo certo em <code>TB_26AI_TECH_PARAMS</code></td><td><code>COMPARTMENT_ID</code>/<code>OCI_CREDENTIAL</code>/<code>REGION</code> nas Application Settings do APEX (config separada, ver seção abaixo) desatualizados em relação à tabela.</td><td>App Builder → Shared Components → Application Settings — compare com <code>TB_26AI_TECH_PARAMS</code>.</td></tr>
 </table>
 </div>
 
@@ -127,6 +129,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>

sql/01_ampminsights_db_setup.sql

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