T-313 - Decidir e provar a retenção do registro de auditoria quando a gravação falha

• Componente: api, com a decisão em docs/decisoes/.
• Depende de: nenhuma tarefa.
• Data máxima: 10/11/2026
• Estimativa: 3 pontos (Fibonacci)

Entregável

• Decisão registrada (DEC-096) sobre como o registro de auditoria é retido quando a gravação falha.
• Contador de consumo de no-concluido, no padrão dos demais consumidores.
• Teste de integração que falha a gravação da trilha, confere que a simulação segue e que a linha é gravada uma única vez depois.
• docs/ARCHITECTURE.md atualizado.

Descrição

O cenário 2 da US04 pede que uma falha na gravação do registro de auditoria não interrompa a simulação e que o registro fique retido até a gravação voltar a funcionar, sem se perder. A arquitetura diz que um buffer em memória ou arquivo para isso não existe e não pode ser considerado garantia. Esta tarefa registra como o sistema atende o cenário e prova esse comportamento.

Contexto e decisões tomadas

• O codegen grava os artefatos no Postgres e publica no-concluido como mensagem persistente numa fila durável. A API confirma a mensagem só depois de gravar a linha. Uma falha de banco propaga, e a mensagem volta para a fila (default-requeue-rejected: true, skill consumidores (api/.agents/skills/consumidores/SKILL.md)). A reentrega não duplica a linha, por causa do índice único de evento_id.
• A gravação da trilha roda num consumidor próprio. O resultado da simulação chega por simulacao-concluida, noutro consumidor, e move o job sem depender da trilha.
• O sistema tem um único Postgres. Uma indisponibilidade dele interrompe todo o processamento, e não só a auditoria. O cenário só se aplica a uma falha na gravação da trilha com o restante funcionando.
• Decisão a confirmar com a PO no requisito 1: a fila durável com reentrega é a retenção exigida pelo cenário 2, no lugar do buffer em memória ou arquivo.
• O consumidor de no-concluido não tem contador de consumo. AppMetrics já tem contadores de consumo para outros eventos, como simulacao.concluida.consumo.

Escopo

Dentro do escopo

• DEC-096, o contador, o teste de integração e o trecho de docs/ARCHITECTURE.md sobre a persistência da trilha.

Fora do escopo

• Buffer em memória ou em arquivo.
• Fila de mensagens mortas para no-concluido.
• Indisponibilidade total do Postgres ou do RabbitMQ.

Requisitos

1. Antes de editar, apresentar ao usuário a decisão do contexto para confirmação da PO.
2. Criar docs/decisoes/dec-096.md com contexto, decisão e consequências, no formato das decisões existentes, cobrindo o caminho do registro do codegen à API, a idempotência, a independência entre a trilha e o resultado e o limite de um Postgres único.
3. Acrescentar a AppMetrics um contador de consumo de no-concluido com o resultado do consumo (gravado, duplicado, descartado e falha), no padrão dos contadores de consumo existentes. A documentação do contador diz que ele conta tentativas de consumo, e que uma reentrega já gravada conta como duplicado, não como gravado.
4. Em ConsumidoresJob.receber, incrementar o contador em cada desfecho e registrar a falha da gravação em log com job_id e no, sem a conclusão, antes de propagar a exceção.
5. Criar um teste de integração que impeça só a gravação em trilhas_auditoria, por exemplo revogando temporariamente o INSERT do usuário da API na tabela ou segurando um bloqueio exclusivo com lock_timeout curto. Com a gravação impedida, o teste publica o no-concluido de um job e o simulacao-concluida do mesmo job, e confere que o job chega à decisão do usuário. Depois de restaurar a gravação, confere que a linha da trilha existe uma única vez e que o contador registrou a falha e a gravação.
6. Em docs/ARCHITECTURE.md, trocar a frase que diz que o buffer não está implementado e não pode ser considerado garantia por uma que aponte a DEC-096.

Contexto técnico

• Entradas: eventos no-concluido e simulacao-concluida.
• Saídas: decisão registrada, contador e teste.
• Componentes afetados: api/src/main/java/synapse/api/job/ConsumidoresJob.java, api/src/main/java/synapse/api/core/metrics/AppMetrics.java, docs/ARCHITECTURE.md e a decisão nova.
• Restrições: o consumidor continua sem lançar exceção nos descartes de validação; a falha de banco continua propagando.
• Referências: consumidores (api/.agents/skills/consumidores/SKILL.md), metrics (api/.agents/skills/metrics/SKILL.md), logging (api/.agents/skills/logging/SKILL.md), NoConcluidoConsumidorTests (api/src/test/java/synapse/api/job/NoConcluidoConsumidorTests.java), api/src/main/java/synapse/api/core/messaging/RabbitTopologyConfig.java, DEC-095 (docs/decisoes/dec-095.md) como modelo de decisão.

Critérios de aceitação

• Com a gravação da trilha impedida, o job avança pelo resultado da simulação.
• Depois de restaurada a gravação, a linha da trilha existe uma única vez.
• O contador mostra a falha e a gravação, e a reentrega de uma mensagem já gravada conta como duplicado.
• A DEC-096 registra a confirmação da PO.

Definição de concluído (DoD)

• make check na api sem falha.
• Saída de /metrics conferida depois do teste, com o contador novo e os desfechos gravado, duplicado e falha.
• Logs da falha serializados conferidos com job_id e no e sem a conclusão.