Microservice Contracts

1. OBJETIVO DO REPOSITÓRIO

Este documento consolida as informações técnicas e de arquitetura do projeto "microservice-contracts", um microsserviço desenvolvido em NestJS que gerencia contratos, documentos, assinaturas digitais e todo o ciclo de vida de projetos de energia solar. O serviço implementa Clean Architecture com Domain-Driven Design, integrando com sistemas de assinatura digital (ZapSign), messaging (AWS SQS) e outros microsserviços do ecossistema Aster/UVA. O microsserviço é responsável por gerenciar desde a criação de contratos até sua finalização, incluindo gestão de documentos, assinaturas digitais, controle de etapas, garantias e integração com todo o fluxo de trabalho de projetos solares.

2. ÚLTIMA REVISÃO

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

3. TECNOLOGIAS UTILIZADAS

Backend:

Node.js com NestJS (framework), TypeScript, Prisma ORM, PostgreSQL, AWS SQS (messaging), ZapSign API (assinatura digital), React PDF (@react-pdf/renderer), PDF-lib, Swagger/OpenAPI, Scalar API Reference, Vitest (testes), Docker (containerização)

Frontend:

React (para geração de PDFs), Não possui interface web própria

Banco de Dados:

PostgreSQL com Prisma ORM, Migrations automatizadas, Relacionamentos complexos entre entidades

Ferramentas de Conexão e Infraestrutura:

Docker Compose (desenvolvimento e produção), AWS SQS para messaging assíncrono, ZapSign API para assinatura digital, Integração com outros microsserviços (Admin, Facilities)

4. FUNCIONALIDADES E DOMÍNIOS

O microsserviço gerencia os seguintes domínios principais:

Domínios de Negócio:

Contract: Gestão completa de contratos de energia solar

Document: Gestão de documentos e assinaturas digitais

Project: Gestão de projetos de instalação

Production: Gestão de produção de equipamentos

Construction: Gestão de construção e instalação

Inspection: Gestão de inspeções técnicas

PostSale: Gestão pós-venda e suporte

Stage: Controle de etapas e workflow

Warranty: Gestão de garantias (painéis, inversores, mão de obra)

Funcionalidades Principais:

Criação e edição de contratos com validações de negócio

Geração e assinatura digital de documentos via ZapSign

Controle de etapas com notificações automáticas

Gestão de garantias com períodos e datas de aquisição

Integração com sistemas de messaging (AWS SQS)

Webhooks para eventos externos

Relatórios e consultas com filtros avançados

5. ARQUITETURA FRONTEND

O microsserviço não possui interface web própria, mas utiliza:

Geração de PDFs:

React (@react-pdf/renderer) para templates dinâmicos

PDF-lib para manipulação de documentos

Templates personalizáveis para contratos

Geração server-side de documentos

API Documentation:

Swagger/OpenAPI para documentação da API

Scalar API Reference para interface interativa

Endpoint /api para acesso à documentação

6. ARQUITETURA BACKEND

Clean Architecture com Domain-Driven Design:

Controllers/Endpoints:

Contract Management: CRUD completo de contratos

Document Management: Upload, download, assinatura de documentos

Stage Management: Controle de etapas do projeto

Warranty Management: Gestão de garantias

Integration: Webhooks e eventos externos

Módulos Principais:

Contract: Gestão de contratos e documentos

Project: Gestão de projetos

Production: Gestão de produção

Construction: Gestão de construção

Inspection: Gestão de inspeções

PostSale: Gestão pós-venda

Stage: Controle de etapas

Use Cases (Domain):

CreateContract, EditContract, GetContract, FetchContracts

SignContractDigital, HandleSignatureWebhook

AddDocument, DeleteDocument, MarkDocumentAsSigned

UpdateContractStage, FinishContract

TriggerContractStage, ValidateWarrantiesBeforeFinish

Repositories:

Prisma-based repositories para cada entidade

