Skip to content

Observabilidade e Tratamento de Erros

jota edited this page Aug 25, 2026 · 1 revision

Observabilidade e Tratamento de Erros

⬅ Voltar para Documentação de Arquitetura


8.4 Logging e Monitoramento {#logging_monitoramento}

O sistema utiliza uma estratégia de Logging Estruturado baseada na biblioteca winston, integrada nativamente ao Logger do NestJS. Isso garante que todos os logs do sistema (incluindo erros não tratados e queries do Prisma) sigam um padrão uniforme, facilitando a ingestão por ferramentas de observabilidade.

Níveis de Log

Nível Quando Usar Exemplo
error Falhas críticas Database down, erro não tratado
warn Situações anormais não críticas Retry de email, token expirado
log Eventos importantes Autenticação bem-sucedida, convite criado
debug Informações detalhadas (apenas dev) Payload de requisição, query SQL gerada

Logs Estruturados (JSON)

Diferente do logger padrão (texto simples), o sistema emite logs em formato JSON. Isso permite filtrar logs por campos específicos (ex: context: 'AuthService') sem necessidade de regex complexo.

Exemplo de estrutura de log atual:

{
  "timestamp": "2025-11-20 15:30:00",
  "level": "info",
  "message": "Usuário autenticado com sucesso",
  "context": "AuthService",
  "userId": "uuid-1234-5678",
  "meta": {
    "ip": "192.168.1.50",
    "userAgent": "Mozilla/5.0..."
  }
}

Sanitização de Dados Sensíveis (LGPD)

O sistema possui um Middleware de Sanitização (Custom Formatter) que intercepta todos os logs antes da escrita. Um algoritmo recursivo varre o objeto de log (mensagem e metadados) em busca de chaves sensíveis e as ofusca automaticamente.

Logs nunca devem conter:

  • Senhas (plaintext ou hash)
  • Tokens (JWT, reset password)
  • CPF

Sanitização de logs atualmente:

// Código (Input)
this.logger.log({
  msg: 'Criando usuário',
  data: { name: 'Marcelo', password: '123' }
});

// Log Gerado (Output Seguro)
{
  "timestamp": "...",
  "message": {
    "msg": "Criando usuário",
    "data": {
      "name": "Marcelo",
      "password": "***[REDACTED]***" // <--- Protegido automaticamente
    }
  }
}

Monitoramento de Processos Críticos

1. CRON Job de Limpeza de Convites

import { Injectable, Logger, Inject } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { IInviteRepository } from '@/domain/repositories/invite.repository';

@Injectable()
export class InvitesCleanupService {
  private readonly logger = new Logger(InvitesCleanupService.name);

  constructor(
    @Inject(IInviteRepository)
    private readonly inviteRepository: IInviteRepository,
  ) {}

  /**
   * Roda todos os dias à meia-noite
   * Marca convites pendentes expirados como EXPIRED
   */
  // [BR-002] Expiração de Convite: Job roda diariamente às 02:00 AM
  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
  async expireOldInvites() {
    this.logger.log('Iniciando verificação de convites expirados...');

    const expiredCount = await this.inviteRepository.expireOldInvites();

    this.logger.log(
      `${expiredCount} convite(s) marcado(s) como expirado(s)`,
    );

    return {
      success: true,
      expiredCount,
      timestamp: new Date(),
    };
  }

2. Retry de Emails

Ver implementação real na seção Tratamento de Erros Assíncronos (EmailListener com MAX_RETRIES = 3).


Observabilidade (Roadmap)

Roadmap v1.1 (3 meses):

// Métricas a coletar:
- Taxa de sucesso de login (%)
- Tempo médio de resposta de API (ms)
- Número de convites criados/aceitos/rejeitados (count)
- Número de coletas registradas por dia (count)
- Taxa de erro de envio de emails (%)
- Uso de memória/CPU do container (%)

// Ferramentas:
- Prometheus: Coleta de métricas
- Grafana: Visualização de dashboards
- @willsoto/nestjs-prometheus: Integração NestJS

8.5 Tratamento de Erros {#tratamento_erros}

O tratamento de erros no QuaLeiDer segue uma abordagem fail-fast e centralizada, garantindo mensagens consistentes e logs estruturados.

Filtros Globais de Exceção

O projeto atualmente implementa apenas o PrismaExceptionFilter para capturar erros de banco de dados. Erros HTTP genéricos são tratados pelo comportamento padrão do NestJS.

Registro Global (main.ts):

// backend/src/presentation/main.ts
import { PrismaExceptionFilter } from "@/common/filters/prisma-exception.filter";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const configService = app.get(ConfigService);

  // Configurar CORS
  const corsOptions = configureCors(configService);
  app.enableCors(corsOptions);

  // Configurar filtros globais
  app.useGlobalFilters(new PrismaExceptionFilter());

  // Configurar Swagger
  setupSwagger(app);

  // Iniciar o servidor
  const port = getAppPort(configService);
  await app.listen(port);
}

Códigos HTTP Padronizados

Código Nome Quando Usar Exemplo
200 OK Operação bem-sucedida (GET, PUT) GET /users/1 retorna usuário
201 Created Recurso criado (POST) POST /invites cria convite
204 No Content Exclusão bem-sucedida (DELETE) DELETE /animals/1 deleta animal
400 Bad Request Validação de DTO falhou Email inválido, senha curta
401 Unauthorized Token JWT inválido/expirado Authorization: Bearer invalid_token
403 Forbidden Usuário sem permissão Produtor tenta criar associação
404 Not Found Recurso inexistente GET /users/999 (usuário não existe)
409 Conflict Recurso duplicado (unique constraint) Email já cadastrado
500 Internal Server Error Erro não tratado Database connection failed

Tratamento de Erros do Prisma

Prisma ORM retorna códigos de erro específicos (PXX) que são traduzidos para HTTP.

Código Real (PrismaExceptionFilter):

// backend/src/common/filters/prisma-exception.filter.ts
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpStatus,
  Logger,
} from "@nestjs/common";
import { Response } from "express";
import { PrismaClientKnownRequestError } from "@prisma/client/runtime/library";

@Catch(PrismaClientKnownRequestError)
export class PrismaExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(PrismaExceptionFilter.name);

  catch(exception: PrismaClientKnownRequestError, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest();

    let status = HttpStatus.INTERNAL_SERVER_ERROR;
    let message = "Erro interno de banco de dados";

    switch (exception.code) {
      case "P2002":
        status = HttpStatus.CONFLICT;
        message = this.handleUniqueConstraintViolation(exception);
        break;

      case "P2025":
        status = HttpStatus.NOT_FOUND;
        message = "Registro não encontrado";
        break;

      case "P2003":
        status = HttpStatus.BAD_REQUEST;
        message = "Violação de chave estrangeira";
        break;

      case "P2014":
        status = HttpStatus.BAD_REQUEST;
        message = "A operação viola uma relação necessária";
        break;

      default:
        this.logger.error(
          `[Prisma Error ${exception.code}] ${exception.message}`,
          exception.stack
        );
        break;
    }

    this.logger.warn(
      `Prisma Error [${exception.code}] on ${request.method} ${request.url}: ${message}`
    );

    response.status(status).json({
      statusCode: status,
      message,
      error: this.getErrorName(status),
      timestamp: new Date().toISOString(),
      path: request.url,
    });
  }

  private handleUniqueConstraintViolation(
    exception: PrismaClientKnownRequestError
  ): string {
    const meta = exception.meta as { target?: string[] };
    const fields = meta?.target?.join(", ") || "campo";
    return `Já existe um registro com este ${fields}`;
  }

  private getErrorName(status: number): string {
    switch (status) {
      case HttpStatus.NOT_FOUND:
        return "Not Found";
      case HttpStatus.CONFLICT:
        return "Conflict";
      case HttpStatus.BAD_REQUEST:
        return "Bad Request";
      default:
        return "Internal Server Error";
    }
  }
}

