Sistema de fluxos e aprovações

No centro há uma máquina de estados persistida. Um workflow é um grafo de nós tipados: entrada, validação, aprovação, integração, notificação, finalização. Cada nó declara o que consome, o que produz e como falha. Uma instância desse grafo é um processo em andamento, e ela vive em duas tabelas: `instance`, com o estado corrente, e `step_run`, com uma linha por tentativa de execução de nó. O estado nunca mora na memória do worker. Se o processo morre no meio da integração, outro worker pega a instância exatamente no passo em que ela parou, porque o passo anterior já foi commitado.

O avanço entre nós passa por fila. O executor não chama o próximo nó direto: ele grava o resultado do nó atual e publica o evento de transição na mesma transação, usando outbox, a linha do evento vai para uma tabela junto com o commit do estado, e um relay a entrega ao broker depois. Isso elimina a janela clássica onde o banco commita e a mensagem se perde, ou a mensagem sai e o banco faz rollback. Filas separadas por tipo de nó: integração e notificação têm perfis de latência e falha completamente diferentes, e uma API de ERP lenta não pode segurar a fila de aprovação.

Cada execução de nó carrega uma chave de idempotência derivada de `(instance_id, node_id, attempt_group)`. O worker grava essa chave antes de chamar o sistema externo e a envia como header quando a API do outro lado suporta. Onde o parceiro não aceita chave de idempotência, a dedupe é por conciliação: antes do retry, o worker consulta o sistema externo pela referência do processo e, se o efeito já está lá, fecha o passo em vez de chamar de novo. O que diferencia o retry aqui é para onde o erro devolve a instância. Timeout e 5xx voltam para a fila no mesmo nó do grafo. 4xx de validação param a instância e abrem pendência humana, que não é um alerta, é um passo do fluxo, com dono, caixa de tarefas e SLA. O que estoura o teto vai para a dead-letter com payload e motivo, e o reprocesso recoloca a instância naquele nó: o processo não reabre, o número não muda, a trilha continua a mesma.

Comecei pelo runtime, não pelo editor. A primeira versão não tinha tela nenhuma: workflow era um JSON versionado em disco e a instância avançava por chamada de API. Isso forçou o modelo de dados a ficar honesto antes de existir uma interface bonita escondendo problema. Só quando o motor executava um fluxo de seis nós com falha injetada em cada um deles, e o reprocesso batia na chave de idempotência em vez de abrir um segundo pedido do outro lado, é que o editor visual entrou.

A parte difícil não foi executar o caminho feliz, foi o que acontece quando o grafo muda. Um processo de compra pode ficar dez dias esperando aprovação, e nesse intervalo alguém edita o fluxo. Resolvi congelando a versão: cada instância guarda a versão do workflow com que nasceu e termina nela. Publicar uma versão nova não move instância em voo. Migração entre versões existe, mas é operação explícita, com mapeamento de nó para nó e registro de quem migrou.

A segunda dor foi o motor de regras. A tentação era permitir código arbitrário no nó de validação. Recusei: regra roda como expressão declarativa em sandbox, com timeout e sem I/O na mão da regra, o que ela precisa do cadastro é declarado no próprio nó e o runtime resolve antes de avaliar. Perde poder, ganha previsibilidade: regra de negócio escrita por analista não derruba worker de produção nem vira vetor de execução remota.