Resumo regional: combinar TXT e Excel com um Join verificável

Escopo do laboratório regional

Esta guia integra a documentação do Dova 22.0.5 e explica componentes presentes nessa versão. O pacote para download preserva os dados e a verificação do laboratório original da edição 6.0.2. Quatro linhas de saída são seu critério esperado, e não uma afirmação de nova execução 22.0.5. O wrapper exige um checkout autorizado do motor; para aprender só pelo navegador, comece pela demonstração CSV de 18 para 10 linhas.

Este laboratório relaciona transações sintéticas de um TXT delimitado por | com um catálogo de clientes em Excel. Cada entrada possui 1.000 registros. O processo mantém transações aprovadas, associa cada cliente à sua região e gera um CSV com quatro linhas de dados. Assim, você pode estudar várias origens, diferenças de tipo nas chaves e uma agregação calculável independentemente.

Entradas e resultado esperado

No pacote histórico de amostras · laboratorios-dova-6.0.2.zipZIP · 43,8 kBBaixar, inputs/transactions.txt contém customer_id, amount e status. Identificador e valor são lidos como texto. De forma determinística, cada quinta transação é REJECTED; as demais são APPROVED. Não há pagamentos nem identificadores de sistemas externos.

inputs/customers.xlsx tem a planilha Customers, cabeçalho na primeira linha e 1.000 registros nas colunas A a C: customer_id, customer_name e region. O identificador é interpretado como inteiro. Nomes e regiões incluem espaços e acentos para tornar a limpeza observável. A saída expected/regional_approved_totals.csv conserva somente sales_region e approved_total.

Revisar as oito transformações

Na primeira ramificação, Convert type transforma amount do TXT em amount_number, numérico. Na segunda, Clean text aplica trim, collapse_whitespace, remove_accents e upper ao nome e à região do Excel. Inspecione as origens separadamente antes de atribuir um problema ao Join.

1. Convert type: amount → amount_number, targetType=number e onError=fail.
2. Clean text: normalize customer_name e region na ramificação XLSX.
3. Join: inner, chave customer_id em ambos os lados, keyType=integer, strategy=hash, nullsEqual=false. O lado esquerdo vem da conversão TXT; o direito, da limpeza XLSX.
4. Row filter: mantenha status equals APPROVED.
5. Group aggregate: groupBy=[region], metric=sum, field=amount_number, outputField=total_amount.
6. Row sort: total_amount em ordem decrescente.
7. Field mapper: region → sales_region e total_amount → approved_total.
8. Field selector: mantenha exatamente sales_region e approved_total.

O destino é Flat File output, CSV UTF-8 com cabeçalho e fim de linha LF. O XLSX é uma entrada; a saída não é uma pasta de trabalho Excel. O tipo inteiro na chave do Join permite comparar o identificador textual do TXT com a célula numérica do XLSX. Várias correspondências do mesmo cliente podem multiplicar registros antes da soma.

Executar sem conexões externas

Prepare um checkout autorizado de DovaETL e suas dependências, incluindo openpyxl conforme o pacote. O motor não vem incluído. Extraia a amostra e execute, na pasta extraída:

python .\run_pocs.py --repo C:\caminho\DovaETL --report .\verification.json

Substitua o caminho ilustrativo pelo real e leia o README · README.mdMarkdown · 2,5 kBBaixar. O wrapper verifica também o laboratório de normalização. Ele usa bytes locais: não exige URL nem chave. Bloqueia rede e armazenamento persistente, copia amostras para um diretório temporário e o elimina ao terminar. O relatório opcional conserva apenas nomes de testes, contagens, hashes e comparações sintéticas.

O programa verifica integridade, valida Mapping, Session e Workflow e resolve os bindings source_txt e source_xlsx pelos identificadores reais das definições. Também confere 1.000 linhas reportadas na planilha Customers. Um erro no nome da planilha ou no intervalo de leitura deve ser tratado como entrada, antes de investigar a agregação.

Aceitação e diagnóstico

O oráculo independente monta um dicionário de regiões por identificador inteiro. Percorre as transações, exclui rejeitadas, soma valores por região e ordena. Ele não chama os operadores Join nem Aggregate do motor. A aceitação exige quatro linhas e correspondência byte a byte entre motor, oráculo e CSV esperado; o relatório esperado contém PASS_BYTE_EXACT.

A representação numérica pertence a esta amostra e não define uma política contábil universal. Em dados financeiros, estabeleça precisão, escala, moeda e arredondamento com o responsável pelo processo. O formato visual de uma planilha não comprova essas regras.

• Menos regiões: confira chaves sem correspondência, tipos e modo de Join.
• Totais duplicados: confira a unicidade das chaves do catálogo de clientes.
• Regiões separadas por acentos ou espaços: confira a limpeza antes da agregação.
• Colunas excedentes: confira Field mapper, Field selector e o destino.
• Comparação diferente: examine cabeçalho, ordenação, fins de linha e valores; não substitua o esperado pela saída sem explicar a diferença.

Levar o caso a um Workflow

Construa o desenho em Mappings e configure os dois bindings em Sessions. Um único upload não substitui duas fontes diferentes. O Run do Mapping dispõe de seleção de entradas compatíveis por origem; para o contexto reutilizável, confira os caminhos acessíveis pelo worker. Na CLI, use opções --source repetidas conforme a guia de automação.

Publique as dependências e teste manualmente antes de habilitar o Workflow em uma agenda. Confira estado e tarefas no Monitor, compare os dois campos de saída e registre o intento e suas versões. A validação local das regras não certifica permissões, caminhos remotos, drivers ou capacidade do worker.