microservice-common

1. OBJETIVO

Microserviço Common (NestJS) responsável por funcionalidades compartilhadas entre microserviços: gestão de workflows, atividades, arquivos, cache inteligente, messaging assíncrono e infraestrutura comum. Sistema robusto com multi-tenancy nativo, arquitetura hexagonal, integração completa com AWS S3/SQS e monitoramento de performance com métricas detalhadas.

2. ÚLTIMA REVISÃO

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

3. TECNOLOGIAS UTILIZADAS

Backend

Node.js, NestJS 10, TypeScript 5.1.3, Prisma 6.2.1, Swagger 8.1.0, class-validator, AWS SDK v3 (S3, SQS, S3-request-presigner), axios, buffer, Vitest 2.1.8

Frontend

Não aplicável (API pura)

Banco de Dados

PostgreSQL (Prisma ORM com multi-tenancy)

Ferramentas de Conexão e Infraestrutura

Docker (multi-stage), AWS S3 (URLs pré-assinadas), AWS SQS (4 handlers), PrismaService otimizado, 20 migrations, seeds automáticos, monitoramento de performance

4. FUNCIONALIDADES E DOMÍNIOS

• Workflows: Sistema de workflows com 6 workspaces (BUDGET, CONTRACT, PROJECT, PRODUCTION, WORK, INSPECTION)
• Atividades: Gestão de atividades com histórico de status e colaboradores
• Arquivos: Sistema de anexos compartilháveis e upload seguro via AWS S3
• Cache: Cache inteligente com TTL/LRU, estatísticas detalhadas e eviction automático
• Messaging: Messaging assíncrono via AWS SQS com 4 handlers especializados
• Multi-tenancy: Isolamento nativo por tenant via schema PostgreSQL
• Auditoria: Sistema completo de auditoria (created/updated/deletedAt)
• Performance: Monitoramento de slow queries e métricas de conexão
• Infraestrutura: Funcionalidades compartilhadas entre microserviços

5. ARQUITETURA FRONTEND

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

6. ARQUITETURA BACKEND

Controllers

21 controllers especializados: HealthCheck, Files (5 endpoints), Workflow (6), Activity (4), Attachment (2), WorkspaceStatus (2), Cache, ConnectionMetrics

Features

Arquitetura hexagonal com repositórios abstratos, Sistema de workflows com 6 workspaces, Gestão de atividades com histórico de status, Sistema de anexos compartilháveis, Upload seguro via AWS S3, Messaging assíncrono via AWS SQS, Cache inteligente com TTL/LRU, Multi-tenancy nativo por request

Caches

CacheService (memória com TTL/LRU avançado), QueryCacheService, Decorators (@QueryCacheable, @InvalidateQueryCache), HttpQueryCacheInterceptor, Estatísticas detalhadas

Repositories

Abstratos + implementações Prisma e in-memory (testes), 7 repositórios específicos, Multi-tenancy via PrismaService otimizado, TransactionService, Mappers

Entities

Workflow, Activity, Attachment, File, User, WorkspaceStatus, StatusHistory, Seeds, Sistema de colaboradores, Auditoria completa (created/updated/deletedAt)

Helper

ValidationPipe global, ErrorHandling, Headers decorator, Seeds automatizados por tenant, Swagger em /api, S3Uploader, SqsListenerService, Monitoramento de performance

7. ROTAS E ENDPOINTS

Base

/api (Swagger) + módulos específicos

Files

GET /files (filtros avançados), POST /files/generate-upload-url (10min), POST /files/register-upload, PATCH /files/:id, DELETE /files/:id

Workflows

GET/PUT /workflows/:workspace/:referenceId, POST/DELETE /workflows/:workspace/:referenceId/collaborators, PATCH /workflows/:workspace/:referenceId/owner/status

Activities

GET/POST /workflows/:workspace/:referenceId/activities, PUT/DELETE /workflows/:workspace/:referenceId/activities/:id

Attachments

POST/DELETE /workflows/:workspace/:referenceId/attachments, POST /workflows/:workspace/:referenceId/attachments/:id/share

Multi-tenancy

via headers x-tenant-id e x-user-id

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Principais

workflows (contractId, updatedBy, deletedBy), activities (reference, referenceId, updatedBy, deletedBy), attachments (deletedBy), files (context, subContext, tags, bannedSlugs), users (referenceId único), workspace_status (createdBy opcional), status_histories, seeds

Relacionamentos

workflows -> activities/attachments/status_histories, activities -> attachments/status_histories, files -> context/subContext, users -> múltiplas relações

Enums

WorkflowWorkspace (6 tipos), ActivityCreationMethod (AUTO/MANUAL)

9. CONFIGURAÇÃO E VARIÁVEIS

Ambiente

DATABASE_URL, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, WORKFLOW_QUEUE_URL, PORT

Performance

DATABASE_CONNECTION_POOL_SIZE, DATABASE_CONNECTION_TIMEOUT, DATABASE_QUERY_TIMEOUT, DATABASE_MAX_CONNECTIONS, DATABASE_SLOW_QUERY_THRESHOLD

