Visão Geral da Solução

Objetivo: Prova de Conceito para módulo de atendimento CRM especializado em "Suporte e Problemas de segmento telecom", com IA integrada (Azure OpenAI, ElevenLabs + LiveKit) e observabilidade completa (Langfuse, Elastic Cloud).

Cenários de Caso de Uso

#CenárioDescriçãoDASDATIData MapC2Fluxo
1PagamentoEnvio de fatura por emailDASDATIDM
2ContestaçãoAjuste de fatura com backoffice (SAGA)DASDATIDM
3NegociaçãoRenegociação de dívida via Legacy Debt CollectionDASDATIDM
42ª ViaGeração e envio de 2ª via (boleto + PIX)DASDATIDM

Stack Tecnológica

Frontend
React (CRM+)
BFF / Microsserviços
SpringBoot 3.x, Java 21
URA / Voz
ElevenLabs + LiveKit
IA
Azure OpenAI (GPT-4)
Observabilidade LLM
Langfuse
API Gateway
API Gateway
Mensageria
Azure Event Hub (Kafka)
Cache
Azure Cache for Redis
Observabilidade
Elastic Cloud (ELK + APM)
Segurança
OAuth2/OIDC, mTLS, Key Vault
Billing
Legacy Billing System (via MS Informação do Cliente)
Cobrança
Legacy Debt Collection

Guidelines e Documentação Técnica

Arquitetura de Referência

Princípios, stack tecnológica, sistemas legados, padrões de integração.

Guideline

Domínios ODA

Core, Supporting e Generic domains (TMForum ODA).

Guideline

Padrões Arquiteturais

Microsserviços, hexagonal, SAGA, CQRS, event-driven, resiliência.

Guideline

Observabilidade

Elastic Cloud, OpenTelemetry, Langfuse, métricas RED/USE, alertas.

Guideline

Segurança

OAuth2/OIDC, mTLS, RBAC, STRIDE, LGPD, classificação de dados.

Guideline

Agentes IA + URA

Guardrails, evaluators, performance, persona Vivi, feedback loop, rollout.

Guideline

DAS — Observabilidade

Elastic Cloud, Langfuse self-hosted, SLIs/SLOs, alertas, dashboards, distributed tracing.

DAS

Architecture Decision Records (ADRs)

Decisões arquiteturais formalizadas seguindo o template corporativo. Cada ADR documenta contexto, decisão, consequências, alternativas avaliadas e rationale.
ADRDecisãoEscopoStatus
ADR-0001BFF Pattern para orquestraçãoTransversalAceito
ADR-0002SAGA Orquestrada para ContestaçãoCenário 2Aceito
ADR-0003Arquitetura Hexagonal nos MicroserviçosTransversalAceito
ADR-0004Event-Driven com Azure Event HubTransversalAceito
ADR-0005Anti-Corruption Layer para Legacy Debt CollectionCenário 3Aceito
ADR-0006Observabilidade — OpenTelemetry + ElasticTransversalAceito
ADR-0007Segurança — OAuth2/OIDC + mTLS + RBACTransversalAceito
ADR-0008Agente IA de Voz — ElevenLabs + LiveKitURA/IAAceito
Localização: .temp/rfp-integracao/adr/ADR-XXXX-*.md — Template corporativo: templates/development/architecture/adr/adr-template.md

Diagramas C4 Disponíveis

NívelDiagramaArquivo
C1 ContextVisão geral do sistemac1-contexto-geral.c4
C2 ContainerCenário 1 — Pagamentoc2-cenario-1-pagamento.c4
C2 ContainerCenário 2 — Contestaçãoc2-cenario-2-contestacao.c4
C2 ContainerCenário 3 — Negociaçãoc2-cenario-3-negociacao.c4
C2 ContainerCenário 4 — 2ª Viac2-cenario-4-segunda-via.c4
C3 ComponentBFF Financial Supportc3-bff-financial-support.c4
C4 CodeMS Billing Inquiryc4-classes-billing-inquiry.c4

Cenário 1: Pagamento (Envio de Fatura por Email)

Cliente solicita envio de fatura por email. Atendente/IA localiza fatura via MS Customer Billing Information (Informação do Cliente) e envia via Customer Communication.

DAS — Pagamento

Documento de Arquitetura de Solução com visão do escopo, jornada, impactos e recursos.

DAS

DATI — Pagamento

Detalhamento técnico de integração: BFF, MS Billing Inquiry, MS Payment Notification.