Mapeamento de Erros do Prisma:

Código Prisma HTTP Status Significado Exemplo
P2002 409 Unique constraint violation Email já existe
P2025 404 Record not found findUniqueOrThrow não encontrou registro
P2003 400 Foreign key constraint userId inválido em DailyCollection
P2014 400 Invalid relation Tentar associar Animal a User inexistente
P1001 500 Can't reach database PostgreSQL offline

Utilitário de Tratamento de Erros Prisma

Para evitar duplicação de código no tratamento de erros do Prisma, o projeto implementa o utilitário handlePrismaError que centraliza a tradução de códigos de erro Prisma para exceções de negócio apropriadas.

Localização: src/common/utils/prisma-error-handler.ts

Implementação completa:

// src/common/utils/prisma-error-handler.ts
import { BusinessException } from '@/common/exceptions/business.exception';
import { EntityNotFoundException } from '@/common/exceptions/entity-not-found.exception';

/**
 * Códigos de erro do Prisma
 * @see https://www.prisma.io/docs/orm/reference/error-reference
 */
export enum PrismaErrorCode {
  UNIQUE_CONSTRAINT_VIOLATION = 'P2002',
  RECORD_NOT_FOUND = 'P2025',
  FOREIGN_KEY_CONSTRAINT_FAILED = 'P2003',
  CONSTRAINT_FAILED = 'P2004',
}

