Skip to content

Blocos de Construcao e Execucao

jota edited this page Aug 25, 2026 · 1 revision

Blocos de Construção e Visão de Execução

⬅ Voltar para Documentação de Arquitetura


5. Visão de Blocos de Construção

A visão de blocos de construção mostra a decomposição estática do sistema em blocos de construção (módulos, componentes, subsistemas) e seus relacionamentos.

5.1 Nível 1: Visão Geral (Whitebox do Sistema QuaLeiDer)

No nível mais alto, o QuaLeiDer é um Monólito Modular construído sobre o framework NestJS. O sistema é composto por um único processo de servidor (AppModule) que orquestra diversos módulos de funcionalidade e infraestrutura.

5.2 Nível 2: Decomposição em Módulos

O sistema divide-se em Módulos de Domínio (Features) e Módulos de Infraestrutura (Shared). O diagrama abaixo ilustra as dependências lógicas entre os principais módulos do sistema.

Decomposição em Módulos

Descrição dos Blocos de Construção

A tabela abaixo descreve as responsabilidades de cada módulo principal identificado na arquitetura.

Bloco de Construção Responsabilidade Principal Colaboradores / Dependências
Auth Module Gerencia a autenticação e emissão de tokens. Implementa estratégias Passport (JWT, Local) e Guards globais. Depende de UsersModule para validar credenciais e JwtService para assinar tokens.
Users Module Gerencia o ciclo de vida dos usuários (Produtores e Associações), perfis e dados cadastrais básicos. Utiliza PrismaModule para persistência e HashService para segurança de senhas.
DailyCollections Module (Core Domain) Gerencia o registro de coletas de leite, contendo as regras de negócio mais críticas sobre produção e validação de dados técnicos. Depende de UsersModule (proprietário) e AnimalsModule (origem do leite).
Animals Module Gerencia o rebanho dos produtores, rastreando características individuais (raça, idade, tipo) e status. Vinculado fortemente ao UsersModule.
Invites Module Gerencia o fluxo de crescimento viral da plataforma (Associações convidando Produtores). Controla tokens, expiração e envio de emails. Usa MailModule para comunicação e EventEmitter para processamento assíncrono.
Associations Module Gerencia dados corporativos das associações e visualização agregada de seus membros. Relaciona-se com UsersModule (membros) e InvitesModule (origem dos convites).
Infrastructure Module Fornece implementações concretas para as interfaces de porta (Ports) da camada de aplicação. Inclui Repositórios, HashService, etc. Isola dependências externas como bibliotecas de criptografia.
Prisma Module Encapsula o PrismaClient, gerenciando a conexão com o PostgreSQL e tratamento de erros de banco de dados. Usado por todos os Repositórios.
Mail Module Abstração sobre o Nodemailer. Responsável pela renderização de templates Handlebars e transporte SMTP. Injetado principalmente em Listeners de eventos.

5.3 Estrutura Interna dos Módulos (Nível 3)

Cada módulo de funcionalidade (ex: UsersModule) segue ESTRITAMENTE a Clean Architecture, organizando seus componentes internos para separar responsabilidades.

Exemplo: Anatomia do UsersModule

Componente Interno Camada (Clean Arch) Descrição
UsersController Presentation Recebe HTTP, valida DTOs (CreateUserDto) e chama o Service.
UsersService Application Orquestra a lógica de negócio. Não conhece HTTP nem SQL. Executa regras como "Remover senha do retorno".
UserEntity Domain Define a estrutura pura do dado e regras invariantes do domínio.
IUserRepository Domain (Port) Interface que define o contrato de persistência.
PrismaUserRepository Infrastructure (Adapter) Implementação que usa o PrismaService para traduzir chamadas de domínio em queries de banco.

6. Visão de Tempo de Execução

