Skip to content

Estrategia de Solucao

jota edited this page Aug 25, 2026 · 1 revision

Estratégia de Solução

⬅ Voltar para Documentação de Arquitetura


Estratégia de Solução {#section-solution-strategy}

Esta seção documenta as decisões arquiteturais de alto nível tomadas para resolver os requisitos do sistema, explicando por que cada tecnologia ou padrão foi escolhido. As decisões são fortemente influenciadas pelas restrições documentadas na Seção 2.


Visão Geral da Estratégia

A arquitetura do QuaLeiDer foi projetada para balancear simplicidade (time pequeno, orçamento zero) com qualidade (segurança, manutenibilidade, testabilidade). A estratégia central é:

"Monólito modular com Clean Architecture, usando tecnologias maduras do ecossistema Node.js/TypeScript, priorizando time-to-market sem sacrificar boas práticas de engenharia de software."


Decisões Arquiteturais Fundamentais

1. Arquitetura: Monólito Modular (NestJS)

Decisão: Sistema único com módulos independentes (UsersModule, AnimalsModule, InvitesModule, etc.) ao invés de microserviços.

Justificativa:

Critério Monólito Modular ✅ Microserviços ❌
Equipe 1-2 desenvolvedores conseguem manter Exige time de 5+ pessoas
Complexidade Deploy único, logs centralizados Requer orquestração (Kubernetes), tracing distribuído
Latência Chamadas de função (nanossegundos) Chamadas HTTP entre serviços (milissegundos)
Transações ACID nativo do PostgreSQL Saga Pattern ou 2PC (complexo)

Referência de Código:

// src/presentation/app.module.ts - Todos os módulos em um só monólito

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: [
        path.resolve(process.cwd(), '.env'),
        path.resolve(
          process.cwd(),
          `.env.${process.env.NODE_ENV || 'development'}`,
        ),
      ],
    }),
    WinstonModule.forRoot(winstonConfig),
    ThrottlerModule.forRoot(throttlerConfig),
    EventEmitterModule.forRoot(),
    ScheduleModule.forRoot(),
    PrismaModule,
    InfrastructureModule,
    UsersPresentationModule,
    AnimalsPresentationModule,
    DailyCollectionsPresentationModule,
    AuthPresentationModule,
    AssociationsPresentationModule,
    InvitesPresentationModule,
    NotificationsPresentationModule,
    MailModule,
  ],
  controllers: [],
  providers: [
    {
      provide: APP_GUARD,
      useClass: AppThrottlerGuard,
    },
  ],
})
export class AppModule {}

2. Padrão Arquitetural: Clean Architecture (4 Camadas)

Decisão: Separar código em 4 camadas: Domain → Application → Infrastructure → Presentation.

Justificativa:

  • Testabilidade: Lógica de negócio isolada da infraestrutura (mocks fáceis)
  • Manutenibilidade: Mudanças em banco de dados não afetam regras de negócio
  • Substituibilidade: Trocar Prisma por TypeORM exige mudanças apenas na camada Infrastructure
  • Requisito Acadêmico: IFPE valoriza arquiteturas bem documentadas

Estrutura de Diretórios:

src/
├── domain/              # Entidades e regras de negócio puras
│   └── entities/        # User, Animal, DailyCollection
├── application/         # Casos de uso (Services)
│   └── services/        # UsersService, AnimalsService
├── infrastructure/      # Adaptadores externos
│   ├── prisma/          # ORM (substituível)
│   └── mail/            # Nodemailer (substituível)
└── presentation/        # Controllers (HTTP)
    └── controllers/     # UsersController, AnimalsController

Regra de Dependência:

Regra de Dependência - Clean Architecture

  • Setas indicam dependência de código-fonte (imports), não fluxo de execução

Princípios:

  • Domain (núcleo isolado) não conhece nenhuma outra camada
  • Application depende apenas de Domain (usa entidades e interfaces)
  • Presentation depende de Application (chama Services)
  • Infrastructure implementa interfaces definidas em Domain/Application (Inversão de Dependência - DIP)

Benefício Concreto: 96.25% de cobertura de testes (582 testes) graças à separação de camadas.


3. Autenticação: JWT Stateless (HS256)

Decisão: Tokens JWT assinados com HMAC-SHA256, sem armazenamento de sessão no servidor.

Justificativa:

Aspecto JWT Stateless ✅ Sessions (Redis) ❌
Escalabilidade Horizontal (stateless) Requer Redis compartilhado
Custo Zero (sem dependência externa) Redis $5/mês
Latência Validação local (1ms) Query Redis (5-10ms)
Revogação Impossível (token válido até expirar) Instantânea (delete key)
Complexidade Baixa (biblioteca padrão) Média (gerenciar conexões Redis)

