// Código legado: verboso, inseguro e difícil de manter
public class VeiculoDAO {
    public Optional<Veiculo> buscarPorPlaca(String placa) throws Exception {
        JapeWrapper dao = JapeFactory.dao("Veiculo");
        // Concatenação de strings é perigosa e propensa a erros
        Collection<DynamicVO> vos = dao.find("PLACA = '" + placa + "'");

        if (vos.isEmpty()) {
            return Optional.empty();
        }
        // Conversão manual de DynamicVO para POJO
        DynamicVO vo = vos.iterator().next();
        Veiculo veiculo = new Veiculo();
        veiculo.setId(vo.asLong("CODVEICULO"));
        veiculo.setPlaca(vo.asString("PLACA"));
        return Optional.of(veiculo);
    }
}

// Código moderno: seguro, declarativo e sem boilerplate
@Repository
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    
    @Criteria("ativo = :ativo AND v.marca = :nomeMarca")
    List<Veiculo> findAtivosPorMarca(
        @Parameter("ativo") boolean ativo, 
        @Parameter("nomeMarca") String nomeMarca
    );

    @Criteria(clause = "ATIVO = :ativo")
    Page<Veiculo> findByAtivoPaginado(Boolean ativo, Pageable pageable);
}

// Uso no serviço:
@Service
public class VeiculoService {
    private final VeiculoRepository repository;

    @Inject
    public VeiculoService(VeiculoRepository repository) {
        this.repository = repository;
    }

    public Optional<Veiculo> buscarPorPlaca(String placa) {
        // Simples, direto e seguro.
        return repository.findByPlaca(placa);
    }
    
    public Page<Veiculo> buscarAtivosPaginados(String nomeMarca) {
        //Objeto de paginação número da página, tamanho da página e argumentos para paginação
        PageRequest pageRequest = PageRequest.of(0, 10, Sort.by("NOME", Direction.DESC), Sort.by("PLACA", Direction.DESC));
        return repository.findByAtivoPaginado(nomeMarca, pageRequest);
    }
}

import br.com.sankhya.sdk.data.repository.JapeRepository;
import br.com.sankhya.studio.stereotypes.Repository;

@Repository
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    // Seus métodos de consulta customizados virão aqui
}

@Criteria(clause = "CAMPO = :parametro")
ReturnType nomeDoMetodo(TipoParametro parametro);

@NativeQuery("SELECT CAMPO1, CAMPO2 FROM MINHA_TABELA WHERE CAMPO = :parametro")
List<MeuDTO> nomeDoMetodo(@Parameter("parametro") TipoParametro parametro);

@NativeQuery(value = "SELECT CAMPO_NVARCHAR FROM MINHA_TABELA", method = ResultSetMethods.GET_N_STRING)
String buscarComNString();

@NativeQuery(value = "SELECT CAMPO_VARCHAR FROM MINHA_TABELA", method = ResultSetMethods.GET_STRING)
String buscarComString();

@Repository
public interface PedidoRepository extends JapeRepository<Pedido, Long> {
    @NativeQuery("SELECT COUNT(1) FROM TGFCAB WHERE STATUS = 'P'")
    Long contarPendentes(JdbcWrapper jdbc);
}

// Uso dentro de um listener:
@Listener(instanceNames = {"CabecalhoNota"})
@RequiredArgsConstructor(onConstructor_ = @Inject)
public class MeuListener extends PersistenceEventAdapter {

    private final PedidoRepository repository;

    @Override
    public void afterInsert(PersistenceEvent event) throws Exception {
        // Reutiliza a conexão da transação do listener
        JdbcWrapper jdbc = event.getJdbcWrapper();
        Long pendentes = repository.contarPendentes(jdbc);
        // ...
    }
}

@Modifying
@NativeQuery("UPDATE TGFPRO SET ATIVO = 'N' WHERE CODGRUPOPROD = :grupo")
int desativarProdutosPorGrupo(@Parameter("grupo") Long grupo);

@Repository
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    
    @NativeQuery(value = "queries/listar-veiculos-ativos.sql", fromFile = true)
    List<VeiculoView> listarAtivos(@Parameter("ativo") String ativo);
}

SELECT 
    v.CODVEI,
    v.PLACA,
    v.DESCRICAO,
    v.ATIVO,
    v.DHINC
FROM TGFVEI v
WHERE v.ATIVO = :ativo
  AND v.DHINC >= :dataInicio
ORDER BY v.DESCRICAO

@Repository
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    @NativeQuery(value = "queries/listar-veiculos-ativos.sql", fromFile = true)
    List<VeiculoView> listarAtivos(
        @Parameter("ativo") String ativo,
        @Parameter("dataInicio") LocalDate dataInicio
    );
}

