2120 lines
103 KiB
HTML
2120 lines
103 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="pt-BR">
|
|
<head>
|
|
<meta charset="UTF-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<title>Knowledge One View CLI Docs</title>
|
|
<style>
|
|
:root {
|
|
--bg: #f6f4ef;
|
|
--card: #fffdf8;
|
|
--ink: #1f2523;
|
|
--muted: #5e6864;
|
|
--line: #d8d2c8;
|
|
--brand: #0f766e;
|
|
--brand-soft: #d8efe9;
|
|
--accent: #b25a28;
|
|
--accent-soft: #f5e2d6;
|
|
--code-bg: #f1eee7;
|
|
--shadow: 0 10px 26px rgba(31, 37, 35, 0.08);
|
|
}
|
|
|
|
* { box-sizing: border-box; }
|
|
html { scroll-behavior: smooth; }
|
|
|
|
body {
|
|
margin: 0;
|
|
font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
|
|
color: var(--ink);
|
|
background:
|
|
radial-gradient(circle at top left, rgba(15, 118, 110, 0.11), transparent 22%),
|
|
radial-gradient(circle at right top, rgba(178, 90, 40, 0.1), transparent 18%),
|
|
var(--bg);
|
|
line-height: 1.5;
|
|
}
|
|
|
|
a { color: var(--brand); }
|
|
p, li { overflow-wrap: anywhere; }
|
|
|
|
.page {
|
|
display: grid;
|
|
grid-template-columns: 250px minmax(0, 1fr);
|
|
min-height: 100vh;
|
|
}
|
|
|
|
.sidebar {
|
|
position: sticky;
|
|
top: 0;
|
|
align-self: start;
|
|
height: 100vh;
|
|
padding: 20px 16px;
|
|
border-right: 1px solid var(--line);
|
|
background: rgba(255, 253, 248, 0.92);
|
|
backdrop-filter: blur(10px);
|
|
}
|
|
|
|
.language-switch {
|
|
display: grid;
|
|
gap: 8px;
|
|
margin-bottom: 18px;
|
|
}
|
|
|
|
.language-button {
|
|
display: flex;
|
|
align-items: center;
|
|
justify-content: center;
|
|
min-height: 52px;
|
|
padding: 12px 14px;
|
|
border-radius: 16px;
|
|
border: 1px solid var(--line);
|
|
background: var(--card);
|
|
color: var(--ink);
|
|
font-size: 0.95rem;
|
|
font-weight: 800;
|
|
letter-spacing: 0.02em;
|
|
text-decoration: none;
|
|
box-shadow: var(--shadow);
|
|
transition: transform 0.15s ease, border-color 0.15s ease, background 0.15s ease;
|
|
}
|
|
|
|
.language-button:hover {
|
|
transform: translateY(-1px);
|
|
border-color: var(--brand);
|
|
}
|
|
|
|
.language-button.active {
|
|
background: linear-gradient(135deg, rgba(216,239,233,0.95), rgba(255,253,248,0.98));
|
|
border-color: var(--brand);
|
|
color: var(--brand);
|
|
}
|
|
|
|
.brand small,
|
|
.eyebrow,
|
|
.pill {
|
|
display: inline-flex;
|
|
align-items: center;
|
|
border-radius: 999px;
|
|
padding: 4px 8px;
|
|
font-size: 0.72rem;
|
|
font-weight: 700;
|
|
letter-spacing: 0.03em;
|
|
text-transform: uppercase;
|
|
}
|
|
|
|
.brand small {
|
|
background: var(--brand-soft);
|
|
color: var(--brand);
|
|
}
|
|
|
|
.brand h1 {
|
|
margin: 10px 0 8px;
|
|
font-size: 1.35rem;
|
|
line-height: 1.1;
|
|
}
|
|
|
|
.muted, .brand p, .sidebar-note, .section-lead, .card p, .metric p, .footer {
|
|
color: var(--muted);
|
|
font-size: 0.9rem;
|
|
}
|
|
|
|
.nav {
|
|
display: grid;
|
|
gap: 6px;
|
|
margin-top: 18px;
|
|
}
|
|
|
|
.nav a {
|
|
text-decoration: none;
|
|
color: var(--ink);
|
|
border: 1px solid transparent;
|
|
border-radius: 10px;
|
|
padding: 8px 10px;
|
|
}
|
|
|
|
.nav a:hover {
|
|
background: rgba(255,255,255,0.75);
|
|
border-color: var(--line);
|
|
}
|
|
|
|
.sidebar-note {
|
|
margin-top: 18px;
|
|
padding: 12px;
|
|
border-radius: 14px;
|
|
border: 1px solid var(--line);
|
|
background: var(--card);
|
|
box-shadow: var(--shadow);
|
|
}
|
|
|
|
main {
|
|
padding: 24px;
|
|
}
|
|
|
|
.hero,
|
|
.section {
|
|
max-width: 1240px;
|
|
margin: 0 auto 18px;
|
|
}
|
|
|
|
.hero-card,
|
|
.panel,
|
|
.table-wrap,
|
|
.code-wrap,
|
|
.details,
|
|
.step-card {
|
|
background: var(--card);
|
|
border: 1px solid var(--line);
|
|
border-radius: 18px;
|
|
box-shadow: var(--shadow);
|
|
}
|
|
|
|
.hero-card {
|
|
padding: 22px 24px;
|
|
background:
|
|
linear-gradient(135deg, rgba(255,253,248,0.97), rgba(216,239,233,0.86));
|
|
}
|
|
|
|
.eyebrow {
|
|
background: var(--accent-soft);
|
|
color: var(--accent);
|
|
}
|
|
|
|
.hero h2 {
|
|
margin: 10px 0 8px;
|
|
font-size: clamp(1.7rem, 3vw, 2.7rem);
|
|
line-height: 1.05;
|
|
max-width: 900px;
|
|
}
|
|
|
|
.grid-4,
|
|
.grid-3,
|
|
.grid-2 {
|
|
display: grid;
|
|
gap: 10px;
|
|
}
|
|
|
|
.grid-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
|
|
.grid-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
|
|
.grid-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
|
|
|
|
.metric,
|
|
.card {
|
|
padding: 14px;
|
|
border-radius: 16px;
|
|
border: 1px solid var(--line);
|
|
background: rgba(255,255,255,0.72);
|
|
}
|
|
|
|
.kpi {
|
|
font-size: 1.6rem;
|
|
font-weight: 800;
|
|
line-height: 1;
|
|
margin-bottom: 8px;
|
|
color: var(--brand);
|
|
}
|
|
|
|
.section h2 {
|
|
margin: 0 0 4px;
|
|
font-size: 1.4rem;
|
|
}
|
|
|
|
.section-lead {
|
|
margin: 0 0 10px;
|
|
}
|
|
|
|
.panel {
|
|
padding: 16px;
|
|
}
|
|
|
|
.section-stack {
|
|
display: grid;
|
|
gap: 10px;
|
|
}
|
|
|
|
.table-wrap {
|
|
overflow-x: auto;
|
|
}
|
|
|
|
table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
min-width: 920px;
|
|
}
|
|
|
|
th, td {
|
|
padding: 9px 11px;
|
|
text-align: left;
|
|
vertical-align: top;
|
|
border-bottom: 1px solid var(--line);
|
|
overflow-wrap: anywhere;
|
|
}
|
|
|
|
th {
|
|
font-size: 0.76rem;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.03em;
|
|
background: rgba(216, 239, 233, 0.52);
|
|
}
|
|
|
|
tr:last-child td { border-bottom: none; }
|
|
|
|
ul, ol {
|
|
margin: 8px 0 0;
|
|
padding-left: 18px;
|
|
}
|
|
|
|
li + li { margin-top: 4px; }
|
|
|
|
code {
|
|
font-family: Consolas, "Courier New", monospace;
|
|
font-size: 0.88em;
|
|
background: var(--code-bg);
|
|
padding: 2px 6px;
|
|
border-radius: 7px;
|
|
}
|
|
|
|
pre {
|
|
margin: 0;
|
|
padding: 12px;
|
|
overflow-x: auto;
|
|
max-width: 100%;
|
|
background: #fbfaf6;
|
|
border-radius: 14px;
|
|
border: 1px solid var(--line);
|
|
}
|
|
|
|
.code-wrap {
|
|
padding: 14px;
|
|
overflow: hidden;
|
|
}
|
|
|
|
.pill-row {
|
|
display: flex;
|
|
flex-wrap: wrap;
|
|
gap: 6px;
|
|
margin-top: 10px;
|
|
}
|
|
|
|
.pill {
|
|
background: rgba(255,255,255,0.8);
|
|
border: 1px solid var(--line);
|
|
color: var(--ink);
|
|
text-transform: none;
|
|
letter-spacing: 0;
|
|
max-width: 100%;
|
|
}
|
|
|
|
.step-card {
|
|
padding: 16px;
|
|
}
|
|
|
|
.step-card h3,
|
|
.panel h3,
|
|
.code-wrap h3,
|
|
.card h3 {
|
|
margin-top: 0;
|
|
}
|
|
|
|
.example-grid {
|
|
display: grid;
|
|
gap: 10px;
|
|
grid-template-columns: repeat(2, minmax(0, 1fr));
|
|
}
|
|
|
|
.steps-grid {
|
|
display: grid;
|
|
gap: 10px;
|
|
grid-template-columns: repeat(3, minmax(0, 1fr));
|
|
}
|
|
|
|
details {
|
|
margin-top: 10px;
|
|
border: 1px solid var(--line);
|
|
border-radius: 14px;
|
|
background: rgba(255,255,255,0.7);
|
|
padding: 10px 12px;
|
|
}
|
|
|
|
summary {
|
|
cursor: pointer;
|
|
font-weight: 700;
|
|
}
|
|
|
|
.footer {
|
|
max-width: 1240px;
|
|
margin: 0 auto 24px;
|
|
text-align: center;
|
|
}
|
|
|
|
@media (max-width: 1180px) {
|
|
.page { grid-template-columns: 1fr; }
|
|
.sidebar {
|
|
position: static;
|
|
height: auto;
|
|
border-right: none;
|
|
border-bottom: 1px solid var(--line);
|
|
}
|
|
.grid-4, .grid-3 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
|
|
.grid-2, .example-grid, .steps-grid { grid-template-columns: 1fr; }
|
|
}
|
|
|
|
@media (max-width: 760px) {
|
|
main { padding: 14px; }
|
|
.hero-card, .panel { padding: 16px; }
|
|
.grid-4, .grid-3, .grid-2 { grid-template-columns: 1fr; }
|
|
.example-grid, .steps-grid { grid-template-columns: 1fr; }
|
|
table { min-width: 700px; }
|
|
}
|
|
|
|
.lang-page {
|
|
display: none;
|
|
}
|
|
|
|
.lang-page.active {
|
|
display: block;
|
|
}
|
|
|
|
.language-button {
|
|
cursor: pointer;
|
|
}
|
|
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="lang-page active" data-lang-page="pt">
|
|
<div class="page">
|
|
<aside class="sidebar">
|
|
|
|
<div class="language-switch" aria-label="Language selector">
|
|
<button class="language-button active" type="button" data-lang-target="pt">Português</button>
|
|
<button class="language-button" type="button" data-lang-target="es">Español</button>
|
|
</div>
|
|
|
|
<div class="brand">
|
|
<small>Skill Guide</small>
|
|
<h1>Knowledge One View CLI</h1>
|
|
<p>Documento único da skill: visão funcional, técnica e operacional.</p>
|
|
</div>
|
|
|
|
<nav class="nav">
|
|
<a href="#overview">Visão Geral</a>
|
|
<a href="#use-cases">Casos de Uso</a>
|
|
<a href="#quickstart">Instalação Rápida</a>
|
|
<a href="#reading-path">Internals</a>
|
|
<a href="#roles">Papéis e Linguagem</a>
|
|
<a href="#architecture">Arquitetura</a>
|
|
<a href="#datasets">Datasets</a>
|
|
<a href="#intents">Intents</a>
|
|
<a href="#views">Views</a>
|
|
<a href="#cli">CLI</a>
|
|
<a href="#auth">Auth e Runtime</a>
|
|
<a href="#output">Contrato de Saída</a>
|
|
<a href="#hierarchy">Hierarquia e Semântica</a>
|
|
<a href="#trees">Estrutura de Pastas</a>
|
|
<a href="#testing">Testes e Validação</a>
|
|
<a href="#commands">Comandos</a>
|
|
<a href="#practices">Boas Práticas</a>
|
|
</nav>
|
|
|
|
<div class="sidebar-note">
|
|
Esta página vive em <code>docs/docs.html</code>. Os arquivos em <code>references/</code> continuam como catálogos de apoio da skill.
|
|
</div>
|
|
</aside>
|
|
|
|
<main>
|
|
<section class="hero" id="overview">
|
|
<div class="hero-card">
|
|
<span class="eyebrow">Oracle DV</span>
|
|
<h2>Skill para consultar o DV LAD Knowledge One View direto pela API.</h2>
|
|
<p class="section-lead">Guia consolidado da skill para onboarding, operação e consulta rápida da superfície atual.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="use-cases">
|
|
<h2>Casos de uso práticos</h2>
|
|
<p class="section-lead">Pense nesta skill como um tradutor entre linguagem de negócio e Oracle DV. Você descreve o recorte desejado no Codex; a skill decide se usa intent, view, query ou SQL, resolve a autenticação e devolve uma saída utilizável.</p>
|
|
|
|
<div class="example-grid">
|
|
<div class="step-card">
|
|
<span class="eyebrow">Exemplo 1</span>
|
|
<h3>Workloads com SR por manager</h3>
|
|
<pre><code>Prompt no Codex:
|
|
|
|
"Me traga todos os workloads do cluster Brazil para a próxima semana fiscal da Oracle, cruzando quais têm SR na oportunidade de recursos abaixo de <manager de recurso>."</code></pre>
|
|
<p class="muted">Esse tipo de pedido costuma cair no intent <code>workloads-by-manager-resource-close-window</code>. A skill resolve a semana Oracle, filtra as revenue lines e enriquece o resultado com recursos e SRs visíveis.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Exemplo 2</span>
|
|
<h3>Pipeline com janela comercial</h3>
|
|
<pre><code>Prompt no Codex:
|
|
|
|
"Quais oportunidades com close no mês atual têm booking acima de 500k e territory owner abaixo de <manager comercial>?"</code></pre>
|
|
<p class="muted">A skill tende a usar intents ou views comerciais em <code>Knowledge DV - Opportunities - V2</code>, mantendo escopo org-wide e o vocabulário comercial consistente.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Exemplo 3</span>
|
|
<h3>SRs por recurso</h3>
|
|
<pre><code>Prompt no Codex:
|
|
|
|
"Liste os SRs do <recurso alocado> com status e opportunityId, em formato tabela."</code></pre>
|
|
<p class="muted">Aqui a skill normalmente usa <code>srs-by-resource</code> ou uma view equivalente em <code>DV - SE Team</code>, respeitando o escopo do time visível ao usuário executor.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Exemplo 4</span>
|
|
<h3>Formato de resposta</h3>
|
|
<pre><code>Resposta típica:
|
|
|
|
- semana Oracle resolvida
|
|
- escopo da leitura
|
|
- total de linhas puxadas da API
|
|
- tabela final com cliente, workload, recurso e SR</code></pre>
|
|
<p class="muted">Se você pedir "mostre em tabela", "gere um relatório HTML", "monte um PDF executivo", "organize em planilha" ou "automatize o envio por email", o Codex pode transformar o payload final em entregáveis mais úteis para consumo e acompanhamento.</p>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="quickstart">
|
|
<h2>Instalação rápida e primeiro uso</h2>
|
|
<p class="section-lead">Em uma máquina nova, a sequência ideal é: instalar a skill, confirmar a sessão Oracle DV uma vez e depois seguir browserless na rotina normal. O objetivo é gastar energia no negócio, não em setup.</p>
|
|
|
|
<div class="steps-grid">
|
|
<div class="step-card">
|
|
<span class="eyebrow">Passo 1</span>
|
|
<h3>Pedir a instalação no Codex</h3>
|
|
<pre><code>Prompt no Codex:
|
|
|
|
"Instale a skill knowledge-one-view-cli no Codex e valide a pasta runtime/output no workspace."</code></pre>
|
|
<p class="muted">Depois disso, a skill fica instalada em <code>~/.codex/skills/knowledge-one-view-cli</code>.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Passo 2</span>
|
|
<h3>Testar a autenticação no Chrome</h3>
|
|
<pre><code>Prompt no Codex:
|
|
|
|
"Faça um teste de autenticação da skill via Chrome e confirme se o backend Oracle DV respondeu."</code></pre>
|
|
<p class="muted">O helper abre o navegador só para gravar <code>auth-state.json</code> e <code>session-meta.json</code> no runtime do workspace.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Passo 3</span>
|
|
<h3>Seguir browserless</h3>
|
|
<pre><code>Prompt no Codex:
|
|
|
|
"Me traga todos os workloads do cluster Brazil para a próxima semana fiscal da Oracle."</code></pre>
|
|
<p class="muted">Daí em diante, a skill normalmente segue sem browser, consultando o backend Oracle DV direto pela API.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section-stack" style="margin-top:10px;">
|
|
<div class="panel">
|
|
<h3>How-to relâmpago</h3>
|
|
<ol>
|
|
<li>Peça ao Codex para instalar ou validar a skill.</li>
|
|
<li>Peça ao Codex para fazer um teste de autenticação da skill via Chrome.</li>
|
|
<li>Conclua login e MFA.</li>
|
|
<li>Depois disso, siga usando em linguagem natural.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Exemplo de resposta após o primeiro uso</h3>
|
|
<pre><code>Resultado típico:
|
|
|
|
"Auth validado no runtime do workspace.
|
|
Backend Oracle DV acessível.
|
|
Raw rows pulled from the API: 5.
|
|
Segue a tabela com cliente, workload, close date e territory owner."</code></pre>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="reading-path">
|
|
<h2>Internals - Não é necessário para usar a skill</h2>
|
|
<p class="section-lead">A página foi reorganizada para funcionar bem tanto para onboarding quanto para troubleshooting. Se você estiver chegando agora, vale seguir esta ordem em vez de pular direto para os comandos.</p>
|
|
|
|
<div class="grid-3">
|
|
<div class="step-card">
|
|
<span class="eyebrow">Leitura 1</span>
|
|
<h3>Entenda o pedido</h3>
|
|
<p class="muted">Comece por <strong>Casos de uso</strong> e <strong>Papéis e linguagem</strong>. Eles mostram como transformar uma pergunta de negócio em um recorte consistente de owner, manager, recurso, workload e SR.</p>
|
|
</div>
|
|
<div class="step-card">
|
|
<span class="eyebrow">Leitura 2</span>
|
|
<h3>Entenda a execução</h3>
|
|
<p class="muted">Depois veja <strong>Arquitetura</strong>, <strong>Datasets</strong> e <strong>Intents</strong>. Essa parte explica de onde os dados vêm e por que a skill escolhe intent, view, query ou SQL.</p>
|
|
</div>
|
|
<div class="step-card">
|
|
<span class="eyebrow">Leitura 3</span>
|
|
<h3>Entenda a operação</h3>
|
|
<p class="muted">Feche com <strong>Auth e Runtime</strong>, <strong>Contrato de saída</strong>, <strong>Testes</strong> e <strong>Comandos</strong>. Aí você já consegue instalar, validar e depurar com segurança.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Atalho mental para usar bem</h3>
|
|
<ul>
|
|
<li>Se a pergunta for recorrente, pense em <code>intent</code>.</li>
|
|
<li>Se você quiser um extrato conhecido, pense em <code>view</code>.</li>
|
|
<li>Se precisar montar um recorte sob medida sem ir para SQL, pense em <code>query</code>.</li>
|
|
<li>Se estiver investigando um caso raro ou depurando Oracle DV, aí sim pense em <code>sql</code>.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="roles">
|
|
<h2>Papéis e linguagem</h2>
|
|
<p class="section-lead">Este guia evita nomes pessoais e usa papéis de negócio. Isso deixa a documentação mais transferível, mais segura e mais fácil de reaproveitar em outros times.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Papéis que aparecem neste guia</h3>
|
|
<ul>
|
|
<li><code><territory owner></code>: dono comercial direto da oportunidade ou workload.</li>
|
|
<li><code><manager comercial></code>: gestor da hierarquia de territory owners usada para recortes comerciais.</li>
|
|
<li><code><manager de recurso></code>: gestor do lado presales/engenharia, usado para cruzar recursos alocados em oportunidades.</li>
|
|
<li><code><recurso alocado></code>: arquiteto, engenheiro ou especialista associado à oportunidade.</li>
|
|
<li><code><time atual do usuário></code>: escopo visível em <code>DV - SE Team</code> para quem executa a skill.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Tradução prática da linguagem</h3>
|
|
<ul>
|
|
<li>Quando alguém pedir "vendedor", a leitura padrão deve ser <code><territory owner></code>.</li>
|
|
<li>Quando alguém pedir "recursos abaixo de um manager", a leitura costuma ser <code><manager de recurso></code> em <code>Knowledge DV - Presales Involvement Aux - V1</code>.</li>
|
|
<li>Quando alguém pedir SR, cobertura ou contexto de sessão, a leitura costuma envolver o escopo do <code><time atual do usuário></code>.</li>
|
|
<li>Quando o pedido mistura comercial e recurso, a skill normalmente combina fonte org-wide com enriquecimento controlado por papel.</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Como ler os exemplos</h3>
|
|
<p class="muted">Sempre que você vir um papel entre <code><...></code>, substitua pelo identificador real da sua pergunta. O papel explica qual atributo da hierarquia a skill deve usar, sem amarrar a documentação a uma pessoa específica.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="architecture">
|
|
<h2>Arquitetura</h2>
|
|
<p class="section-lead">Estrutura simples: o fetch principal concentra a lógica de negócio e <code>scripts/lib/runtime-paths.mjs</code> cuida do runtime, output e bootstrap do workspace.</p>
|
|
|
|
<div class="panel">
|
|
<h3>Fluxo principal</h3>
|
|
<ol>
|
|
<li>Parse de argumentos e validação do modo de execução.</li>
|
|
<li>Resolução de <code>runtime-home</code>, arquivos de sessão e cache.</li>
|
|
<li>Opcionalmente resolução de ano fiscal e contexto de sessão.</li>
|
|
<li>Montagem de SQL via intent, view, query declarativa ou SQL bruto.</li>
|
|
<li>Execução em <code>sqlquery/execute</code> com restauração de sessão se necessário.</li>
|
|
<li>Normalização de linhas, escopo, métricas, warnings e persistência opcional em arquivo.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Módulos atuais</h3>
|
|
<p class="muted">A skill hoje está organizada em um script principal, helpers de autenticação e utilitários internos em <code>scripts/lib/</code>. A lista abaixo reflete os módulos realmente presentes no código atual.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Módulo</th>
|
|
<th>Responsabilidade</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>fetch-sales-intelligence.mjs</code></td>
|
|
<td>Catálogo local, query engine, intents, views, orchestration e execução Oracle DV.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>refresh-auth-direct.mjs</code></td>
|
|
<td>Login Oracle sem abrir Chrome, com MFA.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>refresh-auth-state.mjs</code></td>
|
|
<td>Refresh de auth via browser/Playwright quando o fluxo direto não basta.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>run-sales-intelligence-sql.mjs</code></td>
|
|
<td>Ajuda para SQL longa ou sensível a quoting de shell.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/runtime-paths.mjs</code></td>
|
|
<td>Resolução canônica de <code>runtime</code>, <code>output</code>, <code>tmp</code>, bootstrap de workspace e fallback legado.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/auth-shared.mjs</code></td>
|
|
<td>Leitura, persistência e refresh dos artefatos de sessão, cookies, CSRF e metadados de autenticação.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/cli-shared.mjs</code></td>
|
|
<td>Parse de argumentos, normalização de flags e helpers utilitários de entrada.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/date-windows.mjs</code></td>
|
|
<td>Resolução de janelas temporais, semanas fiscais, quarters e atalhos como <code>today</code> ou <code>+7d</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/output-contract.mjs</code></td>
|
|
<td>Montagem do payload final com <code>apiMetrics</code>, <code>warnings</code>, normalização de linhas e emissão JSON.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Endpoint e estado local</h3>
|
|
<ul>
|
|
<li>Endpoint principal: <code>POST /ui/dv/ui/api/v1/sqlquery/execute</code>.</li>
|
|
<li>Workbook alvo: <code>salesintelligence-dv.oracle.com</code> no report path LAD Knowledge One View.</li>
|
|
<li>Estado persistido: <code>auth-state.json</code> e <code>session-meta.json</code>.</li>
|
|
<li>Fallback legado de leitura: <code>~/.codex/oracle-sales-intelligence-direct/</code>.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="datasets">
|
|
<h2>Datasets</h2>
|
|
<p class="section-lead">Resumo das fontes realmente usadas pela skill e do papel de cada uma. Esta seção existe para evitar o erro mais comum nesse tipo de análise: consultar a fonte certa com a leitura errada de escopo.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Dataset</th>
|
|
<th>Escopo</th>
|
|
<th>Papel principal</th>
|
|
<th>Observações</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>Knowledge DV - Opportunities - V2</code></td>
|
|
<td>Org-wide</td>
|
|
<td>Fonte comercial principal: pipeline, opportunities, won, close date, booking, workload, territory e owner.</td>
|
|
<td>Base normal para <code>opportunities-default</code>, <code>opportunities-close-*</code> e views <code>sa-attach-*</code> comerciais.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Knowledge DV - Hours - V2</code></td>
|
|
<td>Org-wide por padrão; my-team com <code>--scope my-team</code></td>
|
|
<td>Horas, ownership e produtividade por hierarquia.</td>
|
|
<td>Exposto em <code>sa-attach-hours-by-opportunity</code>; em <code>--scope auto</code> preserva a leitura org-wide.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Knowledge DV - Presales Involvement Aux - V1</code></td>
|
|
<td>Org-wide por padrão; my-team com <code>--scope my-team</code></td>
|
|
<td>Cobertura e vínculo manager/recurso/oportunidade.</td>
|
|
<td>Base normal para cobertura presales e linkage manager/recurso; intents de workload/manager usam essa leitura org-wide.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>DV - SE Team</code></td>
|
|
<td>My-team-only</td>
|
|
<td>Session context, SRs e fallback comercial só quando a pergunta é explicitamente do time atual.</td>
|
|
<td>Não usar como fonte comercial genérica org-wide.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Knowledge DV - Revn Lines by SE</code></td>
|
|
<td>Org-wide por padrão; my-team com <code>--scope my-team</code></td>
|
|
<td>Detalhe de revenue lines.</td>
|
|
<td>Exposto por <code>revenue-line-details</code> como extrato org-wide em <code>--scope auto</code>.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Como escolher a fonte certa</h3>
|
|
<ul>
|
|
<li>Se a pergunta é comercial e precisa preservar todas as oportunidades do recorte, a base tende a ser <code>Knowledge DV - Opportunities - V2</code>.</li>
|
|
<li>Se a pergunta é sobre quem está alocado, coberto ou relacionado a uma oportunidade, a base tende a ser <code>Knowledge DV - Presales Involvement Aux - V1</code> e a skill tenta org-wide primeiro.</li>
|
|
<li>Se a pergunta é sobre SR, contexto da sessão ou o time visível do executor, a base tende a passar por <code>DV - SE Team</code>.</li>
|
|
<li>Se a pergunta é sobre horas e produtividade, a skill tende a usar <code>Knowledge DV - Hours - V2</code> em org-wide, salvo pedido explícito de time atual.</li>
|
|
<li>Se a pergunta é sobre revenue line detalhada, a skill tende a olhar <code>Knowledge DV - Revn Lines by SE</code> em org-wide, salvo pedido explícito de time atual.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="grid-3" style="margin-top:10px;">
|
|
<div class="card">
|
|
<h3>Defaults SA Attach</h3>
|
|
<p><code>cluster=Brazil</code>, <code>sales-credit-type=QUOTA</code>, <code>solution=Cloud Infrastructure - Workloads, Hardware - Bookings, On-Premise Technology - Bookings</code>, <code>revenue-type-group=NEW,EXPANSION,WORKLOAD</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Aliases importantes</h3>
|
|
<p><code>workload</code> e <code>workloads</code> normalizam para <code>WORKLOAD</code>. <code>license and hardware</code> normaliza para <code>License,Hardware</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Monetário</h3>
|
|
<p>Outputs comerciais usam preferencialmente <code>bookingValue</code> e <code>workloadAmount</code>; a seção <code>raw</code> preserva o valor nativo do backend.</p>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="intents">
|
|
<h2>Intents</h2>
|
|
<p class="section-lead">Use intent primeiro quando o pedido já parece um caso de negócio recorrente. Essa é a forma mais fácil de pedir algo no Codex sem precisar pensar em SQL, aliases ou tabelas internas.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Intent</th>
|
|
<th>Quando usar</th>
|
|
<th>Entrada chave</th>
|
|
<th>Escopo</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>opportunities-default</code></td><td>Consulta comercial padrão de pipeline/opportunities.</td><td><code>--limit</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-close-date</code></td><td>Close date exata.</td><td><code>--date</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-close-month</code></td><td>Mês calendário.</td><td><code>--month</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-close-quarter</code></td><td>Quarter fiscal.</td><td><code>--quarter</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-current-team-close-window</code></td><td>Janela comercial org-wide enriquecida com cobertura do time atual.</td><td>janela de datas</td><td>Mixed-consistent</td></tr>
|
|
<tr><td><code>opportunities-by-resource-close-window</code></td><td>Janela comercial com cobertura de um recurso explícito.</td><td><code>--resource</code> + janela</td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-by-manager-close-window</code></td><td>Janela comercial com cobertura de um manager explícito.</td><td><code>--manager-email</code> + janela</td><td>Org-wide</td></tr>
|
|
<tr><td><code>workloads-by-owner-current</code></td><td>Estado atual de workloads para um territory owner.</td><td><code>--owner-email</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>workloads-by-owner-manager-current</code></td><td>Estado atual de workloads sob um manager de owners.</td><td><code>--owner-manager-email</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>workloads-by-manager-resource-close-window</code></td><td>Revenue lines workload com manager/resource allocation org-wide e SRs visíveis do time.</td><td><code>--manager-email-list</code> + janela</td><td>Mixed-consistent</td></tr>
|
|
<tr><td><code>srs-by-resource</code></td><td>SRs por recurso Oracle.</td><td><code>--resource</code></td><td>My-team-only</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="views">
|
|
<h2>Views</h2>
|
|
<p class="section-lead">Use view quando você já sabe exatamente o shape do extrato que quer. Views são boas para integrações, análises repetidas e validações em cima de um contrato estável, sem precisar redescobrir campo por campo.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>View</th>
|
|
<th>Fonte</th>
|
|
<th>Escopo</th>
|
|
<th>Uso</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>current-fiscal-year</code></td><td>DV session</td><td>My-team-only</td><td>Ano fiscal da sessão Oracle DV.</td></tr>
|
|
<tr><td><code>data-quality-session-context</code></td><td>DV session</td><td>My-team-only</td><td>Entry point e variáveis fiscais da sessão.</td></tr>
|
|
<tr><td><code>effort-by-se-team</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Horas por membro do time.</td></tr>
|
|
<tr><td><code>effort-task-type-summary</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Horas por task type.</td></tr>
|
|
<tr><td><code>opportunities-close-window</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Uma linha por oportunidade em janela de close date.</td></tr>
|
|
<tr><td><code>opportunity-details</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Detalhe comercial de oportunidades.</td></tr>
|
|
<tr><td><code>revenue-line-details</code></td><td>Knowledge DV - Revn Lines by SE</td><td>Org-wide</td><td>Detalhe de revenue lines.</td></tr>
|
|
<tr><td><code>sa-attach-hours-by-opportunity</code></td><td>Knowledge DV - Hours - V2</td><td>Org-wide</td><td>Horas/cobertura por oportunidade.</td></tr>
|
|
<tr><td><code>sa-attach-involvement-distribution</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Distribuição agregada por bucket de envolvimento.</td></tr>
|
|
<tr><td><code>sa-attach-open-pipeline</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Métrica de pipeline aberto.</td></tr>
|
|
<tr><td><code>sa-attach-pipeline-details</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Extrato comercial mais completo da skill.</td></tr>
|
|
<tr><td><code>sa-attach-presales-coverage</code></td><td>Knowledge DV - Presales Involvement Aux - V1</td><td>Org-wide</td><td>Cobertura presales por oportunidade.</td></tr>
|
|
<tr><td><code>sa-attach-won-pipeline</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Métrica de pipeline won.</td></tr>
|
|
<tr><td><code>sr-details</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Detalhe de SR.</td></tr>
|
|
<tr><td><code>srs-by-resource-email</code></td><td>DV - SE Team</td><td>My-team-only</td><td>SRs por email de recurso.</td></tr>
|
|
<tr><td><code>won-and-open-by-se-opty</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Contribuição por oportunidade e membro do time.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<details>
|
|
<summary>Notas rápidas de escopo</summary>
|
|
<ul>
|
|
<li><code>org-wide</code>: linhas comerciais visíveis para a hierarquia comercial da workbook.</li>
|
|
<li><code>my-team-only</code>: visibilidade limitada ao time do usuário executor em <code>DV - SE Team</code>.</li>
|
|
<li><code>mixed-consistent</code>: linhas comerciais org-wide preservadas, enriquecimento de recursos/SRs restrito ao escopo apropriado.</li>
|
|
<li><code>scope.components</code>: detalhe fonte por fonte; prefira esse campo quando o resultado combinar escopos.</li>
|
|
</ul>
|
|
</details>
|
|
</section>
|
|
|
|
<section class="section" id="cli">
|
|
<h2>Superfície CLI</h2>
|
|
<p class="section-lead">A CLI existe para quando você quer rodar a skill manualmente ou entender o que o Codex está fazendo por baixo. Cada chamada deve escolher exatamente um modo entre <code>--intent</code>, <code>--view</code>, <code>--query</code> e <code>--sql</code>.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Modos</h3>
|
|
<ul>
|
|
<li><code>--intent</code>: caminho preferido para perguntas recorrentes.</li>
|
|
<li><code>--view</code>: extrato conhecido, contrato estável.</li>
|
|
<li><code>--query</code>: aliases + filtros + grouping + ordering, com inferência de fonte e política org-wide-first por padrão.</li>
|
|
<li><code>--sql</code>: SQL lógico Oracle bruto, com placeholders locais.</li>
|
|
<li><code>--render-sql</code>: render local para <code>--query</code> ou <code>--sql</code>, sem backend.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Discovery</h3>
|
|
<ul>
|
|
<li><code>--catalog</code></li>
|
|
<li><code>--list-views</code>, <code>--describe-view</code></li>
|
|
<li><code>--list-intents</code>, <code>--describe-intent</code></li>
|
|
<li><code>--list-fields</code>, <code>--describe-field</code></li>
|
|
<li><code>--list-parameters</code>, <code>--describe-parameter</code></li>
|
|
<li><code>--list-scripts</code>, <code>--describe-script</code></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-3" style="margin-top:10px;">
|
|
<div class="card">
|
|
<h3>Janela temporal</h3>
|
|
<p><code>--date</code>, <code>--month</code>, <code>--quarter</code>, <code>--week</code> ou o par <code>--from-date</code>/<code>--to-date</code>. Nunca combine entre si.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Hierarquia e recurso</h3>
|
|
<p><code>--resource</code>, <code>--resource-email</code>, <code>--manager-email</code>, <code>--manager-email-list</code>, <code>--owner-email</code>, <code>--owner-manager-email</code>, <code>--match-role</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Filtros SA Attach</h3>
|
|
<p><code>--cluster</code>, <code>--solution</code>, <code>--revenue-line-status</code>, <code>--executive-product-lob</code>, <code>--revenue-type-group</code>, <code>--sales-credit-type</code>, <code>--min-opportunity-probability</code>, <code>--forecast-type</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Escopo</h3>
|
|
<p><code>--scope auto</code> tenta org-wide primeiro nas fontes XSA compatíveis; <code>--scope my-team</code> força a leitura do time atual quando a fonte suporta esse recorte.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<details>
|
|
<summary>Modelo de week</summary>
|
|
<ul>
|
|
<li><code>week-year</code> é o ano de início do ciclo Junho-Maio.</li>
|
|
<li>No contexto atual, o ciclo default é <code>2025-06-01</code> até <code>2026-05-31</code>.</li>
|
|
<li>Exemplos: <code>W1 = 2025-06-01..2025-06-07</code>, <code>W43 = 2026-03-22..2026-03-28</code>, <code>W53 = 2026-05-31</code>.</li>
|
|
</ul>
|
|
</details>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Regra prática de escolha</h3>
|
|
<ul>
|
|
<li>Comece por <code>--intent</code> sempre que existir um intent compatível com a pergunta.</li>
|
|
<li>Use <code>--view</code> quando você quer consistência de colunas para export, reconciliação ou integração.</li>
|
|
<li>Use <code>--query</code> quando a pergunta é nova, mas ainda cabe em aliases conhecidos e filtros claros.</li>
|
|
<li>Deixe <code>--sql</code> para casos realmente excepcionais, porque ele exige mais cuidado com Oracle DV e aumenta a chance de drift de contrato.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="auth">
|
|
<h2>Auth e Runtime</h2>
|
|
<p class="section-lead">O objetivo é reutilizar sessão local e abrir browser apenas quando a sessão precisar ser refeita. Em uso normal, a skill deve parecer browserless mesmo quando houve uma autenticação inicial no Chrome.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Arquivos de sessão</h3>
|
|
<ul>
|
|
<li><code><workspace>/knowledge-one-view-cli/runtime/auth-state.json</code></li>
|
|
<li><code><workspace>/knowledge-one-view-cli/runtime/session-meta.json</code></li>
|
|
<li><code><workspace>/knowledge-one-view-cli/runtime/chrome-profile/</code></li>
|
|
</ul>
|
|
<p class="muted">Leitura pode cair para o legado em <code>~/.codex/oracle-sales-intelligence-direct/</code> quando o runtime novo ainda está vazio.</p>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Estratégia de autenticação</h3>
|
|
<ol>
|
|
<li><code>--check-auth</code> só diagnostica.</li>
|
|
<li><code>refresh-auth-direct.mjs</code> é o caminho preferido para MFA sem browser.</li>
|
|
<li><code>refresh-auth-state.mjs</code> é helper de browser para troubleshooting ou refresh interativo.</li>
|
|
<li>Em execução normal, o fetch pode disparar refresh automático e reexecutar a consulta.</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Como pensar o runtime no workspace</h3>
|
|
<p class="muted">A árvore operacional do workspace é a âncora da instalação migrada de máquina. É ali que a skill grava autenticação, outputs e arquivos temporários; por isso a checagem inicial deve validar esse diretório antes de qualquer teste de negócio.</p>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Playwright / browser helper</h3>
|
|
<ul>
|
|
<li>Procura runtime em módulos locais, skill compartilhada <code>~/.codex/skills/playwright</code> e runtimes empacotados do Codex.</li>
|
|
<li>Útil em máquinas novas: normalmente o helper já funciona sem instalação adicional fora do ambiente Codex.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="output">
|
|
<h2>Contrato de saída</h2>
|
|
<p class="section-lead">O formato JSON é estável e foi desenhado para consumo por agente e leitura humana. A ideia é que a mesma execução possa servir para responder no chat, exportar para arquivo e depurar um problema sem reinventar o payload.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Campo</th>
|
|
<th>Função</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>request</code></td><td>Modo, flags resolvidas, escopo, SQL final e contexto da execução.</td></tr>
|
|
<tr><td><code>scope</code></td><td>Disclosure canônico de escopo com <code>scopeMode</code>, explicação e linhas de divulgação.</td></tr>
|
|
<tr><td><code>apiMetrics</code></td><td>Contagem crua de linhas puxadas do Oracle DV. Este é o número oficial de esforço de API.</td></tr>
|
|
<tr><td><code>columns</code></td><td>Colunas estáveis do payload final.</td></tr>
|
|
<tr><td><code>records</code></td><td>Registros já normalizados.</td></tr>
|
|
<tr><td><code>summary</code></td><td>Agregados de intents derivados quando aplicável.</td></tr>
|
|
<tr><td><code>warnings</code></td><td>Limite atingido, fallback, SQL custom sem alias estável, etc.</td></tr>
|
|
<tr><td><code>raw</code></td><td>Payload nativo do Oracle DV para debugging.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="grid-3" style="margin-top:10px;">
|
|
<div class="card">
|
|
<h3>Scope modes</h3>
|
|
<p><code>org-wide</code>, <code>my-team-only</code> e <code>mixed-consistent</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Métricas</h3>
|
|
<p><code>apiMetrics.totalRowsPulledFromApi</code> nunca deve ser trocado por <code>records.length</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Moedas</h3>
|
|
<p><code>bookingValue</code> e <code>workloadAmount</code> saem formatados em <code>k</code>; <code>raw</code> preserva o valor nativo.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Como interpretar o payload sem se perder</h3>
|
|
<ul>
|
|
<li>Leia <code>request</code> para entender o que a skill realmente executou, mesmo que o prompt original tenha sido mais informal.</li>
|
|
<li>Leia <code>scope</code> antes de tirar conclusão de negócio; é ele que explica se o recorte é org-wide, my-team-only ou misto.</li>
|
|
<li>Leia <code>records</code> como resultado final pronto para tabela, CSV ou resumo executivo.</li>
|
|
<li>Volte para <code>raw</code> apenas quando precisar investigar divergência com o backend Oracle DV.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="hierarchy">
|
|
<h2>Hierarquia e semântica</h2>
|
|
<p class="section-lead">Regras que evitam leituras erradas de manager, território, time atual e cobertura. Esta é a seção mais importante quando a pergunta mistura owner comercial, manager de recurso e SR no mesmo resultado.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Heurísticas úteis</h3>
|
|
<ul>
|
|
<li>Em produtividade estilo SA Attach: <code>L3</code> costuma ser o anchor de manager, <code>L4</code> o manager direto e <code>L5</code> o IC/arquiteto.</li>
|
|
<li>Não assumir que <code>Security.Entry Point</code> replica a hierarquia comercial desejada.</li>
|
|
<li><code>vendedor</code>, <code>sales rep</code> e <code>lider de vendas</code> devem ser lidos como <code>territory owner</code> por padrão.</li>
|
|
<li>Para perguntas por manager/recurso, priorizar <code>Knowledge DV - Presales Involvement Aux - V1</code> para cobertura e <code>Knowledge DV - Opportunities - V2</code> para monetário e close date.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Papéis típicos na hierarquia</h3>
|
|
<ul>
|
|
<li>Anchors altos da hierarquia costumam ser úteis para leituras executivas ou rollups amplos.</li>
|
|
<li>O nível usado como <code><manager comercial></code> costuma ser o ponto de corte para pipeline, owner e workload em leitura org-wide.</li>
|
|
<li>O nível usado como <code><manager de recurso></code> costuma ser o ponto de corte para cobertura, recursos alocados e cruzamento com SR.</li>
|
|
<li>O nível usado como <code><recurso alocado></code> costuma representar o IC, arquiteto ou engenheiro diretamente vinculado à oportunidade.</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Regras de escopo que precisam aparecer na resposta</h3>
|
|
<ul>
|
|
<li>Quando o resultado for misto: deixar explícito que oportunidades/workloads são org-wide e recursos/SRs podem ser limitados ao time atual.</li>
|
|
<li>No intent <code>workloads-by-manager-resource-close-window</code>, <code>resourceDetails.srNumbers</code> mistura SR direto confirmado com candidatos internos por mesmo customer quando não há <code>opportunityId</code> utilizável.</li>
|
|
<li>Linhas comerciais org-wide nunca devem sumir só porque não houve match de recurso no enriquecimento.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Leitura segura para perguntas cruzadas</h3>
|
|
<p class="muted">Quando alguém pedir "quais workloads do Brasil têm SR na oportunidade de recursos abaixo de <manager de recurso>", a leitura correta não é "mostrar apenas o que existe no time". A leitura correta é preservar o conjunto comercial do recorte e, em seguida, enriquecer com a visibilidade de recursos e SR disponível para o papel consultado.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="trees">
|
|
<h2>Estrutura de pastas</h2>
|
|
<p class="section-lead">Separação clara entre skill instalada e árvore operacional do workspace.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="code-wrap">
|
|
<h3>Skill instalada</h3>
|
|
<pre><code>knowledge-one-view-cli/
|
|
SKILL.md
|
|
agents/
|
|
openai.yaml
|
|
portable-setup.md
|
|
scripts/
|
|
fetch-sales-intelligence.mjs
|
|
refresh-auth-direct.mjs
|
|
refresh-auth-state.mjs
|
|
run-sales-intelligence-sql.mjs
|
|
lib/
|
|
auth-shared.mjs
|
|
cli-shared.mjs
|
|
date-windows.mjs
|
|
output-contract.mjs
|
|
runtime-paths.mjs
|
|
references/
|
|
api-map.md
|
|
initial-context-catalog.md
|
|
script-catalog.md
|
|
docs/
|
|
docs.html
|
|
tests.html
|
|
tests/
|
|
README.md
|
|
run.mjs
|
|
functions.test.mjs
|
|
sales-prompts.test.mjs
|
|
helpers/
|
|
catalogs.mjs
|
|
cli.mjs
|
|
examples.mjs
|
|
prompts/
|
|
sales-prompts.json</code></pre>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Workspace-side</h3>
|
|
<pre><code><workspace>/
|
|
knowledge-one-view-cli/
|
|
output/
|
|
test-runs/
|
|
*.json / *.csv
|
|
runtime/
|
|
auth-state.json
|
|
session-meta.json
|
|
chrome-profile/
|
|
tmp/
|
|
tmp-render-output-*.json</code></pre>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="testing">
|
|
<h2>Testes e validação</h2>
|
|
<p class="section-lead">A skill possui uma suíte pequena e executável em <code>tests/</code>, com relatório humano em <a href="tests.html">docs/tests.html</a>. Esta parte separa duas perguntas: se o contrato local continua estável e se o backend ainda responde como esperado.</p>
|
|
|
|
<div class="grid-3">
|
|
<div class="card">
|
|
<h3>Status recente</h3>
|
|
<p>Offline passou com <code>12</code> pass, <code>0</code> falhas e <code>1</code> live skipped. Live passou com <code>13</code> pass e <code>0</code> falhas.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>O que o offline cobre</h3>
|
|
<p>Funções locais, SQL renderizado, escopo, contratos de CLI, prompts documentados e summaries com dados controlados.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>O que o live cobre</h3>
|
|
<p>Execução real de comandos já mapeados contra Oracle DV, com <code>--no-cache</code>, escopo, fonte e métricas esperadas.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="table-wrap" style="margin-top:10px;">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Suite</th>
|
|
<th>Objetivo</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>functions.test.mjs</code></td><td>Funções locais, janelas de data, SQL, escopo, summaries e métricas.</td></tr>
|
|
<tr><td><code>sales-prompts.test.mjs</code></td><td>Mapeamento documentado de prompts para comandos CLI e checks live opcionais.</td></tr>
|
|
<tr><td><code>tests/prompts/sales-prompts.json</code></td><td>Casos de prompt com argumentos esperados e placeholders dinâmicos para pessoas.</td></tr>
|
|
<tr><td><code>docs/tests.html</code></td><td>Relatório legível em português e espanhol com objetivos, entradas, saídas e avaliação.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Sequência recomendada de validação</h3>
|
|
<ol>
|
|
<li>Rode <code>node tests/run.mjs</code> para validar contrato local sem Oracle DV.</li>
|
|
<li>Quando houver sessão válida, rode o live com <code>KNOWLEDGE_ONE_VIEW_LIVE=1</code> e <code>ORACLE_SI_RUNTIME_HOME</code>.</li>
|
|
<li>Use <a href="tests.html">docs/tests.html</a> para revisar objetivo, entrada, saída e avaliação de cada caso.</li>
|
|
<li>Só depois avance para um teste de negócio novo, como um workload do Brasil ou um cruzamento com SR.</li>
|
|
</ol>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="commands">
|
|
<h2>Comandos úteis</h2>
|
|
<p class="section-lead">Esses exemplos ajudam a entender o que a skill faz por baixo do pedido em linguagem natural. Use-os como referência manual, não como ponto de partida obrigatório; no dia a dia, o ideal é continuar pedindo em português claro para o Codex.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="code-wrap">
|
|
<h3>Discovery e render</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs --list-intents
|
|
|
|
node scripts/fetch-sales-intelligence.mjs \
|
|
--render-sql \
|
|
--query \
|
|
--select opportunityId,bookingValue \
|
|
--where "opportunityId IS NOT NULL"</code></pre>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Execução normal</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs \
|
|
--intent opportunities-default \
|
|
--limit 200
|
|
|
|
node scripts/fetch-sales-intelligence.mjs \
|
|
--intent opportunities-close-date \
|
|
--date 2026-05-02</code></pre>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-2" style="margin-top:10px;">
|
|
<div class="code-wrap">
|
|
<h3>Janela e cobertura</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs \
|
|
--intent opportunities-by-manager-close-window \
|
|
--manager-email <manager de recurso>@oracle.com \
|
|
--week w2 \
|
|
--week-year 2026
|
|
|
|
node scripts/fetch-sales-intelligence.mjs \
|
|
--intent workloads-by-manager-resource-close-window \
|
|
--manager-email-list <manager de recurso A>@oracle.com,<manager de recurso B>@oracle.com \
|
|
--from-date today \
|
|
--to-date +7d</code></pre>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Auth e testes</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs --check-auth
|
|
|
|
node scripts/refresh-auth-direct.mjs --username <usuario oracle>@oracle.com
|
|
|
|
node tests/run.mjs
|
|
|
|
KNOWLEDGE_ONE_VIEW_LIVE=1 \
|
|
ORACLE_SI_RUNTIME_HOME=/path/to/workspace/knowledge-one-view-cli/runtime \
|
|
node tests/run.mjs</code></pre>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Quando usar cada bloco</h3>
|
|
<ul>
|
|
<li><strong>Discovery e render</strong> serve para entender o catálogo e inspecionar SQL sem tocar o backend.</li>
|
|
<li><strong>Execução normal</strong> serve para consultas diretas de pipeline e close date.</li>
|
|
<li><strong>Janela e cobertura</strong> serve para cruzamentos por manager, recurso e período fiscal.</li>
|
|
<li><strong>Auth e testes</strong> serve para onboarding, migração de máquina e troubleshooting controlado.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="practices">
|
|
<h2>Boas práticas</h2>
|
|
<p class="section-lead">Regras curtas para manter uso e manutenção consistentes. Se a skill continuar simples de operar, a tendência é ela permanecer confiável mesmo quando o workbook ou o ambiente mudarem.</p>
|
|
|
|
<div class="panel">
|
|
<ul>
|
|
<li>Preferir <code>--intent</code> para perguntas recorrentes e <code>--query</code> para ad hoc; cair para <code>--sql</code> só quando necessário.</li>
|
|
<li>Usar aliases de campo locais e placeholders como <code>{{opportunityId}}</code> e <code>{{securityEntryPointFilter}}</code> em vez de adivinhar expressão Oracle.</li>
|
|
<li>Tratar <code>DV - SE Team</code> como fonte de time atual e SR, não como leitura comercial org-wide genérica.</li>
|
|
<li>Quando misturar org-wide com enriquecimento de recurso, preservar sempre a linha comercial original.</li>
|
|
<li>Em PowerShell, usar <code>run-sales-intelligence-sql.mjs</code> para SQL longa ou com quoting frágil.</li>
|
|
<li>Usar <code>--output-file</code> para persistir payloads finais; nomes temporários/intermediários vão para <code>tmp/</code>.</li>
|
|
<li>Documentação oficial da skill fica em <code>docs/docs.html</code>; catálogos operacionais continuam em <code>references/</code>.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<p class="footer">
|
|
Documento consolidado da skill <code>knowledge-one-view-cli</code>. Mantido para leitura rápida, onboarding e referência operacional sem duplicação desnecessária.
|
|
</p>
|
|
</main>
|
|
</div>
|
|
</div>
|
|
<div class="lang-page" data-lang-page="es">
|
|
<div class="page">
|
|
<aside class="sidebar">
|
|
|
|
<div class="language-switch" aria-label="Language selector">
|
|
<button class="language-button" type="button" data-lang-target="pt">Português</button>
|
|
<button class="language-button active" type="button" data-lang-target="es">Español</button>
|
|
</div>
|
|
|
|
<div class="brand">
|
|
<small>Guía de la Skill</small>
|
|
<h1>Knowledge One View CLI</h1>
|
|
<p>Documento único de la skill: visión funcional, técnica y operativa.</p>
|
|
</div>
|
|
|
|
<nav class="nav">
|
|
<a href="#overview">Visión General</a>
|
|
<a href="#use-cases">Casos de Uso</a>
|
|
<a href="#quickstart">Instalación Rápida</a>
|
|
<a href="#reading-path">Internals</a>
|
|
<a href="#roles">Roles y Lenguaje</a>
|
|
<a href="#architecture">Arquitectura</a>
|
|
<a href="#datasets">Datasets</a>
|
|
<a href="#intents">Intents</a>
|
|
<a href="#views">Views</a>
|
|
<a href="#cli">CLI</a>
|
|
<a href="#auth">Auth y Runtime</a>
|
|
<a href="#output">Contrato de Salida</a>
|
|
<a href="#hierarchy">Jerarquía y Semántica</a>
|
|
<a href="#trees">Estructura de Carpetas</a>
|
|
<a href="#testing">Pruebas y Validación</a>
|
|
<a href="#commands">Comandos</a>
|
|
<a href="#practices">Buenas Prácticas</a>
|
|
</nav>
|
|
|
|
<div class="sidebar-note">
|
|
Esta página vive en <code>docs/docs.html</code>. Los archivos en <code>references/</code> siguen como catálogos de apoyo de la skill.
|
|
</div>
|
|
</aside>
|
|
|
|
<main>
|
|
<section class="hero" id="overview">
|
|
<div class="hero-card">
|
|
<span class="eyebrow">Oracle DV</span>
|
|
<h2>Skill para consultar el DV LAD Knowledge One View directamente por la API.</h2>
|
|
<p class="section-lead">Guía consolidada de la skill para onboarding, operación y consulta rápida de la superficie actual.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="use-cases">
|
|
<h2>Casos de uso prácticos</h2>
|
|
<p class="section-lead">Piense en esta skill como un traductor entre el lenguaje de negocio y Oracle DV. Usted describe el alcance deseado en Codex; la skill decide si usa intent, view, query o SQL, resuelve la autenticación y devuelve una salida utilizable.</p>
|
|
|
|
<div class="example-grid">
|
|
<div class="step-card">
|
|
<span class="eyebrow">Ejemplo 1</span>
|
|
<h3>Workloads con SR por manager</h3>
|
|
<pre><code>Prompt en Codex:
|
|
|
|
"Tráeme todos los workloads del cluster Brazil para la próxima semana fiscal de Oracle, cruzando cuáles tienen SR en la oportunidad con recursos bajo <manager de recursos>."</code></pre>
|
|
<p class="muted">Este tipo de solicitud suele caer en el intent <code>workloads-by-manager-resource-close-window</code>. La skill resuelve la semana Oracle, filtra las revenue lines y enriquece el resultado con recursos y SRs visibles.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Ejemplo 2</span>
|
|
<h3>Pipeline con ventana comercial</h3>
|
|
<pre><code>Prompt en Codex:
|
|
|
|
"¿Qué oportunidades con close en el mes actual tienen booking por encima de 500k y territory owner bajo <manager comercial>?"</code></pre>
|
|
<p class="muted">La skill tiende a usar intents o views comerciales en <code>Knowledge DV - Opportunities - V2</code>, manteniendo alcance org-wide y el vocabulario comercial consistente.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Ejemplo 3</span>
|
|
<h3>SRs por recurso</h3>
|
|
<pre><code>Prompt en Codex:
|
|
|
|
"Liste los SRs de <recurso asignado> con status y opportunityId, en formato tabla."</code></pre>
|
|
<p class="muted">Aquí la skill normalmente usa <code>srs-by-resource</code> o una view equivalente en <code>DV - SE Team</code>, respetando el alcance del equipo visible para el usuario ejecutor.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Ejemplo 4</span>
|
|
<h3>Formato de respuesta</h3>
|
|
<pre><code>Respuesta típica:
|
|
|
|
- semana Oracle resuelta
|
|
- alcance de la lectura
|
|
- total de filas obtenidas de la API
|
|
- tabla final con cliente, workload, recurso y SR</code></pre>
|
|
<p class="muted">Si usted pide "muéstralo en tabla", "genera un informe HTML", "arma un PDF ejecutivo", "organiza en una planilla" o "automatiza el envío por email", Codex puede transformar el payload final en entregables más útiles para consumo y seguimiento.</p>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="quickstart">
|
|
<h2>Instalación rápida y primer uso</h2>
|
|
<p class="section-lead">En una máquina nueva, la secuencia ideal es: instalar la skill, confirmar la sesión Oracle DV una vez y luego seguir browserless en la rutina normal. El objetivo es gastar energía en el negocio, no en setup.</p>
|
|
|
|
<div class="steps-grid">
|
|
<div class="step-card">
|
|
<span class="eyebrow">Paso 1</span>
|
|
<h3>Pedir la instalación en Codex</h3>
|
|
<pre><code>Prompt en Codex:
|
|
|
|
"Instala la skill knowledge-one-view-cli en Codex y valida la carpeta runtime/output en el workspace."</code></pre>
|
|
<p class="muted">Después de eso, la skill queda instalada en <code>~/.codex/skills/knowledge-one-view-cli</code>.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Paso 2</span>
|
|
<h3>Probar la autenticación en Chrome</h3>
|
|
<pre><code>Prompt en Codex:
|
|
|
|
"Haz una prueba de autenticación de la skill vía Chrome y confirma si el backend Oracle DV respondió."</code></pre>
|
|
<p class="muted">El helper abre el navegador solo para grabar <code>auth-state.json</code> y <code>session-meta.json</code> en el runtime del workspace.</p>
|
|
</div>
|
|
|
|
<div class="step-card">
|
|
<span class="eyebrow">Paso 3</span>
|
|
<h3>Seguir browserless</h3>
|
|
<pre><code>Prompt en Codex:
|
|
|
|
"Tráeme todos los workloads del cluster Brazil para la próxima semana fiscal de Oracle."</code></pre>
|
|
<p class="muted">A partir de ahí, la skill normalmente sigue sin browser, consultando el backend Oracle DV directamente por la API.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section-stack" style="margin-top:10px;">
|
|
<div class="panel">
|
|
<h3>How-to exprés</h3>
|
|
<ol>
|
|
<li>Pídale a Codex que instale o valide la skill.</li>
|
|
<li>Pídale a Codex que haga una prueba de autenticación de la skill vía Chrome.</li>
|
|
<li>Complete el login y el MFA.</li>
|
|
<li>Después de eso, siga usándola en lenguaje natural.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Ejemplo de respuesta después del primer uso</h3>
|
|
<pre><code>Resultado típico:
|
|
|
|
"Auth validada en el runtime del workspace.
|
|
Backend Oracle DV accesible.
|
|
Raw rows pulled from the API: 5.
|
|
Aquí está la tabla con cliente, workload, close date y territory owner."</code></pre>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="reading-path">
|
|
<h2>Internals - No es necesario para usar la skill</h2>
|
|
<p class="section-lead">La página fue reorganizada para funcionar bien tanto para onboarding como para troubleshooting. Si usted está llegando ahora, conviene seguir este orden en lugar de saltar directo a los comandos.</p>
|
|
|
|
<div class="grid-3">
|
|
<div class="step-card">
|
|
<span class="eyebrow">Lectura 1</span>
|
|
<h3>Entienda la solicitud</h3>
|
|
<p class="muted">Empiece por <strong>Casos de uso</strong> y <strong>Roles y lenguaje</strong>. Muestran cómo transformar una pregunta de negocio en un alcance consistente de owner, manager, recurso, workload y SR.</p>
|
|
</div>
|
|
<div class="step-card">
|
|
<span class="eyebrow">Lectura 2</span>
|
|
<h3>Entienda la ejecución</h3>
|
|
<p class="muted">Después vea <strong>Arquitectura</strong>, <strong>Datasets</strong> e <strong>Intents</strong>. Esta parte explica de dónde vienen los datos y por qué la skill elige intent, view, query o SQL.</p>
|
|
</div>
|
|
<div class="step-card">
|
|
<span class="eyebrow">Lectura 3</span>
|
|
<h3>Entienda la operación</h3>
|
|
<p class="muted">Cierre con <strong>Auth y Runtime</strong>, <strong>Contrato de salida</strong>, <strong>Pruebas</strong> y <strong>Comandos</strong>. Así ya puede instalar, validar y depurar con seguridad.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Atajo mental para usar bien</h3>
|
|
<ul>
|
|
<li>Si la pregunta es recurrente, piense en <code>intent</code>.</li>
|
|
<li>Si quiere un extracto conocido, piense en <code>view</code>.</li>
|
|
<li>Si necesita montar un alcance a medida sin ir a SQL, piense en <code>query</code>.</li>
|
|
<li>Si está investigando un caso raro o depurando Oracle DV, entonces sí piense en <code>sql</code>.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="roles">
|
|
<h2>Roles y lenguaje</h2>
|
|
<p class="section-lead">Esta guía evita nombres personales y usa roles de negocio. Eso hace la documentación más transferible, más segura y más fácil de reutilizar en otros equipos.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Roles que aparecen en esta guía</h3>
|
|
<ul>
|
|
<li><code><territory owner></code>: dueño comercial directo de la oportunidad o workload.</li>
|
|
<li><code><manager comercial></code>: responsable de la jerarquía de territory owners usada para alcances comerciales.</li>
|
|
<li><code><manager de recursos></code>: responsable del lado presales/ingeniería, usado para cruzar recursos asignados en oportunidades.</li>
|
|
<li><code><recurso asignado></code>: arquitecto, ingeniero o especialista asociado a la oportunidad.</li>
|
|
<li><code><equipo actual del usuario></code>: alcance visible en <code>DV - SE Team</code> para quien ejecuta la skill.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Traducción práctica del lenguaje</h3>
|
|
<ul>
|
|
<li>Cuando alguien pida "vendedor", la lectura estándar debe ser <code><territory owner></code>.</li>
|
|
<li>Cuando alguien pida "recursos bajo un manager", la lectura suele ser <code><manager de recursos></code> en <code>Knowledge DV - Presales Involvement Aux - V1</code>.</li>
|
|
<li>Cuando alguien pida SR, cobertura o contexto de sesión, la lectura suele involucrar el alcance del <code><equipo actual del usuario></code>.</li>
|
|
<li>Cuando la solicitud mezcla comercial y recurso, la skill normalmente combina una fuente org-wide con enriquecimiento controlado por rol.</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Cómo leer los ejemplos</h3>
|
|
<p class="muted">Siempre que vea un rol entre <code><...></code>, sustitúyalo por el identificador real de su pregunta. El rol explica qué atributo de la jerarquía debe usar la skill, sin atar la documentación a una persona específica.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="architecture">
|
|
<h2>Arquitectura</h2>
|
|
<p class="section-lead">Estructura simple: el fetch principal concentra la lógica de negocio y <code>scripts/lib/runtime-paths.mjs</code> se ocupa del runtime, output y bootstrap del workspace.</p>
|
|
|
|
<div class="panel">
|
|
<h3>Flujo principal</h3>
|
|
<ol>
|
|
<li>Parse de argumentos y validación del modo de ejecución.</li>
|
|
<li>Resolución de <code>runtime-home</code>, archivos de sesión y caché.</li>
|
|
<li>Opcionalmente resolución de año fiscal y contexto de sesión.</li>
|
|
<li>Construcción de SQL vía intent, view, query declarativa o SQL bruto.</li>
|
|
<li>Ejecución en <code>sqlquery/execute</code> con restauración de sesión si es necesario.</li>
|
|
<li>Normalización de filas, alcance, métricas, warnings y persistencia opcional en archivo.</li>
|
|
</ol>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Módulos actuales</h3>
|
|
<p class="muted">Actualmente, la skill está organizada en un script principal, helpers de autenticación y utilitarios internos en <code>scripts/lib/</code>. La lista siguiente refleja los módulos realmente presentes en el código actual.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Módulo</th>
|
|
<th>Responsabilidad</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>fetch-sales-intelligence.mjs</code></td>
|
|
<td>Catálogo local, query engine, intents, views, orquestación y ejecución Oracle DV.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>refresh-auth-direct.mjs</code></td>
|
|
<td>Login Oracle sin abrir Chrome, con MFA.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>refresh-auth-state.mjs</code></td>
|
|
<td>Refresh de auth vía browser/Playwright cuando el flujo directo no alcanza.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>run-sales-intelligence-sql.mjs</code></td>
|
|
<td>Ayuda para SQL larga o sensible al quoting del shell.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/runtime-paths.mjs</code></td>
|
|
<td>Resolución canónica de <code>runtime</code>, <code>output</code>, <code>tmp</code>, bootstrap de workspace y fallback legado.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/auth-shared.mjs</code></td>
|
|
<td>Lectura, persistencia y refresh de los artefactos de sesión, cookies, CSRF y metadatos de autenticación.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/cli-shared.mjs</code></td>
|
|
<td>Parse de argumentos, normalización de flags y helpers utilitarios de entrada.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/date-windows.mjs</code></td>
|
|
<td>Resolución de ventanas temporales, semanas fiscales, quarters y atajos como <code>today</code> o <code>+7d</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>lib/output-contract.mjs</code></td>
|
|
<td>Construcción del payload final con <code>apiMetrics</code>, <code>warnings</code>, normalización de filas y emisión JSON.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Endpoint y estado local</h3>
|
|
<ul>
|
|
<li>Endpoint principal: <code>POST /ui/dv/ui/api/v1/sqlquery/execute</code>.</li>
|
|
<li>Workbook objetivo: <code>salesintelligence-dv.oracle.com</code> en el report path LAD Knowledge One View.</li>
|
|
<li>Estado persistido: <code>auth-state.json</code> y <code>session-meta.json</code>.</li>
|
|
<li>Fallback legado de lectura: <code>~/.codex/oracle-sales-intelligence-direct/</code>.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="datasets">
|
|
<h2>Datasets</h2>
|
|
<p class="section-lead">Resumen de las fuentes realmente usadas por la skill y del papel de cada una. Esta sección existe para evitar el error más común en este tipo de análisis: consultar la fuente correcta con la lectura equivocada del alcance.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Dataset</th>
|
|
<th>Alcance</th>
|
|
<th>Papel principal</th>
|
|
<th>Observaciones</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>Knowledge DV - Opportunities - V2</code></td>
|
|
<td>Org-wide</td>
|
|
<td>Fuente comercial principal: pipeline, opportunities, won, close date, booking, workload, territory y owner.</td>
|
|
<td>Base normal para <code>opportunities-default</code>, <code>opportunities-close-*</code> y views <code>sa-attach-*</code> comerciales.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Knowledge DV - Hours - V2</code></td>
|
|
<td>Org-wide por defecto; my-team con <code>--scope my-team</code></td>
|
|
<td>Horas, ownership y productividad por jerarquía.</td>
|
|
<td>Expuesto en <code>sa-attach-hours-by-opportunity</code>; en <code>--scope auto</code> preserva la lectura org-wide.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Knowledge DV - Presales Involvement Aux - V1</code></td>
|
|
<td>Org-wide por defecto; my-team con <code>--scope my-team</code></td>
|
|
<td>Cobertura y vínculo manager/recurso/oportunidad.</td>
|
|
<td>Base normal para cobertura presales y linkage manager/recurso; intents de workload/manager usan esta lectura org-wide.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>DV - SE Team</code></td>
|
|
<td>My-team-only</td>
|
|
<td>Session context, SRs y fallback comercial solo cuando la pregunta es explícitamente del equipo actual.</td>
|
|
<td>No debe usarse como fuente comercial genérica org-wide.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Knowledge DV - Revn Lines by SE</code></td>
|
|
<td>Org-wide por defecto; my-team con <code>--scope my-team</code></td>
|
|
<td>Detalle de revenue lines.</td>
|
|
<td>Expuesto por <code>revenue-line-details</code> como extracto org-wide en <code>--scope auto</code>.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Cómo elegir la fuente correcta</h3>
|
|
<ul>
|
|
<li>Si la pregunta es comercial y necesita preservar todas las oportunidades del alcance, la base tiende a ser <code>Knowledge DV - Opportunities - V2</code>.</li>
|
|
<li>Si la pregunta es sobre quién está asignado, cubierto o relacionado con una oportunidad, la base tiende a ser <code>Knowledge DV - Presales Involvement Aux - V1</code> y la skill intenta org-wide primero.</li>
|
|
<li>Si la pregunta es sobre SR, contexto de la sesión o el equipo visible del ejecutor, la base tiende a pasar por <code>DV - SE Team</code>.</li>
|
|
<li>Si la pregunta es sobre horas y productividad, la skill tiende a usar <code>Knowledge DV - Hours - V2</code> en org-wide, salvo solicitud explícita de equipo actual.</li>
|
|
<li>Si la pregunta es sobre revenue line detallada, la skill tiende a consultar <code>Knowledge DV - Revn Lines by SE</code> en org-wide, salvo solicitud explícita de equipo actual.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="grid-3" style="margin-top:10px;">
|
|
<div class="card">
|
|
<h3>Defaults SA Attach</h3>
|
|
<p><code>cluster=Brazil</code>, <code>sales-credit-type=QUOTA</code>, <code>solution=Cloud Infrastructure - Workloads, Hardware - Bookings, On-Premise Technology - Bookings</code>, <code>revenue-type-group=NEW,EXPANSION,WORKLOAD</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Aliases importantes</h3>
|
|
<p><code>workload</code> y <code>workloads</code> se normalizan a <code>WORKLOAD</code>. <code>license and hardware</code> se normaliza a <code>License,Hardware</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Monetario</h3>
|
|
<p>Los outputs comerciales usan preferentemente <code>bookingValue</code> y <code>workloadAmount</code>; la sección <code>raw</code> preserva el valor nativo del backend.</p>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="intents">
|
|
<h2>Intents</h2>
|
|
<p class="section-lead">Use intent primero cuando la solicitud ya parece un caso de negocio recurrente. Esta es la forma más fácil de pedir algo en Codex sin tener que pensar en SQL, aliases o tablas internas.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Intent</th>
|
|
<th>Cuándo usar</th>
|
|
<th>Entrada clave</th>
|
|
<th>Alcance</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>opportunities-default</code></td><td>Consulta comercial estándar de pipeline/opportunities.</td><td><code>--limit</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-close-date</code></td><td>Close date exacta.</td><td><code>--date</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-close-month</code></td><td>Mes calendario.</td><td><code>--month</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-close-quarter</code></td><td>Quarter fiscal.</td><td><code>--quarter</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-current-team-close-window</code></td><td>Ventana comercial org-wide enriquecida con cobertura del equipo actual.</td><td>ventana de fechas</td><td>Mixed-consistent</td></tr>
|
|
<tr><td><code>opportunities-by-resource-close-window</code></td><td>Ventana comercial con cobertura de un recurso explícito.</td><td><code>--resource</code> + ventana</td><td>Org-wide</td></tr>
|
|
<tr><td><code>opportunities-by-manager-close-window</code></td><td>Ventana comercial con cobertura de un manager explícito.</td><td><code>--manager-email</code> + ventana</td><td>Org-wide</td></tr>
|
|
<tr><td><code>workloads-by-owner-current</code></td><td>Estado actual de workloads para un territory owner.</td><td><code>--owner-email</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>workloads-by-owner-manager-current</code></td><td>Estado actual de workloads bajo un manager de owners.</td><td><code>--owner-manager-email</code></td><td>Org-wide</td></tr>
|
|
<tr><td><code>workloads-by-manager-resource-close-window</code></td><td>Revenue lines workload con manager/resource allocation org-wide y SRs visibles del equipo.</td><td><code>--manager-email-list</code> + ventana</td><td>Mixed-consistent</td></tr>
|
|
<tr><td><code>srs-by-resource</code></td><td>SRs por recurso Oracle.</td><td><code>--resource</code></td><td>My-team-only</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="views">
|
|
<h2>Views</h2>
|
|
<p class="section-lead">Use view cuando ya sabe exactamente el shape del extracto que quiere. Las views son buenas para integraciones, análisis repetidos y validaciones sobre un contrato estable, sin tener que redescubrir campo por campo.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>View</th>
|
|
<th>Fuente</th>
|
|
<th>Alcance</th>
|
|
<th>Uso</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>current-fiscal-year</code></td><td>DV session</td><td>My-team-only</td><td>Año fiscal de la sesión Oracle DV.</td></tr>
|
|
<tr><td><code>data-quality-session-context</code></td><td>DV session</td><td>My-team-only</td><td>Entry point y variables fiscales de la sesión.</td></tr>
|
|
<tr><td><code>effort-by-se-team</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Horas por miembro del equipo.</td></tr>
|
|
<tr><td><code>effort-task-type-summary</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Horas por task type.</td></tr>
|
|
<tr><td><code>opportunities-close-window</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Una fila por oportunidad en ventana de close date.</td></tr>
|
|
<tr><td><code>opportunity-details</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Detalle comercial de oportunidades.</td></tr>
|
|
<tr><td><code>revenue-line-details</code></td><td>Knowledge DV - Revn Lines by SE</td><td>Org-wide</td><td>Detalle de revenue lines.</td></tr>
|
|
<tr><td><code>sa-attach-hours-by-opportunity</code></td><td>Knowledge DV - Hours - V2</td><td>Org-wide</td><td>Horas/cobertura por oportunidad.</td></tr>
|
|
<tr><td><code>sa-attach-involvement-distribution</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Distribución agregada por bucket de involucramiento.</td></tr>
|
|
<tr><td><code>sa-attach-open-pipeline</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Métrica de pipeline abierto.</td></tr>
|
|
<tr><td><code>sa-attach-pipeline-details</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Extracto comercial más completo de la skill.</td></tr>
|
|
<tr><td><code>sa-attach-presales-coverage</code></td><td>Knowledge DV - Presales Involvement Aux - V1</td><td>Org-wide</td><td>Cobertura presales por oportunidad.</td></tr>
|
|
<tr><td><code>sa-attach-won-pipeline</code></td><td>Knowledge DV - Opportunities - V2</td><td>Org-wide</td><td>Métrica de pipeline won.</td></tr>
|
|
<tr><td><code>sr-details</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Detalle de SR.</td></tr>
|
|
<tr><td><code>srs-by-resource-email</code></td><td>DV - SE Team</td><td>My-team-only</td><td>SRs por email de recurso.</td></tr>
|
|
<tr><td><code>won-and-open-by-se-opty</code></td><td>DV - SE Team</td><td>My-team-only</td><td>Contribución por oportunidad y miembro del equipo.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<details>
|
|
<summary>Notas rápidas de alcance</summary>
|
|
<ul>
|
|
<li><code>org-wide</code>: filas comerciales visibles para la jerarquía comercial del workbook.</li>
|
|
<li><code>my-team-only</code>: visibilidad limitada al equipo del usuario ejecutor en <code>DV - SE Team</code>.</li>
|
|
<li><code>mixed-consistent</code>: filas comerciales org-wide preservadas, enriquecimiento de recursos/SRs restringido al alcance apropiado.</li>
|
|
<li><code>scope.components</code>: detalle fuente por fuente; prefiera ese campo cuando el resultado combine alcances.</li>
|
|
</ul>
|
|
</details>
|
|
</section>
|
|
|
|
<section class="section" id="cli">
|
|
<h2>Superficie CLI</h2>
|
|
<p class="section-lead">La CLI existe para cuando quiere ejecutar la skill manualmente o entender qué está haciendo Codex por debajo. Cada llamada debe elegir exactamente un modo entre <code>--intent</code>, <code>--view</code>, <code>--query</code> y <code>--sql</code>.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Modos</h3>
|
|
<ul>
|
|
<li><code>--intent</code>: camino preferido para preguntas recurrentes.</li>
|
|
<li><code>--view</code>: extracto conocido, contrato estable.</li>
|
|
<li><code>--query</code>: aliases + filtros + grouping + ordering, con inferencia de fuente y política org-wide-first por defecto.</li>
|
|
<li><code>--sql</code>: SQL lógico Oracle bruto, con placeholders locales.</li>
|
|
<li><code>--render-sql</code>: render local para <code>--query</code> o <code>--sql</code>, sin backend.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Discovery</h3>
|
|
<ul>
|
|
<li><code>--catalog</code></li>
|
|
<li><code>--list-views</code>, <code>--describe-view</code></li>
|
|
<li><code>--list-intents</code>, <code>--describe-intent</code></li>
|
|
<li><code>--list-fields</code>, <code>--describe-field</code></li>
|
|
<li><code>--list-parameters</code>, <code>--describe-parameter</code></li>
|
|
<li><code>--list-scripts</code>, <code>--describe-script</code></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-3" style="margin-top:10px;">
|
|
<div class="card">
|
|
<h3>Ventana temporal</h3>
|
|
<p><code>--date</code>, <code>--month</code>, <code>--quarter</code>, <code>--week</code> o el par <code>--from-date</code>/<code>--to-date</code>. Nunca los combine entre sí.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Jerarquía y recurso</h3>
|
|
<p><code>--resource</code>, <code>--resource-email</code>, <code>--manager-email</code>, <code>--manager-email-list</code>, <code>--owner-email</code>, <code>--owner-manager-email</code>, <code>--match-role</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Filtros SA Attach</h3>
|
|
<p><code>--cluster</code>, <code>--solution</code>, <code>--revenue-line-status</code>, <code>--executive-product-lob</code>, <code>--revenue-type-group</code>, <code>--sales-credit-type</code>, <code>--min-opportunity-probability</code>, <code>--forecast-type</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Alcance</h3>
|
|
<p><code>--scope auto</code> intenta org-wide primero en fuentes XSA compatibles; <code>--scope my-team</code> fuerza la lectura del equipo actual cuando la fuente soporta ese alcance.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<details>
|
|
<summary>Modelo de week</summary>
|
|
<ul>
|
|
<li><code>week-year</code> es el año de inicio del ciclo Junio-Mayo.</li>
|
|
<li>En el contexto actual, el ciclo default es <code>2025-06-01</code> hasta <code>2026-05-31</code>.</li>
|
|
<li>Ejemplos: <code>W1 = 2025-06-01..2025-06-07</code>, <code>W43 = 2026-03-22..2026-03-28</code>, <code>W53 = 2026-05-31</code>.</li>
|
|
</ul>
|
|
</details>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Regla práctica de elección</h3>
|
|
<ul>
|
|
<li>Empiece por <code>--intent</code> siempre que exista un intent compatible con la pregunta.</li>
|
|
<li>Use <code>--view</code> cuando quiera consistencia de columnas para export, reconciliación o integración.</li>
|
|
<li>Use <code>--query</code> cuando la pregunta es nueva, pero todavía cabe en aliases conocidos y filtros claros.</li>
|
|
<li>Deje <code>--sql</code> para casos realmente excepcionales, porque exige más cuidado con Oracle DV y aumenta la posibilidad de drift de contrato.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="auth">
|
|
<h2>Auth y Runtime</h2>
|
|
<p class="section-lead">El objetivo es reutilizar la sesión local y abrir el browser solo cuando la sesión necesite rehacerse. En uso normal, la skill debe parecer browserless incluso cuando hubo una autenticación inicial en Chrome.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Archivos de sesión</h3>
|
|
<ul>
|
|
<li><code><workspace>/knowledge-one-view-cli/runtime/auth-state.json</code></li>
|
|
<li><code><workspace>/knowledge-one-view-cli/runtime/session-meta.json</code></li>
|
|
<li><code><workspace>/knowledge-one-view-cli/runtime/chrome-profile/</code></li>
|
|
</ul>
|
|
<p class="muted">La lectura puede caer al legado en <code>~/.codex/oracle-sales-intelligence-direct/</code> cuando el runtime nuevo todavía está vacío.</p>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Estrategia de autenticación</h3>
|
|
<ol>
|
|
<li><code>--check-auth</code> solo diagnostica.</li>
|
|
<li><code>refresh-auth-direct.mjs</code> es el camino preferido para MFA sin browser.</li>
|
|
<li><code>refresh-auth-state.mjs</code> es helper de browser para troubleshooting o refresh interactivo.</li>
|
|
<li>En ejecución normal, el fetch puede disparar refresh automático y reejecutar la consulta.</li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Cómo pensar el runtime en el workspace</h3>
|
|
<p class="muted">El árbol operativo del workspace es el ancla de la instalación migrada de máquina. Es allí donde la skill graba autenticación, outputs y archivos temporales; por eso la verificación inicial debe validar ese directorio antes de cualquier prueba de negocio.</p>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Playwright / browser helper</h3>
|
|
<ul>
|
|
<li>Busca runtime en módulos locales, skill compartida <code>~/.codex/skills/playwright</code> y runtimes empaquetados de Codex.</li>
|
|
<li>Útil en máquinas nuevas: normalmente el helper ya funciona sin instalación adicional fuera del entorno Codex.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="output">
|
|
<h2>Contrato de salida</h2>
|
|
<p class="section-lead">El formato JSON es estable y fue diseñado para consumo por agente y lectura humana. La idea es que la misma ejecución pueda servir para responder en el chat, exportar a archivo y depurar un problema sin reinventar el payload.</p>
|
|
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Campo</th>
|
|
<th>Función</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>request</code></td><td>Modo, flags resueltas, alcance, SQL final y contexto de la ejecución.</td></tr>
|
|
<tr><td><code>scope</code></td><td>Disclosure canónico de alcance con <code>scopeMode</code>, explicación y líneas de divulgación.</td></tr>
|
|
<tr><td><code>apiMetrics</code></td><td>Conteo bruto de filas obtenidas de Oracle DV. Este es el número oficial de esfuerzo de API.</td></tr>
|
|
<tr><td><code>columns</code></td><td>Columnas estables del payload final.</td></tr>
|
|
<tr><td><code>records</code></td><td>Registros ya normalizados.</td></tr>
|
|
<tr><td><code>summary</code></td><td>Agregados de intents derivados cuando aplica.</td></tr>
|
|
<tr><td><code>warnings</code></td><td>Límite alcanzado, fallback, SQL custom sin alias estable, etc.</td></tr>
|
|
<tr><td><code>raw</code></td><td>Payload nativo de Oracle DV para debugging.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="grid-3" style="margin-top:10px;">
|
|
<div class="card">
|
|
<h3>Scope modes</h3>
|
|
<p><code>org-wide</code>, <code>my-team-only</code> y <code>mixed-consistent</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Métricas</h3>
|
|
<p><code>apiMetrics.totalRowsPulledFromApi</code> nunca debe ser reemplazado por <code>records.length</code>.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Monedas</h3>
|
|
<p><code>bookingValue</code> y <code>workloadAmount</code> salen formateados en <code>k</code>; <code>raw</code> preserva el valor nativo.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Cómo interpretar el payload sin perderse</h3>
|
|
<ul>
|
|
<li>Lea <code>request</code> para entender qué ejecutó realmente la skill, incluso si el prompt original fue más informal.</li>
|
|
<li>Lea <code>scope</code> antes de sacar una conclusión de negocio; ese campo explica si el alcance es org-wide, my-team-only o mixto.</li>
|
|
<li>Lea <code>records</code> como resultado final listo para tabla, CSV o resumen ejecutivo.</li>
|
|
<li>Vuelva a <code>raw</code> solo cuando necesite investigar una divergencia con el backend Oracle DV.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="hierarchy">
|
|
<h2>Jerarquía y semántica</h2>
|
|
<p class="section-lead">Reglas que evitan lecturas equivocadas de manager, territorio, equipo actual y cobertura. Esta es la sección más importante cuando la pregunta mezcla owner comercial, manager de recursos y SR en el mismo resultado.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="panel">
|
|
<h3>Heurísticas útiles</h3>
|
|
<ul>
|
|
<li>En productividad estilo SA Attach: <code>L3</code> suele ser el anchor de manager, <code>L4</code> el manager directo y <code>L5</code> el IC/arquitecto.</li>
|
|
<li>No asumir que <code>Security.Entry Point</code> replica la jerarquía comercial deseada.</li>
|
|
<li><code>vendedor</code>, <code>sales rep</code> y <code>líder de ventas</code> deben leerse como <code>territory owner</code> por defecto.</li>
|
|
<li>Para preguntas por manager/recurso, priorizar <code>Knowledge DV - Presales Involvement Aux - V1</code> para cobertura y <code>Knowledge DV - Opportunities - V2</code> para monetario y close date.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel">
|
|
<h3>Roles típicos en la jerarquía</h3>
|
|
<ul>
|
|
<li>Anchors altos de la jerarquía suelen ser útiles para lecturas ejecutivas o rollups amplios.</li>
|
|
<li>El nivel usado como <code><manager comercial></code> suele ser el punto de corte para pipeline, owner y workload en lectura org-wide.</li>
|
|
<li>El nivel usado como <code><manager de recursos></code> suele ser el punto de corte para cobertura, recursos asignados y cruce con SR.</li>
|
|
<li>El nivel usado como <code><recurso asignado></code> suele representar al IC, arquitecto o ingeniero directamente vinculado a la oportunidad.</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Reglas de alcance que deben aparecer en la respuesta</h3>
|
|
<ul>
|
|
<li>Cuando el resultado sea mixto: dejar explícito que oportunidades/workloads son org-wide y recursos/SRs pueden estar limitados al equipo actual.</li>
|
|
<li>En el intent <code>workloads-by-manager-resource-close-window</code>, <code>resourceDetails.srNumbers</code> mezcla SR directo confirmado con candidatos internos del mismo customer cuando no hay <code>opportunityId</code> utilizable.</li>
|
|
<li>Las filas comerciales org-wide nunca deben desaparecer solo porque no hubo match de recurso en el enriquecimiento.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Lectura segura para preguntas cruzadas</h3>
|
|
<p class="muted">Cuando alguien pida "qué workloads de Brasil tienen SR en la oportunidad con recursos bajo <manager de recursos>", la lectura correcta no es "mostrar solo lo que existe en el equipo". La lectura correcta es preservar el conjunto comercial del alcance y, a continuación, enriquecerlo con la visibilidad de recursos y SR disponible para el rol consultado.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="trees">
|
|
<h2>Estructura de carpetas</h2>
|
|
<p class="section-lead">Separación clara entre la skill instalada y el árbol operativo del workspace.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="code-wrap">
|
|
<h3>Skill instalada</h3>
|
|
<pre><code>knowledge-one-view-cli/
|
|
SKILL.md
|
|
agents/
|
|
openai.yaml
|
|
portable-setup.md
|
|
scripts/
|
|
fetch-sales-intelligence.mjs
|
|
refresh-auth-direct.mjs
|
|
refresh-auth-state.mjs
|
|
run-sales-intelligence-sql.mjs
|
|
lib/
|
|
auth-shared.mjs
|
|
cli-shared.mjs
|
|
date-windows.mjs
|
|
output-contract.mjs
|
|
runtime-paths.mjs
|
|
references/
|
|
api-map.md
|
|
initial-context-catalog.md
|
|
script-catalog.md
|
|
docs/
|
|
docs.html
|
|
tests.html
|
|
tests/
|
|
README.md
|
|
run.mjs
|
|
functions.test.mjs
|
|
sales-prompts.test.mjs
|
|
helpers/
|
|
catalogs.mjs
|
|
cli.mjs
|
|
examples.mjs
|
|
prompts/
|
|
sales-prompts.json</code></pre>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Lado del workspace</h3>
|
|
<pre><code><workspace>/
|
|
knowledge-one-view-cli/
|
|
output/
|
|
test-runs/
|
|
*.json / *.csv
|
|
runtime/
|
|
auth-state.json
|
|
session-meta.json
|
|
chrome-profile/
|
|
tmp/
|
|
tmp-render-output-*.json</code></pre>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="testing">
|
|
<h2>Pruebas y validación</h2>
|
|
<p class="section-lead">La skill posee una suite pequeña y ejecutable en <code>tests/</code>, con reporte humano en <a href="tests.html">docs/tests.html</a>. Esta parte separa dos preguntas: si el contrato local sigue estable y si el backend todavía responde como se espera.</p>
|
|
|
|
<div class="grid-3">
|
|
<div class="card">
|
|
<h3>Estado reciente</h3>
|
|
<p>Offline pasó con <code>12</code> pass, <code>0</code> fallas y <code>1</code> live skipped. Live pasó con <code>13</code> pass y <code>0</code> fallas.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Qué cubre offline</h3>
|
|
<p>Funciones locales, SQL renderizado, alcance, contratos de CLI, prompts documentados y summaries con datos controlados.</p>
|
|
</div>
|
|
<div class="card">
|
|
<h3>Qué cubre live</h3>
|
|
<p>Ejecución real de comandos ya mapeados contra Oracle DV, con <code>--no-cache</code>, alcance, fuente y métricas esperadas.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="table-wrap" style="margin-top:10px;">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Suite</th>
|
|
<th>Objetivo</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>functions.test.mjs</code></td><td>Funciones locales, ventanas de fecha, SQL, alcance, summaries y métricas.</td></tr>
|
|
<tr><td><code>sales-prompts.test.mjs</code></td><td>Mapeo documentado de prompts a comandos CLI y checks live opcionales.</td></tr>
|
|
<tr><td><code>tests/prompts/sales-prompts.json</code></td><td>Casos de prompt con argumentos esperados y placeholders dinámicos para personas.</td></tr>
|
|
<tr><td><code>docs/tests.html</code></td><td>Reporte legible en portugués y español con objetivos, entradas, salidas y evaluación.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Secuencia recomendada de validación</h3>
|
|
<ol>
|
|
<li>Ejecute <code>node tests/run.mjs</code> para validar el contrato local sin Oracle DV.</li>
|
|
<li>Cuando haya sesión válida, ejecute live con <code>KNOWLEDGE_ONE_VIEW_LIVE=1</code> y <code>ORACLE_SI_RUNTIME_HOME</code>.</li>
|
|
<li>Use <a href="tests.html">docs/tests.html</a> para revisar objetivo, entrada, salida y evaluación de cada caso.</li>
|
|
<li>Solo después avance a una prueba de negocio nueva, como un workload de Brasil o un cruce con SR.</li>
|
|
</ol>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="commands">
|
|
<h2>Comandos útiles</h2>
|
|
<p class="section-lead">Estos ejemplos ayudan a entender qué hace la skill detrás de una solicitud en lenguaje natural. Úselos como referencia manual, no como punto de partida obligatorio; en el día a día, lo ideal es seguir pidiendo en español claro a Codex.</p>
|
|
|
|
<div class="grid-2">
|
|
<div class="code-wrap">
|
|
<h3>Discovery y render</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs --list-intents
|
|
|
|
node scripts/fetch-sales-intelligence.mjs \
|
|
--render-sql \
|
|
--query \
|
|
--select opportunityId,bookingValue \
|
|
--where "opportunityId IS NOT NULL"</code></pre>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Ejecución normal</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs \
|
|
--intent opportunities-default \
|
|
--limit 200
|
|
|
|
node scripts/fetch-sales-intelligence.mjs \
|
|
--intent opportunities-close-date \
|
|
--date 2026-05-02</code></pre>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-2" style="margin-top:10px;">
|
|
<div class="code-wrap">
|
|
<h3>Ventana y cobertura</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs \
|
|
--intent opportunities-by-manager-close-window \
|
|
--manager-email <manager de recursos>@oracle.com \
|
|
--week w2 \
|
|
--week-year 2026
|
|
|
|
node scripts/fetch-sales-intelligence.mjs \
|
|
--intent workloads-by-manager-resource-close-window \
|
|
--manager-email-list <manager de recursos A>@oracle.com,<manager de recursos B>@oracle.com \
|
|
--from-date today \
|
|
--to-date +7d</code></pre>
|
|
</div>
|
|
|
|
<div class="code-wrap">
|
|
<h3>Auth y pruebas</h3>
|
|
<pre><code>node scripts/fetch-sales-intelligence.mjs --check-auth
|
|
|
|
node scripts/refresh-auth-direct.mjs --username <usuario oracle>@oracle.com
|
|
|
|
node tests/run.mjs
|
|
|
|
KNOWLEDGE_ONE_VIEW_LIVE=1 \
|
|
ORACLE_SI_RUNTIME_HOME=/path/to/workspace/knowledge-one-view-cli/runtime \
|
|
node tests/run.mjs</code></pre>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="panel" style="margin-top:10px;">
|
|
<h3>Cuándo usar cada bloque</h3>
|
|
<ul>
|
|
<li><strong>Discovery y render</strong> sirve para entender el catálogo e inspeccionar SQL sin tocar el backend.</li>
|
|
<li><strong>Ejecución normal</strong> sirve para consultas directas de pipeline y close date.</li>
|
|
<li><strong>Ventana y cobertura</strong> sirve para cruces por manager, recurso y período fiscal.</li>
|
|
<li><strong>Auth y pruebas</strong> sirve para onboarding, migración de máquina y troubleshooting controlado.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section" id="practices">
|
|
<h2>Buenas prácticas</h2>
|
|
<p class="section-lead">Reglas cortas para mantener el uso y el mantenimiento consistentes. Si la skill sigue siendo simple de operar, la tendencia es que permanezca confiable incluso cuando el workbook o el entorno cambien.</p>
|
|
|
|
<div class="panel">
|
|
<ul>
|
|
<li>Preferir <code>--intent</code> para preguntas recurrentes y <code>--query</code> para ad hoc; caer a <code>--sql</code> solo cuando sea necesario.</li>
|
|
<li>Usar aliases de campo locales y placeholders como <code>{{opportunityId}}</code> y <code>{{securityEntryPointFilter}}</code> en lugar de adivinar la expresión Oracle.</li>
|
|
<li>Tratar <code>DV - SE Team</code> como fuente del equipo actual y SR, no como lectura comercial org-wide genérica.</li>
|
|
<li>Cuando mezcle org-wide con enriquecimiento de recurso, preservar siempre la fila comercial original.</li>
|
|
<li>En PowerShell, usar <code>run-sales-intelligence-sql.mjs</code> para SQL larga o con quoting frágil.</li>
|
|
<li>Usar <code>--output-file</code> para persistir payloads finales; nombres temporales/intermedios van a <code>tmp/</code>.</li>
|
|
<li>La documentación oficial de la skill queda en <code>docs/docs.html</code>; los catálogos operativos siguen en <code>references/</code>.</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<p class="footer">
|
|
Documento consolidado de la skill <code>knowledge-one-view-cli</code>. Mantenido para lectura rápida, onboarding y referencia operativa sin duplicación innecesaria.
|
|
</p>
|
|
</main>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
(function () {
|
|
const STORAGE_KEY = 'knowledge-one-view-cli-docs-lang';
|
|
const pages = Array.from(document.querySelectorAll('[data-lang-page]'));
|
|
const buttons = Array.from(document.querySelectorAll('[data-lang-target]'));
|
|
const html = document.documentElement;
|
|
|
|
function setLanguage(lang) {
|
|
pages.forEach((page) => {
|
|
page.classList.toggle('active', page.getAttribute('data-lang-page') === lang);
|
|
});
|
|
buttons.forEach((button) => {
|
|
button.classList.toggle('active', button.getAttribute('data-lang-target') === lang);
|
|
button.setAttribute('aria-pressed', String(button.classList.contains('active')));
|
|
});
|
|
html.lang = lang === 'es' ? 'es-ES' : 'pt-BR';
|
|
try {
|
|
localStorage.setItem(STORAGE_KEY, lang);
|
|
} catch (error) {
|
|
}
|
|
window.scrollTo({ top: 0, behavior: 'auto' });
|
|
}
|
|
|
|
let initialLang = 'pt';
|
|
try {
|
|
const saved = localStorage.getItem(STORAGE_KEY);
|
|
if (saved === 'pt' || saved === 'es') {
|
|
initialLang = saved;
|
|
}
|
|
} catch (error) {
|
|
}
|
|
|
|
buttons.forEach((button) => {
|
|
button.addEventListener('click', () => {
|
|
setLanguage(button.getAttribute('data-lang-target'));
|
|
});
|
|
});
|
|
|
|
setLanguage(initialLang);
|
|
})();
|
|
</script>
|
|
</body>
|
|
</html>
|