Configuração de Segurança:

// src/auth/auth.module.ts
JwtModule.registerAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        secret: configService.get<string>('JWT_SECRET'),
        signOptions: { expiresIn: '1h' },
      }),
      inject: [ConfigService],
    }),

Trade-off Aceito:

  • ❌ Não é possível revogar tokens antes de expirar (logout instantâneo impossível)
  • ✅ Mitigação: Expiração curta (24h) + blacklist opcional para casos críticos

Alternativas Descartadas:

  • Sessions (Express-Session + Redis): Requer infraestrutura adicional (custo)
  • OAuth2: Overhead desnecessário para sistema interno sem SSO

4. Banco de Dados: PostgreSQL + Prisma ORM

Decisão: PostgreSQL 14+ como SGBD relacional com Prisma como ORM type-safe.

Justificativa para PostgreSQL:

  • Requisito IFPE: Exigência institucional de banco relacional (ACID compliance)
  • Integridade Referencial: Foreign Keys garantem consistência (ex: DailyCollection.userId → User.id)
  • Queries Complexas: Suporte nativo a JOINs, agregações, CTEs (necessário para relatórios)

Justificativa para Prisma:

Aspecto Prisma ORM ✅ SQL Raw ❌ TypeORM ❌
Type-Safety 100% (tipos gerados automaticamente) 0% (strings SQL) 80% (decorators podem quebrar)
SQL Injection Impossível (prepared statements) Alto risco (concatenação manual) Baixo risco (query builder seguro)
Migrations Automáticas (prisma migrate dev) Manuais (scripts SQL versionados) Automáticas (mas verbosas)
Developer Experience Autocomplete perfeito no VSCode Nenhum Médio
Performance Boa (connection pooling nativo) Ótima (controle total) Boa

Exemplo de Type-Safety:

// Exemplo real de implementação no repositório
async findByEmail(email: string) {
  const user = await this.prisma.user.findUnique({
    where: { email },
    select: { 
      id: true, 
      name: true, 
      role: true 
    } 
  });
  
  // O TypeScript sabe que 'user' tem apenas id, name e role
  return user; 
}

// Erro de compilação se tentar acessar campo inexistente
console.log(user.nonExistentField); // TypeScript Error!

Trade-off Aceito:

  • Queries N+1 podem ocorrer (requer include explícito)

Mitigação:

  • Usar prisma.$queryRaw para otimizações críticas

5. Comunicação Assíncrona: EventEmitter (NestJS)

Decisão: @nestjs/event-emitter para processamento assíncrono de emails, CRON jobs e notificações.

Justificativa:

Aspecto EventEmitter ✅ RabbitMQ/Kafka ❌
Custo Zero (biblioteca nativa NestJS) RabbitMQ: $10/mês
Complexidade Baixa (decorators simples) Alta (gerenciar brokers)
Persistência Nenhuma (em memória) Total (mensagens em disco)
Latência < 1ms (mesma thread) 5-10ms (rede)
Escalabilidade Limitada (1 servidor) Ilimitada (cluster)

Casos de Uso Atuais:

// 1. Envio de emails assíncronos
this.eventEmitter.emit('invite.created', {
  userId: 1,
  token: 'abc123'
});

// 2. Auditoria de ações críticas
this.eventEmitter.emit('user.deleted', {
  userId: 42,
  deletedBy: 'admin@example.com'
});

// 3. Limpeza de dados expirados (CRON)
@Cron('0 2 * * *') // Diariamente às 02:00
async cleanupExpiredInvites() {
  this.eventEmitter.emit('cleanup.invites');
}

Limitação Conhecida:

  • Perda de eventos ao reiniciar servidor (retry em memória não persiste)

Referência: Seção 3.2 (Dependências Externas) documenta esta limitação explicitamente.


6. Containerização: Docker + Docker Compose

Decisão: Docker para empacotamento e Docker Compose para orquestração local.

Justificativa:

  • Paridade Dev/Prod: Mesmo ambiente PostgreSQL 14-alpine em desenvolvimento e produção
  • Onboarding Rápido: Novo desenvolvedor roda docker-compose up e está pronto
  • CI/CD Simples: GitHub Actions builda imagem e faz push para registry
  • Gratuito: Docker Desktop é free para uso educacional

docker-compose.yml (Desenvolvimento):

services:
  postgres:
    image: postgres:14-alpine
    environment:
      POSTGRES_DB: qualeider_db
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"

  backend:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/qualeider_db

Multi-Stage Build (Otimização):

