microservice-inventory

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

Índice

1. Objetivo
2. Última Revisão
3. Tecnologias Utilizadas
4. Funcionalidades e Domínios
5. Arquitetura Frontend
6. Arquitetura Backend
7. Rotas e Endpoints
8. Estrutura de dados, Tabelas e Views
9. Configuração e Variáveis
10. Treeview da Arquitetura
11. Integrações e Dependências
12. Integrações externas
13. Controle de Versão
14. Segurança e Acesso
15. Considerações Finais

1. OBJETIVO DO REPOSITÓRIO

Este documento consolida as informações técnicas e de arquitetura do projeto "microservice-inventory", um microsserviço desenvolvido em NestJS para gestão de fornecedores (suppliers) do ecossistema Aster/UVA. O serviço implementa operações CRUD completas, integração com mensageria via AWS SQS e persistência de dados via Prisma/PostgreSQL. O objetivo principal é fornecer uma API robusta para gerenciamento de fornecedores com validações específicas para pessoa física (PF) e pessoa jurídica (PJ), incluindo dados bancários, endereçamento e categorização.

2. ÚLTIMA REVISÃO

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

3. TECNOLOGIAS UTILIZADAS

Backend: Node.js, NestJS 10.0.0, TypeScript 5.4.5, Prisma 5.15.0 (ORM), PostgreSQL (banco de dados), AWS SDK SQS 3.699.0 (mensageria), Swagger/OpenAPI 7.3.1 (documentação), Class Validator/Transformer (validação), Vitest (testes), Husky (git hooks), Commitlint (padronização de commits), Faker.js (dados de teste)
Frontend: Não aplicável (API pura)
Banco de Dados: PostgreSQL (via Prisma ORM), Migrations automáticas via Prisma, Schema com enums para tipos e categorias
Ferramentas de Conexão e Infraestrutura: Docker Compose (desenvolvimento local), AWS SQS (mensageria assíncrona), Prisma Client Manager (gerenciamento de conexões), Cache Manager (NestJS)

4. FUNCIONALIDADES E DOMÍNIOS

Gestão de Fornecedores: Criação com validação de duplicatas por documento, Listagem com filtros (busca textual, categoria, status), Busca individual por ID, Atualização de dados, Exclusão lógica (soft delete), Bloqueio/desbloqueio de fornecedores
Validações Específicas: PF: RG obrigatório, data nascimento; PJ: Contribuinte obrigatório (1,2,9), inscrição estadual condicional; Validação de email, telefone, documentos; Campos obrigatórios por tipo de fornecedor
Integração com Mensageria: Eventos publicados via AWS SQS: SUPPLIER_CREATED, SUPPLIER_UPDATED, SUPPLIER_DELETED, SUPPLIER_BLOCKED, SUPPLIER_UNBLOCKED
Paginação e Ordenação: Paginação configurável (page, limit), Ordenação por múltiplos campos, Ordenação especial por cidade+estado, Contagem total de registros

5. ARQUITETURA FRONTEND

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

6. ARQUITETURA BACKEND

Controllers: SupplierController: Endpoints REST para gestão de fornecedores - GET /suppliers (lista com filtros), GET /suppliers/:id (busca por ID), POST /suppliers (criação), PUT /suppliers/:id (atualização), DELETE /suppliers/:id (soft delete), PATCH /suppliers/toggle-block/:id (bloqueio/desbloqueio)
Use Cases: CreateSupplierUseCase (criação com validação de duplicatas), FindAllSuppliersUseCase (listagem com filtros), FindOneSupplierUseCase (busca individual), UpdateSupplierUseCase (atualização), DeleteSupplierUseCase (exclusão lógica), ToggleBlockSupplierUseCase (bloqueio/desbloqueio)
Repositories: SupplierRepository (abstract), PrismaSupplierRepository (implementação Prisma/PostgreSQL), InMemorySupplierRepository (testes)
Entities/DTOs: SupplierEntity (entidade principal), CreateSupplierDto (criação com validações PF/PJ), UpdateSupplierDto (atualização), FindAllSuppliersQuery (query parameters)
Enums: SupplierType (pf/pj), SupplierCategory (product/supplies), SupplierSortBy (campos ordenação)
Infraestrutura: SqsModule (mensageria AWS SQS), SupplierSqsPublisherService (publicação eventos), DatabaseModule (configuração Prisma), PrismaClientManager (gerenciamento conexões)

7. ROTAS E ENDPOINTS

Base URL: /suppliers (Headers obrigatórios: x-tenant-id)
GET /suppliers: Lista fornecedores com filtros - Query params: search, category, status, page, limit, orderBy, order - Response: Lista paginada de fornecedores
GET /suppliers/:id: Busca fornecedor por ID - Response: Dados completos do fornecedor
POST /suppliers: Cria novo fornecedor - Body: CreateSupplierDto - Response: 204 No Content
PUT /suppliers/:id: Atualiza fornecedor - Body: UpdateSupplierDto - Response: 204 No Content
DELETE /suppliers/:id: Remove fornecedor (soft delete) - Response: 204 No Content
PATCH /suppliers/toggle-block/:id: Bloqueia/desbloqueia fornecedor - Response: 204 No Content
Documentação Swagger: /api

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Tabela: suppliers: Campos principais: id (UUID), type (pf/pj), category (product/supplies), document (CPF/CNPJ), name, email, phone, photo
Dados pessoais/empresariais: stateRegistration (inscrição estadual), birthDate (PF), rg (PF), openingDate (PJ), taxpayer (PJ: 1,2,9)
Dados bancários: bankName, bankAgency, bankAccount, bankPix, bankIspb, bankCode, bankFullName
Endereço: cep, address, homeNumber (obrigatórios), complement (opcional), neighborhood, city, state (obrigatórios)
Controle temporal: createdAt (criação), blockedAt (bloqueio), deletedAt (exclusão lógica)