Cache

TTL padrão 300s, máximo 10000 entradas, limpeza em lotes de 500, eviction LRU

10. 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/ (17 arquivos)
│   ├── decorators/
│   │   ├── class-validator/ (12 decorators de validação)
│   │   └── http/header.ts (decorator para multi-tenancy)
│   ├── filters/ (HttpExceptionFilter, ValidationErrorFilter)
│   └── validation-error-exception.ts
├── core/ (20 arquivos)
│   ├── cache/ (CacheService, QueryCacheService, decorators)
│   ├── database/transaction-service.ts
│   ├── entities/ (Entity base, UniqueEntityId)
│   ├── errors/ (8 tipos de erro customizados)
│   ├── types/optional.ts
│   └── utils/text-normalization.ts
├── domain/ (64 arquivos)
│   ├── entities/ (7 entidades de domínio)
│   ├── repositories/ (13 interfaces + 6 implementações in-memory)
│   ├── storage/uploader.ts (interface para upload)
│   └── use-cases/ (43 casos de uso)
├── infra/ (91 arquivos)
│   ├── app.module.ts (configuração principal com filtros globais)
│   ├── cache/cache.module.ts
│   ├── database/
│   │   ├── database.module.ts (configuração global Prisma)
│   │   └── prisma/
│   │       ├── prisma.service.ts (multi-tenancy otimizado com métricas)
│   │       ├── prisma-transaction.service.ts
│   │       ├── mappers/ (7 mappers)
│   │       ├── repositories/ (7 implementações Prisma)
│   │       └── seeds/ (seeds automatizados por tenant)
│   ├── files/files.module.ts, files.service.ts
│   ├── http/
│   │   ├── http.module.ts (configuração de controllers)
│   │   ├── controllers/ (21 controllers)
│   │   ├── dto/ (22 DTOs)
│   │   ├── presenters/ (9 presenters)
│   │   ├── services/ (4 serviços incluindo ms-administrator)
│   │   └── interceptors/http-query-cache.interceptor.ts
│   ├── messaging/
│   │   ├── messaging.module.ts (SqsModule)
│   │   └── sqs/
│   │       ├── sqs-listener.service.ts
│   │       ├── message-handler.registry.ts
│   │       └── listener/handlers/ (4 handlers especializados)
│   ├── storage/
│   │   ├── s3-uploader.ts (implementação AWS S3 com URLs pré-assinadas)
│   │   └── storage.module.ts
│   ├── tenant/tenant-context.ts
│   └── main.ts

prisma/
├── schema.prisma (definição de modelos e relacionamentos)
├── migrations/ (20 arquivos SQL de migração)
└── seeds/ (seeds automatizados)

test/ (8 arquivos de teste)
├── factories/ (5 factories para testes)
└── *.spec.ts (testes unitá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)

11. INTEGRAÇÕES E DEPENDÊNCIAS

Serviços externos

AWS S3 (armazenamento), AWS SQS (messaging), PostgreSQL (banco principal)

Dependências principais

@nestjs/common/core, @nestjs/swagger, @prisma/client, @aws-sdk/client-s3, @aws-sdk/client-sqs, @aws-sdk/s3-request-presigner, class-validator, axios, buffer, vitest

12. INTEGRAÇÕES EXTERNAS

AWS S3

Armazenamento seguro de arquivos com URLs pré-assinadas

AWS SQS

Messaging assíncrono com 4 handlers especializados para comunicação entre microserviços

PostgreSQL

Banco de dados principal com Prisma ORM, multi-tenancy por schema, monitoramento de performance

Swagger

Documentação automática da API em /api

13. CONTROLE DE VERSÃO

Repositório local/GitHub, versionamento semântico, Prisma migrations versionadas

14. SEGURANÇA E ACESSO

Multi-tenancy

Isolamento por tenant via x-tenant-id, schema PostgreSQL, conexões otimizadas

Validação

ValidationPipe global, class-validator, sanitização de dados

Upload

URLs pré-assinadas (10min), bannedSlugs, soft delete com remoção S3

Auditoria

Soft delete, auditoria completa, headers obrigatórios

15. CONSIDERAÇÕES FINAIS

Base robusta de funcionalidades compartilhadas com arquitetura hexagonal, multi-tenancy, gestão completa de workflows/atividades/arquivos. Preparado para escala com cache inteligente, messaging assíncrono e integração AWS. Principais diferenciais: Arquitetura hexagonal com repositórios abstratos, Multi-tenancy nativo com isolamento completo, Sistema de workflows flexível com 6 workspaces, Upload seguro via AWS S3 com URLs pré-assinadas, Messaging assíncrono via AWS SQS com 4 handlers, Cache inteligente com TTL/LRU e estatísticas detalhadas, Sistema de colaboradores com controle de permissões, Auditoria completa e soft delete, Documentação automática via Swagger, Testes isolados com repositórios in-memory, Integração completa com AWS, Monitoramento de performance com slow query detection, 20 migrations Prisma, 43 use cases, 21 controllers RESTful.