🧪 Teste Local - ecosif-automations-python

Este documento explica como testar o módulo ecosif-automations-python localmente, sem precisar criar a infraestrutura AWS (Lambda, SQS, S3).

📋 Visão Geral

O módulo foi projetado para rodar em AWS Lambda, mas você pode testar tudo localmente usando scripts Python que simulam os eventos Lambda e usam o sistema de arquivos local ao invés de S3.

🎯 Arquitetura Local vs AWS

AWS (Produção)

S3 Upload → Lambda (import) → SQS → Lambda (entries) → SQS → Lambda (consolidation)

Local (Desenvolvimento)

Arquivo Local → Script Python → Serviços → PostgreSQL

🚀 Quick Start

1. Configuração Inicial

# Entrar no diretório do projeto
cd ecosif-automations-python

# Criar ambiente virtual
python3.11 -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

# Instalar dependências
pip install -r requirements.txt

2. Variáveis de Ambiente

Crie um arquivo .env ou exporte as variáveis:

# Modo Local (OBRIGATÓRIO)
export ECOSIF_LOCAL_MODE=true

# Diretório base para arquivos locais (opcional)
export ECOSIF_LOCAL_BASE_DIR=./local_data

# PostgreSQL (OBRIGATÓRIO)
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=ecosif
export DB_USER=postgres
export DB_PASSWORD=senha

# APIs (para validações)
export ECOSIF_API_BASE_URL=http://localhost
export ECOSIF_MASTERDATA_PORT=8081
export ECOSIF_MASTERDATA_CONTEXT_PATH=/ecosif-masterdata

3. Estrutura de Diretórios Local

Os scripts criam automaticamente a seguinte estrutura:

local_data/
├── input/              # Arquivos IPL para processar
├── imported/           # Arquivos processados com sucesso
│   └── reports/        # Relatórios de processamento
└── importError/        # Arquivos com erro

📝 Scripts Disponíveis

1. Teste Completo (Recomendado)

Testa todo o fluxo: import → entries → consolidation

# Tornar executável (Linux/Mac)
chmod +x scripts/test_local_full.py

# Executar
python scripts/test_local_full.py local_data/input/123456_20240101.IPL

O que faz: 1. ✅ Valida e processa arquivo IPL 2. ✅ Estrutura e insere entries no banco 3. ✅ Executa consolidação contábil 4. ✅ Calcula quota 5. ✅ Fecha o dia

2. Teste por Etapa

2.1 Importação

python scripts/test_local_import.py local_data/input/123456_20240101.IPL

Saída: Mensagem JSON para a próxima etapa

2.2 Entries

# Salvar mensagem da etapa anterior em message.json
python scripts/test_local_entries.py message.json

Saída: Mensagem JSON para consolidação

2.3 Consolidação

# Salvar mensagem da etapa anterior em consolidation.json
python scripts/test_local_consolidation.py consolidation.json

📂 Preparar Arquivos de Teste

1. Arquivo IPL

Coloque o arquivo .IPL em local_data/input/:

mkdir -p local_data/input
cp seu_arquivo.IPL local_data/input/123456_20240101.IPL

Formato do nome: {fundCode}_{YYYYMMDD}.IPL

2. Arquivo CT32.LD

Coloque o arquivo CT32.LD no mesmo diretório:

cp CT32.LD local_data/input/CT32.LD

Importante: O arquivo CT32.LD é um arquivo de referência permanente e não é movido durante o processamento.

🔍 Exemplo Completo

# 1. Configurar ambiente
export ECOSIF_LOCAL_MODE=true
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=ecosif
export DB_USER=postgres
export DB_PASSWORD=senha

# 2. Preparar arquivos
mkdir -p local_data/input
cp arquivo_teste.IPL local_data/input/123456_20240101.IPL
cp CT32.LD local_data/input/CT32.LD

# 3. Executar teste completo
python scripts/test_local_full.py local_data/input/123456_20240101.IPL

🐛 Troubleshooting

Erro: "File not found"

Problema: Arquivo IPL ou CT32.LD não encontrado

Solução: - Verifique se o arquivo está em local_data/input/ - Verifique se o nome do arquivo está correto - Verifique se o CT32.LD está no mesmo diretório

Erro: "Database connection failed"

Problema: Não consegue conectar ao PostgreSQL

Solução: - Verifique se o PostgreSQL está rodando - Verifique as variáveis DB_* - Teste a conexão: psql -h localhost -U postgres -d ecosif

Erro: "API validation failed"

Problema: Não consegue validar com APIs (masterdata)

Solução: - Verifique se as APIs estão rodando - Verifique ECOSIF_API_BASE_URL e portas - Ou desabilite validações temporariamente (modificar código)

Erro: "Module not found"

Problema: Imports não funcionam

Solução:

# Certifique-se de estar no diretório correto
cd ecosif-automations-python

# Verifique se o ambiente virtual está ativo
which python  # Deve apontar para venv/bin/python

# Reinstale dependências
pip install -r requirements.txt

🔄 Fluxo de Desenvolvimento

1. Desenvolver/Modificar código bash # Editar arquivos em src/ vim src/services/import_service.py

2. Testar localmente bash python scripts/test_local_full.py local_data/input/teste.IPL

3. Verificar logs - Os logs aparecem no console - Use LOG_LEVEL=DEBUG para mais detalhes

4. Testar unitariamente bash pytest tests/unit/

5. Deploy para AWS (quando pronto) bash cd infrastructure/terraform terraform apply

📊 Diferenças: Local vs AWS

🎓 Entendendo o Código

Modo Local

O código detecta automaticamente o modo local através da variável ECOSIF_LOCAL_MODE=true:

# src/utils/local_mode.py
LOCAL_MODE = os.getenv('ECOSIF_LOCAL_MODE', 'false').lower() == 'true'

Cliente S3 Adaptado

O s3_client.py verifica o modo local e usa sistema de arquivos:

if LOCAL_MODE:
    # Usa sistema de arquivos
    content = read_local_file(key)
else:
    # Usa S3
    content = s3.get_object(...)

Serviços Independentes

Os serviços (import_service, entries_service, etc.) são independentes da infraestrutura AWS. Eles apenas recebem dados e processam, não importa se vieram de S3 ou arquivo local.

📚 Próximos Passos

1. ✅ Testar importação de arquivos IPL
2. ✅ Validar estrutura de dados
3. ✅ Testar inserção no banco
4. ✅ Validar consolidação
5. ✅ Testar cálculo de quota
6. ✅ Verificar fechamento de dia

💡 Dicas

• Use LOG_LEVEL=DEBUG para ver logs detalhados
• Salve as mensagens JSON intermediárias para debug
• Teste com arquivos pequenos primeiro
• Verifique o banco de dados após cada etapa
• Use pytest para testes unitários automatizados

Última Atualização: 2025-12-09
Versão: 2.0.0