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 Products

Microserviço de produtos — NestJS/PostgreSQL

Índice

1. OBJETIVO

Microserviço Products (NestJS) responsável por gestão completa de produtos fotovoltaicos: painéis solares, inversores, estruturas, circuitos, kits geradores, componentes gerais, serviços e geradores completos. Sistema robusto com multi-tenancy, preços, taxas fiscais e relacionamentos complexos.

2. ÚLTIMA REVISÃO

3. TECNOLOGIAS UTILIZADAS

Backend
Node.js, NestJS 10, TypeScript 5.4.5, Prisma 5.15.0, Swagger 7.3.1, class-validator, cache-manager, Vitest 1.6.0 (testes), Husky + Commitlint
Banco de Dados
PostgreSQL (Prisma ORM com multi-tenancy)
Ferramentas de Conexão e Infraestrutura
Docker (multi-stage com Node.js 20), Kubernetes (deployment/service/secret/kustomization), PrismaClientManager para multi-tenancy por schema

4. FUNCIONALIDADES E DOMÍNIOS

Gestão de Produtos
18 tipos de produtos: painéis solares, inversores, estruturas, circuitos, kits geradores, componentes gerais, serviços e geradores completos
Sistema de Preços
Sistema de preços e margens de lucro integrado, Taxas fiscais (ICMS, PIS, COFINS, IPI)
Filtros e Busca
Filtros avançados por preço/potência/marca, Relacionamentos many-to-many complexos
Multi-tenancy
Multi-tenancy nativo por request, Isolamento de dados por tenant via PrismaClientManager, Header x-tenant-id obrigatório
Recursos Avançados
Upload de anexos por produto, Cache global via @nestjs/cache-manager, Auditoria completa (created/updated/deletedAt), Soft delete implementado, Sistema de ativação/desativação de produtos

5. ARQUITETURA FRONTEND

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

6. ARQUITETURA BACKEND

Controllers
18 controllers especializados: Product, SolarPanel, Inverter, Circuit, StringBox, Storage, Service, Structure, GeneralComponent, Kitgenerator, FullgeneratorV2, Category, Brand, Unit, BatteryType, StructureType, AcLeague
Features
Arquitetura hexagonal com repositórios abstratos, Sistema de preços e margens de lucro integrado, Taxas fiscais (ICMS, PIS, COFINS, IPI), Filtros avançados por preço/potência/marca, Relacionamentos many-to-many complexos, Multi-tenancy nativo por request, Upload de anexos por produto
Caches
Cache global via @nestjs/cache-manager
Repositories
Abstratos + implementações Prisma e in-memory (testes), 18 repositórios específicos por domínio, Multi-tenancy via PrismaClientManager
Entities
Product (base) + 10 tipos especializados (Panel, Inverter, Circuit, StringBox, Storage, Service, Structure, GeneralComponent, Kitgenerator, FullGenerator), Sistema de preços (ProductPrice) e taxas (ProductTax, ServiceTax), Relacionamentos: categories, structure_types, ac_leagues, attachments, Auditoria completa (created/updated/deletedAt)
Helper
ValidationPipe global, ErrorHandling, Headers decorator, Seeds automatizados, Swagger em /api, PrismaClientManager para isolamento de dados

7. ESTRUTURA DE DADOS, TABELAS E VIEWS

Principais
products (base), products_panel, products_inverter, products_circuit, products_string_box, products_storage, products_service, products_structure, products_general_components, products_kitgenerator, products_fullgenerator
Relacionamentos
products_kitgenerator_*, products_fullgenerator_*, products_components
Preços/Taxas
product_prices, product_taxes, products_service_taxes
Apoio
categories, structure_types, ac_leagues, attachments

8. ROTAS E ENDPOINTS

Base
/api (Swagger) + módulos específicos, Porta: 3001
Padrão CRUD
GET /filter, POST /, PUT /:id
Especiais
PATCH /product/:id/toggle-active, DELETE /product/:id
Multi-tenancy
via header x-tenant-id

9. TREEVIEW DA ARQUITETURA

