Microservice Commercial

1. OBJETIVO

Este documento consolida as informações técnicas e de arquitetura do projeto "microservice-commercial", um microserviço NestJS responsável por gestão completa do módulo comercial: clientes, orçamentos, propostas, funil de vendas, unidades consumidoras/geradoras, simulações de financiamento e geração de documentos PDF. Implementa Clean Architecture com DDD, multi-tenancy, integração com serviços externos e sistema robusto de geração de propostas comerciais.

2. ÚLTIMA REVISÃO

• 15/09/2025 - Revisão e atualização da documentação (Equipe)

3. TECNOLOGIAS UTILIZADAS

Backend

Node.js 22, NestJS 11.1.0, TypeScript 5.8.3, Prisma 6.7.0

Swagger 11.2.0, class-validator/transformer, AWS SQS SDK 3.803.0

React PDF Renderer 4.3.0, Chart.js 4.4.9, PDF-lib 1.17.1

Multer 1.4.5-lts.2 (upload), Compression 1.8.0, Zod 3.24.4

Vitest 3.1.3 (testes), ESLint, Prettier

Repositórios: Local/GitHub

Frontend

Não aplicável (API pura)

Banco de Dados

PostgreSQL (via Prisma ORM), Multi-tenancy nativo

Ferramentas de Conexão e Infraestrutura

Docker Compose (PostgreSQL + App), Prisma migrations, AWS SQS messaging

Integração com Mapbox (geocoding) e Dotcoding (irradiação), Kubernetes

4. FUNCIONALIDADES E DOMÍNIOS

• Gestão de Clientes: CRUD completo para clientes PF/PJ, múltiplos endereços, endereço de cobrança principal, dados de responsável para PJ, validação de CPF/CNPJ único, soft delete com auditoria
• Sistema de Orçamentos: Criação e gestão de orçamentos, status (progress, closed, lost, archived), relacionamento com funil de vendas, sistema de tags para categorização, anexos de documentos, soft delete com recuperação
• Propostas Comerciais: Criação de propostas com cálculos automáticos, tipos (microgeração, minigeração, OffGrid), cálculos de energia solar (irradiação, perdas, potência), sistema de preços com margens e descontos, parcelas de pagamento configuráveis, simulações de financiamento bancário, garantias de painéis/inversores/mão de obra, geração automática de PDF profissional
• Unidades Consumidoras/Geradoras: Gestão de unidades com tipo (consumer/generator), dados técnicos (UC, fator simultaneidade, consumo médio), consumo mensal detalhado (12 meses), tarifas (TUSD, TE, FIOB), classificação tarifária (grupo, modalidade, classe), anexos técnicos
• Funil de Vendas: Criação de funis personalizáveis, fases configuráveis via JSON, controle de orçamentos por fase, indicadores de conversão
• Sistema de Tags: Criação de tags com cores, categorização de orçamentos, relacionamento many-to-many
• Geração de Documentos: PDFs profissionais com React PDF, componentes reutilizáveis (Header, ProductCard, Charts), gráficos de consumo/geração com Chart.js, simulações de financiamento, detalhes de investimento, garantias e termos, fluxo de caixa projetado
• Integrações Externas: Mapbox (Geocoding de endereços), Dotcoding (Irradiação solar por cidade), AWS SQS (Messaging assíncrono), Microserviços (Administrator, Contracts, Common)
• Observabilidade: Swagger para documentação automática, logs estruturados, tratamento de erros centralizado, validação rigorosa de dados, testes automatizados com Vitest

5. ARQUITETURA FRONTEND

Não aplicável - API pura sem frontend próprio

6. ARQUITETURA BACKEND

Controllers

37 controllers especializados organizados por funcionalidade

Clientes: CreateClient, FetchClient, GetClient, EditClient, DeleteClient

Orçamentos: CreateBudget, FetchBudgets, GetBudget, EditBudget, DeleteBudget, ToggleArchivedBudget, ToggleLostBudget, ChangePhaseBudget

Propostas: CreateProposal, FetchProposal, GetProposal, EditProposal, DeleteProposal, ToggleCloseProposal, ToggleLostProposal, GetCashFlowProposal

Unidades: CreateUnit, FetchUnit, GetUnit, EditUnit, DeleteUnit, SetUnitAsGenerator