<sql>
    <both>
        SELECT 
            CAB.NUNOTA,
            CAB.DTNEG,
            PAR.NOMEPARC,
            CAB.VLRNOTA
        FROM TGFCAB CAB
        JOIN TGFPAR PAR ON CAB.CODPARC = PAR.CODPARC
        WHERE CAB.DTNEG BETWEEN :dataInicio AND :dataFim
    </both>
</sql>

@NativeQuery(value = "queries/relatorio-vendas.xml", fromFile = true)
List<RelatorioVendasDTO> gerarRelatorio(
    @Parameter("dataInicio") LocalDate inicio,
    @Parameter("dataFim") LocalDate fim
);

<sql>
    <oracle>
        SELECT NVL(SUM(ITE.QTDNEG), 0) AS TOTAL
        FROM TGFITE ITE
        WHERE ITE.CODPROD = :codProd
    </oracle>
    <mssql>
        SELECT ISNULL(SUM(ITE.QTDNEG), 0) AS TOTAL
        FROM TGFITE ITE
        WHERE ITE.CODPROD = :codProd
    </mssql>
</sql>

<sql>
    <!-- Prioridade 1: Usada sempre que preenchida -->
    <both>SELECT COUNT(*) FROM TABELA</both>
    
    <!-- Prioridade 2: Ignoradas se <both> existe -->
    <oracle>SELECT COUNT(1) FROM TABELA</oracle>
    <mssql>SELECT COUNT(1) FROM TABELA</mssql>
</sql>

SELECT * FROM TGFVEI 
WHERE ATIVO = :ativo 
  AND CODVEI > :codVei
  AND MARCA = :marca

@NativeQuery(value = "queries/buscar-veiculos.sql", fromFile = true)
List<Veiculo> buscar(
    @Parameter("ativo") String ativo, 
    @Parameter("codVei") Long codVei,
    @Parameter("marca") String marca
);

try {
    List<VeiculoView> veiculos = repository.listarAtivos("S");
} catch (InvalidQueryFileException e) {
    // XML mal formado ou query não aplicável ao banco
    logger.error("Query file inválido: " + e.getMessage());
}

@Repository
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    
    // Busca por placa específica
    @Criteria(clause = "PLACA = :placa")
    Optional<Veiculo> findByPlaca(String placa);
    
    // Busca por status ativo
    @Criteria(clause = "ATIVO = :ativo")
    List<Veiculo> findByAtivo(Boolean ativo);

    // Busca por status ativo com NativeQuery e DTO
    @NativeQuery("SELECT CODVEICULO, PLACA FROM TGFVEI WHERE MODELO = :modelo")
    List<VeiculoDTO> findByModeloNativo(@Parameter("modelo") String modelo);
}

@NativeQuery.Result
interface VeiculoDTO {
    Long getCodVeiculo();
    String getPlaca();
}

@Repository
public interface PedidoRepository extends JapeRepository<Long, Pedido> {
    
    // Busca por empresa e status
    @Criteria(clause = "CODEMP = :empresa AND STATUS = :status")
    List<Pedido> findByEmpresaAndStatus(Long empresa, String status);
    
    // Busca com parâmetros nomeados explicitamente
    @Criteria(clause = "CODEMP = :COD_EMP AND DTNEG BETWEEN :dataInicio AND :dataFim")
    List<Pedido> findByPeriodo(
        @Parameter(name = "COD_EMP") Long codigoEmpresa,
        @Parameter(name = "dataInicio") LocalDate inicio,
        @Parameter(name = "dataFim") LocalDate fim
    );

    // Busca com NativeQuery e DTO
    @NativeQuery("SELECT NUNOTA, VLRNOTA FROM TGFCAB WHERE CODEMP = :empresa AND STATUS = :statusPedido")
    List<PedidoDTO> findByEmpresaAndStatusNativo(
        @Parameter("empresa") Long empresa, 
        @Parameter("statusPedido") String status
    );
}

@NativeQuery.Result
interface PedidoDTO {
    Long getNuNota();
    BigDecimal getVlrNota();
}

@Repository
public interface ProdutoRepository extends JapeRepository<Long, Produto> {
    
    // Busca com LIKE
    @Criteria(clause = "DESCRPROD LIKE :termo")
    List<Produto> findByDescricaoContaining(String termo);
    
    // Busca com IN
    @Criteria(clause = "CODPROD IN :codigos")
    List<Produto> findByCodigos(List<Long> codigos);
    
