Importação IPL via API — ecosif-moviments

Objetivo

Este documento descreve a atualização do processo de importação IPL no ecosif-moviments. O objetivo é manter o mesmo comportamento funcional adotado no ecosif-automations para validação, relatório de importação, interpretação de débito/crédito e tratamento de contrapartida, mas com execução iniciada exclusivamente pelo consumo da API Java.

Inicialização do processo

O processo de importação neste serviço é iniciado somente pelo endpoint:

POST /importMoviment/{company}/{branch}/{fname}
Content-Type: text/plain

O corpo da requisição deve conter o conteúdo textual do arquivo IPL. Este módulo não deve iniciar a importação por gatilho de Lambda, evento S3 ou fila. Caso o arquivo tenha sido recebido por outro componente, esse componente deve chamar a API acima.

Regras de layout IPL

Cada linha válida deve possuir 156 caracteres. As posições relevantes são:

• Colunas 1 a 6: data do lançamento no formato ddMMyy.
• Colunas 7 a 12: número do lote.
• Colunas 13 a 17: número do lançamento.
• Coluna 18: tipo do lançamento, onde 1 significa lançamento simples e 2 significa lançamento com contrapartida.
• Coluna 19: marcador D ou C somente para lançamento simples.
• Colunas 20 a 25: conta reduzida principal.
• Colunas 26 a 29: código de histórico principal.
• Colunas 30 a 79: descrição do histórico principal.
• Colunas 80 a 85: conta reduzida de contrapartida, obrigatória somente para tipo 2.
• Colunas 86 a 89: código de histórico da contrapartida.
• Colunas 90 a 139: descrição do histórico da contrapartida.
• Colunas 140 a 156: valor do lançamento.

As regras aplicadas são as mesmas do ecosif-automations:

• Tipo 1 é lançamento simples. Deve informar D ou C na coluna 19 e não deve possuir dados de contrapartida.
• Tipo 2 é lançamento com contrapartida. A coluna 19 deve estar em branco e a conta de contrapartida deve estar preenchida.
• A conta reduzida é normalizada pelos 6 primeiros caracteres, ignorando dígitos ou sufixos posteriores.
• Histórico principal é validado quando informado.
• Histórico e conta de contrapartida são validados somente em linhas tipo 2.

Geração de lançamentos

No fluxo Java, a regra central fica em IplImportRules e é consumida pelo ImportReportController e pelo ImportReportDetailsServiceImpl.

Para lançamento simples (tipo 1), o serviço gera uma linha em ct_lancamento:

• D na coluna 19 totaliza como débito.
• C na coluna 19 totaliza como crédito.

Para lançamento com contrapartida (tipo 2), o serviço gera duas linhas em ct_lancamento:

• Uma linha de débito usando a conta principal e a contrapartida.
• Uma linha de crédito usando a conta de contrapartida e a conta principal.

Nesse caso, o valor totaliza tanto em débito quanto em crédito no lote.

Relatório e validações

O ecosif-moviments deve registrar o relatório de importação com as mesmas decisões de validação adotadas no ecosif-automations:

• Erro estrutural do IPL encerra o processo antes da montagem do payload Java e chama processError.
• Empresa inexistente encerra o processo com relatório de erro.
• Filial inexistente encerra o processo com relatório de erro.
• Calendário inexistente ou dia bloqueado registra erro em ImportReportDetails.
• Conta principal inexistente registra erro.
• Conta de contrapartida inexistente registra erro somente para linhas tipo 2.
• Histórico principal inexistente registra erro quando o código for informado.
• Histórico de contrapartida inexistente registra erro somente para linhas tipo 2.
• Linha válida cria detalhe de relatório e entra no payload ImportReportJsonDTO.

Testes e cobertura

O processo de teste atualizado fica em src/test/java e cobre:

• Validação de linha simples de débito e crédito.
• Validação de linha com contrapartida.
• Rejeição de tipo simples com dados de contrapartida.
• Rejeição de tipo contrapartida com marcador D/C.
• Rejeição de tipo contrapartida sem conta de contrapartida.
• Normalização de conta reduzida.
• Totalização de débito/crédito.
• Execução do endpoint Java até a montagem do payload de importação.
• Rejeição estrutural antes de criar o payload de importação.

O Maven usa JaCoCo para exigir cobertura mínima de 60% nas classes críticas do processo:

• ImportReportController
• IplImportRules

Comandos:

mvn test
mvn verify

O relatório HTML fica em:

target/site/jacoco/index.html

mvn verify falha caso a cobertura mínima configurada em import.coverage.minimum fique abaixo de 0.60.