Distributed Wagering Processor

Provedores de jogos enviam transações de aposta (BET, WIN, LOSS, REFUND, ROLLBACK) por HTTP ou por fila SQS. O serviço precisa aplicar cada uma na carteira certa e manter um extrato imutável, sem nunca debitar duas vezes, criar dinheiro do nada ou deixar o saldo negativo, mesmo com várias instâncias processando ao mesmo tempo. Como extensão, a carteira também aceita depósito e saque pelo caixa, com as mesmas garantias.

Um único serviço NestJS. A rota HTTP e o consumer da fila chamam o mesmo use case; tudo o que muda dinheiro acontece em uma transação SQL, e só a outbox publica eventos.

• Validação pura, sem abrir transação: dinheiro com exatamente 2 casas, tipo da transação e hash do payload.
• Busca pela Idempotency-Key: mesmo conteúdo devolve o resultado original; conteúdo diferente é 409.
• SELECT … FOR UPDATE só na linha da carteira; carteiras diferentes seguem em paralelo.
• Regras de negócio no domínio, com desfecho PROCESSED, REJECTED ou PENDING_REFERENCE.
• Na mesma transação: transação, novo saldo, lançamento do extrato, eventos na outbox e, se veio da fila, a inbox. Só depois do commit vem a resposta ou o ack.

• Dinheiro nunca é number: centavos em bigint, strings com exatamente 2 casas, numeric(19,2) no banco.
• Concorrência por carteira, sem lock global: SELECT … FOR UPDATE mais UPDATE condicionado pela version; lock_timeout de 5 s vira 503 com Retry-After.
• Idempotência persistente: UNIQUE (idempotency_key) e SHA-256 do JSON canônico dos campos de negócio.
• Uma regra de negócio, três entradas: HTTP, consumer SQS e worker de pendências usam o mesmo decide().
• Inbox e outbox na transação do dinheiro: a inbox deduplica entregas com ON CONFLICT DO NOTHING, e o ack só sai depois do commit; a outbox é publicada com FOR UPDATE SKIP LOCKED.

• Mensagens fora de ordem: um estorno que chega antes da aposta fica PENDING_REFERENCE e é reprocessado com backoff exponencial até a referência existir.
• Corrida real entre instâncias: os testes sobem três processos do serviço disputando a mesma carteira e matam um deles com SIGKILL entre o commit e o ack.
• Invariantes no banco: constraints e triggers garantem as regras mesmo se o código falhar.

248 testes automatizados passando, rodando contra PostgreSQL e LocalStack reais, sem mocks. A mesma aposta enviada 50 vezes em paralelo resulta em um único débito.