agent_contas/docs/FIX_DATABASE_RESILIENCE_AND_FALLBACKS_20260831.md

Robustez de banco e fallbacks transacionais

Objetivo

Evitar que falhas de persistência/cache/idempotência derrubem o atendimento com HTTP 500 e contaminem a continuidade transacional.

Alterações

1. OracleStore.cache_get

   • normaliza datetime naive/aware para UTC antes de comparar TTL;
   • elimina o TypeError: can't compare offset-naive and offset-aware datetimes.

2. IdempotencyStore

   • suporta backend de fallback;
   • quando require_durable=False, falhas do backend primário degradam para InMemoryCache por padrão;
   • get, set e delete não propagam indisponibilidade do backend primário em modo fail-open;
   • quando durabilidade é exigida, a semântica fail-closed continua disponível.

3. cancelamento_vas_avulso_batch

   • boundary por item converte exceções técnicas inesperadas em resultado recuperável;
   • um item com erro não derruba o batch nem o request HTTP inteiro;
   • erros são devolvidos com reason=internal_processing_failed/recoverable=true para composição controlada da resposta.

Configuração opcional

IDEMPOTENCY_FAIL_OPEN=true|false pode sobrescrever o comportamento. Sem configuração explícita, require_durable=False usa fail-open e require_durable=True mantém fail-closed.