Passo 3 v2.0.0: templates de amostra + caminho de distribuição sem App Builder pro cliente

- Achado: DL_TECH_CMDB_V1/DL_TECH_VULNERABILIDADE_V2 vivem dentro de
  sql/02_ampminsights_apex_app.sql via wwv_flow_imp_shared (API interna
  de export/import do APEX) — não escrever isso à mão fora de um
  import completo.
- templates/sample_DL_TECH_CMDB_V2.xlsx (27 col.) e
  templates/sample_DL_TECH_VULNERABILIDADE_V3.xlsx (40 col.): arquivos
  de amostra só-cabeçalho pra criar os perfis via upload no wizard do
  APEX, em vez de preencher campo a campo.
- docs/13 reescrito: seção 5 usa o fluxo de upload de amostra; nova
  seção 7 explica que só o desenvolvedor toca em App Builder uma vez,
  e o cliente recebe um export completo novo (mesmo fluxo de release
  já usado sempre) — nunca precisa saber o que é Data Load Definition.

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

TASKS.md

@@ -43,10 +43,16 @@ teste — a menos que você peça explicitamente o contrário.
       (bloco grande) foi pulado na primeira passada — o checkpoint de compilação deu `VALID`
       porque a view *antiga* (46 colunas) já era válida antes. Resolvido rodando o bloco
       explicitamente; segunda checagem confirmou as 81 colunas.
-- [ ] **Mapeamento pronto e confirmado contra export real** (ver
-      [docs/13-v2-perfis-carga.html](docs/13-v2-perfis-carga.html)) — falta só criar os dois
-      perfis de fato no App Builder (não é scriptável, precisa ser feito na UI). `RAW_JSON`
-      deliberadamente fora do escopo deste item — depende do item de staging abaixo.
+- [ ] **Mapeamento pronto + templates de amostra prontos** (ver
+      [docs/13-v2-perfis-carga.html](docs/13-v2-perfis-carga.html) e `templates/`) — falta criar
+      os dois perfis no App Builder (uma vez, seu acesso, não do cliente — upload dos templates de
+      amostra, não preenchimento campo a campo) e depois gerar um export completo novo da
+      Application 100 (captura os perfis automaticamente, com IDs corretos). O cliente só importa
+      esse export, nunca toca em Data Load Definitions — mesmo fluxo de sempre. **Achado
+      importante:** essas definições vivem dentro de `sql/02_ampminsights_apex_app.sql` via API
+      interna do APEX (`wwv_flow_imp_shared`) — não escrever isso à mão fora de um import
+      completo, risco de corromper os Shared Components. `RAW_JSON` deliberadamente fora do
+      escopo deste item — depende do item de staging abaixo.
 - [ ] Pipeline de staging: bucket → `TB_26AI_TECH_V2_STG` via `DBMS_CLOUD.COPY_DATA` (tabela nova,
       não mexe nas existentes)
 - [ ] `MERGE` com histórico (`LOAD_BATCH_ID`, `TB_26AI_TECH_V2_HIST` — tabela nova), honrando o

docs/13-v2-perfis-carga.html

@@ -113,17 +113,39 @@ coluna, e um `JSON_OBJECT(*)` sobre o staging resolve isso corretamente.</p>
 </table>
 </div>
 
-<h2>5. Como criar os perfis no App Builder</h2>
-<p>Não é scriptável de forma confiável para esta aplicação (ver decisão registrada no
-<a href="08-glossario-roadmap.html">capítulo 8</a>/histórico do projeto sobre export de página) —
-precisa ser feito manualmente no App Builder:</p>
+<h2>5. Como criar os perfis — e por que não é um script SQL</h2>
+<div class="callout danger">
+  <div class="callout-title">Por que isto não vira um .sql como os Passos 1 e 2</div>
+  <p>As definições de carga (<code>DL_TECH_CMDB_V1</code> e as duas de vulnerabilidades) já existem
+  hoje dentro de <code>sql/02_ampminsights_apex_app.sql</code>, criadas via
+  <code>wwv_flow_imp_shared.create_data_profile</code>/<code>.create_data_profile_col</code>/
+  <code>.create_load_table</code> — a API interna que o próprio export/import do APEX usa. Escrever
+  essas chamadas à mão, fora do contexto de um import completo (com os IDs que só o APEX gera
+  corretamente), arrisca corromper os Shared Components da Application 100. Por isso este passo é
+  feito uma vez no App Builder e depois <strong>capturado automaticamente</strong> num novo export
+  completo (seção 7) — o cliente nunca toca em Data Load Definitions manualmente, só importa esse
+  arquivo, exatamente como já faz hoje em cada release.</p>
+</div>
+
+<p>Boa notícia: não precisa preencher campo a campo. O jeito mais rápido é criar o perfil do zero
+apontando pra um arquivo de amostra (só cabeçalho, sem dados) com todas as colunas certas — o APEX
+detecta as colunas automaticamente a partir do cabeçalho. Já preparei os dois arquivos:</p>
+<div class="table-wrap">
+<table>
+<tr><th>Arquivo de amostra (no repositório)</th><th>Colunas</th><th>Perfil a criar</th></tr>
+<tr><td><code>templates/sample_DL_TECH_CMDB_V2.xlsx</code></td><td>27 (16 originais + 11 novas — sem <code>RAW_JSON</code>)</td><td><code>DL_TECH_CMDB_V2</code></td></tr>
+<tr><td><code>templates/sample_DL_TECH_VULNERABILIDADE_V3.xlsx</code></td><td>40 (18 originais + 22 novas — sem <code>RAW_JSON</code>)</td><td><code>DL_TECH_VULNERABILIDADE_V3</code></td></tr>
+</table>
+</div>
+
 <ol>
