Manual de entrega e implantação — ecosif-automations (cliente institucional)

Versão do produto: 0.7.05.202605280
Classificação: documento de entrega auditável — sem execução de código pelo cliente
Fornecedor: Disoft / ECOSIF

1. Princípios desta entrega (bancos e ambientes restritos)

Princípio	O que significa na prática
Clareza	Um único caminho de implantação: infraestrutura declarativa (CloudFormation) + artefacto compilado (`lambda.zip`).
Transparência	Cada ficheiro tem versão, hash SHA-256 e manifesto JSON na entrega.
Auditabilidade	Evidências de testes automatizados com cobertura mínima de 80% nos módulos de regra de negócio (`parsers`, `services`, `models`, `utils`), geradas pelo fornecedor em pipeline controlado. Adaptadores AWS (`handlers`, `aws_clients`, `database`) são validados em homologação E2E.
Segregação	O cliente não executa scripts Python, `build_lambda.sh`, Docker de build nem testes no ambiente bancário.
Imutabilidade	O runtime em produção é o `lambda.zip` assinado por hash, não código-fonte editável.

2. O que é o serviço (sem ambiguidade)

O ecosif-automations não é um container Docker permanente (não é um “microserviço ECS”).

São cinco funções AWS Lambda (Python 3.11) que processam ficheiros de importação contábil:

Upload .IPL (S3) → Import → [import-defer] → Import-Dispatcher → entries FIFO
  → Entries → PostgreSQL → [consolidation-defer] → Scheduler → consolidation FIFO → Consolidation

Função	Gatilho	Responsabilidade
Import	S3 `.IPL`	Regista janela por fundo ou processa imediato
Import-Dispatcher	SQS import-defer	Flush ordenado → fila entries FIFO
Entries	SQS entries FIFO	Persistência RDS + encaminha consolidação
Consolidation-Scheduler	SQS consolidation-defer	Debounce antes da fila consolidation
Consolidation	SQS consolidation FIFO	Consolidação, quota, fechamento, relatórios S3

3. O que o cliente recebe (pacote ZIP de entrega)

O fornecedor entrega um arquivo ZIP montado em pipeline interno (build-client-release.sh). Estrutura:

ecosif-automations-0.7.05.202605280/
├── MANIFESTO_ENTREGA.json          # versão, hashes, referências
├── 01-ARTEFATOS-RUNTIME/
│   ├── lambda.zip                  # código compilado das 5 Lambdas
│   └── SHA256SUMS.txt              # integridade
├── 02-INFRAESTRUTURA-DECLARATIVA/
│   └── ecosif_automations.yaml     # CloudFormation (S3, SQS, DynamoDB, 5 Lambdas)
├── 03-EVIDENCIAS-QUALIDADE/
│   ├── coverage.xml                # cobertura (gate >= 80%)
│   ├── junit.xml                   # resultados dos testes
│   ├── quality-summary.json        # resumo do gate
│   └── coverage-html/              # relatório legível (opcional revisão)
├── 04-DOCUMENTACAO/
│   ├── ../dev/integradores/manual_entrega_cliente_banco.md   # este documento
│   ├── VERSION
│   └── env.*.lambda.example      # import, import-dispatcher, entries, consolidation
├── 05-DADOS-REFERENCIA/            # (opcional) CT32.LD e IPL de exemplo
└── 06-CODIGO-FONTE-AUDITORIA/      # SOMENTE se contratado — ver secção 8

3.1 O que o cliente não recebe para executar

Scripts de build (build_lambda.sh, ci-quality-gate.sh)
docker-compose de desenvolvimento
Repositório Git com histórico (salvo acordo de auditoria)
Instruções para pip install ou pytest no ambiente do banco

3.2 O que o cliente pode executar (alinhado a governança)

Ação	Ferramenta	Quem
Implantar infraestrutura	CloudFormation / pipeline IaC aprovado	DevOps / Cloud do banco
Carregar `lambda.zip` no S3 corporativo	Console AWS ou pipeline com hash verificado	DevOps
Revisar evidências	Leitura de `coverage.xml`, `MANIFESTO_ENTREGA.json`	Risco / Auditoria / SI
Operação	Upload `.IPL` e manutenção `CT32.LD`	Operações contábeis

4. Fluxo de implantação (único caminho)

Passo 1 — Validação de integridade (obrigatório)

sha256sum -c SHA256SUMS.txt

Conferir que o hash coincide com MANIFESTO_ENTREGA.json → sha256_lambda_zip.

Passo 2 — Publicação do artefacto

Copiar lambda.zip para bucket S3 aprovado pelo banco (ex.: bucket de artefactos de deploy).
Registar no CMDB: versão 0.7.05.202605280, data, responsável, hash.

Passo 3 — CloudFormation

Revisar ecosif-automations.yaml (ou stack pai ecosif-backend que inclui a nested stack).
Parâmetros mínimos: VpcId, subnets privadas, RdsSecurityGroupId, AlbDnsName, PostgresHost, RdsSecretArn, LambdaCodeS3Bucket, LambdaCodeS3Key.
Executar apenas via pipeline IaC homologado (Change Management).

Passo 4 — Pós-implantação (operacional)

Item	Ação
Secret `ecosif/{env}/automations-service`	Atualizar JSON com credencial válida do ecosif-auth (nunca usar password de exemplo do template).
Ficheiro `CT32.LD`	Colocar no bucket de import na chave `CT32_MASTER_KEY` (default: `CT32.LD`).
Teste controlado	Upload de um `.IPL` de homologação; verificar logs CloudWatch das 5 funções.

