Validação de schema na ativação de mapping

Quando você muda o status de um mapping de "draft" pra "active", o Lefia roda uma checagem automática contra o schema do formato de destino. Isso evita mandar lixo pra produção e responde a uma das perguntas-padrão de CTO mid-market: "como evito mandar dado incompleto pro destino?".

O que é validado

1. Mapping não pode estar vazio

Você precisa ter pelo menos 1 field mapping configurado.

2. Campos obrigatórios do formato de destino

Cada formato tem um schema mínimo de campos que precisam estar mapeados. Exemplos:

X12 850 (Purchase Order): BEG.BEG02, BEG.BEG03, BEG.BEG05 + PO1[].PO101, PO1[].PO102, PO1[*].PO104
X12 810 (Invoice): BIG.BIG01, BIG.BIG02 + IT1[].IT101, IT1[].IT102, IT1[*].IT104, TDS.TDS01
X12 856 (ASN): BSN.BSN01, BSN.BSN02, BSN.BSN03 + HL[].HL01, HL[].HL03
EDIFACT ORDERS: BGM.1004, BGM.1001, DTM.2005 + LIN[].1082, QTY[].6060
EDIFACT INVOIC: idem ORDERS + MOA.5004
NFe: ide.nNF, ide.dhEmi, emit.CNPJ + det[*].prod.cProd, qCom, vUnCom + total.ICMSTot.vNF
HL7 v2: MSH.3, MSH.7, MSH.9, MSH.10 + PID.3

Se faltar algum, a ativação é bloqueada com erro 422 e mensagem como: "Campo obrigatório BEG.BEG03 do formato X12 850 — Purchase Order não está mapeado. Quis dizer BEG.BEG003?"

3. Required marcado mas source vazio

Se você marcou um field mapping como required=true mas não preencheu o source_field, a ativação é bloqueada.

O que é só warning (não bloqueia)

Formato de destino sem schema definido (ex: ODATA_JSON proprietário) → warning "validação pulada"
Mesmo destination_field aparece em 2+ field mappings → warning "verifique se é encadeamento de transforms ou erro"

Bypass — `?force=true`

Em emergência ou quando o schema do catálogo não cobre seu caso real, você pode forçar a ativação:

PATCH /api/edi-hub/toggle-mapping-status?force=true
{ "mappingId": "...", "status": "active" }

Isso registra um evento mapping.activated_force no audit log (visível em /admin) com a lista de erros que foram bypassados — pra rastreabilidade.

Como destravar uma ativação bloqueada

A resposta 422 traz validation.errors[] com field, message e às vezes suggestion (fuzzy match contra os destinos que você já declarou). Tipicamente:

Verificar erro de digitação no destination_field — sugestão indica qual era a intenção
Adicionar field mappings faltantes
Tentar ativar de novo