[API] Filtro de período no GET /events (matutino, vespertino, noturno)

[Ronildo22]

Filtro de período no GET /events

Contexto

A listagem pública de eventos já permite retornar todos os eventos e ordenar os resultados, mas ainda não permite filtrar por período do dia (turno), como matutino, vespertino e noturno.

Objetivo

Permitir filtrar a listagem via query param no GET /events:

• period — turno do evento (matutino, vespertino, noturno).

O parâmetro é opcional. Sem period, a listagem mantém o comportamento atual (incluindo ordenação padrão por data).

Exemplos de requisição e resposta

Query params (filtro)

Parâmetro	Tipo	Obrigatório?	Default	Descrição
period	string	Não	-	Filtra por turno do evento (matutino, vespertino, noturno).

Exemplo 1 - Sem filtro de período

Requisição:

GET /events

Resposta esperada (200): retorna todos os eventos, mantendo ordenação padrão atual.

Exemplo 2 - Com filtro de período

Requisição:

GET /events?period=noturno

Resposta esperada (200): retorna apenas eventos do período informado.

Exemplo 3 - Período inválido

Requisição:

GET /events?period=invalido

Resposta esperada: 400 Bad Request com mensagem de validação (ou fallback documentado em Swagger).

Comportamento esperado

• Sem period - mantém o retorno atual da listagem.
• Com period válido - retorna subset correto de eventos do turno informado.
• Com period inválido - retorna erro de validação (ou fallback documentado).
• Ordem de aplicação - aplicar filtro antes da ordenação/paginação quando coexistirem: filtrar -> ordenar -> paginar.

Tarefas

• Adicionar period? no DTO de query de listagem, com validação dos valores permitidos (matutino, vespertino, noturno).
• Implementar no EventsService.findAll() a lógica de filtro por período.
• Manter comportamento atual de ordenação por data quando period não for informado.
• Garantir compatibilidade do filtro com sort e order.
• Documentar no Swagger o parâmetro period, valores aceitos e comportamento para inválidos.
• Adicionar/atualizar testes unitários e e2e cobrindo casos com e sem filtro.

Critérios de aceite

• GET /events sem period mantém comportamento atual da listagem.
• GET /events?period=<valor_valido> retorna subset correto (somente eventos do turno solicitado).
• Resposta permanece em JSON com array de eventos.
• period inválido gera 400 (ou fallback explicitamente documentado).
• Filtro funciona em conjunto com ordenação existente.
• Swagger descreve period e valores suportados.