Pedidos: idempotência e outbox transacional

Implementação didática nova e independente para estudar um problema de engenharia: uma entrega repetida precisa preservar a alteração de estado e a intenção de saída sem duplicá-las. Python, SQLite e unittest, somente com a biblioteca padrão e dados sintéticos. Não contém código nem dados de clientes.

Problema e decisão

Um processo pode receber a mesma entrega várias vezes. Se atualizar o pedido antes de registrar a notificação, uma falha pode deixar as duas partes inconsistentes.

order_flow registra a identidade da entrega, a transição do pedido e a intenção na outbox na mesma transação SQLite. Um replay idêntico retorna o resultado persistido; uma chave reutilizada com outro pedido, ação ou payload é rejeitada. BEGIN IMMEDIATE serializa escritores antes da checagem de duplicação.

O domínio é pequeno: pending pode virar confirmed ou cancelled. Os dois destinos são finais. Ações novas sobre um pedido final são inválidas, mesmo quando pedem o mesmo estado; somente o replay da mesma entrega é aceito.

Executar

Python 3.12 ou 3.13, sem instalação de dependências:

git clone https://github.com/LufeDigitalWave/commerce-platform-case-study.git
cd commerce-platform-case-study
python -m order_flow
python -W error -m unittest discover -s tests -v
python -m compileall -q order_flow tests

A demonstração cria um banco temporário, confirma um pedido, repete a entrega, cancela outro pedido e reabre o banco. As conexões são fechadas e o diretório temporário é removido ao terminar. Saída real:

{
  "cancellation": {
    "replayed": false,
    "state": "cancelled"
  },
  "confirmation": {
    "replayed": false,
    "state": "confirmed"
  },
  "outbox": [
    {
      "delivery_id": "delivery-001",
      "order_id": "order-001",
      "state": "confirmed"
    },
    {
      "delivery_id": "delivery-002",
      "order_id": "order-002",
      "state": "cancelled"
    }
  ],
  "reopened_replay": {
    "replayed": true,
    "state": "confirmed"
  },
  "replay": {
    "replayed": true,
    "state": "confirmed"
  }
}

Veja a fronteira transacional e as invariantes verificadas pelos testes. A CI executa testes, demonstração e compilação em Ubuntu/Windows × Python 3.12/3.13; o badge aponta o workflow, cujo resultado depende da execução no GitHub.

Limites

• Não há loja, checkout, gateway, rede, consumidor ou envio de notificações. confirm é uma entrada sintética, não prova de pagamento.
• Outbox registra intenção de saída. Não garante entrega externa nem processamento exactly-once; um consumidor precisaria de suas próprias políticas de repetição e deduplicação.
• Igualdade do payload é textual e exata. Autenticação, validação de contratos externos, canonicalização e retenção não estão implementadas.
• SQLite tem um escritor por vez. A conexão espera por locks até cinco segundos; não há retry automático nem benchmark de escala.
• Os testes cobrem transações locais e duas conexões. Não simulam queda de energia, falha de disco, múltiplos hosts, reembolso ou operação financeira real.