1. Defina um DTO de filtro que implemente GenericFilterDTO

public class FuncionarioFilterDTO implements GenericFilterDTO {
  @Filterable(operation = Filterable.FilterOperation.LIKE)
  private String nome;

  @Filterable(operation = Filterable.FilterOperation.EQUAL)
  private String departamento;

  // getters/setters
}

2. O service base resolve as Specifications automaticamente

public class FuncionarioService extends AbstractBaseCrudService<Funcionario, FuncionarioDTO, Long, FuncionarioFilterDTO> {
  public FuncionarioService(BaseCrudRepository<Funcionario, Long> repo, Class<Funcionario> entityClass) {
    super(repo, entityClass);
  }
}

3. Utilize os endpoints de filtragem do controller base

POST /api/human-resources/funcionarios/filter?page=0&size=20
Content-Type: application/json

{ "nome": "ana", "departamento": "RH" }

• Se o parâmetro sort não for informado, aplica-se a ordenação padrão definida pela entidade (@DefaultSortColumn).
• Para ordenar explicitamente: ?sort=nome,asc&sort=departamento,desc.

• Mantenha os tipos do DTO de filtro coerentes com os campos da entidade/DTO
• Prefira operações específicas (EQUAL, LIKE, BETWEEN) para resultados previsíveis
• Limite o size conforme sua política de performance

• Propriedade praxis.filter.range.allow-scalar-payload:
  • false (padrão): payload escalar de range é inválido e retorna 400.
  • true: fallback temporário para legado, convertendo escalar para lista.
• Propriedade praxis.filter.range.log-legacy-scalar-payload:
  • true (padrão): registra uso de payload escalar legado para plano de migração.
• Erros de payload de filtro retornam 400 com errors[].properties.code = FILTER_PAYLOAD_INVALID.

• Expressivo e seguro: você declara no DTO e o Starter gera a Specification JPA correta.
• Cobertura completa (26 operações): de LIKE/IN/BETWEEN a datas relativas (últimos/próximos N dias) e tamanho de coleções.
• Relações sem dor: use relation="a.b.campo" para navegar por joins de forma legível.
• Ordem previsível: integrado à ordenação padrão e ao PageableBuilder para requests consistentes.

Dicas de UI para filtros com enums grandes

• array de enum com muitas opções: o resolver publica multiSelect como contrato principal.
• Enums pequenos (≤5) tendem a usar radio/chipInput; médios select; grandes autoComplete/multiSelect.

Enums em SELECTs (sem endpoint)

• Campos enum não precisam de endpoint: as opções são derivadas diretamente do schema OpenAPI (o array enum).
• Para array de enum, o schema é “array de enum” e a UI renderiza multi‑select automaticamente.
• Use endpoint (/options/filter) apenas para catálogos dinâmicos/relacionais (id/label), não para enum estático.
• No Angular, endpoint é normalizado para resourcePath, e displayField/valueField são normalizados para optionLabelKey/optionValueKey.
• Para catálogos remotos enterprise, prefira publicar endpoint=/{resource}/options/filter, valueField="id" e displayField="label" de forma explícita.

Lote 2 — Intervalos/Data/Lista/Coleção/Booleanos

Lote 1 (Core) — Operações Adicionadas

Notas: - Para ON_DATE, use LocalDate no DTO. A comparação considera o intervalo [início do dia, início do dia seguinte). - Para IN_LAST_DAYS/IN_NEXT_DAYS, o valor é relativo ao horário atual (UTC) e converte para Instant. - Para SIZE_*, aplique apenas em atributos de coleção (OneToMany/ManyToMany); o builder usa CriteriaBuilder.size. - Requisito de coleção em SIZE_*: defina relation para apontar explicitamente para o atributo de coleção na entidade. Se o caminho não for coleção, o builder lança erro informativo. - Para novos componentes compactos de superfície, prefira controlType canônico com a família INLINE_*.

Notas de Timezone

