Projeto eCosif 02/2026

ecosif-automations (AWS Lambda) — versão: 0.7.05.202605280
Notas de versão, impacto e guia de criação manual dos recursos AWS

Versão anterior (referência): 0.7.02.202602280 (primeira tag Lambda/SQS)
Versão atual: 0.7.05.202605280
Referência Git: v0.7.02.202602280 … v0.7.05.202605280 (17 commits)

1. Resumo executivo

Importante: não há ECS Service para ecosif-automations em produção AWS.

2. Novidades funcionais (desde 0.7.02.202602280)

2.1 Importação IPL

• Handler import: pipeline IPL com validação, persistência SQL, relatórios em S3 (resumo + detalhe por execução).
• Dispatcher / defer: importação ordenada por fundo com janela configurável.
• Correções: contrapartida IPL, totalização decimal, regras alinhadas a IplImportRules no moviments.
• CT32.LD: ficheiro mestre obrigatório (CT32_MASTER_KEY).

2.2 Entries e consolidação

• Handler entries: processamento de fila entries (lançamentos pós-import).
• Handler consolidation: pré-check de lotes, cascata mensal, mensagens PT (CONSOL_001 / CONSOL_040).
• Consolidação diferida: debounce (CONSOLIDATION_DEBOUNCE_SEC), lock por filial, tabelas DynamoDB, fila consolidation-defer (evita perda de IPL em janela).
• Payload SQS v2 para consolidação FIFO.

2.3 Infraestrutura e qualidade

• CloudFormation de referência em ecosif-structure/aws/exemple/ecosif-automations/.
• Testes unitários ampliados (validação de linhas, defer scheduler, quota, janela de import).
• ZIP publicado: ecosif-automations-lambda-0.7.05.202605280.zip (+ SHA256 em delivery/publish-ready/).

2.4 Fluxo de dados e relação entre componentes

O módulo não expõe API HTTP em produção AWS. O processamento é orientado a eventos: upload no S3 dispara o pipeline; filas SQS desacoplam importação, persistência de lançamentos e consolidação contábil.

2.4.1 Visão geral (componentes)

flowchart TB
    subgraph Entrada["Entrada"]
        U[Utilizador / integração]
        S3[(S3 bucket importação)]
        CT32[CT32.LD mestre no bucket]
    end

    subgraph Lambdas["AWS Lambda — mesmo ZIP 0.7.05"]
        LImp[import_handler<br/>S3 ObjectCreated]
        LImpDef[import_dispatcher_handler<br/>fila import-defer]
        LEnt[entries_handler<br/>fila entries]
        LConsSched[consolidation_scheduler_handler<br/>fila consolidation-defer]
        LCons[consolidation_handler<br/>fila consolidation.fifo]
    end

    subgraph Filas["Amazon SQS"]
        QEnt[entries + DLQ]
        QImpDef[import-defer + DLQ]
        QConsDef[consolidation-defer + DLQ]
        QCons[consolidation.fifo + DLQ]
    end

    subgraph Estado["Estado / janelas"]
        DDBImp[(DynamoDB<br/>IMPORT_WINDOW_TABLE)]
        DDBCons[(DynamoDB<br/>CONSOLIDATION_WINDOW_TABLE<br/>CONSOLIDATION_LOCK_TABLE)]
    end

    subgraph Dados["Persistência e APIs ECS"]
        PG[(PostgreSQL / RDS)]
        MD[ecosif-masterdata<br/>validação empresa/filial]
        MOV[ecosif-moviments<br/>monitor API / evolução HTTP]
        ANG[ecosif-angular<br/>upload e monitor admin]
    end

    subgraph Saida["Saída S3"]
        S3ok[imported/ + reports/]
        S3err[importError/ + CSV erro]
    end

    U --> ANG
    ANG --> S3
    U --> S3
    CT32 -.-> S3
    S3 -->|evento .IPL| LImp
    LImp --> MD
    LImp --> DDBImp
    LImp -->|imediato| QEnt
    LImp -->|IMPORT_DEFER_ENABLED| QImpDef
    QImpDef --> LImpDef
    LImpDef --> MD
    LImpDef --> QEnt
    QEnt --> LEnt
    LEnt --> PG
    LEnt --> S3ok
    LEnt --> DDBCons
    LEnt -->|consolidação imediata| QCons
    LEnt -->|CONSOLIDATION_DEFER_ENABLED| QConsDef
    QConsDef --> LConsSched
    LConsSched --> DDBCons
    LConsSched --> QCons
    QCons --> LCons
    LCons --> PG
    LCons --> S3ok
    LCons --> S3err
    LImp --> S3err
    MOV -.-> ANG

