refactor: auditar validações preflight das funcionalidades

[zxkaren]

Objetivo

Revisar as funcionalidades da DocTools API para garantir que erros previsíveis sejam identificados antes do início do processamento.

A API deve seguir o princípio de fail fast:

requisição
→ validação dos parâmetros
→ validação de todos os arquivos
→ processamento
→ resposta

Funcionalidades

• Merge PDF
• Split PDF
• Extract Text
• Compare
• OCR PDF

Cada funcionalidade deverá ser revisada em uma branch própria.

Pontos de validação

Verificar, quando aplicável:

• ausência ou quantidade inválida de arquivos;
• extensão não permitida;
• arquivo vazio, corrompido ou incompatível com a extensão;
• documento protegido ou sem conteúdo processável;
• parâmetros, páginas, intervalos, packs ou ordenações inválidas;
• limites de tamanho ou quantidade excedidos;
• dependências essenciais indisponíveis.

Processamento em lote

Todos os arquivos da requisição devem ser validados antes que o primeiro seja processado.

arquivos recebidos
→ validação completa do lote
→ arquivo inválido encontrado
→ nenhum processamento iniciado

Testes esperados

• Confirmar que o processador não é chamado após uma falha de validação.
• Confirmar que nenhum resultado parcial é criado.
• Confirmar a remoção de arquivos temporários quando necessário.
• Garantir que entradas válidas continuam funcionando.
• Executar a suíte completa sem regressões.

Critérios de aceite

• Erros previsíveis falham antes do processamento.
• Lotes são completamente validados antes da execução.
• Testes automatizados foram adicionados ou ampliados.
• README e CHANGELOG foram atualizados quando necessário.
• Testes manuais e automatizados foram concluídos com sucesso.
  Esses itens serão tratados após a conclusão da auditoria das validações preflight.