# JVA Finance O&G

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

[![SAP BTP](https://img.shields.io/badge/SAP-BTP-blue)](https://www.sap.com/products/technology-platform.html)
[![SAP CAP](https://img.shields.io/badge/SAP-CAP_v8-green)](https://cap.cloud.sap)
[![SAP Fiori](https://img.shields.io/badge/SAP-Fiori_Elements-orange)](https://experience.sap.com/fiori-design-web/)
[![Node.js](https://img.shields.io/badge/Node.js-20+-brightgreen)](https://nodejs.org)
[![License](https://img.shields.io/badge/License-UNLICENSED-red)](LICENSE)

---

## 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

```bash
# 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

```bash
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

```bash
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`:

```bash
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](docs/PLANNING.md)
- [Setup de Comunicação S/4 ↔ BTP](communication-setup/README-comm-setup.md)
- [APIs S/4HANA utilizadas](communication-setup/comm-scenarios.md)
- [Testes de API (REST Client)](communication-setup/test-apis.http)