# Stage 1: Build
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: Production
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/main.js"]

Resultado: Imagem final de 180MB (meta: < 500MB) ✅

Alternativa Descartada:

  • Kubernetes: Overhead desnecessário para 1 container (complexidade 10x maior)

7. Validação de Entrada: class-validator + DTOs

Decisão: Todos os payloads HTTP validados via Data Transfer Objects (DTOs) com decorators.

Justificativa:

  • Segurança: Previne SQL Injection, XSS, buffer overflow
  • Documentação Automática: Swagger gera docs a partir dos decorators
  • Fail-Fast: Erros de validação retornam 400 Bad Request antes de chegar ao banco

Exemplo de DTO:

// src/application/dtos/users/create-user.dto.ts
export class CreateUserDto {
  @ApiProperty({ description: 'Nome do usuário', example: 'Silva Santos' })
  @IsNotEmpty({ message: 'O nome não pode ser vazio.' })
  @IsString({ message: 'O nome deve ser uma string.' })
  @Length(3, 255, { message: 'O nome deve ter entre 3 e 255 caracteres.' })
  name!: string;

  @ApiProperty({
    description: 'Email do usuário',
    example: 'silva.santos@example.com',
  })
  @IsNotEmpty({ message: 'O email não pode ser vazio.' })
  @IsEmail({}, { message: 'O email fornecido não é válido.' })
  @Transform(({ value }) => value?.toLowerCase().trim())
  email!: string;

  @ApiProperty({ description: 'Senha do usuário', example: 'Leite@123' })
  @IsNotEmpty({ message: 'A senha não pode ser vazia.' })
  @IsString()
  @MinLength(8, { message: 'A senha deve ter no mínimo 8 caracteres.' })
  // [BR-003] Validação de Senha
  @Matches(
    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
    {
      message:
        'A senha deve conter pelo menos uma letra maiúscula, uma minúscula, um número e um caractere especial (@$!%*?&).',
    },
  )
  password!: string;

Configuração nos Controllers:

// InvitesService (Publisher) - NÃO conhece MailService
this.eventEmitter.emit('invite.created', {
  inviteId: invite.id,
  token: invite.token,
  userEmail: user.email,
  associationName: association.name,
});

// InviteEmailListener (Subscriber) - escuta automaticamente

export class InviteEmailListener {
  private readonly logger = new Logger(InviteEmailListener.name);
  constructor(
    private readonly mailService: MailService,
    @Inject(IAssociationRepository)
    private readonly associationRepository: IAssociationRepository,
  ) {}

  /**
   * Quando convite é criado, envia email para o usuário convidado
   */
  @OnEvent('invite.created')
  async handleInviteCreated(event: InviteCreatedEvent) {
    const frontendUrl = process.env.FRONTEND_URL || 'http://localhost:3000';
    const acceptUrl = `${frontendUrl}/invites/${event.token}?action=accept`;
    const declineUrl = `${frontendUrl}/invites/${event.token}?action=decline`;

    try {
      this.logger.log(`Enviando email de convite para ${event.userEmail}...`);

      await this.mailService.sendInviteEmail(
        event.userEmail,
        event.userName,
        event.associationName,
        event.message,
        acceptUrl,
        declineUrl,
        event.expiresAt,
      );

      this.logger.log(
        `Email de convite enviado com sucesso para ${event.userEmail}`,
      );
    } catch (error) {
      this.logger.error(
        `Erro ao enviar email de convite para ${event.userEmail}:`,
        error,
      );
    }
  }

Nota: O projeto usa ValidationPipe em nível de controller com transform: true para converter tipos automaticamente.

Benefícios:

Aspecto Sem EventEmitter (Síncrono) Com EventEmitter (Assíncrono)
Performance 3s de resposta (espera envio email) 100ms (retorna imediatamente)
Acoplamento Service depende de MailService Completamente desacoplado
Resiliência Erro no email quebra criação Falha no email não afeta DB
Extensibilidade Difícil adicionar novos listeners Fácil adicionar Notification, Audit
Testabilidade Precisa mockar MailService Testa Service isoladamente

Características de Qualidade

  • Performance: Tempo de resposta < 100ms (email enviado em background)
  • Resiliência:
    • Falha no envio de email não impede criação do convite
    • Sistema de retry automático: 3 tentativas com intervalos de 5min, 15min e 30min
    • Falhas definitivas são logadas para processamento manual posterior
  • Segurança: Token único gerado com crypto.randomBytes(32), expiração em 7 dias
  • Rastreabilidade: Evento invite.created logado para auditoria, incluindo tentativas de retry

Clone this wiki locally