Primeiro Commit v0.beta1

2026-04-29 00:27:50 -03:00
parent 93d4906fb5
commit 8662a153fe
27 changed files with 16303 additions and 0 deletions
--- a/references/api-map.md
+++ b/references/api-map.md
@@ -0,0 +1,514 @@
+# Knowledge-One-View-CLI API Map
+
+Read this file when Oracle DV behavior changes, a workbook tab must be retraced, or you need traced endpoint and default-filter details that are too low-level for the main skill guide.
+
+## Quick Navigation
+
+- Workbook identity: [Traced Workbook](#traced-workbook)
+- Required auth/session state: [Required Session Inputs](#required-session-inputs)
+- Direct and fallback endpoints: [Traced Endpoints](#traced-endpoints)
+- Local metadata and field shortcuts: [Fast Local Metadata](#fast-local-metadata)
+- Common query patterns: [Fast Query Patterns](#fast-query-patterns)
+- Traced workbook-tab defaults: [Traced Tab Defaults](#traced-tab-defaults)
+
+## Traced Workbook
+
+- Workbook URL:
+  `https://salesintelligence-dv.oracle.com/ui/dv/ui/project.jsp?pageid=visualAnalyzer&reportmode=presentation&reportpath=%2F%40Catalog%2Fshared%2FTeam%20Sharing%20Area%2FLAD%2FLAD%20Sales%20Operations%2FLAD%20Production%2FLAD%20Knowledge%20One%20View`
+- Platform:
+  Oracle Analytics / Oracle DV
+- Primary commercial subject area:
+  `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')`
+
+Keep the `ANNA.DE.MAURO@ORACLE.COM` token exactly as traced in XSA dataset references. It is part of the logical dataset identifier, not a disposable example.
+
+## Required Session Inputs
+
+The direct API calls worked with:
+
+- Cookies from Playwright `storageState`
+- `authorization: session`
+- `x-csrf-token`
+- `x-bitech-clientbin`
+- `x-requested-with: XMLHttpRequest`
+- Workbook `referer`
+
+`x-bitech-clientbin` also appears in the workbook bootstrap HTML inside static asset paths such as:
+
+`/static/dv/oracle-jet-bundles/18.1.2.fd48e9d8895d/...`
+
+The refresh helper writes both the cookies and these request headers to disk:
+
+- `auth-state.json`
+- `session-meta.json`
+
+The fetch script also persists refreshed cookies plus updated CSRF/clientbin metadata back to those files after a session restore so later runs reuse the corrected backend state.
+When the saved files are missing or Oracle redirects a normal fetch call back to sign-in, the fetch script can now invoke the browser refresh helper automatically, then reload the session artifacts and retry the backend request.
+That makes the runtime/session path parameters operationally important, not just convenience flags.
+
+## Traced Endpoints
+
+### Preferred Direct Endpoint
+
+- `POST /ui/dv/ui/api/v1/sqlquery/execute`
+  Use for custom Oracle logical SQL and for the reusable `opportunity-details` and `sr-details` views in this skill.
+  Body shape:
+
+```json
+{
+  "aQueryInfos": [
+    {
+      "sQuery": "SELECT valueof(RV_CURR_FISCAL_YEAR) FROM \"DV - SE Team\"",
+      "nResultsLimit": 1
+    }
+  ],
+  "bUseCache": true
+}
+```
+
+  Response shape:
+
+```json
+{
+  "aQueriesResults": [
+    {
+      "eStatus": "FINISHED",
+      "aColumnTypes": ["varchar"],
+      "aResults": [["FY26"]]
+    }
+  ]
+}
+```
+
+### Metadata / Bootstrap Endpoints
+
+- `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
+  Traced from `Data Quality`. Useful when Oracle changes dataset metadata or a new workbook view must be reconstructed.
+- `POST /ui/dv/ui/api/v1/infer/activities`
+  Telemetry only. Ignore for data retrieval.
+- `GET /ui/dv/ui/api/v3/items-content`
+  Static workbook assets such as images. Ignore for data retrieval.
+
+### Workbook Rendering Endpoints
+
+- `POST /ui/dv/ui/api/v2/data/executeOrPoll`
+- `POST /ui/dv/ui/api/v2/data/poll`
+
+These drive the rendered workbook tabs. They are useful as fallback references because the POST payloads contain the exact traced columns and default filters, but they are noisier than `sqlquery/execute`.
+
+## Fast Local Metadata
+
+The skill now keeps a local field catalog inside `scripts/fetch-sales-intelligence.mjs` for the most common logical fields, so repeated asks do not need rediscovery. Use:
+
+- `--catalog`
+- `--list-intents`
+- `--describe-intent srs-by-resource`
+- `--list-fields`
+- `--list-fields --entity Opportunity`
+- `--list-fields --role filter`
+- `--describe-field closeDate`
+
+Use the intent shortcuts first for the recurring asks that previously caused parameter guesswork:
+
+- `opportunities-close-date`
+  Uses `--date`
+- `opportunities-close-month`
+  Uses `--month`
+- `srs-by-resource`
+  Uses `--resource`
+
+For ad hoc SQL, prefer template placeholders over raw Oracle expressions:
+
+- `{{opportunityId}}`
+- `{{closeDate}}`
+- `{{bookingValue}}`
+- `{{workloadAmount}}`
+- `{{subjectArea}}`
+- `{{securityEntryPointFilter}}`
+
+Render those placeholders locally without a backend call:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --render-sql `
+  --sql "SELECT {{opportunityId}}, {{closeDate}} FROM {{subjectArea}} WHERE {{securityEntryPointFilter}}"
+```
+
+For most ad hoc retrieval, prefer declarative query mode over raw SQL:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --query `
+  --select opportunityId,opportunityName,closeDate,bookingValue,workloadAmount `
+  --where "closeDate = DATE '2026-05-02'"
+```
+
+Query mode infers the safest source from the selected aliases. Commercial opportunity, revenue-line, hours, and presales-coverage aliases use org-wide-capable XSA sources in `--scope auto`; SR and session aliases remain on `DV - SE Team`, which is my-team-only.
+
+Important known fields:
+
+- `closeDate`
+  `"Opportunity"."Close Date"`
+  Use direct date literals: `DATE '2026-03-27'`
+- `opportunityId`
+  `"Opportunity"."Opportunity ID"`
+- `opportunityName`
+  `"Opportunity"."Opportunity Name"`
+- `opportunityStatus`
+  `"Opportunity"."Status"`
+- `customerName`
+  `"Customer"."Customer Name"`
+- `salesStage`
+  `"Opportunity"."Sales Stage"`
+- `opportunityValue`
+  `"Opportunity"."Opportunity Value"`
+- `bookingValue`
+  `"Opportunity"."Opportunity Value"`
+  Preferred alias when the intent is to compare booking against `workloadAmount`.
+- `workloadAmount`
+  `"Opportunity"."Workload Amount"`
+- `optyCloseFiscalYear`
+  `"Time (Close Date Opportunity)"."Opty Close Fiscal Year"`
+- `srNumber`
+  `"Service Request"."SR Number"`
+- `srStatus`
+  `"Service Request"."Status"`
+- `srTeamLevel1EmailAddress`
+  `"SR Team"."SE Team Level 1 Email Address"`
+- `srTeamLevel2EmailAddress`
+  `"SR Team"."SE Team Level 2 Email Address"`
+- `srTeamLevel3EmailAddress`
+  `"SR Team"."SE Team Level 3 Email Address"`
+- `srTeamLevel4EmailAddress`
+  `"SR Team"."SE Team Level 4 Email Address"`
+- `leadEmail`
+  `"Service Request"."Lead Email"`
+  Use only when the intent is explicitly to query the SR leader.
+
+## Fast Query Patterns
+
+### Ad Hoc SQL Without Oracle Expression Guesswork
+
+Use the local placeholder expansion:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --sql "SELECT {{opportunityId}}, {{opportunityName}}, {{closeDate}}, {{bookingValue}}, {{workloadAmount}} FROM {{subjectArea}} WHERE {{securityEntryPointFilter}} AND {{closeDate}} = DATE '2026-05-02'"
+```
+
+The script expands that locally to Oracle logical SQL before execution.
+When the `SELECT` list is simple enough, the script also infers output column names and returns object-shaped `records` instead of only raw row arrays. Explicit `AS` aliases are respected.
+
+### Declarative Query Mode
+
+Use query mode when the ask is naturally "fields + filter + grouping + ordering":
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --query `
+  --select opportunityId `
+  --measure sum:bookingValue:totalBooking,sum:workloadAmount:totalWorkload `
+  --where "closeDate = DATE '2026-05-02'" `
+  --group-by opportunityId `
+  --order-by totalBooking:desc
+```
+
+Query mode reduces guesswork by:
+
+- inferring the configured source automatically from the selected aliases
+- using org-wide XSA sources first for commercial aliases in `--scope auto`
+- injecting the standard team-security filter only when the selected source requires it or when `--scope my-team` is explicitly requested on an org-wide-capable source
+- accepting field aliases directly inside `--select` and `--where`
+- supporting aggregate specs like `sum:bookingValue:totalBooking`
+- returning object-shaped records with stable output columns
+
+### Backend Scope Reality
+
+Use this when deciding whether a request can be answered org-wide or must be disclosed as current-team only:
+
+- `Knowledge DV - Opportunities - V2`, `Knowledge DV - Hours - V2`, `Knowledge DV - Presales Involvement Aux - V1`, and `Knowledge DV - Revn Lines by SE` are treated as org-wide-capable XSA datasets by the skill. In `--scope auto`, the script avoids the current-team security predicate unless the chosen view or intent explicitly needs it.
+- `--scope my-team` on an org-wide-capable source intentionally adds the current-team predicate so the same dataset can be used for a narrower current-team read.
+- `DV - SE Team` is effectively my-team-only for this skill. Use it for SRs, session context, and fields that have no org-wide source. Do not use it as a generic org-wide commercial fallback.
+- For mixed outputs, prefer `scope.components` and `scope.disclosureLines` over a single label because one component may be org-wide while another remains my-team-only.
+
+### Opportunities By Close-Date Window
+
+Use the built-in intent or built-in view instead of rewriting SQL:
+
+Exact date:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --intent opportunities-close-date `
+  --date 2026-05-02
+```
+
+Calendar month:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --intent opportunities-close-month `
+  --month 2026-04
+```
+
+Explicit window:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --view opportunities-close-window `
+  --from-date today `
+  --to-date +7d
+```
+
+Primary logical SQL pattern:
+
+```sql
+SELECT
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity ID",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Name",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Customer Name (Original)",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Status",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Sales Stage",
+  MAX(XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Pipeline") AS bookingValue,
+  MAX(XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Pipeline") AS workloadAmount
+FROM XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')
+WHERE XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date" >= DATE '2026-03-27'
+  AND XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date" <= DATE '2026-04-03'
+GROUP BY
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity ID",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Name",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Customer Name (Original)",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Status",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date",
+  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Sales Stage"
+ORDER BY 5, 1
+```
+
+Fallback behavior:
+
+- if the ask is explicitly about the current user's team and the primary XSA query fails, the skill may rerun the commercial read against `DV - SE Team`
+- generic org-wide commercial reads stay on `Knowledge DV - Opportunities - V2` and do not fall back to `DV - SE Team`
+
+In the built-in `opportunities-close-window` view, the last two fields are returned from the org-wide XSA `Pipeline` column:
+
+- `bookingValue` -> `Knowledge DV - Opportunities - V2` / `"Columns"."Pipeline"`
+- `workloadAmount` -> `Knowledge DV - Opportunities - V2` / `"Columns"."Pipeline"`
+
+The `bookingValue` and `workloadAmount` names are preserved for user-facing compatibility with opportunity and workload reports. For org-wide query-mode reads from `Knowledge DV - Opportunities - V2`, prefer the same `Pipeline` backing field because direct row-level reads of `"Opportunity Value"` and `"Workload Amount"` can fail in Oracle DV.
+
+### SRs By Resource Email
+
+Use the built-in intent or built-in view instead of writing custom SQL:
+
+Shortest path:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --intent srs-by-resource `
+  --resource resource.member
+```
+
+Equivalent direct view call:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --view srs-by-resource-email `
+  --resource resource.member
+```
+
+Default matching rule:
+
+```sql
+(
+  "SR Team"."SE Team Level 1 Email Address" = 'resource.member@oracle.com'
+  OR "SR Team"."SE Team Level 2 Email Address" = 'resource.member@oracle.com'
+  OR "SR Team"."SE Team Level 3 Email Address" = 'resource.member@oracle.com'
+  OR "SR Team"."SE Team Level 4 Email Address" = 'resource.member@oracle.com'
+)
+```
+
+Only use lead matching when the ask is explicitly about the leader:
+
+```powershell
+node .\scripts\fetch-sales-intelligence.mjs `
+  --view srs-by-resource-email `
+  --resource-email resource.member@oracle.com `
+  --match-role lead
+```
+
+The built-in `srs-by-resource-email` view also returns:
+
+- `bookingValue` -> `"Opportunity"."Opportunity Value"`
+- `workloadAmount` -> `"Opportunity"."Workload Amount"`
+
+The CLI now normalizes Oracle date strings in built-in output, so values such as `02-MAY-26` are returned as `2026-05-02`.
+
+## Traced Tab Defaults
+
+### Opportunity Details
+
+- Current canvas:
+  `canvas!4`
+- Plugin:
+  `oracle.bi.tech.table`
+- Default filters:
+  - `Security.Entry Point in VALUEOF(NQ_SESSION."SEC_ARIA_SI-SR-TEAM")`
+  - `Opty Close Fiscal Year = current FY`
+  - `Opportunity Status in (Open, Won, Won Pending)`
+  - `SE Team Active Flag = Y`
+  - `SE Team Manager Flag = N`
+  - `SR Source = Opportunity`
+- Important columns:
+  - `Opportunity ID`
+  - `# Opportunity Hours`
+  - `Status`
+  - `Workload Amount`
+  - `Registry ID`
+  - `Customer Name`
+  - `Deal Qualification`
+  - `Forecast Type Group`
+  - `Opportunity Value`
+  - `Current FY Opp Hours`
+  - `Total Opportunity Hours`
+  - `Opty Close Fiscal Quarter`
+  - `# SEs With Effort`
+  - `# Service Requests with Effort`
+  - `Country`
+  - `Sales Stage`
+  - `Revenue Type Group`
+  - `LOB Type`
+  - `All Products`
+  - `Opportunity Name`
+  - `All Workloads`
+  - `Covered Flag`
+  - `All Implementers`
+  - `Win Probability`
+
+### SR Details
+
+- Current canvas:
+  `canvas!5`
+- Plugin:
+  `oracle.bi.tech.table`
+- Default filters:
+  - `Security.Entry Point in VALUEOF(NQ_SESSION."SEC_ARIA_SI-SR-TEAM")`
+  - `Opty Close Fiscal Year = current FY`
+  - `Opportunity Status = Open`
+  - `SE Team Active Flag = Y`
+  - `SE Team Manager Flag = N`
+- Important columns:
+  - `SR Number`
+  - `Parent SR Number`
+  - `Service Request Status`
+  - `Title`
+  - `Queue Name`
+  - `Country`
+  - `Registry ID`
+  - `Customer Name`
+  - `SR Source`
+  - `Opportunity ID`
+  - `Opportunity Name`
+  - `Opportunity Status`
+  - `Win Probability`
+  - `Primary Pillar`
+  - `Opportunity Value`
+  - `Workload Amount`
+  - `Total SR Hours`
+  - `Lead Email`
+  - `SR Requester Email Address`
+  - `Create SR Day`
+  - `Close SR Day`
+  - `Customer Deadline`
+  - `Internal Deadline`
+  - `Last Effort`
+  - `# Service Requests with Effort`
+  - `# SEs With Effort`
+  - `# Hours (Excl. Time Off)`
+  - `Service Description`
+
+Current limitation:
+
+- `Parent SR Number` is visible in traced workbook metadata, but the direct logical SQL path used by the CLI still fails when selecting it explicitly.
+- Because of that, current internal-SR reconciliation in the skill uses a safe fallback: confirmed joins stay based on `Opportunity ID`, and additional internal-SR candidates are inferred only when the same resource has SRs for the same customer without a usable `Opportunity ID`.
+
+### Data Quality
+
+The `Data Quality` tab used:
+
+- `POST /ui/dv/ui/api/v1/sqlquery/execute`
+- `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
+
+That trace confirms the workbook can be queried directly through Oracle logical SQL without rendering the visualization.
+
+### Commercial Opportunity Datasets
+
+- Current canvas:
+  `canvas!15`
+- Traced endpoints:
+  - `POST /ui/dv/ui/api/v2/data/executeOrPoll`
+  - `POST /ui/dv/ui/api/v2/modelmetadata/subjectareas`
+  - `POST /ui/dv/ui/api/v2/metadata/interactionpaths`
+  - `POST /ui/dv/ui/api/v1/dataset/datasets/metadata`
+  - `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
+- Traced workbook sources:
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')`
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Hours - V2')`
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Presales Involvement Aux - V1')`
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Revn Lines by SE')`
+- Observed metadata lookup:
+  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'One View Tech - Usage Information')`
+
+The first traced SA Attach visuals used `Knowledge DV - Opportunities - V2` as the active subject area and exposed these traced defaults:
+
+- Recommended default for generic opportunity retrieval:
+  `--intent opportunities-default`
+- `Cluster = Brazil`
+- `Solution in ('Cloud Infrastructure - Workloads', 'Hardware - Bookings', 'On-Premise Technology - Bookings')`
+- `Sales Credit Type = QUOTA`
+- `Executive Product LOB in ('Cloud Infrastructure', 'Hardware', 'License')`
+- `Revenue Type Group in ('NEW', 'EXPANSION', 'WORKLOAD')`
+- Current skill default: `Opportunity Probability >= 0`
+- Older workbook traces sometimes showed `Opportunity Probability >= 40`
+- `Revenue Line Status = Open` for the open-pipeline visuals
+- `Revenue Line Status in ('Won', 'Won Pending')` for the won-pipeline visual
+- Open rows are allowed in any close year, while won rows are constrained to previous/current fiscal year
+- Compatibility note:
+  older traces may still mention `License and Hardware` or `WORKLOADS`; the skill now normalizes those aliases to the backend values `License` + `Hardware` and `WORKLOAD`.
+
+Traced view mappings:
+
+- `view!1597`
+  `oracle.bi.tech.ngperformancetile`
+  Open pipeline tile based on `SUM(Pipeline)` from `Knowledge DV - Opportunities - V2`
+- `view!1612`
+  `oracle.bi.tech.ngperformancetile`
+  Won pipeline tile based on `SUM(Pipeline)` from `Knowledge DV - Opportunities - V2`
+- `view!1602`
+  `oracle.bi.tech.chart.stackbar100`
+  Involvement distribution chart based on `Pipeline`, `Revenue Line Probability`, `Presales Involvement Flag`, and `Opportunity Hours Attribute`
+
+The traced involvement bucket logic is:
+
+```sql
+CASE
+  WHEN SUM(
+    CASE WHEN <current-team filter on Presales Involvement Aux - V1>
+      THEN "Opportunity Hours Attribute"
+    END BY "Opportunity ID"
+  ) > 0
+    THEN '1. My Team Involvement'
+  WHEN "Presales Involvement Flag" = 'Y'
+    THEN '2. Other Presales Involvement'
+  ELSE '3. No Presales Involvement'
+END
+```
+
+Current skill coverage now maps that tab through these direct views:
+
+- `sa-attach-pipeline-details`
+- `sa-attach-open-pipeline`
+- `sa-attach-won-pipeline`
+- `sa-attach-involvement-distribution`
+- `sa-attach-hours-by-opportunity`
+- `sa-attach-presales-coverage`