Sistema de Gestão de Precatórios

Problema

Dividir um valor entre centenas de pessoas proporcionalmente ao salário produz quotas com infinitas casas decimais. Arredondar cada uma e somar dá um número diferente do total. Num rateio de dinheiro público, essa diferença é um erro contábil que alguém vai encontrar.

Solução

A aritmética roda em decimal de alta precisão. Cada quota é truncada ao centavo, e os centavos que sobram são distribuídos um a um pelos maiores restos fracionários, com desempate determinístico. Deságio e bônus são potes separados, e cada pote fecha sozinho. No fim, o motor confere: se a soma das partes não for exatamente igual ao total, ele lança um erro em vez de gravar.

Por que foi feito assim

O método do maior resto é a forma clássica de fechar uma distribuição proporcional sem criar nem perder unidades. O desempate determinístico é o que garante que reprocessar a mesma entrada — em outra máquina, em outro dia, com o banco devolvendo as linhas em outra ordem — produza exatamente os mesmos centavos para as mesmas pessoas. Um rateio que muda entre execuções é indefensável perante controle externo, mesmo quando as duas execuções fecham no total.

Problema

Testar o rateio com três exemplos escolhidos à mão prova pouco. E verificar apenas que a soma fecha também não basta: uma distribuição grosseiramente injusta — em que uma pessoa leva quase tudo — fecharia no total e passaria no teste.

Solução

Duzentos cenários gerados por um gerador pseudo-aleatório de semente fixa, variando número de pessoas, quantidade de meses, deságio e bônus. Cada cenário verifica quatro invariantes: a soma fecha ao centavo; quem tem peso zero recebe exatamente zero; nenhum valor se afasta mais de dois centavos da quota matematicamente exata; e quem tem peso maior nunca recebe menos que quem tem peso menor. A cada vinte cenários, o mesmo caso é reexecutado com a lista embaralhada e comparado pessoa a pessoa.

Por que foi feito assim

A semente fixa dá o poder de cobertura do teste aleatório sem a instabilidade: a mesma sequência de cenários roda em qualquer máquina, em qualquer dia, e uma falha é sempre reproduzível. E escrever invariantes em vez de valores esperados obriga a declarar o que "correto" significa — foi assim que a verificação de alocação justa entrou, depois de ficar claro que fechar no total era condição necessária e não suficiente.

Problema

Um sistema que move dinheiro público precisa preservar histórico contra dois adversários diferentes: o operador que quer apagar o próprio erro, e quem tem acesso direto ao banco de dados.

Solução

A trilha de auditoria não tem rota de alteração nem de exclusão na aplicação — e o banco recusa alteração, exclusão e limpeza da tabela por gatilho próprio. O conteúdo de cada evento passa por uma redação recursiva que reconhece campos sensíveis por nome, insensível a acento, caixa e separador, com limite de profundidade e tamanho.

Por que foi feito assim

Proteger só na camada da aplicação deixa a trilha à mercê de quem tem credencial de banco — que é exatamente o adversário contra quem a trilha existe. A redação está lá porque log de auditoria é o lugar mais fácil do sistema para vazar um segredo sem perceber: alguém registra "o objeto que mudou" e o objeto tinha um token dentro.

Problema

Registrar pagamento é a operação em que um duplo-clique, um retry automático de proxy ou um timeout de rede custa dinheiro de verdade. E é a operação que mais tende a ser repetida, porque quem opera fica na dúvida se funcionou.

Solução

A rota exige uma chave de idempotência. A chave e a resposta produzida ficam guardadas; repetir a mesma chave devolve a resposta original em vez de executar de novo. Abaixo disso, a transição de estado é feita com guarda condicional — a atualização só ocorre se a linha ainda estiver no estado esperado.

Por que foi feito assim

As duas defesas resolvem problemas diferentes e nenhuma substitui a outra. A chave de idempotência resolve a mesma requisição chegando duas vezes; a guarda de estado resolve duas requisições diferentes disputando a mesma linha. Implementar só a primeira deixa a corrida entre dois operadores em aberto.

Problema

Enviar e-mail, varrer um anexo em busca de código malicioso e gerar relatório são operações lentas e sujeitas a falha externa. Nenhuma delas pode prender a resposta ao usuário — e nenhuma pode falhar em silêncio.

Solução

Fila em Redis consumida por um processo separado, sem porta pública. Cada tipo de job foi classificado antes de ganhar política de retry, pela pergunta "o que acontece se isto rodar duas vezes?". A varredura de anexo é idempotente e pode repetir; o agendamento tem deduplicação por identificador; a importação de planilha não faz retry cego.

Por que foi feito assim

Retry é a configuração mais fácil de ligar e a mais fácil de errar. Numa importação de planilha, repetir cegamente duplicaria beneficiários — o defeito seria descoberto semanas depois, num relatório que não bate. Decidir a política por job, e não por padrão global, é o que torna a fila segura.

Problema

A regra "no máximo uma versão vigente por precatório" vivia numa verificação em código. Sob o nível de isolamento padrão do PostgreSQL, duas publicações simultâneas passam pela verificação antes de qualquer uma gravar — e o sistema fica com duas versões vigentes. A partir daí, a geração do arquivo de pagamento escolheria uma arbitrariamente: o beneficiário veria um valor na tela e a ordem bancária pagaria outro.

Solução

Índice único parcial sobre a condição de vigência, aplicado às tabelas versionadas. A segunda publicação concorrente falha na constraint, e o serviço traduz a falha em uma resposta de conflito. A leitura dos parâmetros passou a ter ordenação determinística, e a publicação retira explicitamente as outras versões.

Por que foi feito assim

Invariante que precisa valer sob concorrência não pertence ao código de aplicação — o banco é o único ponto por onde todas as transações passam obrigatoriamente. E o índice ser *parcial* é o que permite manter todo o histórico de versões na mesma tabela: a restrição vale só sobre as vigentes.