JedIN EnergyHub — Documentação Completa do Produto — JedIN Wiki

O Que é o EnergyHub

O JedIN EnergyHub é um produto SaaS white-label para concessionárias de energia elétrica no Brasil. Ele oferece três interfaces: Portal do Cliente (autoatendimento), Backoffice (operadores) e Admin (configuração da plataforma). O primeiro cliente configurado é a Cemig (Companhia Energética de Minas Gerais).

O EnergyHub é um dos 3 produtos da plataforma JedIN:

JedIN Integration — iPaaS enterprise (Flow Designer, Monitoring, Marketplace)
R2-CX — Consultor autônomo com IA (SAP C4C, CPI, JedIN, e agora EnergyHub)
JedIN EnergyHub — SaaS para utilities (este produto)

Ele reutiliza a infraestrutura compartilhada: autenticação JWT, multi-tenancy com RLS, i18n (pt-BR, en-US, es), e o ecossistema de MCPs para integração com sistemas SAP.

Como Acessar

Faça login em https://d25tkox7rh14oo.cloudfront.net/pt-BR com suas credenciais
Na página de seleção de produtos, clique em JedIN Utilities (verde)
Você será redirecionado para /pt-BR/utilities — o hub do EnergyHub
Escolha o módulo: Portal do Cliente, Backoffice ou Admin

Acesso direto (sem seletor): https://d25tkox7rh14oo.cloudfront.net/pt-BR/utilities

Credenciais de teste: teste.sap@jedin.io / Test@123456

Troca de produto: No sidebar, clique em "Switch Product" (ícone ↔) para voltar ao seletor

R2-CX + EnergyHub

O EnergyHub está registrado como target no R2-CX com 20 tools MCP. Para acessar:

Selecione R2-CX na página de produtos
No Hub, encontre JedIN EnergyHub na categoria "Brazil Focus"
Clique para abrir o workspace
Interaja via chat: "List utility customers", "Show pending bills", etc.

Prompts sugeridos: Listar clientes, Faturas pendentes, Solicitações abertas, Interrupções ativas, Dashboard KPIs, Indicadores DEC/FEC