Funil: CreateFunnel, FetchFunnels, EditFunnel, DeleteFunnel

Tags: CreateTag, FetchTags, EditTag, DeleteTag

Endereços: FetchAddress, Irradiação: IrradiationController

Features

Gestão completa de clientes (PF/PJ) com endereços múltiplos

Sistema de orçamentos com status (progress, closed, lost, archived)

Propostas comerciais com cálculos automáticos de energia solar

Funil de vendas com fases configuráveis

Unidades consumidoras e geradoras com consumo mensal

Sistema de tags para categorização

Simulações de financiamento bancário

Geração automática de documentos PDF profissionais

Cálculos de irradiação solar por cidade

Integração com serviços externos (Mapbox, Dotcoding)

Messaging assíncrono com AWS SQS, Multi-tenancy nativo

Repositories

14 repositórios especializados: Clients, Budgets, Proposals, Units, Funnels, Tags, Addresses

Implementações Prisma + repositórios in-memory para testes

Multi-tenancy via isolamento por tenant, Soft delete implementado

Entities

Client, Address, Budget, Proposal, Unit, Funnel, Tag, Installment

FinancingSimulation, ProposalWarranty, MonthlyKwhConsumption, Attachment

Helper/Utilities

DocumentGeneratorService (PDFs), GeocodingService (Mapbox), IrradiationService (Dotcoding)

SQS Publishers, ValidationPipe, Presenters, Error Handling

7. ROTAS E ENDPOINTS

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Principais tabelas

clients, addresses, budgets, proposals, units, funnels, tags, installments

financing_simulations, proposal_warranties, monthly_kwh_consumptions, attachments

Relacionamentos

clients -> addresses (1:N), clients -> budgets (1:N), budgets -> proposals (1:N)

proposals -> units (1:N), proposals -> installments (1:N), budgets -> tags (N:N)

Enums

Status de orçamentos, propostas, unidades, tipos de cliente, fases do funil

9. CONFIGURAÇÃO E VARIÁVEIS

Arquivo principal

docker-compose.yml

Variáveis principais

DATABASE_URL (PostgreSQL), PORT (3000)

AWS_SQS_* (Configurações AWS SQS), MAPBOX_ACCESS_TOKEN (Geocoding)

DOTCODING_API_KEY (Irradiação solar)

Configurações Docker

PostgreSQL: porta 5432, database "commercial"

App: porta 3000, desenvolvimento com hot reload

Volumes para persistência de dados

Configurações Kubernetes

Deployment com 3 réplicas, Service para exposição, Secret para variáveis sensíveis

10. TREEVIEW DA ARQUITETURA