DATI

Data Mapping

4 fluxos mapeados: consulta cliente, consulta faturas via MS Informação do Cliente, resposta faturas, envio email.

Data Mapping

BFF API

BFF Financial Support — endpoints Billing, Payment, Customers.

BFF

MS Billing Inquiry

Consulta faturas via Informação do Cliente (mTLS).

MS

MS Payment Notification

Envio de fatura por email via Customer Communication SN (mTLS)

MS

ADRs Aplicáveis

ADR-0001: BFF

Agrega MS Billing Inquiry + MS Payment Notification

Transversal

ADR-0004: Event-Driven

Evento billing.invoice.sent

Eventos

ADR-0007: Segurança

OAuth2 JWT + mTLS + RBAC ATENDENTE

Segurança

ADR-0009: MCP

Tools: billing_get_invoices, invoice_send_email

IA/MCP

Fluxo de Sequência — Envio de Fatura por Email

sequenceDiagram
    autonumber
    participant CLI as Cliente
    participant URA as URA (ElevenLabs)
    participant ATD as Atendente
    participant BFF as BFF Financial Support
    participant MCI as MS Customer Interaction (Interação com Cliente)
    participant MCEP as Event Processor (Interação com Cliente)
    participant BIQ as MS Billing Inquiry
    participant Informação do Cliente as MS Customer Billing Info (Informação do Cliente)
    participant FP as Legacy Billing System (Legado)
    participant MPN as MS Payment Notification
    participant COM as Customer Communication
    participant VNX as Legacy Service Desk (Legado)
    participant AMD as Legacy CRM (Legado)
    CLI->>URA: Liga para URA
    rect rgb(232, 245, 233)
    Note over URA,MCI: Abertura de Protocolo (início do atendimento)
    URA->>MCI: POST /customers/protocols
    MCI->>VNX: SOAP: registra protocolo (Legacy Service Desk)
    MCI->>AMD: SOAP: registra protocolo (Legacy CRM)
    MCI-->>URA: protocolNumber #12345678
    end
    URA->>ATD: Transfere (ou resolve via IA) + protocolNumber
    ATD->>BFF: GET /billing/invoices
    BFF->>BIQ: Consulta faturas
    BIQ->>INFO: GET /customers/{id}/invoices
    INFO->>FP: REST: consulta faturas + PDF (4P)
    FP-->>INFO: Lista de faturas + PDF Base64
    INFO-->>BIQ: Lista de faturas
    BIQ-->>BFF: Faturas
    BFF-->>ATD: Exibe faturas
    BFF->>MCI: POST /protocols/{num}/items (palitagem: consulta_faturas)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    ATD->>BFF: POST /billing/invoices/{id}/send
    BFF->>MPN: Envia fatura por email
    MPN->>COM: POST /communications/email (PDF Base64)
    COM-->>MPN: 202 Accepted
    MPN-->>BFF: Fatura enviada
    BFF->>MCI: POST /protocols/{num}/items (palitagem: envio_fatura_email)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    BFF-->>ATD: Protocolo #12345678 + confirmação
            

Cenário 2: Contestação de Fatura (SAGA Pattern)

Atendente/IA abre caso de contestação → Backoffice aprova/rejeita → Crédito aplicado via MS Informação do Cliente → Cliente notificado.

DAS — Contestação

SAGA Pattern (orquestração), alçadas de aprovação, compensação.

DAS

DATI — Contestação

MS Billing Dispute, eventos assíncronos, integração billing via MS Informação do Cliente (crédito).

DATI

Data Mapping

Abertura de contestação, aplicação de crédito via MS Informação do Cliente.

Data Mapping

BFF API

BFF — endpoints Disputes.

BFF

MS Billing Dispute

SAGA contestação (mTLS).

MS

ADRs Aplicáveis

ADR-0002: SAGA

Central — State machine, compensações, outbox, timeout 72h

Resiliência

ADR-0001: BFF

Orquestra MS Billing Dispute + Informação do Cliente

Transversal

ADR-0004: Event-Driven

Eventos dispute.opened/approved/rejected

Eventos

ADR-0007: Segurança

RBAC BACKOFFICE para aprovação

Segurança

Fluxo de Sequência — Contestação (SAGA)