• ON_DATE, IN_LAST_DAYS e IN_NEXT_DAYS utilizam normalização com Instant e horário atual do backend. Em ambientes multi‑região, verifique a zona padrão da aplicação e do banco. Recomenda‑se padronizar em UTC.

Notas: - Operações com ci (case-insensitive) normalizam usando lower(). - Para IS_NULL/IS_NOT_NULL, sugere-se modelar no DTO como Boolean campoIsNull; quando true, o predicado é aplicado. - Para IS_TRUE/IS_FALSE, o predicado é aplicado quando o campo do DTO está presente (não nulo). Recomenda‑se enviar true para indicar que o predicado deve ser considerado.

DTO de filtro (vendas)

import org.praxisplatform.uischema.filter.annotation.Filterable;
import java.time.LocalDate;
import java.util.List;

public class VendaFilterDTO implements org.praxisplatform.uischema.filter.dto.GenericFilterDTO {
  @Filterable(operation = Filterable.FilterOperation.LIKE)
  private String cliente;

  @Filterable(operation = Filterable.FilterOperation.GREATER_OR_EQUAL)
  private java.math.BigDecimal valorMin;

  @Filterable(operation = Filterable.FilterOperation.LESS_OR_EQUAL)
  private java.math.BigDecimal valorMax;

  @Filterable(operation = Filterable.FilterOperation.BETWEEN)
  private List<LocalDate> emissaoEntre; // [de, ate]

  @Filterable(operation = Filterable.FilterOperation.IN)
  private List<String> canais; // ["ONLINE","LOJA"]

  @Filterable(operation = Filterable.FilterOperation.LIKE, relation = "vendedor.nome")
  private String vendedorNome;

  @Filterable(operation = Filterable.FilterOperation.IS_TRUE)
  private Boolean pago;
}

POST /api/vendas/filter?page=0&size=20
Content-Type: application/json

{
  "cliente": "maria",
  "valorMin": 100.00,
  "valorMax": 1000.00,
  "emissaoEntre": ["2024-01-01", "2024-12-31"],
  "canais": ["ONLINE", "LOJA"],
  "vendedorNome": "silva",
  "pago": true
}

• 26 operações prontas de filtro — sem escrever Specifications na mão
• Até 18 operações públicas por recurso — CRUD, filtros, paginação por cursor, options id/label, option-sources, stats e schemas
• Redução de ~97% no payload da documentação por grupo OpenAPI — com cache inteligente

Resultado: menos boilerplate, tempo de entrega menor e APIs/UX mais consistentes — alinhadas com as melhores práticas do ecossistema Spring + OpenAPI.

Sugestoes de combinacao para FilterDTO sem depender de app externo:

• use IN e NOT_IN para listas de enums ou status
• use ON_DATE e IN_LAST_DAYS para datas operacionais
• use relation = "relacao.id" para filtros sobre relacionamento
• use BETWEEN para ranges numericos e datas

Exemplos tipicos:

• statusIn com IN
• statusNotIn com NOT_IN
• dataEventoOnDate com ON_DATE
• dataEventoInLastDays com IN_LAST_DAYS
• categoriaId com EQUAL e relation = "categoria.id"

• IN (lista de enums):

POST /api/human-resources/missoes/filter
Content-Type: application/json

{ "statusIn": ["ABERTA", "EM_ANDAMENTO"] }

• NOT_IN (excluir enums):

POST /api/human-resources/veiculos/filter
Content-Type: application/json

{ "statusNotIn": ["INATIVO"] }

• ON_DATE (comparação por data, campo OffsetDateTime no backend):

POST /api/human-resources/incidentes/filter
Content-Type: application/json

{ "ocorridoEmOn": "2025-03-01" }

• IN_LAST_DAYS (datas relativas):

POST /api/human-resources/sinais-socorro/filter
Content-Type: application/json

{ "abertoEmLastDays": 7 }

• @Filterable
• GenericSpecificationsBuilder
• PageableBuilder
• Ordenação Padrão