5. Variáveis de ambiente (referência auditável)

Os ficheiros env.import.lambda.example, env.import-dispatcher.lambda.example, env.entries.lambda.example e env.consolidation.lambda.example listam valores por função.

5.1 Obrigatórias — Lambda Import

AWS_S3_BUCKET_NAME, AWS_SQS_ENTRIES_QUEUE_URL
ECOSIF_API_BASE_URL, ECOSIF_AUTOMATIONS_SERVICE_SECRET

5.2 Obrigatórias — Lambda Entries / Consolidation

POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, ECOSIF_DB_SECRET
AWS_SQS_CONSOLIDATION_QUEUE_URL (Entries)
AWS_S3_BUCKET_NAME (Consolidation)

5.3 Opcionais (defaults seguros no código)

LOG_LEVEL (default INFO)
ECOSIF_API_URL_MODE (alb | gateway)
Portas e context paths das APIs (ECOSIF_*_PORT, ECOSIF_*_CONTEXT_PATH)
Prefixos S3 (AWS_S3_ERROR_FOLDER, AWS_S3_IMPORTED_FOLDER, …)
CT32_MASTER_KEY (default CT32.LD)

Credenciais: nunca em variáveis em texto claro em produção; usar Secrets Manager (ECOSIF_DB_SECRET, ECOSIF_AUTOMATIONS_SERVICE_SECRET).

6. Rastreabilidade e auditoria

6.1 MANIFESTO_ENTREGA.json

Contém: versão, data UTC, SHA-256 do lambda.zip, caminhos dos artefactos, referência às evidências de qualidade.

6.2 Evidências de qualidade (geradas pelo fornecedor)

Ficheiro	Conteúdo
`quality-summary.json`	Percentagem de cobertura e se passou o gate ≥ 80%
`coverage.xml`	Cobertura de linhas em `src/parsers`, `src/services`, `src/utils`, `src/models` (gate ≥ 80%)
`junit.xml`	Contagem de testes pass/fail
`VERSION`	Versão empacotada

O banco revisa estes ficheiros; não precisa reexecutar os testes.

6.3 Registo recomendado no processo de mudança do banco

Número da change + aprovadores
Hash SHA-256 do lambda.zip
Versão 0.7.05.202605280
Print ou anexo do quality-summary.json
Resultado do teste de homologação (upload IPL)

7. Operação contínua (cliente)

Entrada: upload de NNNNNN_YYYYMMDD.IPL no bucket de import.
Mestre: manter CT32.LD atualizado no bucket (não é movido por cada IPL).
Saída sucesso: imported/, relatórios em imported/reports/.
Saída erro: importError/ + ERRO_*.csv.
Monitorização: CloudWatch Logs /aws/lambda/ecosif-{env}-automations-*, métricas SQS (mensagens visíveis / DLQ).

8. Código-fonte Python (quando o contrato exige)

Se o banco exigir código-fonte para auditoria estática:

Requisito	Como é atendido
Código	Pasta `06-CODIGO-FONTE-AUDITORIA/` (tarball + `tests/`)
Testes	Incluídos em `tests/` — execução apenas em ambiente Disoft/CI
Cobertura ≥ 80%	Evidência em `03-EVIDENCIAS-QUALIDADE/` já gerada no build da mesma versão
Cliente não executa	O banco analisa código + relatório; não roda `pytest` em produção

Regra: entrega de fonte sem evidência de cobertura da mesma versão não cumpre o requisito mínimo.

9. Geração do pacote na Disoft (CI)

Ao criar uma tag Git alinhada com VERSION:

# No repositorio GitHub ds-ecosif-automations (modulo ecosif-automations)
# 1. Confirmar VERSION na raiz do modulo
# 2. Commit e tag (ex.: v0.7.05.202605280)
git tag v0.7.05.202605280
git push origin v0.7.05.202605280

O workflow .github/workflows/client-release.yml deste repositório executa testes (cobertura ≥ 80%), gera lambda.zip, monta o ZIP de entrega e publica:

Saída	Onde obter
Artefacto Actions	Run do workflow → Artifacts → `ecosif-automations-client-<versao>.zip`
Release GitHub	Página Releases da tag (mesmo ZIP)

O cliente recebe esse ZIP; não clona nem executa o repositório.

10. Perguntas frequentes (governança)

Por que não há Docker de “serviço” para o cliente?
Porque o produto é serverless (Lambda). Docker interno do fornecedor serve só para build/CI, não para operação bancária.

O cliente precisa escolher “modo ZIP” ou “modo imagem”?
Não. A entrega padrão é ZIP (lambda.zip). Imagem container só se o contrato AWS do banco exigir PackageType Image — mesmo código, empacotamento diferente (assunto de change separado).

Quem gera o lambda.zip?
Disoft, em pipeline com ci-quality-gate.sh (cobertura ≥ 80%) e build-client-release.sh.

Como validar que o ZIP em produção é o aprovado?
Comparar SHA-256 com MANIFESTO_ENTREGA.json e SHA256SUMS.txt.

11. Contacto e suporte

Incluir no processo interno do banco o fornecedor, versão implantada e hash do artefacto em todos os incidentes relacionados a importação IPL.

Documento vinculado à versão 0.7.05.202605280 — ecosif-automations.