2.4.2 Sequência — caminho imediato (defer desligado)

Cenário típico quando IMPORT_DEFER_ENABLED=false e CONSOLIDATION_DEFER_ENABLED=false:

sequenceDiagram
    autonumber
    participant Op as Operador
    participant S3 as S3
    participant Imp as Lambda import
    participant MD as masterdata
    participant Qe as SQS entries
    participant Ent as Lambda entries
    participant PG as PostgreSQL
    participant Qc as SQS consolidation.fifo
    participant Con as Lambda consolidation

    Op->>S3: Upload CT32.LD + NNNNNN_YYYYMMDD.IPL
    S3->>Imp: s3:ObjectCreated (.IPL)
    Imp->>S3: Download IPL + CT32.LD
    Imp->>Imp: Parse IPL / lookup fundo no CT32
    Imp->>MD: company_exists / branch_exists
    MD-->>Imp: OK
  alt validação OK
        Imp->>Qe: mensagem canónica (entries + metadata)
        Qe->>Ent: invoke
        Ent->>PG: INSERT lançamentos / lotes (SQL)
        Ent->>S3: relatório .report.csv (imported/reports/)
        Ent->>S3: move IPL → imported/
        Ent->>Qc: pedido consolidação (empresa/filial/ano/mês)
        Qc->>Con: invoke FIFO
        Con->>PG: consolidação, quotas, encerramentos
        Con->>S3: relatórios / move em erro se falha
    else validação falha
        Imp->>S3: ERRO_*.csv + move → importError/
    end

2.4.3 Sequência — janelas diferidas (debounce)

Quando há vários IPL do mesmo fundo em curto intervalo, as janelas evitam processar/consolidar a meio do lote:

Parâmetros de tempo: IMPORT_DEBOUNCE_SEC / IMPORT_MAX_WAIT_SEC e CONSOLIDATION_DEBOUNCE_SEC / CONSOLIDATION_MAX_WAIT_SEC (máx. 900 s por mensagem SQS).

2.4.4 Tabela de relação entre elementos

2.4.5 Contrato de mensagens (entre filas)

2.4.6 Diagrama ASCII (referência rápida)

                    ┌─────────────┐
                    │  CT32.LD    │ (mestre fixo no bucket)
                    └──────┬──────┘
                           │
  Operador / Angular ──► S3 bucket (.IPL)
                           │
                           ▼
                  ┌────────────────┐
                  │ Lambda IMPORT  │──► masterdata (empresa/filial)
                  └────────┬───────┘
           defer OFF       │        defer ON
              │            │            └──► SQS import-defer ──► Lambda IMPORT_DISPATCHER ──┐
              │            │                                                                  │
              └────────────┼──────────────────────────────────────────────────────────────────┘
                           ▼
                  ┌────────────────┐
                  │  SQS entries   │
                  └────────┬───────┘
                           ▼
                  ┌────────────────┐
                  │ Lambda ENTRIES │──► PostgreSQL (lançamentos)
                  └────────┬───────┘    S3 imported/ + reports/
                           │
              consol. OFF  │   consol. defer ON
              │            │        └──► SQS consolidation-defer ──► Lambda CONS_SCHEDULER ──┐
              │            │                                                                  │
              └────────────┼──────────────────────────────────────────────────────────────────┘
                           ▼
                  ┌─────────────────────┐
                  │ SQS consolidation   │  (FIFO)
                  │      .fifo          │
                  └──────────┬──────────┘
                             ▼
                  ┌─────────────────────┐
                  │ Lambda CONSOLIDATION│──► PostgreSQL (saldos, cascata)
                  └─────────────────────┘

Deploy completo (CloudFormation): cinco funções Lambda partilham o mesmo artefacto ZIP; ver ecosif-automations/delivery/ecosif-automations.yaml. O guia manual abaixo (secções 7+) cobre o mínimo de três handlers; em produção incluir também import-dispatcher e consolidation-scheduler quando as janelas diferidas estiverem ativas.

3. Escopo operacional desta release

Esta versão consolida o modelo operacional do ecosif-automations para execução em AWS com: - pacote ZIP de Lambda publicado em: https://files.disoft.com.br/ no endereço: itau-ecosif/0_7_05_X/aws/lambda/ecosif_automations_0_7_05_202605280.zip - funções Lambda (mesmo ZIP): import, entries, consolidation (+ import-dispatcher e consolidation-scheduler se janelas defer ativas — ver §2.4) - filas SQS necessárias: entries, consolidation.fifo, import-defer, consolidation-defer (cada uma com DLQ) - DLQ para cada fila principal - variáveis canónicas ECOSIF_* e AWS_*

