Guia de desenvolvimento — equiparação com ecosif-automations

Módulo alvo: ecosif-moviments
Referência: alterações do ecosif-automations nos últimos 7 dias
Premissa: o ecosif-moviments deve processar importação e consolidação somente por API Java, sem iniciar fluxo por Lambda, trigger S3 ou consumidor SQS.

1. Objetivo

Este guia orienta o desenvolvimento necessário para aproximar o comportamento do ecosif-moviments ao que foi implementado no ecosif-automations, preservando a arquitetura própria do serviço Java.

O objetivo não é copiar a implementação Python/AWS, mas replicar as regras de negócio:

• validação estrutural do IPL;
• regras de débito/crédito e contrapartida;
• geração de lançamentos e totais contábeis;
• rastreio por arquivo e por linha;
• relatórios de importação;
• matriz de flags de ct_controle;
• lote por dia/arquivo;
• pré-checks e ordem de consolidação.

2. O que mudou no ecosif-automations

Foram considerados os commits recentes do ecosif-automations, principalmente:

• feat(import): pipeline IPL SQL com relatórios S3, BD e lote por dia
• feat(consolidation): catálogo de mensagens PT e plano de cascata por calendário
• feat(consolidation): pré-check de lotes, cascata mensal e handler CONSOL_001/040
• feat(infra): DynamoDB janela/lock, fila FIFO consolidation e env defer
• feat(consolidation): janela debounce, lock filial e payload SQS v2
• fix(import): corrige contrapartida IPL e totalizacao decimal
• fix(consolidation): evita perda de IPL em janela diferida

Principais áreas alteradas:

3. O que já está alinhado no ecosif-moviments

O branch feature/import-process-refactory já contém uma primeira etapa de paridade:

• POST /importMoviment/{company}/{branch}/{fname} continua sendo a entrada API-only.
• IplImportRules concentra a validação estrutural básica e o mapeamento da linha IPL.
• Coluna 18:
• 1 = lançamento simples;
• 2 = lançamento com contrapartida.
• Coluna 19:
• D/C somente para tipo 1;
• branco obrigatório para tipo 2.
• Tipo 1 rejeita dados de contrapartida.
• Tipo 2 exige conta de contrapartida.
• Conta reduzida é normalizada pelos 6 primeiros caracteres.
• Contrapartida gera duas linhas em ct_lancamento.
• Tipo 2 soma valor em débito e crédito.
• Validação de conta/histórico de contrapartida ocorre somente para tipo 2.
• JaCoCo exige cobertura mínima de 60% nas classes críticas ImportReportController e IplImportRules.

Documento relacionado: importacao_ipl_api.md.

4. Diretriz API-only

No ecosif-moviments, a implementação deve ficar dentro do padrão:

Cliente / serviço chamador
  -> API REST ecosif-moviments
  -> Services Java transacionais
  -> Repositories JPA / SQL
  -> PostgreSQL
  -> resposta HTTP + relatório persistido/disponível

Não deve ser copiado como mecanismo de execução:

• Lambda handlers;
• trigger S3;
• consumidor SQS;
• janela DynamoDB;
• EventBridge Scheduler;
• MessageGroupId/MessageDeduplicationId;
• boto3 ou clientes AWS como regra de negócio;
• scripts operacionais de upload/watch como parte do fluxo da API.

Esses itens podem inspirar semântica e requisitos operacionais, mas no Java devem virar serviços, transações, endpoints, tabelas de controle e jobs explícitos somente se forem acionados pela API ou por rotina Java controlada.

5. Gaps funcionais a fechar

5.1 Validação estrutural do IPL

Expandir IplImportRules para validar:

• arquivo vazio;
• linha física com numeração 1-based para relatório;
• data em formato canônico definido;
• uma única data de movimento por arquivo;
• coerência entre data do nome do arquivo e data das linhas;
• lote e lançamento numéricos;
• conta principal obrigatória;
• valor numérico e positivo;
• tamanho e presença dos campos obrigatórios por tipo.

Decisão pendente: definir a data canônica do IPL no Java. A documentação atual do ecosif-moviments trata como ddMMyy; o ecosif-automations recente usa o prefixo YYMMDD em suas regras. Esta decisão deve ser fechada antes de ampliar validações.

5.2 CT32 e resolução de fundo

No ecosif-automations, o CT32 resolve fundo para empresa/filial. No ecosif-moviments, empresa e filial vêm na URL.

Contrato recomendado para API-only:

• o chamador resolve CT32 antes de chamar a API;
• a API Java valida que {company} e {branch} existem;
• se o fundo no nome do arquivo for enviado/derivado, ele deve ser apenas rastreado no relatório;
• se for obrigatório validar CT32 no Java, criar endpoint ou payload específico para receber o conteúdo CT32, sem depender de trigger S3.

5.3 Conta reduzida e tipo de plano

Alinhar busca de conta ao comportamento do automations:

• obter tipoplano em ct_controle para empresa/filial;
• filtrar ct_plano por empresa, filial e tipo de plano;
• comparar cdreduzido pelos 6 primeiros caracteres;
• considerar somente contas folha quando a regra exigir (nrfilhos = 0).

Hoje o Java já normaliza o código, mas a consulta ainda deve ser reforçada para refletir todos os filtros de negócio.

