Entities, DTOs e Knex rows

O projeto usa três representações distintas dos dados, cada uma com responsabilidade clara.

Entity (APP)

• Instanciada pelo mapper a partir da linha do banco.
• Encapsula estado e comportamento (ex.: AttendanceEntity, QueueEntity).
• Retornada pelos gateways para os use cases.
• Não deve conhecer HTTP nem Knex.

DTO (Domain)

Input DTOs — validados pelo ValidationPipe:

export class ListAttendanceDTO {
  @ValidateNested()
  @Type(() => DateFilter)
  @IsOptional()
  attendanceStartedAt?: DateFilter;

  @IsEnum(ATTENDANCE_FIELD)
  field: ATTENDANCE_FIELD;
}

Response DTOs — usados principalmente para documentação Swagger (@ApiResponse({ type: ... })). O runtime frequentemente retorna objetos de getFriendlyObject() sem instanciar o DTO de response.

Decorators de domínio

src/domain/decorators/ fornecem validação reutilizável:

• IsDateString() — parse de datas no formato YYYY/MM/DD
• Outros decorators compostos com class-validator + class-transformer

Enums

src/domain/enums/ — valores compartilhados entre DTOs, use cases e infra:

• PERMISSION — usado por @Permission() e GCIPermissionGuard
• ATTENDANCE_FIELD, ORDER_TYPE, FLAG_OPTIONS, etc.

Fluxo de dados entre representações

HTTP JSON  →  DTO (validado)  →  UseCase
                                    ↓
                              Gateway método
                                    ↓
                              Knex row (INFRA)
                                    ↓
                              Mapper.toEntity()
                                    ↓
                              Entity (APP)
                                    ↓
                              getFriendlyObject()  →  JSON response

Próximos tópicos

• DefaultRepositoryGateway — mappers APP ↔ INFRA
• HTTP e GCI — validação de DTOs nos controllers