Importante: não há necessidade de ECS Service para ecosif-automations em produção AWS (modelo oficial é Lambda + SQS).

4. Referências no repositório

• Template base (placeholders): ecosif-structure/aws/exemple/ecosif-automations/ecosif-automations-lambda-sqs-minimal.yaml
• Template parametrizado DEV: ecosif-structure/aws/exemple/dev/ecosif-automations/ecosif-automations-lambda-sqs-dev.yaml
• Exemplo DEV dos serviços ECS (demais módulos): ecosif-structure/aws/exemple/dev/task-definitions/

5. Variáveis de ambiente — canónicas (Lambda)

As funções import, entries e consolidation aceitam variáveis ECOSIF_* e AWS_* para operação completa do pipeline.

3.1 Obrigatórias (core)

3.2 S3 (importação e relatórios)

3.3 SQS (pipeline)

3.4 Consolidação diferida

3.5 Opcionais / compatibilidade de SDK

6. Pré-requisitos

• AWS CLI v2 autenticado
• permissões para s3, sqs, lambda, iam, logs e secretsmanager
• bucket S3 de import existente
• role de execução Lambda já criada (com acesso a S3/SQS/Secrets)

3.1 Variáveis de sessão (exemplo DEV)

export AWS_REGION=us-west-1
export ACCOUNT_ID=123456789012
export ENV=dev
export PROJECT=ecosif

export PREFIX="${PROJECT}-${ENV}-automations"

export IMPORT_BUCKET="ecosif-${ENV}-import-${ACCOUNT_ID}"
export LAMBDA_ROLE_ARN="arn:aws:iam::${ACCOUNT_ID}:role/ecosif-${ENV}-lambda-execution-role"

export DB_SECRET_ARN="arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:ecosif/${ENV}/rds"
export SERVICE_SECRET_ARN="arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:ecosif/${ENV}/automations-service"

export ZIP_URL="https://ftp.disoft.com.br/ecosif/aws/ecosif-automations-0.7.05.202605280.zip"
export ZIP_FILE="ecosif-automations-0.7.05.202605280.zip"

7. Download do ZIP e preparo local

curl -fL "$ZIP_URL" -o "$ZIP_FILE"
unzip -t "$ZIP_FILE"

Se o ambiente exigir empacotamento no S3 para update-function-code:

export LAMBDA_ARTIFACT_BUCKET="ecosif-cfn-${ACCOUNT_ID}-${AWS_REGION}"
aws s3 cp "$ZIP_FILE" "s3://${LAMBDA_ARTIFACT_BUCKET}/automations/${ZIP_FILE}" --region "$AWS_REGION"

8. Criação manual das filas SQS

5.1 DLQs

aws sqs create-queue --region "$AWS_REGION" --queue-name "${PREFIX}-entries-dlq"
aws sqs create-queue --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation-dlq"
aws sqs create-queue --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation-defer-dlq"