Mappers para conversão entre Domain e Database

Soft delete implementado

Entities/Domain Models:

Contract, Document, DocumentSigner, Attachment

Warranty, PanelWarranty, InverterWarranty, AdditionalWarranty

Project, Production, Construction, Inspection, PostSale

Stage, Installment, Additive

Services:

ZapSignService: Integração com assinatura digital

EventEmitterService: Emissão de eventos de domínio

StageNotificationService: Notificações de etapas

FacilitiesService: Integração com serviços externos

7. ROTAS E ENDPOINTS

Contract Management:

Document Management:

Stage Management:

Warranty Management:

Webhooks:

Attachments:

API Documentation:

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Entidades Principais:

Contract:

Informações básicas: título, preço, observações. Relacionamentos: cliente, vendedor, gerente, unidade. Datas: criação, emissão, finalização. Pagamento: forma, parcelas, comissões. Etapas: estágio atual, margens, descontos

Document:

Tipos: CONTRACT, ATTACHMENT. Status: pending, awaiting_signature, signed, rejected. Integração ZapSign: ID, URL de assinatura, token. Conteúdo JSON para templates dinâmicos

Warranty:

Garantia de mão de obra. Garantias específicas: painéis, inversores, adicionais. Períodos e unidades (dias, meses, anos). Datas de aquisição

Stage:

Controle de etapas do projeto. Tipos: project, inspection, production, construction, post_sales, contract. Status: not_started, in_progress, blocked, completed

Project/Production/Construction/Inspection/PostSale:

Entidades específicas para cada fase. Relacionamento com Contract. Controle de estágios individuais. Responsáveis e datas específicas

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), ZAPSIGN_API_KEY (Assinatura digital)

Configurações Docker

PostgreSQL: porta 5432, database "contracts"

App: porta 3000, desenvolvimento com hot reload

Volumes para persistência de dados

10. TREEVIEW DA ARQUITETURA

microservice-contracts/
├── src/
│   ├── app.module.ts                 # Módulo principal da aplicação
│   ├── main.ts                       # Bootstrap da aplicação
│   ├── core/                         # Core domain (DDD)
│   │   ├── entities/                 # Entidades base (Entity, AggregateRoot)
│   │   ├── errors/                   # Erros de domínio
│   │   ├── evnets/                   # Sistema de eventos
│   │   └── types/                    # Tipos compartilhados
│   ├── modules/                      # Módulos de domínio
│   │   ├── contract/                 # Módulo de contratos
│   │   │   ├── domain/               # Regras de negócio
│   │   │   │   ├── entities/         # Entidades de contrato
│   │   │   │   ├── use-case/         # Casos de uso
│   │   │   │   └── services/         # Serviços de domínio
│   │   │   └── infra/                # Infraestrutura
│   │   │       ├── http/             # Controllers, DTOs, Presenters
│   │   │       ├── database/         # Repositories, Mappers
│   │   │       ├── messaging/        # SQS integration
│   │   │       ├── pdf/              # Geração de PDFs
│   │   │       └── zap-sign/         # Integração ZapSign
│   │   ├── project/                  # Módulo de projetos
│   │   ├── production/               # Módulo de produção
│   │   ├── construction/             # Módulo de construção
│   │   ├── inspection/               # Módulo de inspeção
│   │   ├── post-sale/                # Módulo pós-venda
│   │   └── stage/                    # Módulo de etapas
│   └── shared/                       # Código compartilhado
│       ├── domain/                   # Enums e tipos compartilhados
│       ├── infra/                    # Infraestrutura compartilhada
│       ├── services/                 # Serviços compartilhados
│       └── utils/                    # Utilitários
├── prisma/                           # Schema e migrations
│   ├── schema.prisma                 # Schema do banco
│   └── migrations/                   # Migrations do banco
├── test/                             # Testes E2E
├── docker-compose.yml                # Ambiente de desenvolvimento
├── Dockerfile                        # Container de produção
├── package.json                      # Dependências e scripts
└── README.md                         # Documentação básica

