rede5/core

Tiago Yamamoto a52bd4519d refactor: optimize Dockerfiles and documentation for core services

- Use Google Distroless images for all services (Go & Node.js).
- Standardize documentation with [PROJECT-NAME].md.
- Add .dockerignore and .gitignore to all projects.
- Remove docker-compose.yml in favor of docker run instructions.
- Fix Go version and dependency issues in observability, repo-integrations, and security-governance.
- Add Podman support (fully qualified image names).
- Update Dashboard to use Node.js static server for Distroless compatibility.

2025-12-30 13:22:34 -03:00

3.5 KiB

Raw Blame History

BILLING-FINANCE-CORE

Este microserviço é o coração financeiro da plataforma SaaS, responsável por gerenciar todo o ciclo de vida de assinaturas, cobranças (billing), emissão de notas fiscais (fiscal) e um CRM operacional para gestão de clientes e vendas.

📋 Visão Geral

O projeto foi construído pensando em Multi-tenancy desde o dia zero, utilizando NestJS para modularidade e Prisma para interação robusta com o banco de dados.

Arquitetura

O diagrama abaixo ilustra a interação entre os componentes e serviços externos:

graph TD
    Client[Cliente/Frontend] -->|HTTP/REST| API[Billing Finance API]
    API -->|Valida Token| Identity[Identity Gateway]
    
    subgraph Core Modules
        API --> Tenants
        API --> Plans
        API --> Subscriptions
        API --> Invoices
        API --> Payments
        API --> Fiscal
        API --> CRM
    end

    Payments -->|Webhook/API| Stripe[Stripe / Gateway]
    Payments -->|Webhook/API| Boleto[Gerador Boleto]
    Fiscal -->|NFS-e| NuvemFiscal[Nuvem Fiscal API]

    API --> DB[(PostgreSQL)]

🚀 Estrutura do Projeto

A aplicação é dividida em módulos de domínio, cada um com responsabilidade única:

Módulo	Descrição
Tenants	Gestão dos clientes (empresas) que usam a plataforma.
Plans	Definição de planos, preços, ciclos (mensal/anual) e limites.
Subscriptions	Vínculo entre um Tenant e um Plan (Ciclo de Vida).
Invoices	Faturas geradas a partir das assinaturas (Contas a Receber).
Payments	Integração com gateways (Stripe, Boleto, Pix) e conciliação.
Fiscal	Emissão de Notas Fiscais de Serviço (NFS-e).
CRM	Gestão leve de empresas, contatos e oportunidades (deals).

🛠️ Tecnologias e Otimizações

Backend: Node.js 20 + NestJS
ORM: Prisma (PostgreSQL)
Containerização:
- Multi-stage builds (Builder + Prod Deps + Runtime).
- Runtime baseado em gcr.io/distroless/nodejs20-debian12.
- Execução segura sem shell e com usuário não-privilegiado (padrão distroless).

💻 Como Executar

O ambiente pode ser levantado facilmente via Docker Compose.

Pré-requisitos

Docker & Docker Compose
Node.js 20+ (para desenvolvimento local)

Passo a Passo

Configuração: Copie o arquivo de exemplo env:
```
cp .env.example .env
```
Inicie os serviços:
```
docker-compose up --build
```
A API estará disponível na porta configurada (padrão 3000 ou similar).

Desenvolvimento Local: Se preferir rodar fora do Docker:

npm install
npm run prisma:generate
npm run start:dev

🔐 Segurança e Multi-tenancy

O serviço opera em um modelo de confiança delegada:

JWT: Não realiza login direto. Confia no cabeçalho Authorization: Bearer <token> validado pelo Identity Gateway.
AuthGuard: Decodifica o token para extrair tenantId e userId.
Isolamento de Dados: O tenantId é injetado obrigatoriamente em todas as operações do banco de dados para garantir que um cliente nunca acesse dados de outro.

🔧 Detalhes do Dockerfile

O Dockerfile foi otimizado para produção:

Builder: Compila o TypeScript e gera o Prisma Client.
Prod Deps: Instala apenas dependências de produção (--omit=dev), reduzindo o tamanho da imagem.
Runtime (Distroless): Copia apenas o necessário (dist, node_modules, prisma) para uma imagem final minimalista e segura.

3.5 KiB Raw Blame History