Documentação Técnica — ecosif-automations

Público-alvo: Desenvolvedores / Arquiteto de Integração
Módulo: ecosif-automations (importação e ETL de arquivos contábeis)

1. Visão Geral

O ecosif-automations é um módulo Python pensado para execução em AWS Lambda (ou localmente em modo simulado). Responsabiliza-se por: (1) ler ficheiros de importação .IPL e o ficheiro mestre CT32.LD a partir de S3 (ou sistema de ficheiros em modo local); (2) resolver empresa/filial a partir do CT32 (lookup por fundo do nome do IPL) e validar no ecosif-masterdata; (3) enviar os lançamentos para a fila entries com contrato canónico; (4) persistir lançamentos no passo seguinte (caminho SQL atual ou integração API moviments conforme plano); (5) gerar relatórios de processamento e mover ficheiros para pastas de sucesso ou erro. O fluxo é assíncrono via SQS.

Nota: O módulo é Python (não Spring Boot). A orquestração em produção é event-driven (S3 + SQS), sem cron no código.

2. Fluxos de Importação

2.1 Arquitetura em AWS (Produção — 5 Lambdas)

Com IMPORT_DEFER_ENABLED=true (default em CloudFormation), vários IPL do mesmo fundo são agrupados antes do envio à fila entries FIFO.

flowchart LR
  S3[S3 .IPL] --> LI[Lambda Import]
  LI --> DDB1[(import-window)]
  LI --> Q1[import-defer SQS]
  Q1 --> LD[Import-Dispatcher]
  LD --> Q2[entries FIFO]
  Q2 --> LE[Lambda Entries]
  LE --> PG[(PostgreSQL)]
  LE --> Q3[consolidation-defer ou FIFO]
  Q3 --> LS[Consolidation-Scheduler]
  LS --> Q4[consolidation FIFO]
  Q4 --> LC[Lambda Consolidation]

Handlers: src.handlers.{import,import_dispatcher,entries,consolidation_scheduler,consolidation}_handler.lambda_handler

IaC: delivery/ecosif_automations.yaml ou infrastructure/terraform/ — ver implantacao_aws.md.

2.2 Leitura de Ficheiros (S3 vs Local)

Modo	Fonte	Como
AWS	S3	Evento s3:ObjectCreated invoca o Lambda de import; o handler lê o `bucket` e a `key` do evento, faz download via boto3 (`s3.get_object`). Ficheiros devem estar no bucket configurado (`AWS_S3_BUCKET_NAME` / `AWS_S3_BUCKET`).
Local	Sistema de ficheiros	Variável ECOSIF_LOCAL_MODE=true; o s3_client delega para `local_mode`: leitura em LOCAL_BASE_DIR (por defeito `./local_data`). Subpastas: input, imported, importError, imported/reports. Scripts em `scripts/` simulam o evento S3 passando caminho do .IPL.

Não existe integração FTP nem upload direto via API no código atual; a entrada é S3 (ou pasta local em modo dev).

2.3 Interação com ecosif-moviments

Estado atual no código: a integração principal em produção está no fluxo import_handler -> entries_handler com persistência em entries_service (SQL).
Caminho evolutivo (plano): substituir/encapsular a persistência SQL por cliente HTTP para o ecosif-moviments (endpoint oficial a confirmar), preservando o contrato canónico da mensagem.
Nota: existe dispatcher_handler no repositório para fluxo via API, mas o uso em infraestrutura deve seguir a decisão do plano operacional.

2.4 Interação com ecosif-masterdata

Quem chama: O import_service durante validate_and_process_files, na função _validate_with_apis(ct32).
Chamadas: api_client.company_exists(ct32.company_code) e api_client.branch_exists(company_code, branch_code).
Objetivo: Garantir que empresa e filial existem antes de enviar os lançamentos para a fila; o fundCode é usado para lookup no CT32.LD (bloco 4), não para validação externa obrigatória no passo inicial.

3. Pastas S3 (Entrada/Saída)

Pasta (prefixo no bucket)	Variável de ambiente	Uso
Entrada	(objeto criado em qualquer prefixo; no evento vem a key)	Upload de `.IPL` dispara o Lambda. O `CT32.LD` é ficheiro mestre fixo (chave `CT32_MASTER_KEY`) e deve existir no bucket.
importError/	AWS_S3_ERROR_FOLDER	Ficheiros com falha de validação ou parse são movidos para aqui; é gerado um CSV ERRO_<nome>.csv com timestamp, nome do ficheiro, mensagem e estado do CT32.
imported/	AWS_S3_IMPORTED_FOLDER	`.IPL` processados com sucesso são movidos para aqui.
imported/reports/	AWS_S3_REPORTS_FOLDER	Relatório de processamento por ficheiro (ex.: `<fileName>.report.csv`) com total de entries, importados, status e timestamp.

4. Componentes Principais

Componente	Ficheiro	Responsabilidade
import_handler	handlers/import_handler.py	S3 `.IPL`: regista janela DynamoDB ou processa imediato; agenda import-defer ou envia entries FIFO.
import_dispatcher_handler	handlers/import_dispatcher_handler.py	SQS import-defer (`FLUSH`): ordena IPL por data do fundo e publica na fila entries.
entries_handler	handlers/entries_handler.py	SQS entries FIFO: `entries_service` (SQL) + consolidação imediata ou defer.
consolidation_scheduler_handler	handlers/consolidation_scheduler_handler.py	SQS consolidation-defer: flush da janela → fila consolidation FIFO.
consolidation_handler	handlers/consolidation_handler.py	SQS consolidation FIFO: consolidação, quota, relatórios S3.
import_service	services/import_service.py	Valida nome do `.IPL`, verifica existência do `CT32.LD` mestre (`CT32_MASTER_KEY`), faz lookup de fundo no CT32 (bloco 4), valida empresa/filial via API, monta mensagem canónica para a fila. Em erro: gera CSV de erro e move `.IPL` para importError.
ipl_parser	parsers/ipl_parser.py	Parse de ficheiros .IPL (layout fixo 156 caracteres por linha); validação do nome `NNNNNN_YYYYMMDD.IPL`.
ct32_parser	parsers/ct32_parser.py	Parse de `CT32.LD` com múltiplas linhas; índice por `fund_code` (bloco 4) para resolver empresa/filial (blocos 2 e 3).
s3_client	aws_clients/s3_client.py	Download, upload, move, file_exists; em modo local delega para `local_mode` (leitura/escrita em disco).
api_client	aws_clients/api_client.py	GET masterdata (company, branch, fund), POST moviments (import_entries).

5. Modelo de Dados (Mensagem para a Fila / API)

Mensagem SQS (exportada pelo import_service): fileName, iplKey, ct32MasterKey, fundCode, companyCode, branchCode, sourceName, description, entries (lista de dicts), entryCount.
Cada entry (canónico para entries_service): movimentDate, batch, entryCode, typeEntry ("1" crédito / "2" débito), contaNo, history, historyPattern, conterpartNo, conterpartHistory, conterpartHistoryPattern, value (string decimal).

Para detalhes operacionais (variáveis, monitorização, logs) e funcionais (layout dos ficheiros, o que fazer quando uma importação falha), ver deploy/operacao.md e user/visao_geral.md.