JVA Finance O&G

Extensão de Governança, AFE e Analytics para JVA no SAP S/4HANA Public Cloud

---

Visão Geral

Esta aplicação é uma extensão side-by-side do SAP S/4HANA Public Cloud, desenvolvida na plataforma SAP BTP (Business Technology Platform), que adiciona uma camada de governança operacional, gestão de AFE, simulação, analytics especializado e ferramentas de IA ao módulo Joint Venture Accounting (JVA) nativo do S/4HANA.

O S/4HANA é o system of record do JVA — gerenciando joint ventures, parceiros, cutback, partner billing e cash calls. Esta extensão não substitui o JVA standard: ela complementa com o que o padrão não cobre para O&G.

O que o JVA Standard cobre (S/4HANA)

• Cadastro de joint ventures e equity groups
• Parceiros e working interest
• Cutback contábil e distribuição de custos
• Partner billing e cash calls
• Lançamentos contábeis e documentos financeiros

O que esta extensão adiciona (BTP)

• AFE Manager — workflow completo de Autorização de Gastos: CAPEX/OPEX/SUPPLEMENT, aprovação multi-nível (Engenharia → CFO → Parceiros), controle aprovado × comprometido × realizado
• Cost Allocation Engine — simulação e explicação de alocações por working interest antes da contabilização no S/4
• JV Billing Portal — revisão de statements, geração de PDF profissional, acompanhamento de pagamentos
• Equity Dashboard — cockpit analítico com alertas de desvio de participação e chart de barras
• Joule/MCP Tools — 6 ferramentas de IA especializadas em O&G para o SAP Joule
• Relatórios ANP — estrutura preparada para formato regulatório brasileiro

---

Arquitetura

┌──────────────────────────────────────────────┐
│         S/4HANA Public Cloud                 │
│   JVA Standard (system of record)            │
│   JVs · Parceiros · Cutback · Billing        │
└──────────────────┬───────────────────────────┘
                   │ APIs OData V4 (SAP Cloud SDK)
┌──────────────────▼───────────────────────────┐
│           SAP BTP — Cloud Foundry             │
│                                              │
│  CAP Service (Node.js) — extensão JVA        │
│  ├── AFE Manager + workflow multi-nível      │
│  ├── Cost Allocation simulation engine       │
│  ├── JV Billing portal + PDF                 │
│  ├── Equity Dashboard (ALP + chart)          │
│  └── MCP Server → SAP Joule                  │
│                                              │
│  HANA Cloud — dados da extensão BTP          │
│  (AFEs, approvals, alloc rules, equity pos.) │
└──────────────────────────────────────────────┘

JV Master: cache do S/4

JointVentures, JVPartners e JVAssets no HANA Cloud são cache read-only sincronizado do S/4 via syncJVMasterFromS4(). O S/4 é a única fonte de verdade — não é possível criar ou editar master data de JV diretamente nesta extensão.

---

Módulos

App	URL (dev)	Descrição
JV Master	/jvmaster/test/flpSandbox.html	Visão agregada dos JVs sincronizados do S/4
AFE Manager	/afemanager/test/flpSandbox.html	Workflow completo de Autorização de Gastos
Cost Allocation	/costallocation/test/flpSandbox.html	Simulação de alocação por Working Interest
JV Billing	/jvbilling/test/flpSandbox.html	Portal de Billing Statements + PDF
Equity Dashboard	/equitydashboard/test/flpSandbox.html	Cockpit analítico de equity e alertas

---

Stack Técnico

Camada	Tecnologia
Frontend	SAP Fiori Elements (OData V4, UI5 1.120.21)
Backend	SAP CAP Node.js v8
Banco (dev)	SQLite in-memory
Banco (prod)	SAP HANA Cloud
Auth	SAP XSUAA (dummy em dev)
Integração	SAP Cloud SDK v3 → S/4HANA OData V4
AI/MCP	@modelcontextprotocol/sdk + SAP Joule
Deploy	SAP BTP Cloud Foundry via MTA
Work Zone	SAP Build Work Zone Standard/Advanced

---

Como Executar Localmente

# Pré-requisitos: Node.js >= 20, @sap/cds-dk

git clone https://github.com/your-org/fiori-ext-finance.git
cd fiori-ext-finance
npm install

# Deploy do schema SQLite com seed data
npx cds deploy --to sqlite:db/jva-finance.db

# Inicia o servidor (todos os 5 apps)
npx cds watch

Acesse: http://localhost:4004

Usar sempre /test/flpSandbox.html para ter o shell do FLP com botão de voltar.

Testes

npm test    # 18 testes, DB in-memory isolado

---

Roles (produção com XSUAA)

Role	Permissões
JVA_ADMIN	Acesso total
JVA_VIEWER	Somente leitura
AFE_REQUESTOR	Criar e submeter AFEs
AFE_APPROVER	Aprovar/rejeitar AFEs
COST_CONTROLLER	Executar alocações

---

Deploy no SAP BTP

mbt build
cf deploy mta_archives/fiori-ext-finance_1.0.0.mtar

Após o deploy, registrar como Content Provider no Work Zone Admin para que os 5 tiles apareçam automaticamente via crossNavigation.inbounds.

---

Variáveis de Ambiente

Copie .env.example para .env:

S4_BASE_URL=https://<tenant>.s4hana.cloud.sap
S4_CLIENT_ID=<communication-arrangement-client-id>
S4_CLIENT_SECRET=<communication-arrangement-client-secret>
DMS_REPOSITORY_ID=jva-finance-repo
ANS_DESTINATION=ANS_SERVICE

---

Documentação

• Planejamento Técnico Completo
• Setup de Comunicação S/4 ↔ BTP
• APIs S/4HANA utilizadas
• Testes de API (REST Client)