sequenceDiagram
    autonumber
    participant ATD as Atendente
    participant URA as URA (ElevenLabs)
    participant BFF as BFF Financial Support
    participant MCI as MS Customer Interaction (Interação com Cliente)
    participant MCEP as Event Processor (Interação com Cliente)
    participant MBD as MS Billing Dispute
    participant Informação do Cliente as MS Customer Billing Info (Informação do Cliente)
    participant FP as Legacy Billing System (Legado)
    participant BO as Backoffice
    participant COM as Customer Communication
    participant VNX as Legacy Service Desk (Legado)
    participant AMD as Legacy CRM (Legado)
    rect rgb(232, 245, 233)
    Note over URA,MCI: Abertura de Protocolo (início do atendimento)
    URA->>MCI: POST /customers/protocols
    MCI->>VNX: SOAP: registra protocolo (Legacy Service Desk)
    MCI->>AMD: SOAP: registra protocolo (Legacy CRM)
    MCI-->>URA: protocolNumber
    end
    ATD->>BFF: GET /billing/invoices (protocolNumber no header)
    BFF->>MBD: Consulta débitos
    MBD->>INFO: GET /tlf/invoices
    INFO->>FP: REST: consulta faturas e cobranças (4P)
    FP-->>INFO: Lista de faturas
    INFO-->>MBD: Débitos do cliente
    MBD-->>BFF: Débitos
    BFF-->>ATD: Exibe débitos
    ATD->>BFF: POST /disputes (protocolNumber no header)
    BFF->>MBD: Abre contestação
    MBD-->>BFF: DSP-001 (PENDING)
    BFF->>MCI: POST /protocols/{num}/items (palitagem: abertura_contestacao)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    BFF-->>ATD: DSP-001 + Protocolo
    BO->>BFF: PUT /disputes/DSP-001/approve
    BFF->>MBD: Aprovar
    MBD->>INFO: POST /adjustments (crédito)
    INFO->>FP: REST: POST /tlf/adjustments (crédito negativo, 4P)
    FP-->>INFO: Crédito aplicado (adjustmentId)
    INFO-->>MBD: Crédito aplicado
    MBD-->>BFF: CREDIT_APPLIED
    BFF->>MCI: POST /protocols/{num}/items (palitagem: credito_aplicado)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    BFF->>COM: Notifica cliente
    COM-->>BFF: 202 Accepted
            

Cenário 3: Negociação/Cobrança (Renegociação via Legacy Debt Collection)

Atendente/IA consulta débitos → Simula opções no Legacy Debt Collection → Cliente aceita → Acordo formalizado.

DAS — Negociação

Integração com Legacy Debt Collection, simulação de parcelamento, timeout de 30min.

DAS

DATI — Negociação

MS Debt Negotiation, operações Legacy Debt Collection, eventos de acordo.

DATI

Data Mapping

Consulta dívidas, simulação, formalização de acordo.

Data Mapping

BFF API

BFF — endpoints Negotiations.

BFF

MS Debt Negotiation

Legacy Debt Collection ACL (mTLS).

MS

ADRs Aplicáveis

ADR-0005: ACL Legacy Debt Collection

Central — Tradução de modelo, idempotência, circuit breaker

DDD

ADR-0001: BFF

Orquestra MS Debt Negotiation + Legacy Debt Collection

Transversal

ADR-0004: Event-Driven

Eventos negotiation.started/completed

Eventos

ADR-0008: Agente IA

Azure OpenAI recomenda melhor opção de parcelamento

IA/URA

Fluxo de Sequência — Negociação