5.4 Calendário

Alinhar a validação de ct_calendario:

• calendário inexistente gera erro por linha;
• dia com indicador 1 bloqueia movimento;
• dia permitido deve ser marcado como *;
• revisar índice do dia no Java para garantir uso de dia - 1.

5.5 Lote por dia e arquivo

Implementar a mesma semântica de lote por arquivo/dia:

• novo IPL no mesmo mês não deve sobrescrever lote de outro dia;
• reimportação do mesmo arquivo deve localizar o lote pelo rastreio do arquivo;
• quando o IPL repetir lote 000001 em dias diferentes, o Java deve alocar próximo lote disponível no mês;
• persistir arquivo_ipl em ct_lote quando a migration estiver disponível;
• manter diareferencia coerente no lote, documento e lançamentos.

Referência do automations: docs/PROCESSO-LOTE-POR-DIA-E-ARQUIVO.md.

5.6 Matriz ct_controle

Replicar a matriz:

No Java, evitar deleção global por número de lançamento. Toda alteração deve restringir por empresa, filial, período, lote, documento e lançamento.

5.7 Relatórios e rastreio

Padronizar relatório com granularidade equivalente:

• relatório por arquivo: {IPL}.REPORT.csv ou representação equivalente via API/BD;
• relatório mensal agregado: {FUNDO}_{YYYYMM}_report.csv ou endpoint equivalente;
• relatório de alterações: {IPL}.CHANGES.csv quando houver substituição;
• persistência por linha em ImportReportDetails;
• status por etapa: CT32, calendário, conta, histórico, lote/documento, lançamento, consolidação, cota;
• mensagens operacionais em português quando possível, alinhadas aos códigos de consolidação.

Se a API não gravar relatórios em S3, ela deve expor endpoint ou persistência suficiente para o cliente consultar o mesmo conteúdo.

5.8 Consolidação, cota e fechamento

O automations avançou em pré-checks, cascata mensal e mensagens PT. Para o Java:

• implementar pré-check antes de consolidar;
• consolidar meses pendentes em ordem cronológica até o mês alvo;
• serializar execução por empresa/filial para evitar concorrência entre importações;
• preservar fluxo síncrono ou explicitamente assíncrono via API Java, sem Lambda/SQS;
• alinhar cálculo de cota e fechamento do dia com os estados do relatório.

Se houver convivência entre Java e automations, definir um lock comum por empresa/filial para evitar consolidação simultânea.

6. Roadmap recomendado

Fase 1 — Contrato e validação estrutural

• Fechar formato canônico da data.
• Definir responsabilidade de CT32.
• Expandir IplImportRules.
• Retornar erros estruturais com linha, campo e mensagem.
• Testes unitários cobrindo arquivo vazio, data inválida, múltiplas datas, valor inválido e nome divergente.

Fase 2 — Validações de domínio

• Reforçar consulta de conta por empresa/filial/tipo de plano.
• Corrigir e testar calendário.
• Validar histórico principal e contrapartida com as mesmas condições do automations.
• Testes com mocks de service/repository.

Fase 3 — Lote, documento e flags

• Implementar lote por dia/arquivo.
• Implementar matriz loteencerra × lanencerra.
• Restringir substituições/deleções ao escopo correto.
• Criar auditoria de alterações.
• Testes cobrindo reimportação e três IPLs no mesmo mês com lote 000001.

Fase 4 — Relatórios

• Padronizar ImportReportDetails.
• Criar DTOs/endpoints para relatório por arquivo e mensal, ou persistir CSV em storage configurável.
• Corrigir composição de CSV/mensagens se houver concatenação ambígua em entidades legadas.
• Testes para erro total, parcial e sucesso.

Fase 5 — Consolidação API-only

• Implementar pré-checks.
• Garantir cascata mensal.
• Implementar lock/serialização Java por empresa/filial.
• Alinhar cota e fechamento.
• Testes de integração com banco.

7. Critérios de aceite

• O endpoint POST /importMoviment/{company}/{branch}/{fname} processa IPL sem depender de Lambda/SQS/S3 trigger.
• Linhas tipo 1 e 2 geram os mesmos lançamentos e totais do ecosif-automations.
• Contas, históricos e calendário seguem as mesmas regras de validação.
• Relatórios possuem rastreio por arquivo e por linha.
• Reimportação e lote por dia/arquivo não sobrescrevem movimentos indevidamente.
• Flags ct_controle são respeitadas em todos os cenários.
• Cobertura mínima de 60% permanece no build e é ampliada para services conforme as fases avançarem.
• mvn verify deve passar antes de merge.

8. Referências

• ecosif-automations/docs/PROCESSO-LOTE-POR-DIA-E-ARQUIVO.md
• ecosif-automations/docs/REGRAS-IMPORT-IPL-FLAGS.md
• ecosif-automations/docs/ESPECIFICACAO-TECNICA-CONSOLIDACAO-DIFERIDA.md
• ecosif-moviments/docs/dev/importacao_ipl_api.md
• ecosif-moviments/src/main/java/io/ecosif/moviments/importreport/service/IplImportRules.java
• ecosif-moviments/src/main/java/io/ecosif/moviments/importreport/service/impl/ImportReportDetailsServiceImpl.java