Arquitetura do Backend

src/
├── main.ts                  # Bootstrap — CORS, ValidationPipe, Swagger, porta
├── app.module.ts            # Módulo raiz — registra todos os imports
├── app.controller.ts        # Health check
│
├── auth/                    # Autenticação (Passport, JWT, estratégias)
│   ├── strategies/          #   LocalStrategy, JwtStrategy
│   ├── guards/              #   JwtAuthGuard
│   ├── session.service.ts   #   Refresh tokens (Redis)
│   └── auth.service.ts      #   Login, logout, refresh
│
├── common/                  # Infraestrutura compartilhada
│   ├── tenancy/             #   ⭐ Multi-tenancy (middleware + subscriber)
│   ├── base-entity/         #   TenantBaseEntity (herança)
│   ├── guards/              #   Filtros de exceção
│   ├── decorators/          #   @CurrentUser, etc.
│   ├── interceptors/        #   Logging, transformação
│   ├── mail/                #   Templates React Email + envio via Resend
│   ├── outbox/              #   Padrão Outbox (eventos assíncronos)
│   ├── queues/              #   Registro global de filas BullMQ
│   ├── redis/               #   RedisCustomModule (ioredis)
│   └── transformers/        #   BigInt, decimais
│
├── catalog/                 # PIM — Gestão de produtos (★ módulo mais complexo)
│   ├── entities/            #   Product, Inventory, InventoryEntry, Kit…
│   ├── services/            #   CQRS: CommandService + QueryService
│   ├── controllers/         #   Endpoints REST
│   ├── processors/          #   Jobs BullMQ do catálogo
│   ├── repositories/        #   Queries especializadas
│   ├── dto/                 #   Create, Update, Bulk DTOs
│   └── types/               #   Enums, interfaces
│
├── integrations/            # Conectores de marketplace
│   ├── adapters/            #   MeliAdapter, ShopeeAdapter
│   ├── base/                #   BaseMarketplaceGateway (contrato)
│   ├── meli/                #   Lógica específica Mercado Livre
│   ├── oauth/               #   Fluxo OAuth callback
│   ├── orchestrators/       #   Orquestração de sincronização
│   ├── tokens/              #   CRUD de tokens criptografados
│   └── services/            #   Serviço principal
│
├── listings/                # Anúncios em marketplaces
├── orders/                  # Pedidos de venda
├── tenants/                 # Contas SaaS (tenants)
├── users/                   # Usuários e RBAC
├── companies/               # Perfil de empresa do tenant
├── brands/                  # Cadastro de marcas
├── suppliers/               # Cadastro de fornecedores
├── warehouses/              # Depósitos e locais de estoque
├── processing/              # Lógica de processamento em batch
├── workers/                 # Consumers BullMQ
├── config/                  # Configuração centralizada
├── database/                # Migrations TypeORM
├── types/                   # Tipos globais
└── utils/                   # Utilitários puros

               ┌──────────────────────────────────┐
  Request ───▶ │   TenancyMiddleware              │
               │   Decodifica JWT, extrai          │
               │   tenantId e userId               │
               │   Salva no CLS (nestjs-cls)       │
               └───────────┬──────────────────────┘
                           │
               ┌───────────▼──────────────────────┐
   Service ───▶│   TenantAwareService             │
               │   this.currentTenantId            │
               │   Herança: extends TenantAware    │
               └───────────┬──────────────────────┘
                           │
               ┌───────────▼──────────────────────┐
     ORM  ───▶ │   TenantSubscriber               │
               │   beforeInsert() → injeta         │
               │   tenantId automaticamente        │
               └──────────────────────────────────┘

@Entity('products')
@Index('idx_product_tenant', ['tenantId'])
export class Product extends TenantBaseEntity {
  @Column({ name: 'name' })
  name: string;
  // ...
}

async createProduct(dto: CreateProductDto) {
  return this.repository.manager.transaction(async (manager) => {
    // 1. Validação
    await this.validationService.validate(dto);
    // 2. Criação da entity principal
    const product = manager.create(Product, { ...dto, tenantId: this.currentTenantId });
    await manager.save(product);
    // 3. Criação de dependentes dentro da MESMA transação
    await this.createInventory(manager, product);
    return product;
  });
}

  Controller               FIla (Redis)              Worker (Processor)
  ──────────                ──────────                ──────────────────
  Ação do usuário  ───▶   enfileira job   ───▶      processa em background
                           (auto-retry 3x)           (exponential backoff)

                       ┌──────────────────────────────┐
                       │   BaseMarketplaceGateway     │
                       │   (contrato / interface)      │
                       └──────────┬───────────────────┘
                                  │
               ┌──────────────────┤──────────────────────┐
               │                  │                      │
       ┌───────▼───┐      ┌──────▼──────┐       ┌───────▼───────┐
       │MeliAdapter│      │ShopeeAdapter│       │ Futuro adapter│
       └───────────┘      └─────────────┘       └───────────────┘

// ✅ Correto
@Entity('products')
@Index('idx_product_tenant', ['tenantId'])
@Index('idx_product_tenant_sku', ['tenantId', 'sku'])
export class Product extends TenantBaseEntity {
  @Column({ name: 'seq_id' })
  seqId: number;

  @Column({ name: 'sku', nullable: true })
  sku: string;
}

// Separar em Create, Update e Bulk
export class CreateProductDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsOptional()
  @IsString()
  sku?: string;
}

export class UpdateProductDto extends PartialType(CreateProductDto) {}

// ✅ Usar exceções HTTP do NestJS
throw new NotFoundException(`Produto ${id} não encontrado`);
throw new BadRequestException('SKU já existe para este tenant');

// ❌ Nunca expor erros internos do banco
// throw error;  ← NÃO FAÇA ISSO