sequenceDiagram
    autonumber
    participant ATD as Atendente
    participant URA as URA (ElevenLabs)
    participant BFF as BFF Financial Support
    participant MCI as MS Customer Interaction (Interação com Cliente)
    participant MCEP as Event Processor (Interação com Cliente)
    participant MDN as MS Debt Negotiation
    participant DCL as Legacy Debt Collection
    participant BIQ as MS Billing Inquiry
    participant Informação do Cliente as MS Customer Billing Info (Informação do Cliente)
    participant FP as Legacy Billing System (Legado)
    participant AI as Azure OpenAI
    participant COM as Customer Communication
    participant VNX as Legacy Service Desk (Legado)
    participant AMD as Legacy CRM (Legado)
    rect rgb(232, 245, 233)
    Note over URA,MCI: Abertura de Protocolo (início do atendimento)
    URA->>MCI: POST /customers/protocols
    MCI->>VNX: SOAP: registra protocolo (Legacy Service Desk)
    MCI->>AMD: SOAP: registra protocolo (Legacy CRM)
    MCI-->>URA: protocolNumber
    end
    ATD->>BFF: GET /negotiations/eligible-debts (protocolNumber no header)
    BFF->>BIQ: Consulta faturas vencidas
    BIQ->>INFO: GET /tlf/invoices (vencidas)
    INFO->>FP: REST: consulta faturas vencidas (4P)
    FP-->>INFO: Faturas vencidas
    INFO-->>BIQ: Débitos pendentes
    BIQ-->>BFF: Débitos pendentes
    BFF->>MDN: Consulta dívidas elegíveis (Legacy Debt Collection)
    MDN->>DCL: GET /debt-collection/debts
    DCL-->>MDN: Dívidas ativas
    MDN-->>BFF: Dívidas elegíveis
    BFF->>MCI: POST /protocols/{num}/items (palitagem: consulta_dividas)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    ATD->>BFF: POST /negotiations/simulate
    BFF->>MDN: Simula acordo
    MDN->>DCL: POST /debt-collection/simulations
    DCL-->>MDN: Opções de parcelamento
    BFF->>AI: Qual melhor opção?
    AI-->>BFF: Recomenda opção 2
    BFF-->>ATD: Opções + recomendação IA
    BFF->>MCI: POST /protocols/{num}/items (palitagem: simulacao_acordo)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    ATD->>BFF: POST /negotiations (aceita opção 2)
    BFF->>MDN: Formaliza acordo
    MDN->>DCL: POST /debt-collection/agreements
    DCL-->>MDN: Acordo formalizado
    BFF->>MCI: POST /protocols/{num}/items (palitagem: acordo_formalizado)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    BFF->>COM: Confirmação por email
    BFF-->>ATD: Protocolo + acordo
            

Cenário 4: 2ª Via de Fatura (Boleto + PIX)

Atendente/IA gera 2ª via com novo boleto e QR Code PIX → Envia por email, SMS ou link de download (24h).

DAS — 2ª Via

Geração de PDF com barcode atualizado e PIX BRCode.

DAS

DATI — 2ª Via

MS Customer Invoice Mgmt v2, MS Informação do Cliente, Blob Storage.

DATI

Data Mapping

Geração 2ª via via MS Informação do Cliente (boleto+PIX), envio multi-canal.

Data Mapping

BFF API

BFF — endpoints Invoices.

BFF

MS Invoice Delivery

2ª via + Blob Storage (mTLS).

MS

ADRs Aplicáveis

ADR-0001: BFF

Orquestra MS Invoice Delivery + Informação do Cliente + Blob

Transversal

ADR-0004: Event-Driven

Evento invoice.duplicate-generated

Eventos

ADR-0007: Segurança

SAS token Blob Storage (TTL 24h)

Segurança

ADR-0009: MCP

Tools: invoice_generate_duplicate

IA/MCP

Fluxo de Sequência — 2ª Via

sequenceDiagram
    autonumber
    participant ATD as Atendente
    participant URA as URA (ElevenLabs)
    participant BFF as BFF Financial Support
    participant MCI as MS Customer Interaction (Interação com Cliente)
    participant MCEP as Event Processor (Interação com Cliente)
    participant BIQ as MS Billing Inquiry
    participant Informação do Cliente as MS Customer Billing Info (Informação do Cliente)
    participant CIMV2 as MS Customer Invoice Mgmt v2
    participant FP as Legacy Billing System (Legado)
    participant BLOB as Azure Blob Storage
    participant COM as Customer Communication
    participant VNX as Legacy Service Desk (Legado)
    participant AMD as Legacy CRM (Legado)
    rect rgb(232, 245, 233)
    Note over URA,MCI: Abertura de Protocolo (início do atendimento)
    URA->>MCI: POST /customers/protocols
    MCI->>VNX: SOAP: registra protocolo (Legacy Service Desk)
    MCI->>AMD: SOAP: registra protocolo (Legacy CRM)
    MCI-->>URA: protocolNumber
    end
    ATD->>BFF: GET /billing/invoices (protocolNumber no header)
    BFF->>BIQ: Consulta faturas
    BIQ->>INFO: GET /customers/{id}/invoices
    INFO->>FP: REST: consulta fatura + status (4P)
    FP-->>INFO: Fatura + status
    INFO-->>BIQ: Faturas + payment_code + download_url
    BIQ-->>BFF: Faturas
    BFF-->>ATD: Exibe faturas
    BFF->>MCI: POST /protocols/{num}/items (palitagem: consulta_faturas)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    ATD->>BFF: POST /invoices/{id}/duplicate
    BFF->>CIMV2: GET /invoiceDetails/{type}/{id}?responseContent=pdf
    CIMV2->>FP: REST: POST /tlf/invoices/{id}/payment-slip + PIX (4P)
    FP-->>CIMV2: Novo boleto + BRCode PIX
    CIMV2-->>BFF: PDF Base64 (gzip)
    BFF->>BLOB: Upload PDF (TTL 24h)
    BLOB-->>BFF: URL temporária (SAS token)
    BFF-->>ATD: PDF pronto
    BFF->>MCI: POST /protocols/{num}/items (palitagem: geracao_segunda_via)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    ATD->>BFF: POST /invoices/{id}/deliver (EMAIL)
    BFF->>COM: POST /communications/email
    COM-->>BFF: 202 Accepted
    BFF->>MCI: POST /protocols/{num}/items (palitagem: envio_segunda_via_email)
    MCI-->>MCEVP: Evento tpc-csit-protocol-item-topic
    MCEP->>VNX: SOAP: palitagem (Legacy Service Desk)
    MCEP->>AMD: SOAP: palitagem (Legacy CRM)
    BFF-->>ATD: Protocolo + confirmação
            