    // Busca com comparação numérica e NativeQuery
    @NativeQuery("SELECT CODPROD, DESCRPROD FROM TGFPRO WHERE VLRVENDA >= :valorMinimo")
    List<ProdutoDTO> findByValorMinimoNativo(@Parameter("valorMinimo") BigDecimal valorMinimo);
}

@NativeQuery.Result
interface ProdutoDTO {
    Long getCodProd();
    String getDescrProd();
}

@Repository
public interface NotaRepository extends JapeRepository<Long, Nota> {
    
    // Usando função UPPER
    @Criteria(clause = "UPPER(NOMEPARC) = UPPER(:nome)")
    List<Nota> findByNomeParceiroCaseInsensitive(String nome);
    
    // Usando CONCAT com NativeQuery
    @NativeQuery("SELECT NUNOTA, CODTIPOPER FROM TGFCAB WHERE CONCAT(CODPARC, ' - ', NOMEPARC) LIKE :busca")
    List<NotaDTO> findByCodigoOuNomeParcNativo(@Parameter("busca") String busca);
}

@NativeQuery.Result
interface NotaDTO {
    Long getNuNota();
    Long getCodTipoOper();
}

@Repository
public interface MovimentacaoRepository extends JapeRepository<Long, Movimentacao> {
    
    // Usando macro dbDate()
    @Criteria(clause = "DTMOV = dbDate()")
    List<Movimentacao> findByDataAtual();
    
    // Usando macro com NativeQuery
    @NativeQuery("SELECT NUFIN, NUNOTA FROM TGFFIN WHERE DTMOV = dbDate()")
    List<MovimentacaoDTO> findByDataAtualNativo();
}

@NativeQuery.Result
interface MovimentacaoDTO {
    Long getNuFin();
    Long getNuNota();
}

@Repository
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    
    // Busca páginada por status ativo
    @Criteria(clause = "ATIVO = :ativo")
    Page<Veiculo> findByAtivoPaginado(Boolean ativo, Pageable pageable);
}

@Component
public class VeiculoService {

    private final VeiculoRepository repository;

    @Inject
    public VeiculoService(VeiculoRepository repository) {
        this.repository = repository;
    }

    public Page<Veiculo> buscarPorAtivoPaginado(Boolean ativo) {
        if (ativo == null) {
            throw new IllegalArgumentException("Ativo não pode ser nulo. Valores aceitos: true ou false");
        }
        // page: número da página (inicia em 0)
        // size: tamanho da página (mínimo 1)
        // sort: se não informado, ordena por ID de forma crescente.
        int page = 0;
        int size = 10;
        PageRequest pageRequest = PageRequest.of(page, size, Sort.by("PLACA", Direction.DESC));
        return repository.findByAtivoPaginado(ativo, pageRequest);
    }
}

// Chave primária composta
@Embeddable
public class ItemNotaPK {
    @Column(name="NUNOTA")
    private Long numeroUnico;
    
    @Column(name="SEQUENCIA")
    private Long sequenciaItem;
    // getters e setters
}

// Entidade
@JapeEntity(entity="ItemNota", table="TGFITE")
public class ItemNota {
    @Id
    private ItemNotaPK id;
    
    @Column(name="CODPROD")
    private Long codProduto;
    
    @Column(name="CODVOL")
    private String unidadeMedida;
    // getters e setters
}

// Repositório
@Repository
public interface ItemNotaRepository extends JapeRepository<ItemNota, ItemNotaPK> {
    // Métodos CRUD para chave composta funcionam automaticamente
}

// ❌ NÃO SUPORTADO - Query methods do Spring
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    List<Veiculo> findByPlacaStartingWith(String prefix); // Não funciona
}

// ✅ SUPORTADO - Use @Criteria ou @NativeQuery
public interface VeiculoRepository extends JapeRepository<Long, Veiculo> {
    @Criteria(clause = "PLACA LIKE :prefix")
    List<Veiculo> findByPlacaStartingWith(@Parameter("prefix") String prefix);
}

@Repository
public interface ProdutoRepository extends JapeRepository<Long, Produto> {
    
    // ⚠️ ATENÇÃO: Retorna no máximo 500 registros (configuração padrão da sessão)
    @Criteria(clause = "ATIVO = 'S'")
    List<Produto> findAllAtivos();
}

// ✅ BOM: Nomes descritivos e consistentes
@Criteria(clause = "PLACA = :placa")
Optional<Veiculo> findByPlaca(String placa);

// ❌ RUIM: Nomes genéricos
@Criteria(clause = "PLACA = :placa")
Optional<Veiculo> buscar(String placa);

