Documentação Operacional — ecosif-automations¶
Público-alvo: DevOps / SRE
Módulo: ecosif-automations (importação e ETL)
1. Agendamentos e Gatilhos (Sem Cron)¶
O módulo não utiliza cron jobs no código. O processamento é event-driven:
| Gatilho | Onde | O que dispara |
|---|---|---|
| S3 ObjectCreated | Bucket de import (.IPL) |
Lambda import — regista janela ou processa imediato (IMPORT_DEFER_ENABLED). |
| SQS import-defer | …-automations-import-defer |
Mensagens FLUSH → Lambda import-dispatcher → fila entries FIFO. |
| SQS entries FIFO | …-automations-entries.fifo |
Lambda entries (MessageGroupId = fundo). |
| SQS consolidation-defer | …-automations-consolidation-defer |
FLUSH com debounce → Lambda consolidation-scheduler. |
| SQS consolidation FIFO | …-automations-consolidation.fifo |
Lambda consolidation (MessageGroupId = empresa|filial). |
Em modo local (ECOSIF_LOCAL_MODE=true), não há filas; os scripts em scripts/ chamam os serviços diretamente (ex.: test_local_import.py, test_local_full.py).
2. Pastas de Entrada e Saída¶
2.1 Em AWS (S3)¶
| Pasta (prefixo no bucket) | Variável | Descrição |
|---|---|---|
| Entrada | — | Qualquer prefixo; o evento S3 contém a key do .IPL. O ficheiro mestre CT32.LD deve existir na chave definida em CT32_MASTER_KEY. |
| importError/files/ | AWS_S3_ERROR_FILES_FOLDER (default: importError/files/) |
.IPL com falha de validação/import/consolidação. |
| importError/ (raiz) | AWS_S3_ERROR_FOLDER |
CSV ERRO_<nome_ipl>.csv (mensagem de erro). |
| imported/files/ | AWS_S3_IMPORTED_FILES_FOLDER (default: imported/files/) |
.IPL processados com sucesso. |
| imported/reports/ | AWS_S3_REPORTS_FOLDER |
Resumo mensal {FUNDO}_{YYYYMM}_report.csv e {nome}.CHANGES.csv. |
| imported/reports/details/ | AWS_S3_REPORTS_DETAILS_FOLDER |
Relatório linha a linha {nome}.IPL.REPORT.csv. |
| Raiz do bucket | — | Apenas CT32.LD (mestre) e .IPL à espera de processamento. |
2.2 Em Modo Local¶
Com ECOSIF_LOCAL_MODE=true e ECOSIF_LOCAL_BASE_DIR (default: ./local_data):
| Pasta | Uso |
|---|---|
| local_data/input/ | Colocar .IPL para processamento e garantir CT32.LD na chave configurada por CT32_MASTER_KEY. |
| local_data/imported/ | Ficheiros processados com sucesso. |
| local_data/importError/ | Ficheiros com erro. |
| local_data/imported/reports/ | Relatórios de processamento. |
3. Variáveis de Ambiente Principais¶
| Variável | Obrigatória | Descrição |
|---|---|---|
| ECOSIF_LOCAL_MODE | Local: sim | true = usa sistema de ficheiros; false = usa S3/SQS. |
| ECOSIF_LOCAL_BASE_DIR | Não | Base para pastas locais (default: ./local_data). |
| AWS_S3_BUCKET_NAME / AWS_S3_BUCKET | AWS: sim | Nome do bucket S3. |
| AWS_S3_ERROR_FOLDER | Não | Prefixo para erros (default: importError/). |
| AWS_S3_IMPORTED_FOLDER | Não | Prefixo para importados (default: imported/). |
| AWS_S3_REPORTS_FOLDER | Não | Prefixo para relatórios (default: imported/reports/). |
| CT32_MASTER_KEY | Não | Chave S3 (ou path local relativo) do ficheiro mestre CT32 (default: CT32.LD). |
| AWS_SQS_ENTRIES_QUEUE_URL | AWS (import / dispatcher) | URL da fila FIFO entries. |
| AWS_SQS_IMPORT_DEFER_QUEUE_URL | AWS (import) | Fila de agendamento da janela de importação por fundo. |
| IMPORT_DEFER_ENABLED | Não | true = janela por fundo (default produção CFN). |
| IMPORT_WINDOW_TABLE | Se defer | DynamoDB …-import-window. |
| IMPORT_DEBOUNCE_SEC / IMPORT_MAX_WAIT_SEC | Se defer | 30 / 300 (defaults CFN). |
| AWS_SQS_CONSOLIDATION_QUEUE_URL | AWS (entries) | URL da fila FIFO de consolidação (nome termina em .fifo). MessageGroupId = empresa\|filial. |
| Republicar consolidação (IPL na raiz) | Ops | python scripts/republish-root-consolidation.py (ver script; requer entries já gravados). |
| CONSOLIDATION_DEFER_ENABLED | Não | true = janela debounce antes de consolidar (fase 4); false = envio imediato após entries. |
| CONSOLIDATION_DEBOUNCE_SEC | Se defer | Segundos de calma após o último IPL (default 120). |
| CONSOLIDATION_MAX_WAIT_SEC | Se defer | Teto desde o primeiro IPL da janela (default 600). |
| CONSOLIDATION_WINDOW_TABLE | Se defer | Tabela DynamoDB da janela por período. |
| CONSOLIDATION_LOCK_TABLE | Se defer | Tabela DynamoDB de lock por empresa\|filial. |
| AWS_REGION | AWS | Região (ex.: us-east-1). |
| ECOSIF_API_BASE_URL | Sim (validação/import) | Base das APIs (ex.: http://localhost ou https://api.ecosif.com). |
| ECOSIF_AUTH_PORT, ECOSIF_AUTOMATIONS_SERVICE_SECRET | AWS (import) | Sign-in ecosif-auth (8081 default). |
| ECOSIF_MASTERDATA_PORT, ECOSIF_MASTERDATA_CONTEXT_PATH | Sim | Masterdata (8082 default). |
| ECOSIF_MOVIMENTS_PORT, ECOSIF_MOVIMENTS_CONTEXT_PATH | Sim | Moviments (8083 default). |
| ECOSIF_API_URL_MODE | Não | alb (default) ou gateway. |
Credenciais AWS: IAM role (Lambda) ou variáveis AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (conforme ambiente).
4. Como Monitorar se uma Importação Falhou¶
4.1 Ficheiros e Pastas¶
- S3: Verificar a pasta importError/ no bucket. Se existir um ficheiro
.IPLe um ERRO_<nome>.csv com o mesmo nome base, a importação desse ficheiro falhou. O conteúdo do CSV inclui: timestamp, nome do ficheiro, mensagem de erro e estado do CT32 (ex.: "CT32.LD FILE NOT FOUND"). - Local: Ver local_data/importError/ e os ficheiros ERRO_*.csv no mesmo diretório.
4.2 Logs¶
- AWS Lambda: Consultar CloudWatch Logs do grupo de log de cada Lambda (import e entries). Em falha, o handler regista exceções com
logger.error(..., exc_info=True). Mensagens de erro também são adicionadas à listaerrorse devolvidas no body da resposta (status 207 em caso de erros parciais). - Local: Saída no stdout/stderr do script; em caso de exceção, o script termina com código não zero e a mensagem é exibida.
4.3 Fila SQS¶
- Mensagens que não forem processadas com sucesso pelo Lambda entries não são apagadas e podem voltar a ser entregues (retry). Após o número máximo de receções, podem ser enviadas para uma DLQ (Dead Letter Queue) se configurada no Terraform/console. Monitorizar a DLQ e a fila principal (mensagens em voo, mensagens disponíveis) no console AWS.
4.4 CT32 mestre¶
- Se o
CT32.LDnão existir na chaveCT32_MASTER_KEY, o import falha antes da fila entries. - Se o fundo do nome do IPL não existir no CT32, ou existir duplicado, o import falha com CSV em
importError/.
5. Dependências e Execução Local¶
- requirements.txt: boto3, requests, pydantic, python-dateutil, psycopg2-binary, pandas, numpy, python-dotenv, etc.
- Execução:
python scripts/test_local_import.py local_data/input/<ficheiro>.IPL(com ECOSIF_LOCAL_MODE=true e variáveis de API/DB definidas). Veranotations/local_testing.mdpara passos completos.
Para layouts dos ficheiros e guia "O que fazer quando uma importação falha", ver user/visao_geral.md. Para fluxos e integração com moviments/masterdata, ver architecture/arquitetura.md.