Documentação técnica • Autor: Leonardo Norbiato - Equipe de Engenharia
Cliente: Aster Technology / UVA Última Atualização: 15/09/2025 Autores: Leonardo Norbiato - Equipe de Engenharia

Microservice Financial

Microserviço financeiro — NestJS/PostgreSQL/AWS

Índice

1. OBJETIVO

Microserviço Financial (NestJS) responsável por gestão completa do módulo financeiro: contas, faturas, transações, categorias, clientes, fornecedores e colaboradores. Sistema robusto com multi-tenancy, integração AWS SQS, Firebase Admin e arquitetura clean com padrões DDD.

2. ÚLTIMA REVISÃO

3. TECNOLOGIAS UTILIZADAS

Backend
Node.js 20, NestJS 10.4.13, TypeScript 5.4.5, Prisma 6.0.0, Swagger 8.1.0, class-validator, AWS SQS, Firebase Admin, Vitest 2.1.5 (testes unitários e E2E)
Banco de Dados
PostgreSQL (Prisma ORM com multi-tenancy)
Ferramentas de Conexão e Infraestrutura
Docker Compose (PostgreSQL local), AWS SQS messaging, Firebase Admin para autenticação

4. FUNCIONALIDADES E DOMÍNIOS

Multi-tenancy
Multi-tenancy nativo com middleware de isolamento por tenant, Header x-tenant-id obrigatório, Isolamento total de dados por tenant
Gestão Financeira
Sistema completo de contas a pagar/receber com hierarquia, Transações com descontos/juros/taxas, Categorias hierárquicas, Sistema de totais e relatórios financeiros
Gestão de Pessoas
Gestão completa de colaboradores (PF/PJ) com dados pessoais e profissionais, Clientes e fornecedores integrados, Endereços e contatos múltiplos, Soft delete e restore
Integrações
Integração AWS SQS para eventos assíncronos, Firebase Admin para autenticação, Sistema de eventos de domínio

5. ARQUITETURA FRONTEND

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

6. ARQUITETURA BACKEND

Arquitetura
Clean Architecture com Domain-Driven Design (DDD)
Controllers
6 controllers especializados: Accounts, Bills, Transactions, Categories, Collaborator, Tenant
Domain Layer
8 services com regras de negócio, 7 interfaces abstratas, 4 factories, Builders, DTOs de domínio
Infrastructure
12 implementações Prisma, 13 arquivos AWS SQS, Firebase Admin integration
Features
Multi-tenancy nativo, Sistema completo de gestão financeira, Categorias hierárquicas, Gestão de colaboradores, Integração AWS SQS, Soft delete e restore
Entities
Account (contas bancárias e caixas), Bill (faturas com hierarquia), Transaction (transações financeiras), Category (categorias hierárquicas), Collaborator (dados completos PF/PJ), Client/Supplier (integração)
Helper
TenantMiddleware, HttpExceptionFilter, ValidationPipe, Messaging com AWS SQS, Swagger automático em /api

7. ROTAS E ENDPOINTS

Base
/api (Swagger) + módulos específicos
Accounts
CRUD completo com filtros (name, status, isBankAccount, unitId) e paginação
Bills
CRUD + hierarquia + totais + soft delete/restore, Filtros avançados (search, accountId, categoryId, clientId, type, status, date, contractId, unitId)
Transactions
CRUD + create-with-bill + totals + restore, Filtros (amount, date, paymentMethod, accountId, billId, type, unitId, search, categoryId)
Categories
CRUD com hierarquia, Filtros (name, type) e validação canBeDeleted
Collaborators
CRUD completo + toggle-status, Filtros (name, status) e paginação
Tenants
POST /tenants para criação de tenant
Multi-tenancy
Header x-tenant-id obrigatório em todas as rotas (exceto /tenants)

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Principais
Account, Bill, Transaction, Category, Collaborator, CollaboratorAddress, CollaboratorContact, Client, Address, Supplier, Seeds
Enums
TransactionType (income/expense), BillStatus (pending/partially_paid/paid/canceled), BillType (payable/receivable), PersonType, MaritalStatus, Gender, TaxRegime, EmploymentType/Status, AddressType, ContactType, ClientType, SupplierType/Category
Relacionamentos
Hierarquia de Bills (pai/filho), Categorias hierárquicas, Colaboradores com endereços/contatos múltiplos, Clientes com endereços e dados do responsável

