Sugerir mapping com IA: rode o teste de conexão antes

Quando rodar o teste de conexão antes de criar mapping?

• Sempre na primeira vez que vai usar uma mensagem SAP OData nova (A_BillingDocument, A_SalesOrder, A_PurchaseOrder, etc).
• Sempre que o sistema SAP foi modificado (novos campos, fields removidos, navs adicionadas).
• Sempre que aparecer banner "Mapeamento referencia campos que não existem no catálogo" ao salvar.

Por quê?

O Lefia guarda o catálogo do SAP no banco em catalog_user_messages. Esse catálogo é populado apenas quando você roda o teste de conexão — nesse momento o Lefia baixa o $metadata do SAP e grava a lista canônica de fields.

Quando você cria um mapping novo, o sistema usa esse catálogo do banco como fonte da verdade. Se o catálogo nunca foi populado pra essa mensagem (ou está stale porque você adicionou fields no SAP depois), a IA tem que adivinhar os fields disponíveis — e pode propor campos que não existem mais ou nunca existiram.

Sinais de que o catálogo está stale

1. Save do mapping retorna 422 — campos não existem no catálogo.
2. Banner amarelo no editor: "Mapeamento referencia campos desatualizados".
3. Lista de fields no wizard mostra campos com nomes "esquisitos" que você não reconhece (ex: VATRegistrationCountry quando deveria ser ToCountry).

Como atualizar

1. Abra a integração no Lefia.
2. Clique em Testar conexão.
3. Aceite o preview que mostra fields adicionados/removidos.
4. Agora pode rodar Sugerir IA no editor — vai usar a lista atualizada.

Sob o capô (V3.1 — 21/05/2026)

Antes do release V3.1, o endpoint que populava o wizard usava só uma lista estática shipada com o build (não consultava o banco). Agora consulta findEffectiveFormat que mescla DB + lista estática — DB tem prioridade. Resultado: catálogo populado pelo teste de conexão é honrado em toda a cadeia.