Mapping — erros explicáveis

Atualizado 2026-05-06. Substitui o comportamento antigo de mostrar "Erro ao aplicar mapping: <stack>" sem contexto.

O que mudou

Antes, qualquer falha no mapping retornava uma mensagem genérica e pipeline_status: error sem indicar o quê quebrou. O operador tinha que abrir o payload manualmente e adivinhar.

Agora a mensagem traz kind, campo, valor recebido, valor esperado e sugestão de origem quando há um candidato próximo nos segments.

4 tipos de erro

Como ver os erros

1. Logs da mensagem

Em /edi-hub/empresa/[id] ou /monitor, abrir uma mensagem com pipeline_status: error e ver os logs. O log de step: error agora traz:

Erro ao aplicar mapping:
  Campo obrigatório invoiceNumber não encontrado (origem invoice_number ausente).
  Origem sugerida: invoice_number;
  Transform "multiply" em total esperava número mas recebeu "abc" (origem qty).

E em details do log, um array errors estruturado com kind, field, source_field, transform, expected, received, suggestion.

2. Warnings (mensagem segue OK)

Se o mapping tiver apenas warnings (campos opcionais ausentes), o pipeline_status continua mapped e a mensagem segue pro destino. Aparece um log step: mapped, status: warning listando o que ficou de fora.

Sugestão de origem (fuzzy match)

Quando o source_field configurado não bate, o sistema procura nos segments reais por algum nome próximo (Levenshtein normalizado em chars, capa em distância 3). Pega:

• typos (Belnnr → BELNR)
• diferença de case (invoiceNumber → invoice_number)
• separadores (billing-document → billing_document)

Não pega nomes muito diferentes (abc → totally_other_field_name retorna null).

Como marcar campo como required

No JSON field_mappings da tabela mappings:

[
  {
    "source_field": "E1EDK01.BELNR",
    "destination_field": "purchaseOrder",
    "transform": "direct",
    "required": true
  }
]

required: true = bloqueia pipeline se source ausente. required: false ou omitido = warning, segue pro destino.

A UI de edição de mapping ainda não tem checkbox de required (vai entrar junto com #66 — Validação de schema antes de ativar). Por enquanto, marcar via SQL:

UPDATE mappings SET field_mappings = jsonb_set(
  field_mappings,
  '{0,required}', 'true'::jsonb
) WHERE id = '<mapping-id>';

Reprocessamento após corrigir

Depois de ajustar o field_mappings (corrigir source_field, adicionar required, corrigir transform_config), o operador clica Reprocessar na mensagem em erro. O pipeline aplica o mapping novo e — se passar — segue pro destino.

Para reprocessar em lote, usar o painel /admin/queue (super_admin/support) ou a ação bulk em /edi-hub.

Itens relacionados no roadmap

• #66 — Mapping: Validação de schema antes de ativar: usa o mesmo tipo MappingError pra rodar contra um payload de exemplo e bloquear ativação se houver kind: error
• #65 — Mapping: Preview do payload convertido: aproveita os erros estruturados pra destacar campos problemáticos no UI antes de enviar
• #68 — Mapping: arrays/items ✅ entregue 2026-05-06: ver mapping-arrays-items
• #67 — Este item: Mensagens de erro explicáveis ✅ entregue 2026-05-06