9. CONFIGURAÇÃO E VARIÁVEIS

Variáveis de Ambiente
DATABASE_URL, PORT (padrão: 3000), NODE_ENV
Docker
Docker Compose com PostgreSQL, Dockerfile multi-stage, Rede 'aster', Volume persistente
Desenvolvimento
ts-node-dev para hot reload, Prisma Studio, Vitest, ESLint + Prettier

10. TREEVIEW DA ARQUITETURA

src/
├── app.module.ts (módulo principal, multi-tenancy)
├── app.controller.ts/.service.ts (health check)
├── common/ (5 arquivos)
│   ├── decorators/http/header.ts (decorators para headers)
│   ├── exceptions/http-exception.filter.ts (tratamento de erros)
│   ├── middleware/tenant.middleware.ts (isolamento multi-tenant)
│   ├── providers/tenant.provider.ts (provider de tenant)
│   └── utils/database.utils.ts (utilitários de banco)
├── domain/ (33 arquivos - Clean Architecture)
│   ├── entities/ (Account, Bill, Transaction, Category, Collaborator)
│   ├── services/ (8 services com regras de negócio)
│   ├── repositories/ (7 interfaces abstratas)
│   ├── factories/ (4 factories para criação de entidades)
│   ├── builders/ (builders para construção complexa)
│   ├── dtos/ (4 DTOs de domínio)
│   └── interfaces/ (2 interfaces de contratos)
├── presentation/ (23 arquivos - Camada de apresentação)
│   ├── controllers/ (6 controllers especializados)
│   ├── dtos/ (7 DTOs para requests/responses)
│   └── modules/ (10 módulos NestJS)
├── infra/ (27 arquivos - Infraestrutura)
│   ├── database/
│   │   ├── prisma/prisma.service.ts (configuração Prisma)
│   │   └── repositories/ (12 implementações Prisma)
│   ├── messaging/ (13 arquivos)
│   │   ├── messaging.module.ts (configuração SQS)
│   │   └── sqs/ (implementações AWS SQS)
│   └── main.ts (bootstrap da aplicação)
└── test/ (2 arquivos - configuração de testes)

prisma/
├── schema.prisma (modelos e relacionamentos)
├── migrations/ (23 arquivos - 22 migrations SQL)
└── prisma.service.ts (serviço Prisma)

Configurações:
├── docker-compose.yml (PostgreSQL + app)
├── Dockerfile (multi-stage build)
├── vitest.config.ts (testes unitários)
├── vitest.config.e2e.ts (testes E2E)
├── package.json (dependências e scripts)
└── tsconfig*.json (configuração TypeScript)

11. INTEGRAÇÕES E DEPENDÊNCIAS

Dependências principais
Node.js 20, NestJS 10.4.13, TypeScript 5.4.5, Prisma 6.0.0, Swagger 8.1.0, class-validator, AWS SQS, Firebase Admin, Vitest 2.1.5
Banco de Dados
PostgreSQL (Prisma ORM com multi-tenancy), 23 migrations, Suporte a soft delete
Ferramentas
Docker Compose, AWS SQS messaging, Firebase Admin, ESLint + Prettier

12. INTEGRAÇÕES EXTERNAS

AWS SQS
Eventos assíncronos para comunicação entre microserviços, Handlers para client/supplier events, Sistema de messaging robusto
Firebase Admin
Autenticação e autorização, Integração com sistema de usuários, Validação de tokens JWT
Sistema de Eventos
Eventos de domínio para operações financeiras, Processamento assíncrono, Integração com ecossistema

13. CONTROLE DE VERSÃO

14. SEGURANÇA E ACESSO

15. CONSIDERAÇÕES FINAIS

Microserviço financeiro robusto com arquitetura clean, multi-tenancy nativo e integração completa com AWS e Firebase. Implementa padrões DDD com separação clara de responsabilidades entre domínio, apresentação e infraestrutura.

Principais diferenciais:

Retornar para home