/**
 * Tipo de erro do Prisma
 */
interface PrismaError extends Error {
  code?: string;
  meta?: {
    target?: string[];
    modelName?: string;
  };
}

/**
 * Verifica se o erro é um erro do Prisma
 */
export function isPrismaError(error: unknown): error is PrismaError {
  return (
    typeof error === 'object' &&
    error !== null &&
    'code' in error &&
    typeof (error as PrismaError).code === 'string'
  );
}

/**
 * Trata erros do Prisma e os converte em exceções de negócio apropriadas
 * 
 * @param error Erro capturado
 * @param customMessages Mensagens customizadas por código de erro
 * @throws BusinessException ou EntityNotFoundException
 */
export function handlePrismaError(
  error: unknown,
  customMessages?: Partial<Record<PrismaErrorCode, string>>,
): never {
  if (!isPrismaError(error)) {
    throw error;
  }

  const { code, meta } = error;

  switch (code) {
    case PrismaErrorCode.UNIQUE_CONSTRAINT_VIOLATION: {
      const field = meta?.target?.[0] || 'campo';
      const message =
        customMessages?.[PrismaErrorCode.UNIQUE_CONSTRAINT_VIOLATION] ||
        `${field} já está em uso.`;
      throw new BusinessException(message);
    }

    case PrismaErrorCode.RECORD_NOT_FOUND: {
      const modelName = meta?.modelName || 'Registro';
      const message =
        customMessages?.[PrismaErrorCode.RECORD_NOT_FOUND] ||
        `${modelName} não encontrado.`;
      throw new EntityNotFoundException(message);
    }

    case PrismaErrorCode.FOREIGN_KEY_CONSTRAINT_FAILED: {
      const message =
        customMessages?.[PrismaErrorCode.FOREIGN_KEY_CONSTRAINT_FAILED] ||
        'Referência inválida. Verifique os dados relacionados.';
      throw new BusinessException(message);
    }

    case PrismaErrorCode.CONSTRAINT_FAILED: {
      const message =
        customMessages?.[PrismaErrorCode.CONSTRAINT_FAILED] ||
        'Operação violou uma restrição do banco de dados.';
      throw new BusinessException(message);
    }

    default:
      throw error;
  }
}

