ajuste no contas

docs/FIX_DATABASE_RESILIENCE_AND_FALLBACKS_20260831.md

@@ -0,0 +1,25 @@
+# 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.