Diagramas C4 (LikeC4 DSL)

Todos os diagramas C4 utilizam LikeC4 DSL com a specification corporativa Vivo. O servidor LikeC4 deve estar rodando em https://docs-c4.acntechlab.com. Para iniciar: npx likec4 serve -w diagrams/
NívelDiagramaArquivoEscopo
C1Context — Visão Geralc1-contexto-geral.c4Todos os cenários
C2Container — Pagamentoc2-cenario-1-pagamento.c4Cenário 1
C2Container — Contestaçãoc2-cenario-2-contestacao.c4Cenário 2
C2Container — Negociaçãoc2-cenario-3-negociacao.c4Cenário 3
C2Container — 2ª Viac2-cenario-4-segunda-via.c4Cenário 4
C2Container — Observabilidadec2-observabilidade.c4Transversal
C3Component — BFFc3-bff-financial-support.c4Transversal
C3Component — MS Billing Disputec3-ms-billing-dispute.c4Cenário 2
C3Component — MS Debt Negotiationc3-ms-debt-negotiation.c4Cenário 3
C3Component — URA Agent Servicec3-ura-agent-service.c4URA/IA
C4Code — MS Billing Inquiryc4-classes-billing-inquiry.c4Cenário 1

C1 — Context: Visão Geral

C1 Context — PoC CRM+ Suporte Financeiro Abrir no LikeC4 ↗
C1 Context

C2 — Container: Cenário 1 (Pagamento)

C2 Container — Envio de Fatura por Email Abrir no LikeC4 ↗
C2 Cenário 1

C2 — Container: Cenário 2 (Contestação)

C2 Container — Fatura/Contestação (SAGA) Abrir no LikeC4 ↗
C2 Cenário 2

C2 — Container: Cenário 3 (Negociação)

C2 Container — Negociação/Cobrança via Legacy Debt Collection Abrir no LikeC4 ↗
C2 Cenário 3

C2 — Container: Cenário 4 (2ª Via)

C2 Container — 2ª Via de Fatura Abrir no LikeC4 ↗
C2 Cenário 4

C2 — Container: Observabilidade (Elastic Cloud + Langfuse)

C2 Container — Observabilidade: Elastic Cloud + Langfuse Abrir no LikeC4 ↗
C2 Observabilidade

C3 — Component: BFF Financial Support

C3 Component — BFF Financial Support Abrir no LikeC4 ↗
C3 BFF

C3 — Component: MS Billing Dispute (SAGA)

C3 Component — MS Billing Dispute (SAGA Orchestrator) Abrir no LikeC4 ↗
C3 MS Billing Dispute

C3 — Component: MS Debt Negotiation (ACL Legacy Debt Collection)

C3 Component — MS Debt Negotiation (ACL Legacy Debt Collection) Abrir no LikeC4 ↗
C3 MS Debt Negotiation

C3 — Component: URA Agent Service (AI Pipeline)

C3 Component — URA Agent Service (AI Pipeline: STT → NLP → TTS) Abrir no LikeC4 ↗
C3 URA Agent