/**
 * Helper específico para erros de constraint unique em email
 */
export function handleEmailUniqueError(error: unknown): never {
  handlePrismaError(error, {
    [PrismaErrorCode.UNIQUE_CONSTRAINT_VIOLATION]: 'Email já está em uso.',
  });
}

Exemplo de uso em Services (Application Layer):

IMPORTANTE: Services NÃO devem usar handlePrismaError ou qualquer outro ORM que seja responsável por tratar erros de banco de dados. Essa responsabilidade pertence aos Repositories (Infrastructure Layer).

// src/application/services/users/users.service.ts

import { Injectable, Logger, Inject } from '@nestjs/common';
import { IUserRepository } from '@/domain/repositories/user.repository';
import { IHashService } from '@/application/ports/hash.service';
import { BCRYPT_ROUNDS_USER_CREATION } from '@/common/constants/security.constants';

@Injectable()
export class UsersService {
  private readonly logger = new Logger(UsersService.name);

  constructor(
    @Inject(IUserRepository) private readonly userRepository: IUserRepository,
    @Inject(IHashService) private readonly hashService: IHashService,
  ) {}

  async create(createUserDto: CreateUserDto) {
    const { password, ...rest } = createUserDto;
    
    const hashedPassword = await this.hashService.hash(
      password,
      BCRYPT_ROUNDS_USER_CREATION,
    );

    // SEM try-catch: Repository lança BusinessException se email duplicar
    // Repository já tratou erro Prisma P2002 e converteu para BusinessException
    const user = await this.userRepository.create({
      ...rest,
      password: hashedPassword,
    });

    this.logger.log(`Usuário criado: ${user.email} (ID: ${user.id})`);
    return this.removePassword(user);
  }

  async update(id: number, updateDto: UpdateUserDto) {
    await this.findOne(id); // Valida existência
    
    const dataToUpdate = await this.prepareUpdateData(updateDto);
    
    // SEM try-catch: Repository lança EntityNotFoundException (P2025) ou BusinessException (P2002)
    const updatedUser = await this.userRepository.partialUpdate(id, dataToUpdate);
    
    this.logger.log(`Usuário atualizado: ID ${id}`);
    return this.removePassword(updatedUser);
  }

  private async prepareUpdateData(data: UpdateUserDto) {
    const dataToUpdate = { ...data };
    if (dataToUpdate.password) {
      dataToUpdate.password = await this.hashService.hash(
        dataToUpdate.password,
        BCRYPT_ROUNDS_USER_CREATION,
      );
    }
    return dataToUpdate;
  }

  private removePassword<T>(entity: T): Omit<T, 'password'> {
    if (entity && typeof entity === 'object' && 'password' in entity) {
      const { password, ...rest } = entity as any;
      return rest;
    }
    return entity as Omit<T, 'password'>;
  }
}

Exemplo de uso em Repositories (Infrastructure Layer):

// src/infrastructure/repositories/prisma-user.repository.ts

import { handlePrismaError, PrismaErrorCode } from '@/common/utils/prisma-error-handler';

@Injectable()
export class PrismaUserRepository implements IUserRepository {
  async create(data: Omit<UserEntity, 'id' | 'createdAt' | 'updatedAt'>) {
    try {
      return await this.prisma.user.create({ data });
    } catch (error) {
      // Repository trata erros Prisma e lança exceções de negócio
      handlePrismaError(error, {
        [PrismaErrorCode.UNIQUE_CONSTRAINT_VIOLATION]: 'Email já está em uso.',
      });
    }
  }

  async partialUpdate(id: number, data: Partial<UserEntity>) {
    try {
      return await this.prisma.user.update({
        where: { id },
        data,
      });
    } catch (error) {
      handlePrismaError(error, {
        [PrismaErrorCode.UNIQUE_CONSTRAINT_VIOLATION]: 'Email já cadastrado',
        [PrismaErrorCode.RECORD_NOT_FOUND]: `Usuário com ID ${id} não encontrado.`,
      });
    }
  }
}