-  <li>App Builder → Application 100 → <strong>Shared Components</strong> → <strong>Data Load Definitions</strong>.</li>
-  <li>Selecione <code>DL_TECH_CMDB_V1</code> (ou <code>DL_TECH_VULNERABILIDADE_V2</code>) e use <strong>Copy</strong> (não edite o original) — renomeie a cópia para <code>DL_TECH_CMDB_V2</code> (ou <code>DL_TECH_VULNERABILIDADE_V3</code>).</li>
-  <li>Na cópia, adicione os campos novos da tabela da seção 3 (ou 4) — cada campo novo mapeado para a coluna de destino correspondente.</li>
-  <li>Para os campos flag (<code>ATTESTED_FLAG</code>, <code>CISA_KEV_FLAG</code>, <code>EXPLOITED_BY_MALWARE_FLAG</code>, <code>EXPLOITED_BY_NESSUS_FLAG</code>): configure a transformação de valor (Value Map / Column Transformation) <code>Verdadeiro(a)/true → 1</code>, <code>Falso(a)/false → 0</code>.</li>
-  <li>Para <code>U_FIM_DO_SUPORTE</code>: configure a máscara de data como <code>DD-MM-YYYY</code>.</li>
-  <li>Salve e teste com uma planilha pequena (5-10 linhas de ativos <code>AM...</code>) antes de rodar a carga completa.</li>
+  <li>Baixe os dois arquivos de <code>templates/</code> neste repositório.</li>
+  <li>App Builder → Application 100 → <strong>Shared Components</strong> → <strong>Data Load Definitions</strong> → <strong>Create</strong>.</li>
+  <li>Na tela de criação, escolha carregar a partir de um arquivo e faça upload do <code>sample_DL_TECH_CMDB_V2.xlsx</code> (ou o de vulnerabilidades) — o APEX lê o cabeçalho e monta o Data Profile com as 27 (ou 40) colunas automaticamente.</li>
+  <li><strong>Name</strong>: <code>DL_TECH_CMDB_V2</code> (ou <code>DL_TECH_VULNERABILIDADE_V3</code>). <strong>Target Type</strong>: Table. <strong>Table Name</strong>: <code>TB_26AI_TECH_CMDB</code> (ou <code>TB_26AI_TECH_V2</code>). <strong>Loading Method</strong>: Append — mesma configuração do perfil original (ver aba "Data Load" da tela, igual à do <code>DL_TECH_CMDB_V1</code>).</li>
+  <li>Em <strong>Edit Data Profile</strong>, confira o tipo de cada coluna nova contra a tabela da seção 3 (ou 4) — a maioria detecta como <code>VARCHAR2</code>/texto por padrão, então ajuste manualmente: <code>DEFINITION_CVSS3_BASE_SCORE</code>, <code>DEFINITION_EPSS_SCORE</code>, <code>PORT</code>, <code>TIME_TO_FIX</code>, <code>ATTESTATION_SCORE</code> → <code>NUMBER</code>; <code>LAST_FIXED</code>, <code>VULN_SLA_DATE</code>, <code>PATCH_PUBLISHED</code>, <code>VULNERABILITY_PUBLISHED</code> → data/timestamp; <code>U_FIM_DO_SUPORTE</code> → data, máscara <code>DD-MM-YYYY</code>.</li>
+  <li>Para os campos flag (<code>ATTESTED_FLAG</code>, <code>CISA_KEV_FLAG</code>, <code>EXPLOITED_BY_MALWARE_FLAG</code>, <code>EXPLOITED_BY_NESSUS_FLAG</code>): configure a transformação de valor (Column Transformation) <code>Verdadeiro(a)/true → 1</code>, <code>Falso(a)/false → 0</code> — mesma convenção já usada em <code>SOX</code>/<code>COFRE</code>/<code>TENABLE</code>/<code>SIEM</code>.</li>
+  <li>Salve e teste com uma planilha pequena (5-10 linhas de ativos <code>AM...</code>, com dado real nas colunas — não só o cabeçalho) antes de rodar a carga completa.</li>
 </ol>
 
 <h2>6. Como validar</h2>
@@ -143,6 +165,21 @@ FETCH FIRST 5 ROWS ONLY;</code></pre>
 <code>EXPLOITED_BY_MALWARE_FLAG</code> como <code>1</code> ou <code>0</code> (nunca texto), os
 perfis estão funcionando.</p>
 
+<h2>7. Como isso chega ao cliente (sem ele tocar em App Builder)</h2>
+<p>Depois dos perfis criados e testados (seções 5 e 6), a captura definitiva é um novo
+<strong>export completo</strong> da Application 100 (App Builder → Application 100 → ícone de
+exportar/download → SQL Script) — isso gera um <code>02_ampminsights_apex_app.sql</code> novo, com
+os dois perfis novos já embutidos com os IDs corretos gerados pelo próprio APEX. Esse arquivo
+substitui o atual no próximo release (mesmo fluxo já usado em toda entrega anterior — zip →
+bucket → PAR, ver o processo de release do projeto). O cliente só importa esse arquivo via
+App Builder → Import — um wizard guiado, não precisa entender Data Load Definitions.</p>
+<div class="callout info">
+  <div class="callout-title">Você faz isso uma vez; o cliente nunca faz</div>
+  <p>As seções 5-6 (criar e testar os perfis) são trabalho seu, num ambiente com acesso ao App
+  Builder. O cliente recebe só o resultado — o export completo atualizado — e importa como já
+  importa qualquer outra versão da aplicação.</p>
+</div>
+
     <div class="pillnav"><a class="prev" href="12-v2-view-procedure.html">&larr; v2.0.0 — View & Procedure</a></div>
   </main>
 </div>