Arquitetura

                         +-----------------------+
                         |   Subdomain Router    |
                         | cemig.jedin.io        |
                         | copel.jedin.io        |
                         +-----------+-----------+
                                     |
                    +----------------+----------------+
                    |                |                 |
             +------+------+  +-----+------+  +------+------+
             |   Portal    |  |  Backoffice |  |    Admin    |
             |  (Cliente)  |  | (Operador)  |  |  (JedIN)   |
             | 13 páginas  |  |  7 páginas  |  |  4 páginas  |
             +------+------+  +-----+------+  +------+------+
                    |                |                 |
                    +----------------+----------------+
                                     |
                    +----------------+----------------+
                    |        NestJS API (3001)        |
                    |   /api/v1/utilities/*            |
                    |   33 arquivos, 11 controllers   |
                    |   15 services, 5 DTOs           |
                    +----------------+----------------+
                                     |
              +----------+-----------+-----------+----------+
              |          |           |           |          |
        +-----+----+ +--+---+ +-----+-----+ +--+---+ +----+-----+
        | Prisma   | | JWT  | | Payment   | | MCP  | | JedIN    |
        | 17 models| | Auth | | Gateway   | | C4C  | | Flows    |
        | (PG+RLS) | |      | | PIX/Bol.  | | 19t  | | 4 flows  |
        +----------+ +------+ +-----------+ +------+ +----------+
                                     |
              +----------+-----------+-----------+----------+
              |          |           |           |          |
        +-----+----+ +--+---+ +-----+-----+ +--+---+ +----+-----+
        | SAP      | | SAP  | | SAP Sales | | SAP  | | SAP BTP  |
        | S/4HANA  | | C4C  | | Cloud V2  | | Svc  | | Adapter  |
        | (OData)  | | (RPA)| | (REST)    | | V2   | | (XSUAA)  |
        +----------+ +------+ +-----------+ +------+ +----------+

Stack Tecnológica

Camada	Tecnologia	Detalhes
Frontend	Next.js 14 + React 18 + Tailwind	29 páginas TSX, App Router
Backend	NestJS 10 + Prisma 5	33 arquivos, JWT auth, multi-tenant
Banco	PostgreSQL 16 + RLS	17 modelos Utility, isolamento por tenant
Cache	Redis 7	Sessões, filas BullMQ
MCP	Express (port 3360)	20 tools para R2-CX
Integrações	JedIN Flows + MCP C4C	4 flows bidirecionais C4C ↔ EnergyHub
Deploy	AWS EKS + CloudFront	Kaniko builds, ECR registry

Modelos de Dados (17 Modelos Prisma)

Todos os modelos estão em apps/api/prisma/schema.prisma (linhas 2609-3231).

Modelos Principais

Modelo	Campos-chave	Propósito
UtilityTenantConfig	name, domain, branding (JSON), features (JSON), contacts, tariffs, regulatory	Configuração white-label por concessionária
UtilityCustomer	name, email, cpfCnpj, documentType (cpf/cnpj), customerType (6 tipos), passwordHash, externalSapId	Cliente final (PF ou PJ)
UtilityInstallation	installationNumber, meterNumber, tariffType, voltage, phase, contractedDemand, status	Ponto de conexão elétrica
UtilityBill	referenceMonth, consumptionKwh, peakConsumption, offPeakConsumption, totalAmount, dueDate, barcode, pixCode, status	Fatura mensal
UtilityPayment	method (pix/boleto/card), amount, status, gatewayRef, gatewayData	Registro de pagamento
UtilityConsumption	readingDate, readingValue, consumptionKwh, readingType (4 tipos), tariffFlag	Leitura de medidor
UtilityServiceRequest	protocol (UTL-YYYYMMDD-NNNNNN), type (13 tipos), subject, status, priority, slaDeadline, assignedTo	Solicitação de serviço
UtilityOutage	latitude, longitude, outageType, affectedCustomers, startTime, endTime, crewAssigned, cause, decContribution	Interrupção de energia
UtilityNotification	channel (email/sms/whatsapp/push), template, subject, body, sentAt, status	Notificação ao cliente

Modelos Especializados (Cemig)

Modelo	Propósito
UtilityEnergyCredit	Créditos de geração distribuída (validade 60 meses, compensação: self/remote/shared)
UtilityGenerationUnit	Usina solar/eólica (capacidade kW, inversor, painéis, registro ANEEL)
UtilityPublicLighting	Coordenação CIP (iluminação pública municipal)
UtilityRegulatoryIndicator	Indicadores DEC/FEC por município (metas ANEEL)
UtilityOmbudsmanCase	Ouvidoria (SLA 10 dias úteis, reclamação formal)
UtilityRuralCustomer	Cemig Agro (tamanho propriedade, CNAE, potência irrigação)
UtilityContentPage	CMS (páginas FAQ, banners, descrições de serviço)
UtilitySapSyncLog	Auditoria de sincronização SAP (registros processados, erros, duração)

Enums

Enum	Valores
UtilityDocType	cpf, cnpj
UtilityCustomerType	residential, commercial, industrial, rural, government, prosumer
UtilityPaymentStatus	pending, processing, paid, overdue, cancelled, refunded
UtilityPaymentMethod	pix, boleto, credit_card, debit_card, auto_debit
UtilityReadingType	automated, manual, self_reading, estimated
UtilityServiceType	second_bill, new_connection, reconnection, ownership_transfer, outage_report, complaint, indemnification, profile_update, auto_debit_setup, tariff_change, solar_registration, social_tariff, vital_customer
UtilityOutageStatus	active, investigating, crew_dispatched, repairing, resolved, scheduled

Mapeamento SAP

EnergyHub	SAP C4C	SAP S/4HANA	Sales Cloud V2	Service Cloud V2
UtilityCustomer	CorporateAccount / Contact	BusinessPartner (BP)	Account	—
UtilityServiceRequest	ServiceRequest	ServiceOrder (PM)	ServiceTicket	Case
UtilityBill	—	BillingDocument (FI-CA)	—	—
UtilityInstallation	—	Installation (ISU)	—	—
UtilityOutage	—	—	—	FieldServiceCase
Lead (mercado livre)	—	—	Lead / Opportunity	—

API Endpoints

Todos os endpoints estão sob /api/v1/utilities/. O módulo principal está em apps/api/src/modules/utilities/utilities.module.ts.

Autenticação e Perfil do Cliente

Método	Rota	Auth	Descrição
POST	`/customers/register`	Pública	Registrar cliente (name, email, cpfCnpj, password)
POST	`/customers/login`	Pública	Login com email + senha, retorna JWT (15min)
GET	`/customers/me`	JWT	Perfil do cliente com instalações
PUT	`/customers/me`	JWT	Atualizar perfil (email/CPF imutáveis)
GET	`/customers/me/installations`	JWT	Listar instalações do cliente

Segurança: Senha com bcrypt (10 rounds). CPF/CNPJ único por tenant. Email mascarado em logs (LGPD). JWT tipo utility-customer separado do JWT admin.

Faturamento e Pagamentos

Método	Rota	Auth	Descrição
GET	`/bills`	JWT	Listar faturas (filtros: installationId, status, referenceMonth)
GET	`/bills/:id`	JWT	Detalhes da fatura com histórico de pagamentos
GET	`/bills/:id/pdf`	JWT	Download PDF da fatura (TODO: geração real)
POST	`/bills/:id/payment`	JWT	Processar pagamento (PIX, boleto, cartão)

Gateway de Pagamento (billing/payment-gateway.service.ts):

PIX: Gera código EMV/BRCode, txId formato JEDIN{timestamp}{random}, expira em 60 min
Boleto: Barcode FEBRABAN 44 dígitos, gera nosso número
Cartão: Token-based (PCI-safe), retorna authorization code
Status: Todos os gateways são MOCK. Produção: BACEN SPI (PIX), APIs bancárias (boleto), Stripe/PagSeguro (cartão)

Consumo e Analytics

O serviço ConsumptionService (billing/consumption.service.ts) fornece:

getHistory(installationId, months) — Histórico de consumo com bandeiras tarifárias
getAnalytics(installationId) — Média, pico, mínimo, tendência, MoM%, estimativa de custo
compareMonths(installationId, month1, month2) — Comparação lado-a-lado
getTariffFlag(month) — Bandeira ANEEL: verde, amarela, vermelha1, vermelha2, escassez
Tendência: Regressão linear (limiar 5 kWh/mês para classificar como crescente/decrescente)

Solicitações de Serviço

Método	Rota	Auth	Descrição
POST	`/service-requests`	JWT	Criar solicitação (gera protocolo UTL-YYYYMMDD-NNNNNN)
GET	`/service-requests`	JWT	Listar com filtros (status, type, priority)
GET	`/service-requests/:id`	JWT	Detalhes com timeline
PUT	`/service-requests/:id/status`	Admin	Atualizar status (máquina de estados)

13 Tipos de Serviço com SLA:

Tipo	SLA (horas)	Descrição
second_bill	24h	Segunda via de conta
new_connection	120h (5 dias)	Ligação nova
reconnection	48h	Religação
ownership_transfer	72h	Troca de titularidade
outage_report	24h	Relato de falta de energia
complaint	120h	Reclamação
indemnification	720h (30 dias)	Indenização
profile_update	24h	Alteração cadastral
auto_debit_setup	48h	Débito automático
tariff_change	72h	Alteração de tarifa
solar_registration	—	Cadastro geração distribuída
social_tariff	—	Tarifa social
vital_customer	—	Cliente vital

Máquina de Estados:

open → {in_progress, cancelled}
in_progress → {waiting_customer, waiting_inspection, resolved, cancelled}
waiting_customer → {in_progress, cancelled}
waiting_inspection → {in_progress, resolved, cancelled}
resolved → (terminal)
cancelled → (terminal)

Interrupções (Outages)

Método	Rota	Auth	Descrição
POST	`/outages/report`	Pública	Reportar falta com GPS (lat/lng)
GET	`/outages`	Pública	Listar interrupções ativas
GET	`/outages/map`	Pública	Dados para renderizar mapa
PUT	`/outages/:id/resolve`	Admin	Resolver com causa e notas

Agrupamento automático: Relatos dentro de 500m (~0.005 graus) são agrupados na mesma interrupção, incrementando affectedCustomers.

Cálculo DEC: DEC = SUM(Ca_i * t_i) / Ct onde Ca_i = clientes afetados, t_i = duração em horas, Ct = total de consumidores.

Notificações

4 canais: email (AWS SES), SMS (Twilio), WhatsApp (Meta Cloud API), Push (Web Push). Todos são MOCK atualmente — logam no console com [AUDIT].

7 Templates: bill_due, payment_confirmed, request_updated, outage_alert, outage_resolved, welcome, password_reset.

Preferências: Opt-out model. Default: email/SMS/push habilitados, WhatsApp desabilitado.

Bot WhatsApp

8 intenções detectadas por keyword matching:

Intenção	Keywords	Ação
segunda_via	"segunda via", "2a via", "conta"	Envia boleto + PIX
debitos	"débito", "dívida", "pagar"	Lista faturas pendentes
falta_energia	"falta", "sem luz", "apagou"	Registra interrupção
religacao	"religar", "religação"	Cria solicitação
autoleitura	"leitura", "medidor"	Inicia autoleitura guiada
saudacao	"oi", "olá", "bom dia"	Saudação
ajuda	"ajuda", "help", "menu"	Menu de opções
desconhecido	(fallback)	Resposta padrão

Conformidade ANEEL

O serviço AneelComplianceService (regulatory/aneel-compliance.service.ts) calcula:

DEC (Duração Equivalente de Interrupção): horas de interrupção por consumidor
FEC (Frequência Equivalente de Interrupção): número de interrupções por consumidor
Metas default: DEC = 12.0h, FEC = 8.0 interrupções/ano (configuráveis por tenant)
Relatório ANEEL: Cabeçalho + indicadores + desdobramento municipal + tendência 12 meses + top 10 piores interrupções
Base regulatória: PRODIST Módulo 8, Resolução ANEEL 1.000/2021

Configuração de Tenant

Método	Rota	Auth	Descrição
GET	`/config`	Pública	Branding e configuração (carregado antes do login)
PUT	`/config`	Admin	Atualizar branding, features, contatos, tarifas, integrações

Telas do Portal do Cliente (13 páginas)

Todas em apps/web/app/[locale]/utilities/portal/.

Login (`/utilities/portal`)

Layout dividido: hero à esquerda (gradient, feature pills), formulário à direita. Campos: email/CPF + senha com toggle de visibilidade. Botões de login social (Google, Facebook, Apple). Links para registro e esqueci a senha.

Dashboard (`/utilities/portal/dashboard`)

Saudação com número da instalação e tipo de tarifa
4 cards de ação rápida: 2ª Via, Consumo, Serviços, Minha Conta
Card da fatura atual: valor (R$ 287,45), vencimento, consumo, status
Gráfico de barras CSS com consumo dos últimos 6 meses
Seção de solicitações recentes (status, tipo, data, protocolo)
3 dicas de economia de energia (horário fora de ponta, selo Procel, LED)

Faturas (`/utilities/portal/bills`)

Header com total pendente
Filtros: dropdown de status (todas/pagas/pendentes/vencidas), slider de período (3/6/12/24 meses)
Tabela desktop: protocolo, mês, consumo (kWh), valor, vencimento, status, botões download/pagar
Cards mobile com as mesmas informações
Modal de pagamento PIX: QR code placeholder, código de barras com botão copiar
Paginação
Dados mock: 7 faturas de set/2025 a mar/2026

Negociação de Dívidas (`/utilities/portal/bills/negotiation`)

Total da dívida em destaque (caixa vermelha)
Lista de faturas vencidas com dias de atraso
5 opções de parcelamento: 1x (sem juros), 2x, 3x (1% juros), 6x (1,5%), 12x (2%)
Cálculo de custo por plano com indicador de economia
Calendário de pagamentos (mostra datas/valores individuais)
Checkbox de termos e condições
Estado de sucesso: protocolo, calendário, boletos para download
Dados mock: 3 faturas vencidas totalizando R$ 771,60

Consumo (`/utilities/portal/consumption`)

Filtro de período: botões 6/12/24 meses
4 cards resumo: último mês, média mensal, custo médio, bandeira atual
Gráfico de barras empilhadas (24 meses): ponta (escuro) vs fora de ponta (claro)
Legenda de bandeiras tarifárias (verde/amarela/vermelha)
Tabela: mês, total, ponta, fora de ponta, bandeira, custo
Info box: explicação das bandeiras e regras ANEEL
Dados mock: 24 meses (último: 342 kWh, R$ 287,45)

Serviços (`/utilities/portal/services`)

Tabs de categoria: todos, faturamento, fornecimento, cadastro, atendimento
Grid de cards (10 serviços): ícone, título, descrição, tempo estimado, botão "Solicitar"
Banner de emergência (vermelho): telefone 116
Modal de solicitação: informações da instalação (read-only), descrição (textarea obrigatório), telefone de contato (obrigatório), botões de prioridade (Baixa, Normal, Urgente), tempo estimado
Estado de confirmação com número de protocolo

Autoleitura (`/utilities/portal/services/self-reading`)

Instruções colapsáveis: 4 passos com ícones (localizar medidor, ler números, tirar foto, enviar)
Formulário: informações da instalação (read-only), valor da leitura (kWh) com validação, date picker, upload de foto (câmera/arquivo ou drag & drop)
Tabela de histórico: data, valor (kWh), consumo, fonte (leiturista/autoleitura)
Estado de sucesso com resumo da leitura
Dados mock: 6 leituras anteriores, leitura atual = 45.872 kWh

Programas (`/utilities/portal/programs`)

4 cards de estatísticas: programas ativos, beneficiários, economia média %, aprovação %
Barra de busca + tabs de categoria (todos, tarifas, geração, social, eficiência)
Cards de programa (4): ícone, título, descrição, badge de categoria, beneficiários, tempo estimado
Botão "Ver Critérios" expande lista de elegibilidade
4 programas: Tarifa Social TSEE, Geração Distribuída Solar, Cliente Vital, Tarifa Branca

Geração Distribuída Solar (`/utilities/portal/programs/solar`)

4 abas:

Como Funciona: 6 passos numerados + 3 cards informativos (validade créditos 60 meses, economia estimada R$ 285/mês, 2 instalações)
Créditos e Consumo: Gráfico dual de barras (geração vs consumo, 12 meses), 3 cards de créditos (acumulados, gerados, consumidos), alerta de expiração, compensação por instalação com barra de progresso
Documentos: 5 documentos obrigatórios (ART/TRT, Diagrama Unifilar, Datasheet Módulos, Datasheet Inversor, Fotos), status de upload, barra de progresso 3/5
Status do Cadastro: Timeline de 6 passos (solicitação até ativação), indicador de status por passo (concluído, atual, pendente)

Simulador de Tarifas (`/utilities/portal/tariffs`)

Slider de consumo (50-1000 kWh) com botões preset
3 cards de comparação de tarifas: ícone, título, descrição, custo mensal estimado, indicador de economia, barra de custo visual, botão "Ver detalhes" com desdobramento de taxas
Gráfico horizontal de comparação de custos
Caixa de recomendação com tarifa sugerida e CTA
Dados mock: Consumo 350 kWh. Convencional: R$ 0,656/kWh, Branca: fora-ponta R$ 0,412 / ponta R$ 1,142, Social: R$ 0,230

Mapa de Interrupções (`/utilities/portal/outages`)

Botão "Reportar Falta de Energia"
4 cards de estatísticas: interrupções ativas, clientes afetados, tempo médio de resolução, resolvidas hoje
Layout mapa + sidebar: mapa placeholder com pins animados (pulsing) coloridos por status (vermelho/laranja/amarelo/verde), legenda de status
Sidebar: lista de interrupções com filtro de status, cada item mostra: badge de status, bairro, área, clientes afetados, hora de início
Painel de detalhes da interrupção selecionada
Banner de emergência: telefone 116
Modal de reporte: número da instalação, localização, descrição
Dados mock: 5 interrupções ativas em diferentes regiões, 780-3200 clientes afetados

Conta (`/utilities/portal/account`)

Seção de perfil: modo visualização/edição, dados pessoais (nome, CPF, email, telefone), endereço
Detalhes da instalação: número, medidor, tarifa, classe, fase, tensão, demanda contratada, status
Preferências de notificação: toggles para email, SMS, WhatsApp, push
Segurança: botão alterar senha (com data da última alteração), configuração 2FA (desabilitado)
Dados mock: Maria da Conceição Silva, instalação 3004567890, tarifa residencial B1

PWA Mobile (`/utilities/portal/mobile`)

Banner offline (laranja, quando sem internet)
Banner de instalação PWA com lista de features e botão instalar
4 cards de ação rápida: escanear código de barras, pagar PIX, reportar falta, ver consumo
Prompt de notificação push
Info box de suporte offline: o que funciona online vs offline
Barra de navegação inferior fixa: 4 tabs (início, faturas, interrupções, serviços)

Telas do Backoffice (7 páginas)

Todas em apps/web/app/[locale]/utilities/backoffice/. Layout com sidebar escuro (slate-900).

Dashboard (`/utilities/backoffice`)

4 cards KPI: total clientes (284.391), solicitações abertas (1.847), faturas vencidas (12.456), interrupções ativas (3)
4 boxes rápidos: solicitações hoje, tempo médio resolução, SLA compliance %, NPS
Tabela de solicitações recentes (10 linhas): protocolo, cliente, tipo, prioridade, status, operador, prazo SLA

Clientes (`/utilities/backoffice/customers`)

Busca: nome, CPF, email, número instalação
Botões de filtro e exportação
Tabela (10 clientes mock): nome+ID, CPF/CNPJ, email, telefone, tipo (badge), instalações, status (badge)
Painel de detalhes (sidebar direita): nome, CPF, status, contato, tipo, 4 botões rápidos (Nova Solicitação, Ver Faturas, Histórico Consumo, Editar Cadastro)
Tipos: residential, commercial, industrial, rural, public
Status: Ativo, Inadimplente, Suspenso, Desligado

Solicitações (`/utilities/backoffice/requests`)

Tabs de status com contadores: Todas (10), Aberta (3), Em Andamento (2), Aguardando (1), Resolvida (3), Cancelada (1)
Busca: protocolo, cliente, CPF
Filtros: tipo e prioridade (dropdowns)
Tabela: protocolo, cliente+CPF, tipo, prioridade, status, prazo SLA, operador
Painel de detalhes (wide): protocolo, tipo, status+prioridade (badges), grid de informações, descrição, dropdown de atribuição, botões de transição de status (Iniciar, Aguardar, Resolver, Cancelar), timeline de notas (autor, hora, texto), campo para adicionar nota

Faturamento (`/utilities/backoffice/billing`)

Gestão de faturas: geração, correção, reembolsos, parcelamentos.

Operações (`/utilities/backoffice/operations`)

Gestão de interrupções: mapa operacional, despacho de equipes, SLA, manutenção.

Equipes de Campo (`/utilities/backoffice/field-crew`)

Despacho e rastreamento de equipes: atribuição, localização, checklists, fotos.

Analytics (`/utilities/backoffice/analytics`)

Dashboard de analytics com 5 abas: visão geral, clientes, faturamento, operações, conformidade.

Relatórios (`/utilities/backoffice/reports`)

Categorias de relatórios: atendimento, faturamento, operações, conformidade ANEEL, executivo.

Telas do Admin (4 páginas)

Todas em apps/web/app/[locale]/utilities/admin/. Layout com sidebar escuro (gray-900, acento indigo).

Dashboard (`/utilities/admin`)

Seletor de período: Hoje, Semana, Mês
4 cards KPI: total tenants (12), total clientes (847.320), faturas processadas (2,1M), receita total (R$ 18,4M)
Tabela de tenants: nome, domínio, clientes, tier (badge), status (badge), receita mensal
Saúde do sistema: API, Database, Redis, MinIO — cada um com status, latência, uptime
Log de atividades recentes (8 itens)

Configuração de Tenants (`/utilities/admin/tenants`)

8 abas de configuração:

Branding: nome, logo URL, favicon, cor primária (#00A651), cor secundária (#003E87), cor do header, cor do footer, imagem hero, nome do app
Features: toggles on/off para cada funcionalidade (segunda via, mapa de interrupções, geração distribuída, marketplace, agro, tarifa social, cliente vital, WhatsApp, Telegram, autoleitura, iluminação pública, DEC/FEC, ouvidoria)
Contatos: telefone principal (116), fora do estado (0800), deficiente auditivo, ouvidoria, agro, geração distribuída, WhatsApp, Telegram, email
Tarifas: tipos disponíveis (convencional, verde, horossazonal, social, rural), moeda, fuso horário
Serviços: catálogo de serviços com toggle habilitado/desabilitado e SLA por serviço
Integrações: SAP S/4HANA (endpoint), gateway de pagamento (provedor, credenciais), SMS (provedor), WhatsApp (businessId), Google Maps (apiKey), Weather API
Regulatório: código ANEEL (CEMIG-D), área de atendimento (Minas Gerais), municípios (774), meta DEC (12,5h), meta FEC (6,2)
Usuários: gestão de usuários backoffice + roles

CMS (`/utilities/admin/cms`)

Gestão de conteúdo: páginas, banners, FAQs, descrições de serviço.

Configurações (`/utilities/admin/settings`)

Templates de email/SMS/WhatsApp, configuração de gateway de pagamento, integrações.

Integrações SAP (5 Serviços)

Todos em apps/api/src/modules/utilities/integration/.

1. SAP S/4HANA (`sap-s4-integration.service.ts`)

Sincronização via execução de JedIN Flows (Camel K):

Método	OData/RFC	Mapeamento
syncCustomerMaster	`/sap/opu/odata/sap/API_BUSINESS_PARTNER`	BP_NUMBER → bpNumber, TAX_NUMBER → cpfCnpj, NAME_FULL → name
syncMeterReadings	ISU Installation	ANLAGE → installationId, ZWSTAND → readingValue, ABLART → readingType
syncBillingDocuments	FI-CA	OPBEL → billNumber, BETRW → totalAmount, FAEDN → dueDate
pushPaymentConfirmation	FI-CA	billId → OPBEL, amount → BETRW, paymentDate
syncServiceOrders	PM	AUFNR → orderNumber, KTEXT → description, PRIOK → priority

Retry: Backoff exponencial (3 tentativas, 2s delay base). Logs de auditoria em UtilitySapSyncLog.

2. SAP Cloud for Customer — C4C (`sap-c4c-integration.service.ts`)

Integração via MCP C4C (browser RPA com Playwright):

Método	Descrição
syncCustomerToC4C(customer)	Upsert CorporateAccount (busca por ExternalID = CPF/CNPJ, PATCH se existe, POST se não)
syncServiceRequestToC4C(request)	Cria ServiceRequest linkado ao CorporateAccount
getCustomer360(cpfCnpj)	Visão agregada: account + tickets + atividades + oportunidades
listServiceRequests(cpfCnpj)	Histórico de service requests do cliente

Mapeamento de campos:

name → AccountName
cpfCnpj → ExternalID
customerType → ABCClassificationCode (industrial/prosumer=A, commercial/government=B, residential/rural=C)
protocol → ExternalReference
priority → PriorityCode (critical=1, high=2, normal=3, low=7)

3. SAP Sales Cloud V2 (`sap-sales-cloud-v2.service.ts`)

API REST moderna com OAuth2 Client Credentials:

Método	Entidade	Descrição
syncAccount(customer)	Account	Upsert conta por externalId
createLead(input)	Lead	Criar lead comercial (source, qualification, consumo estimado MWh)
syncOpportunity(input)	Opportunity	Pipeline de vendas (fase, receita esperada, probabilidade)
getAccountById(id)	Account	Detalhes da conta
listServiceTickets(accountId)	ServiceTicket	Tickets da conta

Indústrias: UTIL_RESIDENTIAL, UTIL_COMMERCIAL, UTIL_INDUSTRIAL, UTIL_RURAL, UTIL_GOVERNMENT, UTIL_PROSUMER

4. SAP Service Cloud V2 (`sap-service-cloud-v2.service.ts`)

Compartilha OAuth2 token com Sales Cloud V2:

Método	Entidade	Descrição
createCase(request)	Case	Criar caso de atendimento
updateCaseStatus(caseId, newStatus)	Case	Atualizar status
createFieldServiceCase(outageId)	Case	Despachar caso para equipe de campo
addInteraction(caseId, content)	Interaction	Adicionar nota/comentário
createAppointment(input)	Appointment	Agendar visita (5 tipos: METER_READING, INSPECTION, RECONNECTION, NEW_CONNECTION, FIELD_SERVICE)
getKnowledgeArticles(category)	KnowledgeArticle	Buscar FAQ/base de conhecimento

Categorias: SVC_OUTAGE, SVC_COMPLAINT, SVC_BILLING, SVC_TECHNICAL, SVC_CONNECTION, SVC_RECONNECTION, SVC_METER_READING, SVC_NEW_CONNECTION, SVC_OWNERSHIP, SVC_TARIFF, SVC_INDEMNIFICATION, SVC_SECOND_BILL

5. SAP BTP Adapter (`btp-adapter.service.ts`)

Camada de abstração para deploy em AWS (padrão) ou SAP BTP:

Método	Descrição
getEnvironmentInfo()	Retorna subaccount, landscape, org, space, serviços vinculados
getXsuaaToken()	OAuth2 contra XSUAA (BTP) ou fallback para env var (AWS)
resolveDestination(name)	Lookup no Destination Service (URL + auth tokens, cache 5min)
getHanaConnection()	Parâmetros de conexão HANA Cloud

Feature flag: DEPLOY_TARGET=btp ativa modo BTP. Default: AWS.

JedIN Integration Flows (4 Flows Bidirecionais)

Package: "EnergyHub - SAP C4C Integration" (ID: cfb7c157-01b9-4912-97c5-1909de144c9d)

Script de criação: create-c4c-energyhub-flows.mjs (raiz do projeto)

Flow 1: C4C Account → EnergyHub Customer

Timer(30min) → GET C4C /CorporateAccountCollection → Groovy Transform → Splitter → POST EH /customers/register → Log

OData Query: $top=50&$select=AccountName,AccountID,Phone,Email,City,State,Street,HouseNumber,District,ObjectID

Transformação Groovy (mapeamento de campos):

C4C (CorporateAccount)	EnergyHub (UtilityCustomer)
AccountName	name
AccountID	cpfCnpj, externalSapId
Email	email (auto-gerado se ausente)
Phone	phone
Street + HouseNumber + District	address
City (default: Belo Horizonte)	city
State (default: MG)	state
—	documentType = "cnpj"
—	customerType = "commercial"
—	sapSystem = "c4c", sapEntity = "CorporateAccount"

Flow 2: C4C ServiceRequest → EnergyHub Service Request

Timer(15min) → GET C4C /ServiceRequestCollection → Groovy Transform → Splitter → POST EH /service-requests → Log

Mapeamento de Prioridade: "1"→urgent, "2"→high, "3"/"7"→normal

Mapeamento de Status: "1"→open, "2"/"3"→in_progress, "4"→escalated, "5"→resolved, "6"→closed

Flow 3: EnergyHub → C4C Service Request (Reverso)

Webhook(/energyhub/service-request/new) → Groovy Transform → POST C4C /ServiceRequestCollection → Log

Mapeamento Reverso de Prioridade: urgent→"1", high→"2", normal→"3", low→"7"

Descrição C4C: Concatena subject + description + "--- Synced from JedIN EnergyHub ---" + protocol + type + customer name

Flow 4: C4C Contact → EnergyHub Customer (PF)

Timer(60min) → GET C4C /ContactCollection → Groovy Transform → Splitter → POST EH /customers/register → Log

Mapeamento: FirstName+LastName→name, Email→email, Phone/Mobile→phone, TaxID→cpfCnpj, documentType="cpf", customerType="residential"

IDs dos Flows (produção)

Flow	ID	Status
C4C Account → EH Customer	308a7204-6524-4867-9755-16f121c37a09	active
C4C Ticket → EH ServiceRequest	a5dc98a1-efb7-4d87-9a3e-56c57ecc468c	active
EH → C4C Reverse Sync	0df97d2b-6cf0-433c-8dcf-44754e530824	active
C4C Contact → EH Customer (PF)	fd500666-28c8-46b5-8d74-9a412fb4fe91	active

MCP EnergyHub (20 Tools para R2-CX)

Servidor MCP em packages/mcp-energyhub/. Express na porta 3360. Deploy no Kubernetes como mcp-energyhub (Deployment + Service ClusterIP).

Imagem Docker: 005250954903.dkr.ecr.sa-east-1.amazonaws.com/jedin-mcp-energyhub:v1775712669 Service URL (interno): http://mcp-energyhub.jedin.svc.cluster.local:3360

Arquitetura do Servidor

Sessões com TTL de 45 minutos (máximo 10 concorrentes)
Auto-login com credenciais teste.sap@jedin.io
Re-autenticação automática em 401
Health check: GET /health
Listagem de tools: GET /tools
Execução: POST /tools/:name

Inventário de Tools (20)

Customer (4)

Tool	Descrição	Endpoint API
`energyhub_list_customers`	Listar clientes com filtros (type, status, city)	GET /utilities/customers
`energyhub_get_customer`	Detalhes do cliente por ID	GET /utilities/customers/:id
`energyhub_search_customer`	Buscar por CPF/CNPJ, email, nome, instalação	GET /utilities/customers/search
`energyhub_create_customer`	Registrar novo cliente	POST /utilities/customers/register

Billing (4)

Tool	Descrição	Endpoint API
`energyhub_list_bills`	Listar faturas (filtros: installationId, status, period)	GET /utilities/bills
`energyhub_get_bill`	Detalhes da fatura (consumo, barcode, PIX, PDF)	GET /utilities/bills/:id
`energyhub_generate_bill`	Gerar fatura para instalação + mês	POST /utilities/bills
`energyhub_process_payment`	Processar pagamento (PIX, boleto, cartão)	POST /utilities/bills/:id/payment

Service Requests (4)

Tool	Descrição	Endpoint API
`energyhub_create_request`	Criar solicitação (13 tipos)	POST /utilities/service-requests
`energyhub_list_requests`	Listar com filtros (status, type, priority)	GET /utilities/service-requests
`energyhub_update_request`	Atualizar status + atribuir operador	PUT /utilities/service-requests/:id/status
`energyhub_get_request`	Detalhes: protocolo, timeline, documentos, SLA	GET /utilities/service-requests/:id

Outages (3)

Tool	Descrição	Endpoint API
`energyhub_report_outage`	Reportar falta com GPS (auto-agrupa 500m)	POST /utilities/outages/report
`energyhub_list_outages`	Listar ativas com status, clientes, equipe	GET /utilities/outages
`energyhub_resolve_outage`	Resolver com causa e notas, calcula DEC/FEC	PUT /utilities/outages/:id/resolve

Analytics (3)

Tool	Descrição	Endpoint API
`energyhub_get_consumption`	Histórico de consumo (kWh, ponta/fora-ponta, bandeira)	GET /utilities/consumption
`energyhub_get_dashboard`	KPIs do backoffice	GET /utilities/backoffice/dashboard
`energyhub_get_dec_fec`	Indicadores DEC/FEC ANEEL por município	GET /utilities/regulatory/dec-fec

Config (2)

Tool	Descrição	Endpoint API
`energyhub_get_config`	Branding, features, contatos, tarifas, integrações	GET /utilities/config
`energyhub_update_config`	Atualizar configuração do tenant	PUT /utilities/config

White-Label e Multi-Tenancy

Roteamento por Subdomínio

Middleware em apps/web/middleware.ts:

Subdomínio	Tenant
cemig.jedin.io	Cemig
copel.jedin.io	Copel
cpfl.jedin.io	CPFL
energisa.jedin.io	Energisa
equatorial.jedin.io	Equatorial
enel.jedin.io	Enel
neoenergia.jedin.io	Neoenergia
light.jedin.io	Light
celesc.jedin.io	Celesc
demo.jedin.io	Demo

Extração: cemig.jedin.io → header x-tenant-slug: cemig + cookie TENANT_SLUG.

Domínio custom: atende.cemig.com.br → CNAME → cemig.jedin.io → mesmo tenant.

Configuração Cemig (Padrão)

Nome:          Cemig (Companhia Energética de Minas Gerais)
Cor primária:  #00A651 (verde Cemig)
Cor secundária: #003E87 (azul Cemig)
Telefone:      116
WhatsApp:      +553135061160
Email:         atendimento@cemig.com.br
Código ANEEL:  CEMIG-D
Área:          Minas Gerais (774 municípios)
Meta DEC:      12,5 horas
Meta FEC:      6,2 interrupções

Perfis de Cliente (6 tipos)

Perfil	ID	Features
Residencial (PF)	CPF	Faturas, consumo, tarifa social, autoleitura, reclamações
Comercial (PJ)	CNPJ	Multi-instalação, NF-e, relatórios corporativos
Industrial	CNPJ	Demanda contratada, tarifa horossazonal, medição horária
Rural	CPF/CNPJ	Tarifa rural, irrigação, geração distribuída
Governo	CNPJ	Iluminação pública, multi-ponto, relatórios de gestão
Prosumer (GD)	CPF/CNPJ	Créditos de energia, monitoramento de geração, compensação

Perfis de Backoffice (RBAC)

Role	Nível	Permissões
Atendente	L1	Ver cliente, emitir 2ª via, abrir solicitação
Supervisor	L2	L1 + aprovações, relatórios SLA, métricas de equipe
Técnico de Campo	L1	Ordens de serviço, leituras, fotos, checklists
Analista Faturamento	L2	Gerar faturas, corrigir consumo, reembolsos, parcelamento
Analista Comercial	L2	Nova ligação, transferência, cancelamento
Gerente Operações	L3	Mapa de interrupções, despacho, SLA, manutenção
Compliance/ANEEL	L3	Indicadores DEC/FEC, relatórios ANEEL, auditorias
Admin	L4	Config, usuários, permissões, CMS, branding, integrações

Teste e Verificação

URLs de Acesso

Recurso	URL
Login JedIN	`https://d25tkox7rh14oo.cloudfront.net/pt-BR`
Seletor de Produtos	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/products`
Hub EnergyHub	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/utilities`
Portal do Cliente	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/utilities/portal`
Backoffice	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/utilities/backoffice`
Admin	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/utilities/admin`
R2-CX Hub	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/r2cx`
R2-CX EnergyHub Workspace	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/r2cx/energyhub/workspace`
Blog/Wiki	`https://d25tkox7rh14oo.cloudfront.net/pt-BR/blog` (seção "JedIN EnergyHub")
API Health	`http://localhost:3001/api/v1/health` (port-forward)
MCP EnergyHub	`http://localhost:3360/health` (port-forward)

Credenciais de teste: teste.sap@jedin.io / Test@123456

Fluxo de navegação:

Login → Seletor de Produtos → JedIN Utilities → Hub EnergyHub → Portal/Backoffice/Admin
                             → R2-CX           → Hub R2-CX    → EnergyHub Workspace (chat)
                             → JedIN Integration → Design/Monitor/Marketplace

Resultado de Testes de Rota (25/25 OK)

/en-US/utilities                           → 200
/pt-BR/utilities                           → 200
/en-US/utilities/portal                    → 200
/en-US/utilities/portal/dashboard          → 200
/en-US/utilities/portal/bills              → 200
/en-US/utilities/portal/services           → 200
/en-US/utilities/portal/consumption        → 200
/en-US/utilities/portal/outages            → 200
/en-US/utilities/portal/programs           → 200
/en-US/utilities/portal/programs/solar     → 200
/en-US/utilities/portal/tariffs            → 200
/en-US/utilities/portal/bills/negotiation  → 200
/en-US/utilities/portal/services/self-reading → 200
/en-US/utilities/backoffice                → 200
/en-US/utilities/backoffice/customers      → 200
/en-US/utilities/backoffice/requests       → 200
/en-US/utilities/backoffice/billing        → 200
/en-US/utilities/backoffice/operations     → 200
/en-US/utilities/backoffice/analytics      → 200
/en-US/utilities/backoffice/field-crew     → 200
/en-US/utilities/backoffice/reports        → 200
/en-US/utilities/admin                     → 200
/en-US/utilities/admin/tenants             → 200
/en-US/utilities/admin/cms                 → 200
/en-US/utilities/admin/settings            → 200

Como Testar Cada Módulo

Portal do Cliente:

Acesse /pt-BR/utilities/portal — deve aparecer tela de login com branding Cemig
Navegue pelas páginas: Dashboard, Faturas, Consumo, Serviços, Programas
Teste modal de pagamento PIX em Faturas
Teste simulador de tarifas com slider
Verifique mapa de interrupções com pins animados

Backoffice:

Acesse /pt-BR/utilities/backoffice — dashboard com 4 KPIs
Teste busca de clientes em /backoffice/customers
Teste painel de detalhes (click em um cliente)
Teste workflow de solicitações em /backoffice/requests

Admin:

Acesse /pt-BR/utilities/admin — dashboard com saúde do sistema
Explore 8 abas de configuração em /admin/tenants

API (via curl ou MCP):

# Login
curl -X POST http://localhost:3001/api/v1/utilities/customers/login \
  -H "Content-Type: application/json" \
  -d '{"email":"teste.sap@jedin.io","password":"Test@123456"}'

# Listar faturas
curl http://localhost:3001/api/v1/utilities/bills \
  -H "Authorization: Bearer {token}"

# Criar solicitação
curl -X POST http://localhost:3001/api/v1/utilities/service-requests \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"type":"second_bill","subject":"Segunda via janeiro","priority":"normal"}'

MCP EnergyHub (via R2-CX):

# Health check
curl http://localhost:3360/health

# Listar tools
curl http://localhost:3360/tools

# Executar tool
curl -X POST http://localhost:3360/tools/energyhub_get_dashboard \
  -H "Content-Type: application/json" \
  -H "x-session-id: test" \
  -d '{}'

Status de Implementação e Roadmap

O Que é Real vs Mock

Componente	Status	Detalhes
Customer APIs (CRUD, auth)	Real	bcrypt, JWT, validação
Faturas (listagem, detalhes)	Real	Paginação, filtros
Geração de PDF	Mock	Retorna dados para geração client-side
Pagamento PIX	Mock	Gera código EMV fake
Pagamento Boleto	Mock	Gera barcode FEBRABAN fake
Pagamento Cartão	Mock	Token-based fake
Solicitações de Serviço	Real	Protocolo, SLA, máquina de estados
Interrupções	Real	GPS, agrupamento 500m, DEC calc
Notificações	Mock	Todos 4 canais logam no console
WhatsApp Bot	Parcial	Detecção de intenção funciona, integração com serviços TODO
SAP S/4HANA	Framework	Estrutura pronta, execução via JedIN flows
SAP C4C	Real	Via MCP browser RPA (19 tools testadas)
SAP Sales Cloud V2	Framework	REST + OAuth2 estruturado, credenciais pendentes
SAP Service Cloud V2	Framework	REST + OAuth2 estruturado, credenciais pendentes
BTP Adapter	Framework	XSUAA + Destinations implementados
DEC/FEC (ANEEL)	Real	Cálculo + relatório + metas
JedIN Integration Flows	Real	4 flows criados e publicados (active)
MCP EnergyHub	Real	20 tools operacionais, deployed no K8s (port 3360)
Frontend (29 páginas)	Real	Todas renderizando com dados mock

Gaps Críticos para Produção

Gateways de pagamento reais — substituir mocks por BACEN SPI (PIX), APIs bancárias (boleto), Stripe/PagSeguro (cartão)
Canais de notificação reais — AWS SES (email), Twilio (SMS), Meta Cloud API (WhatsApp), Web Push
PDF de fatura — geração server-side com layout ANEEL
Login social — OAuth2 Google, Facebook, Apple (campos no schema, implementação pendente)
Jobs agendados — cron para geração de faturas, sincronização SAP, envio de notificações
Testes automatizados — zero testes escritos
LGPD — endpoints de exclusão/exportação de dados pessoais
Rate limiting — proteção em endpoints públicos

Fases do Roadmap

Fase	Escopo	Status
1 - Fundação	Modelos, auth, portal básico, backoffice básico	~70% concluído
2 - Serviços Core	Pagamentos reais, consumo, serviços (5 tipos), mapa, notificações	~30% concluído
3 - Portal Completo	11 tipos de serviço, parcelamento, programas, tarifa, WhatsApp, push	~20% concluído
4 - Enterprise + SAP BTP	S/4HANA real, BTP deploy, analytics avançado, mobile app, equipe campo	~10% concluído

Arquivos-Chave para Continuar o Desenvolvimento

Área	Caminho	Descrição
Módulo NestJS	`apps/api/src/modules/utilities/utilities.module.ts`	Entry point do backend
Customer	`apps/api/src/modules/utilities/customer/`	Auth + CRUD
Billing	`apps/api/src/modules/utilities/billing/`	Faturas, pagamentos, consumo
Service Requests	`apps/api/src/modules/utilities/service-request/`	13 tipos, SLA, workflow
Outages	`apps/api/src/modules/utilities/outage/`	GPS, agrupamento, DEC
Notifications	`apps/api/src/modules/utilities/notification/`	4 canais (substituir mocks)
WhatsApp	`apps/api/src/modules/utilities/whatsapp/`	Bot com 8 intenções
Regulatory	`apps/api/src/modules/utilities/regulatory/`	DEC/FEC ANEEL
SAP Integrations	`apps/api/src/modules/utilities/integration/`	5 serviços SAP
DTOs	`apps/api/src/modules/utilities/dto/`	5 DTOs com class-validator
Prisma Models	`apps/api/prisma/schema.prisma` (linhas 2609-3231)	17 modelos Utility
Web Pages	`apps/web/app/[locale]/utilities/`	29 páginas TSX
MCP Server	`packages/mcp-energyhub/src/`	server.js + tools.js
Flow Script	`create-c4c-energyhub-flows.mjs`	4 flows de integração
Product Store	`apps/web/stores/product.store.ts`	Registro do produto utilities (defaultRoute: /utilities)
Product Selector	`apps/web/app/[locale]/(dashboard)/products/page.tsx`	Página de seleção de produtos (3 cards)
R2-CX Target Store	`apps/web/stores/target-system.store.ts`	EnergyHub registrado (port 3360, 20 tools)
R2-CX Target Registry	`apps/web/lib/r2cx/target-registry.ts`	Prompts sugeridos, nav items, tool prefix
R2-CX Hub	`apps/web/app/[locale]/(dashboard)/r2cx/page.tsx`	EnergyHub na categoria "Brazil Focus"
R2-CX Chat Service	`apps/api/src/modules/r2cx-session/r2cx-chat.service.ts`	MCP_PORT_MAP: energyhub: 3360
Middleware	`apps/web/middleware.ts`	Detecção de subdomínio