C4 — Code: MS Billing Inquiry (Hexagonal)

C4 Code — MS Billing Inquiry (Arquitetura Hexagonal) Abrir no LikeC4 ↗
C4 Code

Specification Corporativa

specs.c4

Cores, shapes e relationships padrão Vivo para LikeC4 DSL.

Spec

externals.c4

Sistemas externos compartilhados: Legacy Billing System (via MS Informação do Cliente), Legacy Debt Collection, API Gateway, IdP, etc.

Externals

Observabilidade — Stack Transversal

Stack de observabilidade separada dos diagramas de solução. Elastic Cloud (logs, traces, métricas) + Langfuse self-hosted (observabilidade LLM).

DAS — Observabilidade

Elastic Cloud, Langfuse, SLIs/SLOs, alertas, dashboards + 4 ADRs.

DAS

Contratos OpenAPI — Por Serviço

Contratos OpenAPI 3.0 individuais para cada microsserviço (novo/alterado) + BFF. Abrir Swagger UI multi-contrato (com seletor de serviço) ↗
ServiçoContratoTipoAutenticaçãoEndpoints
BFF Financial Supportapi-crm-financial-support-bff-v1.yamlBFF (externo)OAuth2 JWT16
MS Billing Inquiryapi-crm-billing-inquiry-ms-v1.yamlMS (interno)mTLS5
MS Billing Disputeapi-crm-billing-dispute-ms-v1.yamlMS (interno)mTLS5
MS Debt Negotiationapi-crm-debt-negotiation-ms-v1.yamlMS (interno)mTLS6
MS Invoice Deliveryapi-crm-invoice-delivery-ms-v1.yamlMS (interno)mTLS5
MS Payment Notificationapi-crm-payment-notification-ms-v1.yamlMS (interno)mTLS3

Swagger UI — Por Serviço

BFF Financial Support

Contrato externo consumido pelo CRM+ Frontend — agrega todos os cenários (OAuth2 JWT)

BFF

MS Billing Inquiry

Consulta faturas e débitos via Informação do Cliente — cache Redis (mTLS)

MS

MS Billing Dispute

Contestação SAGA — abertura, aprovação backoffice, crédito via Informação do Cliente (mTLS)

MS

MS Debt Negotiation

Negociação via Legacy Debt Collection — simulação, formalização (mTLS)

MS

MS Invoice Delivery

2ª via — geração PDF, boleto, PIX, Blob Storage, multi-canal (mTLS)

MS

MS Payment Notification

Envio de fatura por email via Customer Communication SN (mTLS)

MS

Architecture Decision Records (ADRs)

Decisões arquiteturais documentadas formalmente. Cada ADR registra contexto, decisão, consequências e alternativas consideradas.
IDDecisãoStatusTema
ADR-0001Adoção do padrão BFF para orquestraçãoAceitoIntegração
ADR-0002SAGA Orquestrada para fluxo de ContestaçãoAceitoResiliência
ADR-0003Arquitetura Hexagonal para MicroserviçosAceitoDesign
ADR-0004Event-Driven Architecture com Azure Event HubAceitoEventos
ADR-0005Anti-Corruption Layer para Legacy Debt CollectionAceitoDDD
ADR-0006Stack de Observabilidade — OpenTelemetry + ElasticAceitoObservabilidade
ADR-0007Segurança — OAuth2/OIDC + mTLS + RBACAceitoSegurança
ADR-0008Agente IA de Voz — ElevenLabs + LiveKit + Azure OpenAIAceitoIA/URA
ADR-0009MCP Servers para desacoplamento Microsserviços ↔ Agentes IAAceitoIA/MCP

ADRs por Tema

ADR-0001: BFF Pattern

Camada de orquestração dedicada ao CRM+ — contrato único, agregação server-side, circuit breaker.

Integração

ADR-0002: SAGA Orquestrada

State machine para contestação — compensações, outbox pattern, timeout 72h.

Resiliência

ADR-0003: Arq. Hexagonal

Ports & Adapters em todos os microserviços — isolamento do domain, substituição de legados.

Design

ADR-0004: Event-Driven

Azure Event Hub com protocolo Kafka — CloudEvents, schema registry, outbox pattern.

Eventos

ADR-0005: ACL Legacy Debt Collection

Anti-Corruption Layer para Legacy Debt Collection — tradução de modelo, idempotência, circuit breaker.

DDD

ADR-0006: Observabilidade