Benefícios:

  • ✅ DRY (Don't Repeat Yourself): Elimina duplicação de código de tratamento de erros
  • ✅ Consistência: Garante mensagens de erro padronizadas em todo o sistema
  • ✅ Customização: Permite mensagens específicas por contexto (create vs update)
  • ✅ Extensibilidade: Fácil adicionar tratamento para novos códigos Prisma
  • ✅ Type-Safety: Enum PrismaErrorCode previne erros de digitação

Mapeamento de Erros do Prisma:

Código Prisma HTTP Status Exception Lançada Mensagem Padrão Exemplo de Uso
P2002 409 BusinessException "{campo} já está em uso." UsersService.create() com email duplicado
P2025 404 EntityNotFoundException "{modelo} não encontrado." findUniqueOrThrow em registro inexistente
P2003 400 BusinessException "Referência inválida..." DailyCollection com userId inválido
P2004 400 BusinessException "Operação violou restrição..." Constraint check failure
Outros - Re-lançado - Erro original preservado

Exception Customizada: EntityNotFoundException

Para complementar o BusinessException, o projeto implementa EntityNotFoundException para casos específicos onde uma entidade não é encontrada no banco de dados.

Localização: src/common/exceptions/entity-not-found.exception.ts

Implementação:

// src/common/exceptions/entity-not-found.exception.ts
import { HttpException, HttpStatus } from '@nestjs/common';

export class EntityNotFoundException extends HttpException {
  constructor(message: string) {
    super(message, HttpStatus.NOT_FOUND);
  }
}

Quando usar:

  • ✅ Quando uma entidade específica não é encontrada por ID
  • ✅ Em métodos findOne, update, remove de Services
  • ✅ Para fornecer mensagens descritivas com o ID não encontrado

Exemplos de uso em Services:

// AnimalsService
async findOne(id: number) {
  const animal = await this.animalRepository.findById(id);
  if (!animal) {
    throw new EntityNotFoundException(`Animal com ID ${id} não encontrado.`);
  }
  return animal;
}

// DailyCollectionsService
async findOne(id: number) {
  const collection = await this.dailyCollectionRepository.findById(id);
  if (!collection) {
    throw new EntityNotFoundException(`Coleta diária com ID ${id} não encontrada.`);
  }
  return collection;
}

// UsersService
private async validateUser(userId: number) {
  const user = await this.userRepository.findById(userId);
  if (!user) {
    throw new EntityNotFoundException(`Usuário com ID ${userId} não encontrado.`);
  }
  return user;
}

Resposta HTTP:

{
  "statusCode": 404,
  "message": "Animal com ID 999 não encontrado.",
  "timestamp": "2025-11-22T20:15:30.123Z",
  "path": "/animals/999"
}

Diferença vs NotFoundException do NestJS:

Aspecto EntityNotFoundException NotFoundException (NestJS)
Semântica Específica para entidades de domínio Genérica para qualquer recurso não encontrado
Mensagem Customizada com ID e tipo de entidade Genérica
Testabilidade Fácil identificar em testes Menos específica
Rastreabilidade Clara no contexto de domínio Pode ser ambígua

Hierarquia de Exceções:

HttpException (NestJS)
├── BusinessException (regras de negócio - 400)
├── EntityNotFoundException (entidade não encontrada - 404)
└── [Exceções padrão do NestJS]
    ├── NotFoundException
    ├── UnauthorizedException
    ├── ConflictException
    └── ...

Mensagens de Erro Amigáveis

O projeto implementa as seguintes exceções customizadas para padronizar erros:

1. BusinessException

Para erros de regra de negócio e validações.

Implementação real:

// src/common/exceptions/business.exception.ts
import { HttpException, HttpStatus } from "@nestjs/common";

export class BusinessException extends HttpException {
  constructor(message: string, status: HttpStatus = HttpStatus.BAD_REQUEST) {
    super({ message, error: "BusinessException" }, status);
  }
}

Exemplo de uso:

// Uso em regras de negócio

if (new Date(dto.date) > new Date()) {
  throw new BusinessException("Data não pode ser futura");
}

Exemplo de resposta:

{
  "statusCode": 400,
  "message": "Produtor não vinculado",
  "error": "BusinessException"
}

Vantagens:

  • Padroniza mensagens de erro de negócio
  • Facilita internacionalização e testes
  • Permite distinguir erros de regra de negócio dos demais

Tratamento de Erros Assíncronos

Código Real (InviteEmailListener):

// backend/src/listener/invite-email.listener.ts
@Injectable()
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,
      );
    }
  }