microservice-commercial/
├── src/
│   ├── @types/index.d.ts                    # Definições de tipos globais
│   ├── assets/
│   │   ├── icons/                           # Ícones (5 arquivos PNG)
│   │   └── images/                          # Imagens (5 arquivos PNG)
│   ├── common/
│   │   ├── decorators/                      # Decorators (13 arquivos)
│   │   ├── filters/                         # Filtros de exceção (2 arquivos)
│   │   ├── utils/                           # Utilitários (2 arquivos)
│   │   └── validation-error-exception.ts    # Exceção de validação
│   ├── core/
│   │   ├── either.ts                        # Padrão Either para tratamento de erros
│   │   ├── entities/                        # Entidades base (2 arquivos)
│   │   ├── errors/                          # Erros customizados (8 arquivos)
│   │   ├── types/                           # Tipos base (1 arquivo)
│   │   └── utils/                           # Utilitários core (1 arquivo)
│   ├── domain/
│   │   ├── entities/                        # Entidades de domínio (18 arquivos)
│   │   ├── repositories/                    # Interfaces de repositórios (14 arquivos)
│   │   ├── services/                        # Serviços de domínio (3 arquivos)
│   │   └── use-case/                        # Casos de uso (78 arquivos)
│   └── infra/
│       ├── app.module.ts                    # Módulo principal
│       ├── main.ts                          # Bootstrap da aplicação
│       ├── database/
│       │   ├── database.module.ts           # Módulo de banco
│       │   └── prisma/                      # Configuração Prisma (27 arquivos)
│       ├── DocumentGenerator/
│       │   ├── document-generator.module.ts # Módulo gerador de documentos
│       │   ├── generator/                   # Geradores (7 arquivos)
│       │   ├── pdf/                         # Componentes PDF (34 arquivos: 20 TTF, 14 TSX)
│       │   └── utils/                      # Utilitários PDF (8 arquivos)
│       ├── http/
│       │   ├── controllers/                 # Controllers (37 arquivos)
│       │   ├── dto/                         # DTOs (28 arquivos)
│       │   ├── http.module.ts               # Módulo HTTP
│       │   ├── pipes/                       # Pipes (1 arquivo)
│       │   ├── presenters/                  # Presenters (14 arquivos)
│       │   └── services/                    # Serviços HTTP (8 arquivos)
│       ├── messaging/
│       │   ├── messaging.module.ts          # Módulo de messaging
│       │   └── sqs/                         # AWS SQS (4 arquivos)
│       ├── notification/
│       │   └── notification.module.ts       # Módulo de notificações
│       └── services/                        # Serviços externos (4 arquivos)
├── prisma/
│   ├── schema.prisma                        # Schema do banco
│   ├── migrations/                          # Migrations (58 arquivos)
│   └── migrations.toml                      # Configuração migrations
├── test/                                    # Testes (9 arquivos)
├── k8s/                                     # Kubernetes
│   ├── deployment.yaml                      # Deployment
│   ├── service.yaml                         # Service
│   └── secret.yaml                          # Secret
├── docker-compose.yml                       # Orquestração
├── Dockerfile                               # Build produção
├── package.json                             # Dependências
├── tsconfig.json                            # Configuração TypeScript
├── tsconfig.build.json                      # Configuração build
├── nest-cli.json                            # Configuração NestJS
├── vitest.config.ts                         # Configuração testes
├── vitest-e2e.config.ts                     # Configuração testes E2E
└── README.md                                # Documentação

11. INTEGRAÇÕES E DEPENDÊNCIAS

Serviços externos

Mapbox (Geocoding de endereços), Dotcoding (Irradiação solar por cidade)

AWS SQS (Messaging assíncrono), Microserviços (Administrator, Contracts, Common)

PostgreSQL (Banco de dados principal)

Dependências principais

@nestjs/common/core, @nestjs/swagger, @nestjs/config, @prisma/client

@aws-sdk/client-sqs, @react-pdf/renderer, chart.js, pdf-lib

class-validator/transformer, axios, multer, compression, zod, vitest

12. INTEGRAÇÕES EXTERNAS

Mapbox

Geocoding de endereços para validação e preenchimento automático

Dotcoding

API de irradiação solar por cidade para cálculos de energia

AWS SQS

Messaging assíncrono para comunicação entre microserviços

Microserviços

Administrator, Contracts, Common para funcionalidades compartilhadas

PostgreSQL

Banco de dados principal com Prisma ORM

13. CONTROLE DE VERSÃO

• Repositório: Local/GitHub
• Versionamento semântico recomendado
• Docker multi-stage build
• Docker Compose para desenvolvimento
• Kubernetes para produção
• Prisma migrations versionadas
• Scripts organizados (build, test, migrate, deploy)
• Vitest para testes unitários e E2E

14. SEGURANÇA E ACESSO

• Multi-tenancy nativo com isolamento por tenant
• Headers obrigatórios (x-tenant-id, authorization)
• Validação rigorosa com class-validator
• Soft delete para auditoria
• CORS configurado
• Tratamento de erros centralizado
• Validação de CPF/CNPJ únicos
• Upload seguro de arquivos (limite 20MB)
• Compressão de respostas para performance

15. CONSIDERAÇÕES FINAIS

Microserviço Commercial robusto e bem estruturado em NestJS, seguindo Clean Architecture e DDD. Implementa gestão completa do módulo comercial com clientes, orçamentos, propostas, funil de vendas e unidades. Sistema avançado de geração de documentos PDF profissionais com cálculos automáticos de energia solar. Preparado para produção com multi-tenancy, integrações externas, testes automatizados e documentação completa. Arquitetura modular permite fácil manutenção e extensão das funcionalidades comerciais do ecossistema Aster/UVA. Sistema essencial para gestão comercial e geração de propostas fotovoltaicas.