# 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:

```mermaid
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

1.  **Configuração:**
    Copie o arquivo de exemplo env:
    ```bash
    cp .env.example .env
    ```

2.  **Inicie os serviços:**
    ```bash
    docker-compose up --build
    ```
    A API estará disponível na porta configurada (padrão `3000` ou similar).

3.  **Desenvolvimento Local:**
    Se preferir rodar fora do Docker:
    ```bash
    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:

1.  **JWT**: Não realiza login direto. Confia no cabeçalho `Authorization: Bearer <token>` validado pelo `Identity Gateway`.
2.  **AuthGuard**: Decodifica o token para extrair `tenantId` e `userId`.
3.  **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.