Código Real (EmailListener com retry):

// backend/src/listener/email.listener.ts
@Injectable()
export class EmailListener {
  private readonly logger = new Logger(EmailListener.name);
  constructor(
    private readonly mailService: MailService,
    private readonly failedEmailRepository: IFailedEmailRepository,
  ) {}

  @OnEvent('notification.send')
  async handleNotificationSend(payload: NotificationSendPayload) {
    await this.safeSendEmail(payload, 1);
  }

  private async safeSendEmail(
    payload: NotificationSendPayload,
    attempt: number,
  ) {
    try {
      this.logger.log(
        `Tentativa ${attempt} de enviar email para ${payload.to}...`,
      );

      await this.mailService.sendNotificationEmail(
        payload.to,
        payload.subject,
        payload.message,
        payload.userName,
        payload.metadata,
      );

      this.logger.log(
        `Email enviado com sucesso para ${payload.to} na tentativa ${attempt}.`,
      );
    } catch (error) {
      this.logger.error(
        `Erro na Tentativa ${attempt} para ${payload.to}:`,
        error,
      );

      if (attempt < MAX_RETRIES) {
        const delayTime = DELAY_MS * attempt; // 2s, 4s, 6s
        this.logger.log(
          `Aguardando ${delayTime}ms antes da próxima tentativa...`,
        );
        await new Promise((resolve) => setTimeout(resolve, delayTime));

        await this.safeSendEmail(payload, attempt + 1);
      } else {
        this.logger.error(
          `Falha final ao enviar email para ${payload.to} após ${MAX_RETRIES} tentativas. Salvando na DLQ...`,
        );

        try {
          await this.failedEmailRepository.create({
            payload: {
              to: payload.to,
              subject: payload.subject,
              template: 'notification',
              context: {
                userName: payload.userName,
                subject: payload.subject,
                message: payload.message,
                metadata: payload.metadata,
              },
            },
            errorReason: error instanceof Error ? error.message : String(error),
            retryCount: MAX_RETRIES,
          });
          this.logger.log(`Email falho salvo na DLQ com sucesso.`);
        } catch (dlqError) {
          this.logger.error(
            `CRÍTICO: Falha ao salvar email na DLQ!`,
            dlqError,
          );
        }
      }
    }
  }
}

Dead Letter Queue (DLQ) para Emails Falhados

Dead Letter Queue

Motivação:

Quando o envio de email falha após todas as tentativas de retry, o sistema precisa preservar essas informações para análise posterior e possível reenvio manual. A DLQ (Dead Letter Queue) armazena emails que falharam definitivamente.

Modelo de Dados:

// src/domain/entities/failed-email.entity.ts
export interface EmailPayload {
  to: string;
  subject: string;
  template: string;
  context: Record<string, any>;
}

export class FailedEmail {
  id: string;
  payload: EmailPayload;
  errorReason: string;
  retryCount: number;
  createdAt: Date;
  updatedAt: Date;
}

Schema Prisma:

model FailedEmail {
  id          String   @id @default(uuid())
  payload     Json     
  errorReason String   
  retryCount  Int      @default(0)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  @@map("failed_emails")
}