OpenTelemetry + Elastic Cloud + Langfuse — traces, logs, métricas, SLOs.

Observabilidade

ADR-0007: Segurança

3 camadas — Edge (API Gateway), Service Mesh (mTLS), Aplicação (RBAC). LGPD, SOX, PCI DSS.

Segurança

ADR-0008: Agente IA Voz

ElevenLabs TTS + LiveKit WebRTC + Azure OpenAI GPT-4o — latência < 2s, guardrails.

IA/URA

ADR-0009: MCP Servers

Model Context Protocol — desacoplamento, descoberta dinâmica de tools, reutilização multi-agente.

IA/MCP

Código Fonte — Repositórios Azure DevOps

Repositórios Git dos microsserviços e BFF desenvolvidos na PoC CRM Financeiro. Projeto: Architecture and Integration RFP.

MS Debt Negotiation v1

Microsserviço de negociação de dívida — ACL para Legacy Debt Collection, simulação e formalização de acordos.

MicrosserviçoAzure DevOps ↗

BFF Financial Support v1

Backend for Frontend — orquestração de todos os cenários (pagamento, contestação, negociação, 2ª via).

BFFAzure DevOps ↗

MS Billing Inquiry v1

Consulta de faturas e débitos via Informação do Cliente — cache Redis, integração 4P.

MicrosserviçoAzure DevOps ↗

MS Invoice Delivery v1

Geração de 2ª via de fatura — PDF, boleto, PIX BRCode, Blob Storage com TTL 24h.

MicrosserviçoAzure DevOps ↗

MS Payment Notification v1

Envio de fatura por email via Customer Communication SN — notificações multi-canal.

MicrosserviçoAzure DevOps ↗

Mapeamento Serviço → Repositório

ServiçoRepositório Azure DevOpsDownload ZIPCenários
BFF Financial Support bff-financial-support-v1 ↗ ⬇ ZIP (136 KB) 1, 2, 3, 4
MS Billing Inquiry ms-billing-inquiry-v1 ↗ ⬇ ZIP (81 KB) 1, 3, 4
MS Billing Dispute Azure DevOps ⬇ ZIP (50 KB) 2
MS Debt Negotiation ms-debt-negotiation-v1 ↗ ⬇ ZIP (56 KB) 3
MS Invoice Delivery ms-invoice-delivery-v1 ↗ ⬇ ZIP (57 KB) 4
MS Payment Notification ms-payment-notification-v1 ↗ ⬇ ZIP (59 KB) 1

Estrutura dos Arquivos ZIP

Cada arquivo ZIP contém a estrutura completa do projeto Spring Boot 3.x com Java 21:
Diretório/ArquivoDescrição
src/main/java/Código fonte Java — arquitetura hexagonal (domain, application, infrastructure)
src/main/resources/Configurações (application.yml, logback.xml)
src/test/java/Testes unitários e de integração
pom.xmlDependências Maven (Spring Boot 3.x, OpenTelemetry, etc.)
DockerfileImagem Docker multi-stage build
README.mdDocumentação do microsserviço

Stack Tecnológica

Framework
Spring Boot 3.x
Linguagem
Java 21
Build
Maven 3.9+
Arquitetura
Hexagonal (Ports & Adapters)
Observabilidade
OpenTelemetry + Micrometer
Segurança
Spring Security + mTLS

MCP Servers — Model Context Protocol

Servidores MCP (Model Context Protocol) dos microsserviços da PoC CRM Financeiro. Permitem integração com agentes de IA (Claude, Windsurf, etc.) via SSE (Server-Sent Events).

Endpoints MCP Disponíveis

MicrosserviçoEndpoint SSEStatus
MS Billing Dispute https://cl0.acntechlab.com/billing-dispute/sse Ativo
MS Billing Inquiry https://cl0.acntechlab.com/billing-inquiry/sse Ativo
MS Debt Negotiation https://cl0.acntechlab.com/debt-negotiation/sse Ativo
MS Invoice Delivery https://cl0.acntechlab.com/invoice-delivery/sse Ativo
MS Payment Notification https://cl0.acntechlab.com/payment-notification/sse Ativo

Operações por Microsserviço

MS Billing Dispute — Contestação de Faturas

create_dispute

Abre uma nova contestação de fatura. Inicia o fluxo SAGA de contestação.

POST SAGA

get_dispute

Consulta detalhes de uma contestação específica pelo seu ID.

GET

list_disputes

