Normalizar clientes: demonstração CSV e laboratório reproduzível

Esta guia começa com um exercício que você pode montar no navegador do Dova 22.0.5. Depois preserva o laboratório local de 1.000 linhas para quem tem um checkout autorizado do motor. São amostras diferentes: mantenha seus arquivos, regras e contagens esperadas separados.

Demonstração CSV: de 18 para 10 linhas

Os arquivos públicos e as capturas pertencem a uma demonstração real preservada do Dova 20.0.4. Os bytes e as contagens foram conferidos nesta edição, e os campos dos componentes foram comparados com o código ativo 22.0.5. Esta guia não afirma que um novo intento 22.0.5 tenha sido executado durante sua preparação.

Baixe o CSV sintético de entrada e guarde a saída de referência separadamente. A entrada contém 18 registros e oito colunas; a saída contém 10 registros e seis colunas. Nomes, zonas e identificadores estão explicitamente marcados como DEMO.

• customers-demo.csvEntrada sintética (18 linhas) · CSV · 2,2 kBAbrir arquivo
• clientes-demo-excel.csvSaída de referência (10 linhas) · CSV · 773 BAbrir arquivo

Um registro antes e depois

O fragmento mostra DEMO-C002, e não o arquivo inteiro. Espaços excedentes são removidos e o texto fica em maiúsculas; HABILITADO passa a ACTIVO. O valor torna-se numérico: 2500.0 e 2500.00 representam o mesmo número nesta amostra.

customer_id,full_name,city,segment,status,credit_limit,demo_row_ref,internal_note
DEMO-C002, cliente   demo beta ,zona demo sur, empresa demo , habilitado ,2500.00,DEMO-R02,MUESTRA SINTETICA; SIN DATOS REALES

cliente_id,cliente_nombre,ciudad,segmento,estado,limite_credito
DEMO-C002,CLIENTE DEMO BETA,ZONA DEMO SUR,EMPRESA DEMO,ACTIVO,2500.0

Configurar os doze componentes

Crie um Mapping no Domain e na Folder do laboratório. Adicione os componentes da tabela e conecte uma cadeia linear nessa ordem. Cada bloco mostra a configuração técnica equivalente aos controles do inspetor; não é um documento de importação nem deve ser colado na visualização Advanced, que é somente leitura. Seu próprio desenho gera os identificadores dos nós.

{
  "format": "csv",
  "delimiter": ",",
  "hasHeader": true,
  "headerRowNumber": 1,
  "columns": [
    "customer_id",
    "full_name",
    "city",
    "segment",
    "status",
    "credit_limit",
    "demo_row_ref",
    "internal_note"
  ],
  "headerMappings": [],
  "encoding": "utf-8"
}

{
  "fields": [
    "customer_id",
    "full_name",
    "city",
    "segment",
    "status",
    "credit_limit"
  ],
  "operations": [
    "trim",
    "collapse_whitespace",
    "upper"
  ]
}

{
  "field": "status",
  "find": "HABILITADO",
  "replacement": "ACTIVO",
  "matchMode": "exact",
  "caseSensitive": true
}

{
  "field": "status",
  "operator": "equals",
  "value": "ACTIVO"
}

{
  "field": "customer_id",
  "operator": "not_empty",
  "value": ""
}

{
  "field": "full_name",
  "operator": "not_empty",
  "value": ""
}

{
  "field": "credit_limit",
  "operator": "not_empty",
  "value": ""
}

{
  "field": "credit_limit",
  "targetType": "number",
  "outputField": "",
  "onError": "fail",
  "defaultValue": ""
}

{
  "mapping": {
    "customer_id": "cliente_id",
    "full_name": "cliente_nombre",
    "city": "ciudad",
    "segment": "segmento",
    "status": "estado",
    "credit_limit": "limite_credito"
  }
}

{
  "fields": [
    "cliente_id",
    "cliente_nombre",
    "ciudad",
    "segmento",
    "estado",
    "limite_credito"
  ]
}

{
  "field": "cliente_id",
  "direction": "asc"
}

{
  "format": "csv",
  "fileName": "clientes-demo-excel.csv",
  "delimiter": ",",
  "includeHeader": true,
  "textQualifier": "double",
  "quoteMode": "minimal",
  "escapeCharacter": "\\",
  "lineEnding": "crlf",
  "encoding": "utf-8-bom",
  "nullValue": ""
}

Há dez transformações entre origem e destino: limpeza, substituição, quatro filtros, conversão, renomeação, seleção e ordenação. Os quatro filtros precisam vir antes de Convert type: a amostra contém um registro inativo com valor inválido, que deve ser excluído antes da conversão. not_empty verifica se o valor limpo está preenchido; não comprova que qualquer texto seja numérico.

Publicar e executar pelo navegador

