Pular para conteúdo

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:

Área Comportamento implementado no automations
Importação IPL Parser valida layout, data, tipo simples/contrapartida, fundo, CT32 e payload para entries.
Entries SQL Grava ct_lote, ct_documentos, ct_lancamento diretamente, com rastreio de arquivo.
Contrapartida Tipo 2 gera duas linhas contábeis: uma débito e uma crédito.
Totalização Débito/crédito usam cálculo decimal e refletem linhas geradas, não apenas linhas IPL.
Lote por arquivo/dia Arquivos diferentes no mesmo mês não sobrescrevem o mesmo lote; novo arquivo aloca próximo lote.
Flags ct_controle documento, loteencerra, lanencerra definem criação, rejeição, atualização ou substituição.
Relatórios Gera relatório por IPL, relatório mensal agregado e relatório de alterações.
Validações Conta, histórico, calendário e dia bloqueado são refletidos por linha no relatório.
Consolidação Pré-checks, catálogo de mensagens PT, cascata mensal e serialização por filial.
Consolidação diferida Janela debounce/lock em DynamoDB e fila FIFO para agrupar vários IPLs antes da consolidação.

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:

loteencerra lanencerra Comportamento esperado
N N Lote existente rejeita arquivo; lançamento existente rejeita linha.
S S Permite substituir lançamento e gera relatório de alterações.
N S Não altera estrutura do lote; insere/substitui lançamentos conforme dia compatível.
S N Pode reabrir lote, mas não substitui lançamento existente; apenas novos códigos entram.

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