9. CONFIGURAÇÃO E VARIÁVEIS

Variáveis de Ambiente: DATABASE_URL (String de conexão PostgreSQL), SUPPLIER_CREATED_QUEUE_URL (URL da fila AWS SQS), PORT (Porta da aplicação - padrão: 3001)
Docker Compose: PostgreSQL: porta 5432, Usuário: postgres, Senha: 12345678, Database: postgres
Configurações NestJS: CORS habilitado para todas as origens, Validação global com ValidationPipe, Swagger configurado em /api, Cache global habilitado

10. TREEVIEW DA ARQUITETURA

microservice-inventory/
├── src/
│   ├── app.module.ts                 # Módulo principal da aplicação
│   ├── main.ts                       # Bootstrap da aplicação
│   ├── common/                       # Utilitários compartilhados
│   │   ├── decorators/               # Decorators customizados
│   │   │   └── class-validator/      # Validações específicas
│   │   ├── error-handling/           # Tratamento de erros
│   │   └── utils/                    # Funções utilitárias
│   ├── database/                     # Configuração do banco
│   │   ├── database.module.ts       # Módulo do banco
│   │   └── prisma-client-manager.ts  # Gerenciador Prisma
│   ├── infra/                        # Infraestrutura
│   │   └── messaging/               # Mensageria AWS SQS
│   │       ├── adapters/            # Adaptadores de eventos
│   │       ├── publisher/           # Serviços de publicação
│   │       └── messaging.module.ts  # Módulo de mensageria
│   ├── modules/                      # Módulos de negócio
│   │   └── supplier/                # Módulo de fornecedores
│   │       ├── dto/                 # Data Transfer Objects
│   │       ├── entities/            # Entidades de domínio
│   │       ├── enum/                # Enumeradores
│   │       ├── ports/               # Interfaces/contratos
│   │       ├── use-cases/           # Casos de uso
│   │       │   └── unit-tests/      # Testes unitários
│   │       ├── supplier.controller.ts # Controller REST
│   │       └── supplier.module.ts   # Módulo do fornecedor
│   └── repositories/                 # Camada de persistência
│       ├── in-memory/               # Repositório em memória
│       ├── prisma/                  # Repositório Prisma
│       └── supplier.abstract.ts     # Interface abstrata
├── prisma/                          # Configuração Prisma
│   ├── migrations/                  # Migrations do banco
│   └── schema.prisma               # Schema do banco
├── docker-compose.yml              # Ambiente de desenvolvimento
├── package.json                    # Dependências e scripts
├── tsconfig.json                   # Configuração TypeScript
└── README.md                       # Documentação do projeto

11. INTEGRAÇÕES E DEPENDÊNCIAS

Dependências principais: Node.js, NestJS, TypeScript, Prisma, PostgreSQL, AWS SDK SQS, Swagger/OpenAPI, Class Validator/Transformer, Vitest, Husky, Commitlint, Faker.js
Banco de Dados: PostgreSQL (via Prisma ORM), Migrations automáticas via Prisma
Ferramentas: Docker Compose, AWS SQS, Prisma Client Manager

12. INTEGRAÇÕES EXTERNAS

AWS SQS: Queue: SUPPLIER_CREATED_QUEUE_URL, Eventos: Criação, atualização, exclusão, bloqueio de fornecedores, Formato: JSON com tenant-id
PostgreSQL: Conexão via Prisma ORM, Migrations automáticas, Pool de conexões gerenciado

13. CONTROLE DE VERSÃO

Repositório: Local/GitHub
GitHub Actions configuradas
Workflows para ECS e EC2
Validação de pull requests
Commitlint para padronização de commits
Husky para git hooks

14. SEGURANÇA E ACESSO

Headers obrigatórios: x-tenant-id
Validação de dados com class-validator
Soft delete para exclusão lógica
Documentação Swagger com autenticação
CORS configurado para todas as origens
Validação global com ValidationPipe

15. CONSIDERAÇÕES FINAIS

Este microsserviço implementa uma arquitetura limpa e bem estruturada para gestão de fornecedores, com separação clara de responsabilidades, validações robustas e integração com sistemas externos via mensageria. A documentação Swagger facilita o consumo da API e os testes garantem a qualidade do código.

Principais características:

Arquitetura limpa com separação de responsabilidades
Validações robustas para PF/PJ
Integração com AWS SQS para mensageria
Documentação automática com Swagger
Testes unitários com Vitest
Soft delete e controle de bloqueio
Paginação e ordenação avançadas

Retornar para home