export ENTRIES_DLQ_URL=$(aws sqs get-queue-url --region "$AWS_REGION" --queue-name "${PREFIX}-entries-dlq" --query QueueUrl --output text)
export CONS_DLQ_URL=$(aws sqs get-queue-url --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation-dlq" --query QueueUrl --output text)
export CONS_DEFER_DLQ_URL=$(aws sqs get-queue-url --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation-defer-dlq" --query QueueUrl --output text)

export ENTRIES_DLQ_ARN=$(aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$ENTRIES_DLQ_URL" --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)
export CONS_DLQ_ARN=$(aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$CONS_DLQ_URL" --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)
export CONS_DEFER_DLQ_ARN=$(aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$CONS_DEFER_DLQ_URL" --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)

5.2 Filas principais

aws sqs create-queue --region "$AWS_REGION" --queue-name "${PREFIX}-entries" \
  --attributes "VisibilityTimeout=300,MessageRetentionPeriod=1209600,RedrivePolicy={\"deadLetterTargetArn\":\"${ENTRIES_DLQ_ARN}\",\"maxReceiveCount\":\"5\"}"

aws sqs create-queue --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation.fifo" \
  --attributes "FifoQueue=true,ContentBasedDeduplication=false,VisibilityTimeout=300,MessageRetentionPeriod=1209600,RedrivePolicy={\"deadLetterTargetArn\":\"${CONS_DLQ_ARN}\",\"maxReceiveCount\":\"5\"}"

aws sqs create-queue --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation-defer" \
  --attributes "VisibilityTimeout=300,MessageRetentionPeriod=1209600,RedrivePolicy={\"deadLetterTargetArn\":\"${CONS_DEFER_DLQ_ARN}\",\"maxReceiveCount\":\"5\"}"

export ENTRIES_QUEUE_URL=$(aws sqs get-queue-url --region "$AWS_REGION" --queue-name "${PREFIX}-entries" --query QueueUrl --output text)
export CONS_QUEUE_URL=$(aws sqs get-queue-url --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation.fifo" --query QueueUrl --output text)
export CONS_DEFER_QUEUE_URL=$(aws sqs get-queue-url --region "$AWS_REGION" --queue-name "${PREFIX}-consolidation-defer" --query QueueUrl --output text)

export ENTRIES_QUEUE_ARN=$(aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$ENTRIES_QUEUE_URL" --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)
export CONS_QUEUE_ARN=$(aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$CONS_QUEUE_URL" --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)
export CONS_DEFER_QUEUE_ARN=$(aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$CONS_DEFER_QUEUE_URL" --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)

9. Criação manual das Lambdas (ZIP)

6.1 Arquivos de ambiente (JSON)

Crie import-env.json:

{
  "Variables": {
    "APP_ENV": "dev",
    "AWS_REGION": "us-west-1",
    "AWS_DEFAULT_REGION": "us-west-1",
    "AWS_S3_BUCKET": "ecosif-dev-import-123456789012",
    "AWS_S3_BUCKET_NAME": "ecosif-dev-import-123456789012",
    "AWS_S3_ERROR_FOLDER": "importError/",
    "AWS_S3_IMPORTED_FOLDER": "imported/",
    "AWS_S3_REPORTS_FOLDER": "imported/reports/",
    "AWS_S3_ERROR_FILES_FOLDER": "importError/files/",
    "AWS_S3_IMPORTED_FILES_FOLDER": "imported/files/",
    "AWS_S3_REPORTS_DETAILS_FOLDER": "imported/reports/details/",
    "AWS_SQS_ENTRIES_QUEUE_URL": "https://sqs.us-west-1.amazonaws.com/123456789012/ecosif-dev-automations-entries",
    "AWS_SQS_CONSOLIDATION_QUEUE_URL": "https://sqs.us-west-1.amazonaws.com/123456789012/ecosif-dev-automations-consolidation.fifo",
    "AWS_SQS_CONSOLIDATION_DEFER_QUEUE_URL": "https://sqs.us-west-1.amazonaws.com/123456789012/ecosif-dev-automations-consolidation-defer",
    "ECOSIF_API_BASE_URL": "http://internal-ecosif-dev-alb.local",
    "ECOSIF_API_URL_MODE": "alb",
    "ECOSIF_DB_SECRET": "arn:aws:secretsmanager:us-west-1:123456789012:secret:ecosif/dev/rds",
    "ECOSIF_AUTOMATIONS_SERVICE_SECRET": "arn:aws:secretsmanager:us-west-1:123456789012:secret:ecosif/dev/automations-service",
    "CT32_MASTER_KEY": "CT32.LD",
    "CONSOLIDATION_DEFER_ENABLED": "false",
    "CONSOLIDATION_DEBOUNCE_SEC": "60",
    "CONSOLIDATION_MAX_WAIT_SEC": "60",
    "CONSOLIDATION_WINDOW_TABLE": "ecosif-dev-consolidation-window",
    "CONSOLIDATION_LOCK_TABLE": "ecosif-dev-consolidation-lock"
  }
}

Crie entries-env.json e consolidation-env.json reaproveitando as variáveis acima e removendo as que não são necessárias para cada função.

6.2 create-function (primeira criação)

aws lambda create-function \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-import" \
  --runtime python3.11 \
  --handler src.handlers.import_handler.lambda_handler \
  --zip-file "fileb://${ZIP_FILE}" \
  --role "$LAMBDA_ROLE_ARN" \
  --timeout 120 \
  --memory-size 512 \
  --environment file://import-env.json

aws lambda create-function \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-entries" \
  --runtime python3.11 \
  --handler src.handlers.entries_handler.lambda_handler \
  --zip-file "fileb://${ZIP_FILE}" \
  --role "$LAMBDA_ROLE_ARN" \
  --timeout 180 \
  --memory-size 768 \
  --environment file://entries-env.json

aws lambda create-function \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-consolidation" \
  --runtime python3.11 \
  --handler src.handlers.consolidation_handler.lambda_handler \
  --zip-file "fileb://${ZIP_FILE}" \
  --role "$LAMBDA_ROLE_ARN" \
  --timeout 300 \
  --memory-size 1024 \
  --environment file://consolidation-env.json

6.3 update-function-code (atualização de versão)

aws lambda update-function-code \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-import" \
  --zip-file "fileb://${ZIP_FILE}"

aws lambda update-function-code \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-entries" \
  --zip-file "fileb://${ZIP_FILE}"

aws lambda update-function-code \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-consolidation" \
  --zip-file "fileb://${ZIP_FILE}"

10. Event source mapping SQS -> Lambda

aws lambda create-event-source-mapping \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-entries" \
  --event-source-arn "$ENTRIES_QUEUE_ARN" \
  --batch-size 1 \
  --enabled

aws lambda create-event-source-mapping \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-consolidation" \
  --event-source-arn "$CONS_QUEUE_ARN" \
  --batch-size 1 \
  --enabled

A função import normalmente é acionada por evento S3 (ObjectCreated) ou por invocação manual/orquestrada; não depende obrigatoriamente de fila de entrada própria.

11. Permissão de trigger S3 para Lambda import (opcional, recomendado)

aws lambda add-permission \
  --region "$AWS_REGION" \
  --function-name "${PROJECT}-${ENV}-automations-import" \
  --statement-id "allow-s3-invoke-import" \
  --action "lambda:InvokeFunction" \
  --principal s3.amazonaws.com \
  --source-arn "arn:aws:s3:::${IMPORT_BUCKET}"

Configuração de notificação no bucket (exemplo):

cat > s3-notification.json <<JSON
{
  "LambdaFunctionConfigurations": [
    {
      "LambdaFunctionArn": "arn:aws:lambda:${AWS_REGION}:${ACCOUNT_ID}:function:${PROJECT}-${ENV}-automations-import",
      "Events": ["s3:ObjectCreated:*"]
    }
  ]
}
JSON

aws s3api put-bucket-notification-configuration \
  --region "$AWS_REGION" \
  --bucket "$IMPORT_BUCKET" \
  --notification-configuration file://s3-notification.json

12. Validação operacional

aws lambda get-function-configuration --region "$AWS_REGION" --function-name "${PROJECT}-${ENV}-automations-import"
aws lambda get-function-configuration --region "$AWS_REGION" --function-name "${PROJECT}-${ENV}-automations-entries"
aws lambda get-function-configuration --region "$AWS_REGION" --function-name "${PROJECT}-${ENV}-automations-consolidation"

aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$ENTRIES_QUEUE_URL" --attribute-names All
aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$CONS_QUEUE_URL" --attribute-names All
aws sqs get-queue-attributes --region "$AWS_REGION" --queue-url "$CONS_DEFER_QUEUE_URL" --attribute-names All

Upload de teste:

aws s3 cp ./arquivo_teste.IPL "s3://${IMPORT_BUCKET}/arquivo_teste.IPL" --region "$AWS_REGION"
aws s3 cp ./CT32.LD "s3://${IMPORT_BUCKET}/CT32.LD" --region "$AWS_REGION"

Acompanhamento de logs:

aws logs tail "/aws/lambda/${PROJECT}-${ENV}-automations-import" --follow --region "$AWS_REGION"
aws logs tail "/aws/lambda/${PROJECT}-${ENV}-automations-entries" --follow --region "$AWS_REGION"
aws logs tail "/aws/lambda/${PROJECT}-${ENV}-automations-consolidation" --follow --region "$AWS_REGION"

13. Checklist final (0.7.01.x / legado → 0.7.05.202605280)

• [ ] ZIP 0.7.05.202605280 obtido de https://files.disoft.com.br/ e aplicado nas 3 funções.
• [ ] Filas entries, consolidation.fifo e consolidation-defer criadas com DLQ.
• [ ] Handlers corretos:
• [ ] src.handlers.import_handler.lambda_handler
• [ ] src.handlers.entries_handler.lambda_handler
• [ ] src.handlers.consolidation_handler.lambda_handler
• [ ] Variáveis ECOSIF_*, AWS_* e secrets configurados conforme ambiente.
• [ ] Bucket de import com trigger da Lambda import (quando aplicável).
• [ ] Fluxo testado de ponta a ponta com upload IPL + CT32.LD.