a52bd4519d
- 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.
102 lines
3.5 KiB
Markdown
102 lines
3.5 KiB
Markdown
# 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.
|