Características:

  • Payload Genérico: Armazena template e contexto, permitindo reenvio de qualquer tipo de email
  • Rastreabilidade: Registra motivo da falha e número de tentativas
  • Resiliência: Falha ao salvar na DLQ não quebra o fluxo principal (apenas loga erro crítico)
  • Testado: Cobertura de testes unitários valida salvamento correto na DLQ

Benefícios:

  • Nenhum email perdido, mesmo em falhas críticas de infraestrutura
  • Permite análise de padrões de falha (ex: domínios bloqueados, SMTP offline)
  • Facilita reenvio manual ou automático via job agendado
  • Auditoria completa de falhas de comunicação

Validação em Camadas

Estratégia: Validar dados em múltiplas camadas para garantir consistência.

Validation layers

Exemplo de Código (Validação em Camadas):

// Camada 1: DTO (formato)
export class CreateDailyCollectionDto {
  @IsNumber()
  userId: number;

  @IsDateString()
  date: string;

  @IsPositive()
  quantity: number; // > 0
}


async create(dto: CreateDailyCollectionDto) {
  const user = await this.usersService.findOne(dto.userId);

  if (new Date(dto.date) > new Date()) {
    throw new BusinessException('Data não pode ser futura');
  }

  return this.prisma.dailyCollection.create({ data: dto });
}

// Camada 3: Database (constraints)
// @@unique([userId, date]) no schema Prisma

8.6 Estratégia de Consultas (Specification Pattern Simplificado) {#estrategia_consultas}

Para manter a flexibilidade e o desacoplamento, adotamos o padrão de objetos de critério (Specification Pattern simplificado).

Diagrama do Fluxo Criteria

Descrição do Processo:

  1. Construção: O Service monta um objeto Criteria contendo apenas os dados necessários para o filtro (ex: ID da associação, intervalo de datas).
  2. Contrato: Este objeto não possui dependência de bibliotecas de banco de dados (Prisma/TypeORM), mantendo a camada de domínio limpa.
  3. Tradução: O Repositório concreto lê as propriedades do Criteria e as converte dinamicamente para o formato Prisma.WhereInput, aplicando as cláusulas necessárias antes de consultar o banco.

Exemplo de Contrato (Domain):

// src/domain/criteria/daily-collection.criteria.ts
export interface DailyCollectionCriteria {
  associationId?: number;
  userId?: number;
  dateRange?: {
    start: Date;
    end: Date;
  };
  includeUser?: boolean;
}

Exemplo de Tradução (Infrastructure):

// src/infrastructure/repositories/prisma-animal.repository.ts
async findAll(criteria: AnimalCriteria = {}): Promise<AnimalEntity[]> {
    const where: Prisma.AnimalWhereInput = {};

    where.status = criteria.status !== undefined ? (criteria.status as PrismaStatus) : PrismaStatus.Active;

    if (criteria.userId) {
      where.userId = criteria.userId;
    }

    if (criteria.associationId) {
      where.user = {
        associationId: criteria.associationId,
      };
    }

    if (criteria.animalType) {
      where.animalType = criteria.animalType as any;
    }

    const include: Prisma.AnimalInclude = {};
    if (criteria.includeUser) {
      include.user = true;
    }

    const animals = await this.prisma.animal.findMany({
      where,
      include: Object.keys(include).length > 0 ? include : undefined,
      orderBy: { createdAt: 'desc' },
    });

    return animals.map(AnimalMapper.toDomain);
  }

Benefícios:

  • Desacoplamento: A camada de aplicação não conhece a estrutura do banco ou o ORM.
  • Flexibilidade: É fácil adicionar novos filtros sem alterar a assinatura dos métodos do repositório.
  • Testabilidade: Facilita a criação de mocks para os repositórios, pois os critérios são objetos simples.

Clone this wiki locally