14 lines
1.3 KiB
Markdown
14 lines
1.3 KiB
Markdown
# ADR-003 — Idempotência de comandos e integrações
|
|
|
|
- Estado: Aceite como padrão para operações repetíveis com efeitos.
|
|
- Data: 2026-10-01
|
|
- Contexto: há recibos idempotentes territoriais, chaves em outbox e `insertOrIgnore` localizados, mas não contrato uniforme.
|
|
|
|
## Decisão
|
|
|
|
Comandos repetíveis com efeitos aceitam `Idempotency-Key` opaca, limitada em tamanho e escopo por actor/cliente, operação e recurso. Persistir chave, hash canónico dos parâmetros relevantes, estado e resultado mínimo por janela de retenção aprovada; a mesma chave e mesmo pedido reproduzem a resposta, a mesma chave com payload diferente produz conflito. A criação do recibo e a mutação de negócio pertencem à mesma transacção. Jobs e consumidores deduplicam por identificador de evento e guardam progresso sem reexecutar efeitos já confirmados. Não registar a chave em claro em logs; guardar apenas referência/hash adequado. Retenção não é fixada aqui.
|
|
|
|
## Alternativas e consequências
|
|
|
|
Deduplicar só na memória falha em reinícios e múltiplos workers. Usar só UUID do recurso não cobre criação repetida. Integrações externas exigem reconciliação e chave do destinatário; não se promete exactly-once, mas entrega pelo menos uma vez com consumidor idempotente. Cada API define respostas de replay e conflito.
|