Visão Geral

O que é

Neppo Billing é o sistema (Kotlin/Spring Boot) responsável por coletar métricas
de uso das bases de dados dos clientes e enviá-las para uma API de billing externa.

Ele é somente a camada de coleta de dados — não calcula preços, não gera faturas
e não administra contratos financeiros. Essas responsabilidades pertencem a sistemas
posteriores (downstream), fora deste projeto.

Por que existe

Substitui um sistema legado que misturava coleta de consumo com cálculo de preço na
mesma base de código — o que trazia problemas concretos: IDs mágicos fixos no meio de
queries (license_id IN (2, 3, 4, 5, 10)), risco de SQL injection nas rotas da API, e
uma lógica de precificação com 11 cenários de if-else só para decidir um valor. O
Neppo Billing separa essa responsabilidade: aqui só se mede e coleta consumo; o
cálculo financeiro vive em outro lugar, com sua própria lógica e seus próprios testes.

As 4 responsabilidades centrais

1. Coletar — roda templates SQL (Licenses) contra o banco de cada cliente para
   medir consumo por período

2. Armazenar — persiste os snapshots de consumo no banco analítico (MySQL) para
   auditoria e reprocessamento

3. Sincronizar — envia os registros de consumo ainda não sincronizados para uma
   API externa via job em background

4. Gerenciar — expõe uma API REST para o frontend Angular gerenciar configuração
   (Operations, Licenses, Packages)

O que o Neppo Billing NÃO faz

• NÃO calcula valores de cobrança nem aplica regras de precificação

• NÃO gera faturas ou documentos financeiros

• NÃO administra contratos, acordos ou negociações

• Packages/Planos existem só como referência de catálogo — sem valores monetários

• Cálculos financeiros acontecem em um sistema downstream separado, que consome a API
  externa deste sistema

Quem usa isso

• Time de billing/produto — configura Operations, Licenses e Packages pela UI interna

• Sistemas downstream/integradores externos — consomem a API /api/v1 via chave
  de API para ler consumo e registrar operações

• Qualquer pessoa da empresa — para entender de onde vêm os números de consumo que
  alimentam o billing, e por que um valor específico apareceu (ou não) para um cliente

Onde encontrar mais

• Repositório

• Documentação técnica completa: pasta docs/ no repositório (decisões de arquitetura,
  referência, funcionalidades, runbooks)

Ver também: Como Funciona · Glossário de Domínio · Perguntas Frequentes