1. Use Validate e resolva as mensagens; salve com Save draft.
2. Escolha Publish, confirme a publicação e confira a versão persistida. Alterações posteriores exigem salvar e publicar novamente.
3. Clique em Run no Mapping e selecione customers-demo.csv no seletor de arquivo CSV. Este teste direto não exige conexão S3, Session ou Workflow.
4. Acompanhe o intento no Monitor e registre seu identificador. Aguarde o sucesso terminal; queued ou uma solicitação aceita ainda não significam conclusão.
5. Use Download output quando o intento bem-sucedido tiver saída armazenada. Salve o CSV baixado separado do arquivo de referência.
6. Compare o download real com o resultado esperado, sem reordenar nem editar o arquivo para forçar a coincidência.

Critérios de aceitação

Confira o cabeçalho exato, seis colunas e dez registros de dados, identificadores únicos e ordem física crescente por cliente_id, textos normalizados, estado ACTIVO e valores numericamente equivalentes. Verifique que demo_row_ref e internal_note não estejam na saída. O destino configura BOM UTF-8 e CRLF, adequados para abrir ou importar o CSV no Excel. O arquivo continua sendo CSV, e não uma pasta de trabalho XLSX.

Se faltarem linhas, identifique o primeiro filtro que exclui cada registro. Se Convert type falhar, confira os filtros anteriores e o valor aceito. Para colunas incorretas, revise Field mapper e Field selector. Se Download output não aparecer, confira o estado terminal, a saída armazenada e as permissões; publicar não gera o arquivo por si só.

Ver as capturas reais das 16 etapas da demonstração

Laboratório local adicional: 1.000 linhas → 667

O pacote local pertence ao laboratório da edição 6.0.2 e preserva sua verificação original. As 667 linhas são o critério esperado dessa amostra, não um novo intento 22.0.5. Ele exige um checkout autorizado; para aprender apenas pelo navegador, use a demonstração acima.

Material e escopo do laboratório local

O pacote histórico de amostras · laboratorios-dova-6.0.2.zipZIP · 43,8 kBBaixar contém inputs/customers.csv, expected/customer_normalized.csv e definições de Mapping, Session e Workflow. A entrada tem 1.000 registros com customer_id, raw_name, location, amount e status. Inclui espaços repetidos, acentos, localização separada por | e estados ACTIVE, ENABLED e INACTIVE. O resultado de referência contém 667 registros.

O executor requer um checkout autorizado de DovaETL e suas dependências Python, incluindo openpyxl na versão indicada no pacote. O motor não está incluído. O wrapper não instala programas, não inicia servidor, não cria objetos em um tenant e não testa workers remotos. As verificações preservadas pertencem ao laboratório original; não representam um novo teste executado em Dova 22.0.5.

Entender as oito transformações do laboratório

1. Clean: trim, collapse_whitespace e remove_accents em raw_name e location.
2. Replace: substitua exatamente ENABLED por ACTIVE.
3. Split: separe location em city e country usando | e remova o campo original.
4. Concat: forme customer_key com raw_name, # e customer_id.
5. Derive: monte segment com o template ${country}-${status}; é substituição de texto.
6. Convert: converta amount para amount_number, com onError=fail, preservando o original.
7. Filter: mantenha status=ACTIVE.
8. Sort: ordene amount_number em ordem decrescente.

Replace antes de Filter mantém também os registros originalmente ENABLED. Convert antes de Sort ordena números, não sua representação textual. Não misture esta cadeia de oito transformações com as dez transformações da demonstração de 18 linhas.

Executar a verificação local

Extraia o pacote e, na pasta extraída, informe seu checkout autorizado:

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

Substitua o caminho ilustrativo pelo real. Consulte o README do laboratório · README.mdMarkdown · 2,5 kBBaixar. O wrapper verifica as duas POCs, força local_json, bloqueia rede e acesso persistente a app/shared, copia os arquivos para um diretório temporário e o remove ao terminar. O relatório opcional contém somente evidência sintética. Integridade dos arquivos, definições e referência de fingerprint são verificadas antes da comparação.

Interpretar o oráculo

O oráculo usa funções Python independentes dos operadores DovaETL: limpa textos, normaliza estados, divide localização, deriva campos, exclui inativos e ordena. Aceite a amostra quando houver 667 linhas e coincidência byte a byte entre motor, oráculo e CSV de referência; o relatório esperado mostra PASS_BYTE_EXACT. Uma exceção ou código diferente de zero significa que o teste não passou no seu ambiente.

A comparação também detecta cabeçalho, ordem, fim de linha e representação numérica. Não substitua o resultado esperado por uma saída ainda não compreendida. Ao alterar a regra, calcule o novo esperado independentemente e preserve a amostra original.

Levar o laboratório à interface

Estude a cadeia em Mappings e os bindings source_csv e target_csv em Sessions. Prepare Domain, Folder, worker e caminhos de laboratório. As definições de exemplo explicam o contrato, mas não substituem a configuração explícita do ambiente.

Publique as dependências, execute manualmente pelo Workflow e confira Monitor. Compare com expected/customer_normalized.csv. Se o teste local passar e o remoto falhar, investigue versão, caminhos, bindings, permissões e worker; uma regra correta não torna o arquivo do computador local acessível em outro host.