6.1. Fluxo de Autenticação (Login) {#fluxo_autenticacao_login}

Diagrama de Sequência

Fluxo de Login

Descrição do Fluxo

Este diagrama ilustra o processo completo de autenticação JWT, desde a validação de credenciais até a geração do token de acesso.

Atores e Componentes:

  • User: Usuário (Produtor, Associação) solicitando autenticação
  • AuthController: Camada de apresentação (HTTP) que recebe credenciais
  • AuthService: Camada de aplicação contendo lógica de autenticação
  • UsersService: Serviço responsável por buscar usuários no banco
  • JwtService: Serviço de infraestrutura para geração de tokens JWT
  • ORM (Prisma): Camada de acesso a dados (PostgreSQL)
  • PostgreSQL: Banco de dados relacional

Etapas do Fluxo:

  1. Requisição HTTP: User envia POST /auth/login com {email, password}
  2. Validação de Credenciais: AuthService chama validateUser(email, password)
  3. Busca de Usuário: UsersService consulta banco via findByEmail(email)
  4. Query SQL: Prisma executa SELECT * FROM "User" WHERE email = ?
  5. Validação de Senha: AuthService compara senha com bcrypt.compare(password, hash)
  6. Remoção de Senha: Campo password é removido do objeto antes de retornar
  7. Geração de Token: AuthService cria payload JWT e solicita assinatura
  8. Assinatura JWT: JwtService gera token com algoritmo HS256 e secret
  9. Auditoria: Logger registra autenticação bem-sucedida com email do usuário
  10. Resposta HTTP: Retorna 200 OK com {access_token} válido por 24 horas

Segurança e Validações

Validação de Credenciais:

// AuthService.validateUser()
async validateUser(email: string, password: string): Promise<any> {
    const user = await this.userRepository.findByEmail(email);

    if (user && (await this.hashService.compare(password, user.password))) {
      const { password, ...result } = user;
      return result;
    }

    throw new UnauthorizedException('Credenciais inválidas.');
  }

Payload do JWT:

// AuthService.login()
const payload = {
  email: user.email,
  sub: user.id,
  associationId: user.associationId,
};

return {
  access_token: this.jwtService.sign(payload),
};

Configuração do Token:

Propriedade Valor Descrição
Algoritmo HS256 (HMAC-SHA256) Assinatura simétrica
Secret process.env.JWT_SECRET Chave secreta do servidor
Expiração 24 horas Token válido por 1 dia
Payload {email, sub, associationId} Dados do usuário (sem informações sensíveis)
Stateless Sim Servidor não armazena sessão

Cenários de Erro

1. Usuário Não Encontrado:

POST /auth/login {email: "wrong@example.com", password: "123"}
→ UserRepository.findByEmail() retorna null
→ throw UnauthorizedException("Credenciais inválidas.")
→ Response: 401 Unauthorized

2. Senha Incorreta:

POST /auth/login {email: "user@example.com", password: "WrongPass"}
→ UserRepository.findByEmail() retorna user
→ HashService.compare() retorna false
→ throw UnauthorizedException("Credenciais inválidas.")
→ Response: 401 Unauthorized

Note: Por questões de segurança, ambos os erros retornam a mesma mensagem genérica "Credenciais inválidas" para não revelar se o email existe no sistema.

Características de Qualidade

  • Performance: Tempo de resposta < 200ms (validação + geração de token)
  • Segurança:
    • Senhas hasheadas com bcrypt (12 rounds)
    • JWT assinado com HS256 + secret forte
    • Senha nunca retornada ao cliente
    • Mensagens de erro genéricas (não revelam se email existe)
  • Auditoria: Cada autenticação bem-sucedida é registrada em log com timestamp e email
  • Escalabilidade: Autenticação stateless permite balanceamento de carga sem sessão compartilhada

Uso do Token

Após autenticação bem-sucedida, o cliente deve incluir o token em todas as requisições protegidas:

GET /animals HTTP/1.1
Host: api.qualeider.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

O token é validado automaticamente pelo JwtAuthGuard em endpoints protegidos com decorator @UseGuards(JwtAuthGuard).


6.2. Fluxo de Registro de Coleta Diária {#fluxo_registro_coleta}

Diagrama de Sequência

Registro de Coleta Diária

Descrição do Fluxo

Este documento descreve o processo técnico de registro de uma coleta diária de leite

Atores e Componentes:

  • User (Produtor): Produtor de leite registrando a coleta diária
  • DailyCollectionsController: Camada de apresentação (HTTP)
  • DailyCollectionsService: Camada de aplicação com lógica de negócio e validações
  • ORM (Prisma): Camada de acesso a dados (PostgreSQL)
  • PostgreSQL: Banco de dados relacional

Etapas do Fluxo:

  1. Requisição HTTP: Produtor envia POST /daily-collections com dados da coleta
  2. Validações de Pré-requisitos:
    • Produtor existe e está ativo
  3. Persistência: 2 operações SQL executadas em transação:
    • INSERT INTO "DailyCollection" (coleta principal)
  4. Resposta HTTP: Retorna 201 Created com dados da coleta

Características de Qualidade

  • Performance:

    • Tempo médio de resposta: 250ms
    • Meta: < 300ms para 95% das requisições
    • 2 queries de validação + 1 INSERT atômico
  • Atomicidade:

    • Transação Prisma garante criação de coleta + relacionamentos
    • Rollback automático em caso de falha
  • Rastreabilidade:

    • Histórico completo de coletas por produtor
    • Dados técnicos para análise de produtividade (TO DO)
  • Validação Rigorosa:

    • validações de negócio antes de persistir
    • Garante integridade referencial
    • Previne dados inconsistentes no banco

Clone this wiki locally