Pular para conteúdo

Pendências e decisões em aberto

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-12

O que ainda depende de terceiros (PIED / X-Adm) para fechar. Itens já decididos saíram daqui — o conhecimento ficou destilado na doc do assunto (Modelagem, Mapeamento, API do Integrador, Tratamento de dados no ZIM, decisões).

Dono: 🔌 PIED · 🧮 X-Adm/ERP.

P1 — Quais dealStatus marcam "enviar ao X-Adm" 🔌 · bloqueia o quando enviar (Fase 2)

O X-Adm só faz INSERT de pedido (nunca UPDATE), então só se envia pedido em estado que já conta como venda. Campo identificado nos dados reais (14.300 pedidos capturados, jul/2026): é o dealStatus — e o requestStatus veio com distribuição idêntica (espelho; usar dealStatus). stockStatus (removed/none/reserved) não serve de gate. Valores observados, agrupados:

Grupo Valores (dealStatus) qtd Enviar?
Finalizado Finalizado (8269), Finalizado Garantia/Avaria (312) 8581 ✅ provável
Despachado Despachado (2727), Despachado Garantia/Avaria (63) 2790 ✅ provável
Pago / em produção Pedido Pago - Liberado para Produção (40), OP Gerada (34), NF Faturamento Banco - Financiamento (13), Nota Futura Emitida (7), Pedido Pago - Venda Futura (2) 96 🟡 decidir
Aguardando Aguardando Transportadora Coletar (55), Aguardando Controladoria (22), Aguardando Financiamento (2) 79 🟡 provavelmente não
Novo Novo (39) 39 ❌ não
Recusado Recusado Falta de Pagamento (2230), Recusado Alterar Informações (433), Recusado Desistência (45), Recusado Devolução/Estorno (7) 2715 ❌ não

Decisão (2026-07-13): âncora do gate = Pedido Pago - Liberado para Produção — o pedido é lançado ao X-Adm ao atingir esse marco.

✅ RESOLVIDA (2026-08-07) — Maxsul confirmou, e o gate MUDOU de eixo: não é mais por dealStatus. Análise dos pedidos reais mostrou que dealStatus não distingue pago de não-pago (ex.: "OP Gerada" aparece pago e não-pago) e que a PIED tem um campo payment.status dedicado (received, notRequested, requested, partial, cancelled). O gate passou a ser a transição de pagamento: envia quando um pedido que já tínhamos não-pago recebe um update com payment.status='received'. Detectada por evento no upsert (payment_status/payment_status_anterior). estados-venda não governa mais o envio (sobrou como filtro do "Puxar da PIED"). Ver docs/glossario.md (Gate) e IntegracaoConfig.

Ponto de atenção — o furo da 1ª captura (trade-off da transição): o gate é a transição para received, então precisa de um estado anterior não-pago que a gente tenha testemunhado. Um pedido que aparece já pago na 1ª captura (sem anterior) não dispara automaticamente — é intencional (pode ser pedido antigo da PIED chegando agora; evita despejar backlog). O operador manda esses pelo /console (Enfileirar exige payment_status='received'). Como o X-Adm só faz INSERT, envia uma vez. Ver decisão 0001 (design detalhado na spec 002 da linhagem .ia/).

⚠️ COBRADO NA PRÁTICA (2026-09-21) — o furo custou quatro pedidos. No apagão de webhook de 18/09/2026 (a PIED desativou o webhook após timeout; 2h44 de silêncio no pico da sexta), quatro pedidos nasceram e foram pagos na janela cega. O poll REST de backstop os trouxe já pagos — sem transição a testemunhar, encalharam em CAPTURADO e ninguém viu até a segunda. A válvula manual não basta: ninguém olha o console sem saber que há o que olhar. A decisão 0023 fecha os dois lados — watchdog com régua comercial (45 min, seg–sex 8h–18h) para o apagão virar visível, e resgate automático da 1ª captura já paga, cercado por orderCreated (piso de ativação + janela de 7 dias). Nasce desligado: ligar é pôr PIED_GATE_PRIMEIRA_CAPTURA_DESDE no deploy.

P2 — De-para restante 🧮 · não bloqueia o esqueleto da Fase 2

Já resolvidos (movidos ao Mapeamento): TpVda←freight.type, TaxaFrete←freight.price, InscEst←companies.stateInscription. Faltam quatro:

ClassForma (forma de pagamento)

