core/billing-finance-core

billing-finance-core

Backend financeiro, billing, fiscal e CRM para uma plataforma SaaS multi-tenant.

Visão geral

• Multi-tenant desde o início com isolamento por tenantId.
• Sem autenticação própria: confia no identity-gateway via JWT interno.
• Core financeiro: planos, assinaturas, invoices, pagamentos, conciliação.
• Fiscal (base): estrutura para emissão de NFS-e.
• CRM: empresas, contatos e pipeline simples de negócios.

Stack

• Node.js + TypeScript
• NestJS
• PostgreSQL + Prisma
• Docker

Integração com identity-gateway

• Todas as rotas são protegidas por JWT interno.
• O token deve conter:
  • tenantId
  • userId
  • roles
• O guard valida issuer e assina com JWT_PUBLIC_KEY ou JWT_SECRET.

Modelo de dados (resumo)

• Tenant: empresa cliente
• Plan: preço, ciclo e limites
• Subscription: tenant + plano
• Invoice: contas a receber
• Payment: pagamentos com gateway
• FiscalDocument: base para NFS-e
• CRM: companies, contacts, deals

Fluxo de cobrança

1. Criar plano
2. Criar assinatura
3. Gerar invoice
4. Criar pagamento via gateway
5. Receber webhook e conciliar

Endpoints mínimos

POST   /tenants
GET    /tenants
POST   /plans
GET    /plans
POST   /subscriptions
GET    /subscriptions
POST   /invoices
GET    /invoices
POST   /payments/:invoiceId
POST   /webhooks/:gateway
GET    /crm/companies
POST   /crm/deals
GET    /health

Configuração local

cp .env.example .env
npm install
npm run prisma:generate
npm run prisma:migrate
npm run start:dev

Docker

docker compose up --build

Estrutura

• src/core: guard e contexto do tenant
• src/modules: domínios de negócio
• prisma/: schema e migrations
• docs/: documentação técnica