src/
├── main.ts (bootstrap da aplicação, Swagger, CORS, ValidationPipe)
├── app.module.ts (módulo principal, imports de todos os módulos)
├── common/ (34 arquivos)
│   ├── decorators/http/header.ts (decorator para multi-tenancy)
│   ├── error-handling/ (ErrorResponse, ValidationErrorException)
│   └── filters/ (HttpExceptionFilter, ValidationErrorFilter)
├── database/ (3 arquivos)
│   ├── database.module.ts (configuração global Prisma)
│   └── prisma/prisma-client-manager.ts (isolamento por tenant)
├── modules/ (300 arquivos organizados por domínio)
│   ├── product/ (módulo base de produtos)
│   ├── solar-panel/ (painéis solares)
│   ├── inverter/ (inversores/otimizadores)
│   ├── circuit/ (circuitos elétricos)
│   ├── string-box/ (caixas de junção)
│   ├── storage/ (sistemas de armazenamento)
│   ├── service/ (serviços)
│   ├── structure/ (estruturas de fixação)
│   ├── general-component/ (componentes gerais)
│   ├── kitgenerator/ (kits geradores)
│   ├── fullgenerator/ (geradores completos - legado)
│   ├── fullgenerator-v2/ (geradores completos - atual)
│   ├── category/ (categorias)
│   ├── brand/ (marcas)
│   ├── unit/ (unidades de medida)
│   ├── battery-type/ (tipos de bateria)
│   ├── structure-type/ (tipos de estrutura)
│   └── ac-league/ (ligas CA para inversores)
├── repositories/ (53 arquivos)
│   ├── abstracts/ (interfaces de repositórios)
│   ├── prisma/ (implementações Prisma - 18 arquivos)
│   └── in-memory/ (implementações para testes - 17 arquivos)
└── utils/ (1 arquivo de utilitários)

Estrutura por Módulo (padrão):
module-name/
├── dto/ (Data Transfer Objects para requests/responses)
├── entities/ (entidades de domínio)
├── use-cases/ (casos de uso/regras de negócio)
├── module-name.controller.ts (endpoints REST)
├── module-name.module.ts (configuração do módulo)
└── __tests__/ (testes unitários e integração)

prisma/
├── schema.prisma (definição de modelos e relacionamentos)
├── migrations/ (77 arquivos SQL de migração)
└── seed.toml (configuração de seeds)

k8s/
├── deployment.yaml (configuração do pod)
├── service.yaml (exposição do serviço)
├── secret.yaml (variáveis sensíveis)
└── kustomization.yaml (configuração Kustomize)

10. CONFIGURAÇÃO E VARIÁVEIS

Variáveis de Ambiente
DATABASE_URL, PORT (padrão: 3001), NODE_ENV
Configurações
Multi-tenancy via x-tenant-id obrigatório, Cache global, Swagger em /api, CORS configurado, Soft delete

11. CONTROLE DE VERSÃO

12. SEGURANÇA E ACESSO

13. TESTES E QUALIDADE

14. DEPLOYMENT E INFRAESTRUTURA

15. INTEGRAÇÕES E DEPENDÊNCIAS

Dependências Principais
@nestjs/core, @nestjs/common, @prisma/client, @nestjs/swagger, class-validator, @nestjs/cache-manager, @nestjs/config
Dependências de Desenvolvimento
@nestjs/testing, vitest, @commitlint/cli, husky, typescript, eslint, prettier
Banco de Dados
PostgreSQL com Prisma ORM, Multi-tenancy por schema, Migrations automáticas

16. INTEGRAÇÕES EXTERNAS

Não aplicável - API pura sem integrações externas documentadas. Preparado para integração com outros microserviços via HTTP.

17. CONSIDERAÇÕES FINAIS

Base robusta de produtos fotovoltaicos com arquitetura modular, multi-tenancy, relacionamentos complexos e sistema completo de preços/taxas. Preparado para escala com testes, cache e deployment Kubernetes.

Principais diferenciais:

Retornar para home