Catálogo X-Adm: 01 Dinheiro · 02 Cheque · 03 Cartão de Crédito · 04 Cartão de Débito · 05 Crédito da Loja · 15 Boleto · 16 Depósito · 17 PIX · 18 Transferência · 90 Sem Pagamento · 99 Outros. Valores reais de payment.type (14.300 pedidos, jul/2026) e o de-para proposto:

payment.type qtd → ClassForma obs
boleto 6950 15 Boleto ✅
pix 6201 17 PIX ✅
credito 379 03 Cartão de Crédito payment.condition.name = "Cartão 3x/6x/10x" (parcelado)
financiamento 711 ? a decidir sub-tipos em condition.name: BV, Santander, "outros". Sem código X-Adm direto → 99? código novo?
other 41 99 Outros fallback
  • A (recomendada): de-para configurável (boleto→15, pix→17, credito→03, other→99), default 99 p/ tipo não mapeado — ajustável sem recompilar.
  • A fechar com a equipe: o código de financiamento (não há equivalente óbvio no catálogo).

Implementado (Fase 2): de-para configurável em pied.integracao.transform.class-forma com esses defaults; financiamento→99 é o default até a equipe decidir. Falta só a confirmação do código.

Prazo (data de entrega)

payment.condition ("30/60 dias") é condição de pagamento, não data de entrega. A PIED aparentemente não tem data de entrega. A confirmar com a PIED; enquanto isso, branco (regra "branco não nulo").

TaxaFrete (rateio)

freight.price é do pedido (valor único). Para gravar por item:

  • A (recomendada): ratear proporcional ao valor de cada item.
  • B: lançar o total no primeiro item.

EAN13

Não vem da API de produtos → branco; enriquecer de outra fonte depois, se necessário.

P3 — Contrato de entrada do zimrtmu 🧮 · bloqueia a gravação real (ps-java)

Como o cliente Java grava no ZIM. Ver Tratamento de dados no ZIM e decisão 0003.

A confirmar com a equipe X-Adm
Recebe o valor-armazenado ou o mascarado? Formato de ingestão (JSON, string ;)?
Largura / escala / padding por campo das cinco tabelas.

Interino: o ps-java segue como exemplo simulado (simulaXadm) até o contrato; a formatação por tipo já está especificada para a equipe.

P4 — Gate de identidade da segurança 🧮 · bloqueia fechar as telas administrativas

O int-pied roda com security.enabled: false (Fase 1 por design — decisões 0001, 0004, 0005): /console, /captura, /destinatarios e o /admin/mensageria que veio da lib xadm-mensageria (decisão 0012) nascem abertos. Ligar xadm-seguranca (Firebase idToken + sessão JWT, como o bi-transporte-xls) é trabalho pequeno.

Decidido (2026-09-12) — quem loga e o que fica público, para quando fechar:

Rota Acesso
GET / (painel) e GET /pedidos/{code} público
POST /webhook/pied público (autenticado pelo segredo do webhook)
todo o resto — ações do painel (POST /pedidos/{code}/importar, /dispensar, /reimportar, /importado-manual), /console, /captura, /dados, /destinatarios, /admin/mensageria, /test login Google restrito a @xadm.com.br (xadm-seguranca, AUTH_XADM_EMAIL_DOMAIN, default xadm.com.br)

Operador da Maxsul não loga nesta etapa.

Interino (decisão do dono): tudo aberto enquanto a implantação está em fase final. O deploy é público (https://pied.maxsul.xadm.biz) — as telas não expõem segredo, mas expõem ações (enfileirar, reenviar, reconciliar). Risco aceito conscientemente, não esquecido.

Reavaliar a cada release: o CLAUDE.md do repo manda o agente perguntar ao dono, antes de cada release, "a implantação terminou? fechar as telas agora?". Fechar = ligar micronaut.security, configurar auth.* e as regras de rota acima, e provar no e2e (rota pública responde sem sessão; rota fechada redireciona para o login).

Resumo — o que trava o quê

Para desenvolver… Precisa antes
maxsul-pied Fase 1 (captura raw) ✅ pronta (em produção)
maxsul-pied Fase 2 (transform + push) ✅ implementada e em produção (2026-08-07). P1 resolvida (gate = transição de pagamento payment.status→received); resta P2 código do financiamento (default configurável cobre)
Integrador ✅ colunas de venda + fones + INT-PIED em KNOWN_ORIGENS + GET …/retorno já no repo do Integrador
ps-java (gravação real) P3 (zimrtmu) — até lá, exemplo simulado
PowerSync pronto (sync rules já definidas)
Fechar as telas administrativas P4 decidida (só @xadm.com.br); aguarda o fim da implantação — até lá tudo aberto