JVA Finance O&G

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

Related MCP server: SAP OData to MCP Server

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

Stack Técnico

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)

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)