Lista contestações de um cliente com filtro opcional por status.

GET

approve_dispute

Aprova uma contestação (backoffice). Aplica crédito na fatura do cliente.

BACKOFFICE

reject_dispute

Rejeita uma contestação (backoffice). Informa o motivo da rejeição.

BACKOFFICE

MS Billing Inquiry — Consulta de Faturas

getInvoices

Lista faturas de um cliente com filtros opcionais (período, status).

GET

getInvoiceDetail

Retorna o detalhe de uma fatura específica, incluindo cobranças e PDF em Base64.

GET

getInvoicePdf

Obtém o PDF de uma fatura codificado em Base64.

GET PDF

getDebts

Consulta débitos pendentes de um cliente com valor original, atual, vencimento e dias de atraso.

GET

MS Debt Negotiation — Negociação de Dívidas

query_eligible_debts

Consulta as dívidas elegíveis para negociação de um cliente.

GET

simulate_negotiation

Simula opções de negociação para uma dívida específica com parcelas, valores e descontos.

POST

formalize_agreement

Formaliza um acordo de negociação selecionando uma das opções da simulação.

POST Acordo

MS Invoice Delivery — Geração de 2ª Via

previewInvoice

Preview dos dados da fatura do cliente antes de gerar a 2ª via.

GET

generateDuplicate

Gera 2ª via de fatura com nova data de vencimento.

POST 2ª Via

deliverInvoice

Entrega fatura via canal (EMAIL, SMS, DOWNLOAD_LINK).

POST Multi-canal

getDownloadLink

Obtém link temporário de download da fatura com expiração configurável.

GET TTL

MS Payment Notification — Notificações de Pagamento

sendInvoiceByEmail

Envia uma fatura por email para o cliente. Retorna ID da notificação, status e protocolo.

POST Email

Recursos e Benefícios

Integração Nativa com IA

Agentes de IA podem invocar operações de negócio diretamente via MCP, sem necessidade de código customizado.

Zero Code

Server-Sent Events (SSE)

Comunicação bidirecional em tempo real entre agente e microsserviços.

Real-time

Descoberta Automática

Agentes descobrem automaticamente as operações disponíveis via protocolo MCP.

Auto-discovery

Observabilidade Integrada

Todas as chamadas MCP são rastreadas via OpenTelemetry com correlation ID.

Tracing

Argo CD — Continuous Deployment

Acesso ao Argo CD para monitoramento de deployments, sincronização GitOps e status de aplicações Kubernetes da PoC CRM Financeiro.

Dashboard Principal

Argo CD Dashboard ↗

Console web para visualização de aplicações, histórico de deployments, sincronização manual/automática e logs de pods.

GitOps Kubernetes

Credenciais de Acesso

Solicitar credenciais ao time de DevOps/SRE. Autenticação via SSO corporativo (Azure AD).

SSO

Aplicações Monitoradas

AplicaçãoNamespaceRepositório GitSync Policy
bff-financial-support-v1crm-financial-pocAzure DevOps ↗Automated
ms-billing-inquiry-v1crm-financial-pocAzure DevOps ↗Automated
ms-billing-dispute-v1crm-financial-pocAzure DevOpsAutomated
ms-debt-negotiation-v1crm-financial-pocAzure DevOps ↗Automated
ms-invoice-delivery-v1crm-financial-pocAzure DevOps ↗Automated
ms-payment-notification-v1crm-financial-pocAzure DevOps ↗Automated

Recursos e Funcionalidades

Sync Status

Visualização em tempo real do status de sincronização entre Git e cluster Kubernetes (Synced, OutOfSync, Unknown).

Real-time

Health Status

Monitoramento de saúde das aplicações (Healthy, Progressing, Degraded, Suspended, Missing).

Health Check

Rollback

Capacidade de rollback para versões anteriores via histórico de revisões Git.

Rollback

Logs & Events

Acesso a logs de pods e eventos Kubernetes diretamente pelo dashboard.

Logs

Pipeline GitOps

graph LR
    A[Developer Push] --> B[Azure DevOps Git]
    B --> C[Argo CD Sync]
    C --> D{Sync Policy}
    D -->|Automated| E[Auto Deploy]
    D -->|Manual| F[Manual Approval]
    E --> G[AKS Cluster]
    F --> G
    G --> H[Health Check]
    H -->|Healthy| I[Deployment OK]
    H -->|Degraded| J[Rollback]
    J --> B