// ✅ BOM: Optional para resultados que podem não existir
@Criteria(clause = "CODPROD = :codigo")
Optional<Produto> findByCodigo(String codigo);

// ❌ RUIM: Pode lançar exceção ou retornar null, exigindo verificação extra
@Criteria(clause = "CODPROD = :codigo")
Produto findByCodigo(String codigo);

@Component
public class VeiculoService {
    private final VeiculoRepository repository;
    // ...
    
    // ✅ BOM: Validação antes da consulta
    public Optional<Veiculo> buscarPorPlaca(String placa) {
        if (placa == null || placa.trim().isEmpty()) {
            throw new IllegalArgumentException("Placa não pode ser vazia");
        }
        return repository.findByPlaca(placa.toUpperCase());
    }
}

// ❌ RUIM: Consulta pode retornar muitos registros e causar problemas de performance
@Criteria(clause = "1 = 1")
List<Produto> findAll();

// ✅ BOM: Consultas específicas com filtros obrigatórios
@Criteria(clause = "ATIVO = 'S' AND CODEMP = :empresa")
List<Produto> findAtivosByEmpresa(Long empresa);

// ❌ RUIM: @Modifying sem transação
public class LogService {
    public int limparLogsAntigos(LocalDate data) {
        // Pode falhar e deixar o banco em estado inconsistente
        return logRepository.excluirLogsExpirados(data);
    }
}

// ✅ BOM: @Modifying dentro de uma transação
@Component
public class LogService {
    @Transactional
    public int limparLogsAntigos(LocalDate data) {
        return logRepository.excluirLogsExpirados(data);
    }
}

// ❌ RUIM: Lógica de negócio no repositório
@Repository
public interface PedidoRepository extends JapeRepository<Long, Pedido> {
    default void aprovarPedido(Long nunota) {
        // ... lógica para aprovar ...
    }
}

// ✅ BOM: Lógica no serviço
@Component
public class PedidoService {
    private final PedidoRepository repository;
    // ...
    @Transactional
    public void aprovarPedido(Long nunota) {
        Pedido pedido = repository.findById(nunota).orElseThrow(...);
        // ... lógica para aprovar ...
        repository.save(pedido);
    }
}

// --- Entidade ---
@JapeEntity(entity = "CabecalhoNota", table = "TGFCAB")
@Data
public class Pedido {
    @Id @Column(name = "NUNOTA")
    private Long numero;
    @Column(name = "CODPARC")
    private Long codigoCliente;
    @Column(name = "VLRNOTA")
    private BigDecimal valor;
    @Column(name = "STATUS")
    private String status; // "R" = Rascunho, "A" = Aprovado
    @Column(name = "DHALTER")
    private LocalDateTime dataAlteracao;
}

// --- DTO ---
@NativeQuery.Result
public interface PedidoResumoDTO {
    Long getNumero();
    BigDecimal getValor();
}

// --- Repositório ---
@Repository
public interface PedidoRepository extends JapeRepository<Pedido, Long> {
    
    @Criteria(clause = "CODPARC = :codigoCliente")
    List<Pedido> findByCliente(@Parameter("codigoCliente") Long codigoCliente);
    
    @NativeQuery("SELECT NUNOTA as numero, VLRNOTA as valor FROM TGFCAB WHERE STATUS = :status AND CODEMP = :empresa")
    List<PedidoResumoDTO> findResumoPorStatus(
        @Parameter("status") String status, 
        @Parameter("empresa") Long empresa
    );
    
    @Modifying
    @NativeQuery("DELETE FROM TGFCAB WHERE STATUS = 'R' AND DHALTER < :dataLimite")
    int deleteRascunhosAntigos(@Parameter("dataLimite") LocalDateTime dataLimite);
}

// --- Serviço ---
@Component
public class PedidoService {
    
    private final PedidoRepository pedidoRepository;
    
    @Inject
    public PedidoService(PedidoRepository pedidoRepository) {
        this.pedidoRepository = pedidoRepository;
    }
    
    @Transactional
    public void limparRascunhosAntigos() {
        LocalDateTime dataLimite = LocalDateTime.now().minusDays(30);
        int removidos = pedidoRepository.deleteRascunhosAntigos(dataLimite);
        System.out.println("Removidos " + removidos + " rascunhos antigos.");
    }
    
    public List<Pedido> buscarPedidosDoCliente(Long codigoCliente) {
        if (codigoCliente == null) {
            throw new IllegalArgumentException("Código do cliente é obrigatório.");
        }
        return pedidoRepository.findByCliente(codigoCliente);
    }
}