0004 — MODO staging: gate manual da entrega ao Integrador¶

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

Contexto¶

A Fase 1 (decisão 0001) só captura raw; a Fase 2 fará o transform e o push ao Integrador, que chega no ERP do cliente via PowerSync → cliente Java. Antes de confiar nesse fluxo em produção, a equipe X-Adm precisa validar a integração ponta a ponta — mas um push automático no primeiro deploy da Fase 2 inunda o ERP do cliente com dado de teste, sem chance de inspecionar pedido a pedido o que está sendo gravado.

Falta um gate controlável sobre o passo de entrega — separado do transform, para poder segurar o envio sem parar a captura nem a normalização.

Decisão¶

Uma variável de ambiente MODO (env do Coolify, PRODUCAO | STAGING, default PRODUCAO) governa o push ao Integrador na Fase 2:

PRODUCAO — fluxo natural da Fase 2: cada pedido normalizado e elegível é enviado automaticamente ao Integrador.
STAGING — o transform roda e o pedido é enfileirado como pendente; nada é enviado ao Integrador até um comando manual. A liberação se dá por uma tela com:
Processar próximo — solta exatamente 1 item da fila (inspeção item a item);
Processar todos os pendentes — libera a fila inteira, para quando a confiança subir.

A fila é sobre o normalizado, não sobre o raw. O que se processa é um pedido (pied_pedido, Fase 2), não uma página crua (pied_rest, Fase 1). O estado vive como status na tabela normalizada (pendente → enviando → enviado | erro); o transform sempre roda até pendente — o MODO só decide se o passo seguinte (push) é automático ou manual.

Precedência sobre o toggle existente: o pied.integracao.habilitada (esqueleto de hoje) liga a Fase 2 como um todo; o MODO refina como ela entrega. Combinação:

`pied.integracao.habilitada`	`MODO`	Comportamento
`false`	(ignorado)	Fase 2 desligada — só captura raw (estado atual, Fase 1).
`true`	`PRODUCAO`	Transform + push automático ao Integrador.
`true`	`STAGING`	Transform + enfileira pendente; push só por comando na tela.

Consequências¶

A Fase 2 nasce com o transform desacoplado do push. O passo de entrega é uma etapa separada, gated pelo MODO — não dá para "colar" o push dentro do transform sem quebrar o gate.
Status de entrega na tabela normalizada (pied_pedido), com o ciclo pendente/enviando/enviado/ erro — vira também a base de reprocessamento e de auditoria da entrega.
Superfície nova: tela + auth. Este app hoje é API pura, sem views nem security (build.gradle.kts). A tela de fila (processar próximo / todos) e seu login-gate são escopo de Fase 2, a desenhar junto com o transform.
MODO é env do Coolify, default PRODUCAO — o comportamento seguro de produção é o padrão; STAGING é opt-in por deploy/ambiente de teste.
Não muda a Fase 1 (spec 001) nem o código atual — é uma restrição de desenho que a Fase 2 herda, não trabalho a fazer agora.

Alternativas consideradas¶

Toggle único liga/desliga o push, sem fila nem tela: rejeitada — desligar o push segura tudo, mas não deixa inspecionar e liberar pedido a pedido, que é justamente o valor do teste da equipe.
Push sempre automático (sem MODO): rejeitada — arrisca inundar o ERP do cliente com dado de teste no primeiro ciclo da Fase 2.
Só um ambiente de staging separado (deploy apontando a um Integrador de teste): complementar, não substituto — resolve onde grava, não dá o controle manual passo a passo contra o fluxo real. Pode coexistir com o MODO.