# Runbook de rollout — IB, Merchant, PIX/DICT, TED e API pública

Data: 24/07/2026
Origem das correções: `audit/ib-merchant-pix-ted-2026-07-24`
Ambiente externo auditado: produção AWS, somente leitura

## Objetivo e restrições

Este runbook coloca em produção as correções locais da auditoria sem repetir
mutações no DICT/Bacen. Ele não autoriza alteração de AWS, deploy, criação ou
exclusão de chave PIX. Essas ações exigem a aprovação operacional normal.

Não usar a Partner API nem `docs.monetarie.internal` como referência. O contrato
público deste rollout é `docs.monetarie.com` + `api.monetarie.com`.

## Bloqueador de rollout comum

As réplicas antigas da cabine assinam os subjects NATS sem queue group. Durante
um rolling deploy misto, cada réplica antiga ainda recebe uma cópia e uma das
réplicas novas do grupo também recebe outra. Portanto, um rolling deploy comum
mantém uma janela de efeitos duplicados.

Para a primeira implantação do P0, escolher uma das estratégias abaixo em change
aprovado:

1. janela de manutenção com mutações DICT suspensas, retirada completa das
   réplicas antigas e subida das novas; ou
2. rollout blue/green com subject versionado e corte atômico do publisher.

O código atual implementa a primeira opção operacional, usando os subjects
existentes. Não reabrir criação, exclusão, claims, MED ou infrações enquanto
houver qualquer réplica antiga assinando sem queue group.

## Ordem obrigatória

1. Confirmar backup e acesso de rollback dos artefatos atuais.
2. Aplicar a migration aditiva
   `20260724190000_create_dict_nats_request_deduplications.exs` no banco da
   cabine.
3. Suspender mutações DICT expostas pelos portais e APIs.
4. Encerrar todas as tasks antigas da cabine PIX/DICT.
5. Implantar a nova cabine e confirmar que todas as réplicas usam:
   - `dict-api-responders-v1`;
   - `dict-lookup-responders-v1`;
   - `dict-list-keys-responders-v1`.
6. Implantar o Core, que passa `operation_id` e aplica os contratos fail-closed.
7. Implantar `ib-front` e `merchant-front`.
8. Publicar a documentação pública atualizada.
9. Corrigir a topologia AWS antes de liberar carga plena:
   - habilitar `sa-east-1c` no ALB/target group; ou
   - remover a subnet `1c` do serviço PIX.
10. Executar os critérios de aceite abaixo e só então reabrir mutações DICT.

## Critérios de aceite

Executar com conta controlada e sem registrar PII nos logs ou evidências:

- Um `GET` de chaves produz uma resposta NATS e nenhuma resposta tardia extra.
- Uma criação controlada produz exatamente:
  - uma intenção no Core;
  - uma chamada externa ao DICT/Bacen;
  - uma resposta;
  - um evento de chave criada.
- A chave criada/listada aparece com status canônico `active`.
- Falha ou timeout do DICT resulta em erro distinguível; não aparece chave
  sintética nem lista vazia tratada como sucesso.
- QR só apresenta sucesso com BR Code não vazio e chave ativa da conta.
- TED com duas contas debita a conta explicitamente selecionada.
- Retry com a mesma `Idempotency-Key` não cria uma segunda TED/TEF.
- TEF entre contas próprias usa `/api/transfers/between-accounts`.
- A opção sem contrato de TEF entre titulares diferentes não aparece no
  Merchant.
- `X-Key-Case: camelCase` converte respostas JSON de sucesso e erro.
- MED retorna:
  - `200` e lista vazia somente quando a consulta concluiu sem itens;
  - `404` somente para ausência/escopo;
  - `502` em indisponibilidade do provider.

## Observabilidade mínima

Monitorar, sem payloads ou documentos:

- razão `chamadas externas DICT / operation_id`;
- contagem de respostas NATS tardias ou “request no longer registered”;
- conflitos e `422` por ação DICT;
- `502` de chaves, QR e MED;
- falhas de persistência do espelho de QR;
- deduplicações concluídas e expiradas;
- tasks por Availability Zone e saúde dos targets;
- profundidade e idade do DLQ, após classificação do conteúdo.

Alertar imediatamente se uma intenção produzir mais de uma chamada externa.

## Rollback

- Não remover a tabela de deduplicação; a migration é aditiva.
- Se a cabine nova falhar, voltar a suspender mutações antes de reativar qualquer
  versão antiga sem queue group.
- Core e frontends podem voltar aos artefatos anteriores somente com mutações
  DICT congeladas, pois o comportamento antigo fabrica fallback e aceita
  contratos ambíguos.
- Não excluir ou recriar automaticamente a chave envolvida no incidente.
  Reconciliar diretamente com o DICT e o espelho local, em procedimento
  autorizado.

## Pendências que não devem ser inferidas

- Decisão de produto e contrato para TEF entre titulares diferentes.
- Decisão de produto para iniciação de TED em `api.monetarie.com`.
- Tratamento de QR dinâmico URL-only no copia-e-cola.
- Unificação semântica de “PIX agendado” entre os dois portais.
- Política operacional para saneamento dos logs com PII e classificação do DLQ.

Esses itens exigem decisão explícita ou mudança externa autorizada; não foram
preenchidos com rotas ou comportamentos presumidos.