9. CONFIGURAÇÃO E VARIÁVEIS

Variáveis de Ambiente:

DATABASE_URL: String de conexão PostgreSQL

PORT: Porta da aplicação (padrão: 3000)

NODE_ENV: Ambiente de execução (development/production)

Configurações Docker:

PostgreSQL 15 com volume persistente

Rede compartilhada (aster-network)

Porta 5432 para banco de dados

Porta 3000 para aplicação

Configurações de Desenvolvimento:

Hot reload com webpack

Migrations automáticas do Prisma

Volume mounting para desenvolvimento

Configurações de Produção:

Build otimizado com webpack

Container isolado

Health checks configurados

11. INTEGRAÇÕES E DEPENDÊNCIAS

Dependências Principais:

@nestjs/core, @nestjs/common, @nestjs/platform-express

@prisma/client, prisma

@aws-sdk/client-sqs

@react-pdf/renderer, pdf-lib

@nestjs/swagger, @scalar/nestjs-api-reference

class-validator, class-transformer

axios, reflect-metadata, rxjs

Dependências de Desenvolvimento:

@nestjs/cli, @nestjs/testing

@types/node, typescript

vitest, @vitest/ui, @vitest/coverage-v8

eslint, prettier

webpack, ts-loader

Integrações Internas:

PrismaModule: Acesso ao banco de dados

SqsModule: Messaging assíncrono

FacilitiesModule: Serviços de infraestrutura

AdminModule: Serviços administrativos

12. INTEGRAÇÕES EXTERNAS

ZapSign API:

Criação de documentos para assinatura, Webhook para eventos de assinatura, Consulta de status e signatários, Suporte a CPF/CNPJ

AWS SQS:

Listener para eventos de propostas (abertas/fechadas), Publisher para eventos financeiros e comuns, Handlers específicos para cada tipo de evento

Facilities Service:

Integração com serviços de infraestrutura, Comunicação HTTP com outros microsserviços

Admin Service:

Integração com serviços administrativos, Validações e permissões

13. CONTROLE DE VERSÃO

Repositório:

GitHub

Versionamento:

Semantic versioning

CI/CD:

Docker-based deployment

Ambiente:

Docker Compose para desenvolvimento, Container Docker com PostgreSQL para produção

Scripts Disponíveis:

• build: Compilação do projeto
• start:dev: Desenvolvimento com hot reload
• test: Testes unitários
• test:e2e: Testes end-to-end
• prisma:generate: Geração do cliente Prisma
• prisma:migrate: Aplicação de migrations

14. SEGURANÇA E ACESSO

• Validação de dados com class-validator
• Middleware de autenticação (ZapSign webhook)
• CORS configurado para múltiplas origens
• Headers customizados (x-tenant-id)
• Soft delete em todas as entidades
• Validações de domínio nos use cases
• Multi-tenancy com isolamento por tenant
• Autenticação via JWT tokens
• Rate limiting e proteção contra ataques

15. CONSIDERAÇÕES FINAIS

O microservice-contracts é um microsserviço robusto e bem estruturado que implementa Clean Architecture e Domain-Driven Design. Ele gerencia todo o ciclo de vida de contratos de energia solar, desde a criação até a finalização, incluindo gestão de documentos, assinaturas digitais e controle de etapas.

Principais pontos fortes:

• Arquitetura limpa e bem organizada
• Integração robusta com serviços externos
• Controle completo do ciclo de vida de contratos
• Sistema de eventos e messaging assíncrono
• Documentação API completa
• Testes E2E abrangentes
• Geração dinâmica de PDFs

O microsserviço demonstra maturidade arquitetural e está bem preparado para escalar com o crescimento do negócio, oferecendo uma base sólida para o gerenciamento de contratos de energia solar.