Spec-Driven Development (SDD): a nova espinha dorsal

# Spec: <nome curto da feature>

**Owner:** @fernando · **Status:** draft · **Data:** 2026-04-16 · **Review by:** 2026-04-19

## 1. Contexto
Em 2-3 frases: qual o problema, quem sofre, qual a oportunidade.
Exemplo: "Hoje quando um pagamento falha por erro transitório do PSP, o
usuário clica 'pagar' 3x e gera 3 cobranças. Precisamos de idempotência
na camada de checkout."

## 2. Objetivos
O1. Garantir que dois POST /payments com mesma idempotency-key em
    janela de 24h retornem sempre a mesma resposta (idempotente).
O2. Expor a chave no header da resposta para debugging.

## 3. Não-objetivos
- NÃO vamos implementar retry automático (fica com o cliente).
- NÃO muda o contrato atual da API (backward compatible).

## 4. Requisitos funcionais
R1. Header 'Idempotency-Key' obrigatório em POST /payments.
R2. Chave persistida em payments.idempotency_key (índice único).
R3. Segunda chamada com mesma chave retorna a resposta original.
R4. Expira em 24h (row deletada).
R5. Chaves inválidas (<16 ou >64 chars) retornam 400.

## 5. Critérios de aceite
CA1. GIVEN uma chave nova
     WHEN POST /payments
     THEN cria pagamento, responde 201, header X-Idempotency-Key.
CA2. GIVEN uma chave já vista há 1h
     WHEN POST /payments (mesmo body)
     THEN devolve 200 e MESMA resposta (sem criar outro).
CA3. GIVEN uma chave já vista há 25h
     WHEN POST /payments
     THEN trata como chave nova.
CA4. GIVEN uma chave com 5 caracteres
     WHEN POST /payments
     THEN responde 400 com código 'invalid_idempotency_key'.
CA5. GIVEN 100 requests paralelos com mesma chave
     WHEN concorrência alta
     THEN só 1 pagamento é criado (teste de race).

## 6. Restrições
- Stack: Node 20 + Fastify + Postgres 15.
- Latência: <5ms de overhead por request (p99).
- Segurança: chave não deve vazar em logs.

## 7. Exemplos
POST /payments  Idempotency-Key: abc-123
Body: { amount: 1000, currency: "BRL" }
Resposta 201: { id: "pay_01", status: "paid", ... }

POST /payments  Idempotency-Key: abc-123  (10 min depois)
Body: { amount: 1000, currency: "BRL" }
Resposta 200: { id: "pay_01", status: "paid", ... }  (MESMO id)

## 8. Riscos & mitigações
- Race condition (2 req paralelas): lock com INSERT unique + retry de leitura.
- Chave com body diferente: rejeita com 409 (payload mismatch).
- Crescimento da tabela: índice + job de limpeza diário.

## 9. Plano de teste
- Unit: handler, validador, storage.
- Integração: Postgres real em docker, 100 requests paralelos.
- Property-based: qualquer body válido + chave válida → idempotente.
- Manual: via Bruno/Postman com 3 cenários do item 7.

## 10. Rollback
- Feature flag idempotency.enabled (GrowthBook).
- Se p99 subir >10ms ou taxa de 5xx >0.1%: desliga flag.
- Migration é aditiva (sem drop). Reverter = desligar flag, não rollback de schema.

# Em Claude Code (ou similar)
# 1. abre a spec no editor ou cola no prompt
# 2. comanda o agent com precisão

"Leia a spec em docs/specs/idempotency.md. Implemente os requisitos R1-R5
 na camada de rota POST /payments em src/routes/payments.ts.
 Escreva testes cobrindo CA1-CA5 em tests/payments.spec.ts.
 Não altere o schema da resposta atual (não-objetivo 2).
 Não implemente retry (não-objetivo 1).
 Se algum critério não ficar claro, pare e pergunte — não invente."