Pular para conteúdo

0007 — Saneamento de texto para o X-Adm: sem diacríticos e caixa alta

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-21 · Decidido em: 2026-07-21

Contexto

O X-Adm — ERP legado da Maxsul — historicamente exige texto em caixa alta e sem acentos nos campos texto-livre (Painel Solar 550W chega como PAINEL SOLAR 550W). O TransformService já emitia o NomeProd do Kit assim ("GERADOR FOTOVOLTAICO DE CORRENTE CONTINUA COM POTENCIA …", ver mapeamento §4), mas os demais textos vindos do PIED (nome, razão social, endereço, cidade, contato, nome de produto do fluxo não-Kit) passavam como recebidos — mistura de caixa e com diacríticos.

Ao avaliar, três candidatos:

  1. Convenção do X-Adm — regra do ERP, aplicável por campo (não a tudo).
  2. Limitação de charset do ZIM — regra do banco, universal para toda saída.
  3. Não fazer — deixar o próprio driver zimrtmu decidir.

A Maxsul confirmou: é (1) — convenção do ERP, não do ZIM. Logo, a regra é por campo, não universal, e a escolha da allowlist é nossa.

Decisão

Introduzir SaneadorTexto.paraXadm(String) (NFD + strip \p{Mn} + toUpperCase(ROOT), null/blank → null preservando a regra "branco não nulo"), aplicado no TransformService na seguinte allowlist de campos texto-livre destinados ao X-Adm:

Aplica Campos X-Adm
✅ propriedades.NomeProp, propriedades.Fantasia, propriedades.Endereco, propriedades.Bairro, propriedades.Cidade, propriedades.Numero, fones.Nome, estoque.NomeProd (Kit e não-Kit)
❌ fones.Email — local-part é case-sensitive por RFC; uppercase + strip quebra entrega
— CgcCpf, CEP, DDD, Telefone, InscEst (só dígitos), Estado (UF já em caixa alta), códigos (xPed, CodigoAlt, NatOp, Compl, TpVda, ClassForma)

O saneador vive na camada de transform, imediatamente antes de compor o EstadoDesejado. O pied_pedido.payload (e demais landing pied_*) permanece cru — saneamento não toca a trilha de auditoria, só a saída para o Integrador.

Consequências

  • O de-para fica consistente: o que chega no X-Adm sempre segue a convenção do ERP, sem depender de dado bem-comportado na PIED.
  • O NomeProd do Kit deixa de ser literal hardcoded em caixa alta e passa pelo mesmo saneador — se o texto-base mudar amanhã, continua saneado. Efeito colateral: o kW vira KW (aceitável — a regra é global sobre o campo).
  • E-mail preservado — evita quebra de entrega com provedores que respeitam case no local-part.
  • Reversível: o saneador é uma função pura sem estado; retirar/mudar a allowlist é uma edição pontual no TransformService. Idempotente: aplicar duas vezes dá o mesmo resultado.

Alternativas consideradas

  • Sanear tudo (blanket) — rejeitado: quebra Email (case-sensitive por RFC), poluiria códigos/dígitos sem ganho, e o próprio Estado (UF) já vem em caixa alta.
  • Sanear no NormalizadorService (gravar já sem acento) — rejeitado: perde a fidelidade do pied_cliente/pied_produto/pied_pedido como espelho do PIED, dificultando diagnóstico e reprocessamento futuro.
  • Deixar para o zimrtmu — rejeitado: é convenção do ERP, não do ZIM (fonte da regra confirmada com a Maxsul); e o TransformService é o lugar onde o de-para já está — mantém a regra visível no ponto onde os campos são de-parados.