# Troubleshooting

Guia de resolucao de problemas baseado em sintomas para a plataforma Monetarie PIX. Cada problema e apresentado no formato: sintoma observado, possiveis causas, comandos de diagnostico e solucao.

## Pre-requisitos

- Acesso kubectl ao cluster Kubernetes (namespace `pix`)
- Acesso psql ao banco de dados PostgreSQL
- Acesso redis-cli ao Redis
- Acesso nats CLI ao cluster NATS
- Permissao para visualizar logs de pods

## Indice de Problemas

| # | Sintoma | Severidade |
|---|---------|-----------|
| 1 | [Pods em CrashLoopBackOff](#_1-pods-em-crashloopbackoff) | Critica |
| 2 | [Erro 403 em todas as requisicoes](#_2-erro-403-em-todas-as-requisicoes) | Alta |
| 3 | [Transacoes travadas em PDNG](#_3-transacoes-travadas-em-pdng) | Alta |
| 4 | [NATS consumer lag alto](#_4-nats-consumer-lag-alto) | Alta |
| 5 | [Login falha com erro generico](#_5-login-falha-com-erro-generico) | Media |
| 6 | [WebSocket nao conecta](#_6-websocket-nao-conecta) | Media |
| 7 | [Certificado BACEN invalido](#_7-certificado-bacen-invalido) | Critica |
| 8 | [Migration falha no fresh DB](#_8-migration-falha-no-fresh-db) | Alta |
| 9 | [Seed data falha](#_9-seed-data-falha) | Media |
| 10 | [ANS excedido (>1.6s)](#_10-ans-excedido-1-6s) | Alta |
| 11 | [Circuit breaker aberto](#_11-circuit-breaker-aberto) | Alta |
| 12 | [Idempotency key conflito](#_12-idempotency-key-conflito) | Baixa |

---

## 1. Pods em CrashLoopBackOff

**Sintoma:** Pods do backend reiniciam continuamente com status `CrashLoopBackOff`.

**Possiveis causas:**
- Banco de dados inacessivel (DB_HOST incorreto ou Cloud SQL fora do ar)
- `SECRET_KEY_BASE` ausente ou invalido
- Variavel de ambiente faltando no ConfigMap/Secret
- Migration pendente com erro

**Diagnostico:**

```bash
# Verificar status dos pods
kubectl get pods -n pix -l app=pix-backend
# Saida esperada (problema):
# NAME                           READY   STATUS             RESTARTS   AGE
# pix-backend-7b8f9d6c4-abc12   0/1     CrashLoopBackOff   5          10m

# Verificar logs do pod que esta falhando
kubectl logs deployment/pix-backend -n pix --previous
# Procurar por:
# ** (RuntimeError) connect raised KeyError exception: key :hostname not found
# ** (Postgrex.Error) FATAL: password authentication failed
# ** (RuntimeError) you must set SECRET_KEY_BASE

# Verificar variaveis de ambiente
kubectl exec deployment/pix-backend -n pix -- env | grep -E "DB_|SECRET_KEY"
# Saida esperada:
# DB_HOST=10.140.241.2
# DB_PORT=5432
# DB_USER=postgres
# SECRET_KEY_BASE=<valor>

# Testar conectividade com o banco
kubectl exec deployment/pix-backend -n pix -- \
  bin/monetarie_pix eval "IO.inspect(Ecto.Adapters.SQL.query!(Shared.Repo, \"SELECT 1\", []))"
```

**Solucao:**

```bash
# Se o problema for DB_HOST
kubectl edit configmap pix-backend-config -n pix
# Corrigir DB_HOST para 10.140.241.2

# Se o problema for SECRET_KEY_BASE ausente
kubectl create secret generic pix-backend-secrets -n pix \
  --from-literal=secret-key-base="$(mix phx.gen.secret)" \
  --dry-run=client -o yaml | kubectl apply -f -

# Se o problema for migration pendente
kubectl exec deployment/pix-backend -n pix -- \
  bin/monetarie_pix eval "Shared.Release.migrate()"

# Reiniciar pods apos correcao
kubectl rollout restart deployment/pix-backend -n pix
```

---

## 2. Erro 403 em Todas as Requisicoes

**Sintoma:** Todas as requisicoes retornam HTTP 403 Forbidden, mesmo com credenciais corretas.

**Possiveis causas:**
- RBAC: usuario sem permissao na tabela `group_features`
- Token CSRF invalido ou ausente
- Header `x-internal-service` enviado de IP nao-privado
- Token JWT expirado ou blacklisted

**Diagnostico:**

```bash
# Verificar resposta da API
curl -v https://pixapi-dev.fluxiq.com.br/api/v1/transactions \
  -H "Cookie: pix_session=<token>" \
  -H "X-CSRF-Token: <csrf_token>"
# Procurar no corpo da resposta:
# {"type":"about:blank","title":"Forbidden","status":403,"detail":"..."}

# Verificar se RBAC esta bloqueando
kubectl logs deployment/pix-backend -n pix --tail=50 | grep "RequirePermission"
# Saida esperada (problema):
# [RequirePermission] Denied: user=admin action=transactions.list reason=no_permission

# Verificar permissoes do grupo no banco
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT gf.feature_name, gf.can_read, gf.can_write
  FROM monetarie_auth.group_features gf
  JOIN monetarie_auth.user_groups ug ON ug.group_id = gf.group_id
  JOIN monetarie_auth.users u ON u.id = ug.user_id
  WHERE u.username = 'admin';
"
```

**Solucao:**

```bash
# Se o problema for CSRF token
# 1. Fazer login para obter novo cookie + CSRF
curl -c cookies.txt -X POST https://pixapi-dev.fluxiq.com.br/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@2026!"}'
# 2. Usar o cookie __monetarie_csrf retornado no header X-CSRF-Token

# Se o problema for RBAC — conceder permissao
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  INSERT INTO monetarie_auth.group_features (group_id, feature_name, can_read, can_write)
  SELECT g.id, 'transactions', true, true
  FROM monetarie_auth.groups g
  WHERE g.name = 'administrators'
  ON CONFLICT (group_id, feature_name) DO UPDATE
  SET can_read = true, can_write = true;
"

# Se o problema for token blacklisted
redis-cli -h 10.140.240.4 KEYS "blacklist:*"
# Fazer novo login para obter token valido
```

---

## 3. Transacoes Travadas em PDNG

**Sintoma:** Transacoes permanecem no status PDNG (Pendente) indefinidamente, sem progredir para ACSP ou STLD.

**Possiveis causas:**
- Workers NATS nao estao executando (NATS_ENABLED=false)
- Circuit breaker aberto para o servico SPI ou DICT
- Conexao NATS perdida (cluster inacessivel)
- Consumer NATS nao criado ou desconectado

**Diagnostico:**

```bash
# Verificar se NATS esta habilitado
kubectl exec deployment/pix-backend -n pix -- env | grep NATS_ENABLED
# Saida esperada: NATS_ENABLED=true

# Verificar se workers estao rodando (heartbeat nos logs)
kubectl logs deployment/pix-backend -n pix --tail=20 | grep "Heartbeat"
# Saida esperada (saudavel):
# [InboundProcessor] Heartbeat: processed=4521 failed=3 retried=12 uptime=3600s
# [OutboundSender] Heartbeat: processed=3890 failed=1 retried=5 uptime=3600s
# [StatusUpdater] Heartbeat: processed=2100 failed=0 retried=2 uptime=3600s

# Se NAO houver heartbeat, verificar logs de inicializacao
kubectl logs deployment/pix-backend -n pix | grep -E "Worker|NATS|consumer"

# Verificar estado do circuit breaker
curl -s https://pixapi-dev.fluxiq.com.br/api/v1/monitoring/health | jq .

# Verificar conexao NATS
kubectl exec deployment/pix-backend -n pix -- \
  bin/monetarie_pix eval "IO.inspect(Process.whereis(:monetarie_pix_nats))"
# Saida esperada: #PID<0.xxx.0> (se nil, NATS nao conectado)

# Contar transacoes travadas
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT status_id, COUNT(*)
  FROM monetarie_spi.messages
  WHERE created_at > NOW() - INTERVAL '1 hour'
  GROUP BY status_id
  ORDER BY status_id;
"
# status_id: 1=PDNG, 2=ACSP, 7=STLD
```

**Solucao:**

```bash
# Se NATS_ENABLED=false
kubectl set env deployment/pix-backend -n pix NATS_ENABLED=true
kubectl rollout restart deployment/pix-backend -n pix

# Se NATS cluster inacessivel — verificar conectividade
kubectl exec deployment/pix-backend -n pix -- \
  nc -zv 10.10.40.5 4222
# Saida esperada: Connection to 10.10.40.5 4222 port [tcp/*] succeeded!

# Se consumer nao existe — sera recriado automaticamente ao reiniciar
kubectl rollout restart deployment/pix-backend -n pix
```

---

## 4. NATS Consumer Lag Alto

**Sintoma:** Mensagens NATS se acumulam sem serem processadas. Consumer lag visivel no monitoramento.

**Possiveis causas:**
- Worker processando lentamente (queries DB pesadas)
- `batch_size` ou `max_concurrency` muito baixo
- Connection pool do banco esgotado
- Disco lento nos nos NATS

**Diagnostico:**

```bash
# Verificar lag de cada consumer
nats consumer info MONETARIE_SPI inbound-processor \
  --server=nats://10.10.40.5:4222
# Saida esperada (problema):
#   Pending Messages: 15,230
#   Redelivered Messages: 450

# Verificar throughput dos workers
kubectl logs deployment/pix-backend -n pix --tail=10 | grep "Heartbeat"
# Comparar processed/uptime para calcular TPS real

# Verificar pool de conexoes DB
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT count(*), state FROM pg_stat_activity
  WHERE datname = 'monetarie' GROUP BY state;
"
# Se 'idle in transaction' alto → workers estao lentos

# Verificar CPU/Memoria dos pods
kubectl top pods -n pix -l app=pix-backend
```

**Solucao:**

```bash
# Opcao 1: Escalar pods (mais instancias de workers)
kubectl scale deployment/pix-backend -n pix --replicas=4

# Opcao 2: Aumentar batch_size e max_concurrency (requer rebuild)
# Editar o worker e fazer deploy:
# batch_size: 200, max_concurrency: 20

# Opcao 3: Aumentar POOL_SIZE
kubectl set env deployment/pix-backend -n pix POOL_SIZE=300

# Opcao 4: Verificar queries lentas
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT query, calls, mean_exec_time, total_exec_time
  FROM pg_stat_statements
  WHERE mean_exec_time > 100
  ORDER BY total_exec_time DESC
  LIMIT 10;
"
```

---

## 5. Login Falha com Erro Generico

**Sintoma:** Tentativa de login retorna mensagem generica "Credenciais invalidas" mesmo com senha correta.

**Possiveis causas:**
- Conta bloqueada apos 10 tentativas falhas (`is_blocked = true`)
- Rate limit atingido (10 tentativas por 15 minutos por IP)
- Senha expirada (`password_expires` no passado)
- Conta inativa (`is_active = false`)

**Diagnostico:**

```bash
# Verificar se a conta esta bloqueada
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT username, is_active, is_blocked, failed_login_attempts,
         password_expires, last_login_at
  FROM monetarie_auth.users
  WHERE username = 'admin';
"
# Saida esperada (problema):
#  username | is_active | is_blocked | failed_login_attempts | password_expires
# ----------+-----------+------------+-----------------------+-----------------
#  admin    | t         | t          | 10                    | 2026-12-31

# Verificar rate limiting no Redis
redis-cli -h 10.140.240.4 KEYS "rate_limit:*"
redis-cli -h 10.140.240.4 GET "rate_limit:<ip_do_cliente>:/api/v1/auth/login"
# Saida esperada (problema): "10" (limite atingido)

# Verificar TTL do rate limit
redis-cli -h 10.140.240.4 TTL "rate_limit:<ip_do_cliente>:/api/v1/auth/login"
# Saida: 543 (segundos restantes)
```

**Solucao:**

```bash
# Desbloquear conta
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  UPDATE monetarie_auth.users
  SET is_blocked = false, failed_login_attempts = 0
  WHERE username = 'admin';
"

# Limpar rate limit
redis-cli -h 10.140.240.4 DEL "rate_limit:<ip_do_cliente>:/api/v1/auth/login"

# Atualizar senha expirada
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  UPDATE monetarie_auth.users
  SET password_expires = NOW() + INTERVAL '90 days'
  WHERE username = 'admin';
"

# Reativar conta
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  UPDATE monetarie_auth.users SET is_active = true WHERE username = 'admin';
"
```

::: tip Seguranca
A mensagem de erro generica e intencional para evitar enumeracao de contas (account enumeration attack). Nunca retornar informacao especifica sobre por que o login falhou para usuarios nao-autenticados.
:::

---

## 6. WebSocket Nao Conecta

**Sintoma:** O dashboard de monitoramento real-time nao exibe dados. Console do navegador mostra erro de conexao WebSocket.

**Possiveis causas:**
- Nginx nao configurado para proxy WebSocket (`/socket`)
- Token JWT invalido ou expirado no handshake
- Pod do backend reiniciou (conexoes WebSocket sao stateful)
- Ingress/Load Balancer sem suporte a WebSocket

**Diagnostico:**

```bash
# Testar conexao WebSocket via curl
curl -v \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  https://pixapi-dev.fluxiq.com.br/socket/websocket?token=<jwt>
# Saida esperada (sucesso): HTTP/1.1 101 Switching Protocols
# Saida esperada (falha): HTTP/1.1 403 Forbidden ou timeout

# Verificar configuracao nginx do admin frontend
kubectl exec deployment/pix-admin-frontend -n pix -- cat /etc/nginx/conf.d/default.conf | grep -A5 socket
# Deve conter:
# location /socket {
#   proxy_pass http://pix-backend.pix.svc.cluster.local:4003;
#   proxy_http_version 1.1;
#   proxy_set_header Upgrade $http_upgrade;
#   proxy_set_header Connection "upgrade";
# }

# Verificar se o endpoint /socket existe no backend
kubectl exec deployment/pix-backend -n pix -- \
  bin/monetarie_pix eval "IO.inspect(SettlementServiceWeb.Endpoint.url())"
```

**Solucao:**

```bash
# Se nginx nao tem proxy WebSocket, adicionar configuracao
# Rebuild do frontend com nginx.conf corrigido

# Se token expirado, fazer novo login no portal admin
# O useAuthStore().checkSession() renova automaticamente

# Se pods reiniciaram, aguardar reconexao automatica
# O Phoenix Socket client reconecta com backoff exponencial

# Forcar reconexao no navegador
# Console JS: window.location.reload()
```

---

## 7. Certificado BACEN Invalido

**Sintoma:** Chamadas para APIs do BACEN (DICT, SPI) falham com erro de certificado SSL/TLS.

**Possiveis causas:**
- Certificado ICP-Brasil expirado
- Cadeia de certificados incompleta (CA intermediaria faltando)
- CertificatePool nao carregou certificados (arquivo nao encontrado)
- Clock do servidor desincronizado (NTP)

**Diagnostico:**

```bash
# Verificar validade do certificado
openssl x509 -in /opt/monetarie/certs/cpic.pem -noout -dates
# Saida esperada:
# notBefore=Jan  1 00:00:00 2026 GMT
# notAfter=Dec 31 23:59:59 2027 GMT

# Verificar cadeia de certificados
openssl verify -CAfile /opt/monetarie/certs/ca-chain.pem /opt/monetarie/certs/cpic.pem
# Saida esperada (sucesso): /opt/monetarie/certs/cpic.pem: OK
# Saida esperada (falha): unable to get local issuer certificate

# Verificar logs do CertificatePool
kubectl logs deployment/pix-backend -n pix | grep "CertificatePool"
# Saida esperada:
# [CertificatePool] Loaded 3 certificates, next refresh in 300s

# Verificar clock do servidor
kubectl exec deployment/pix-backend -n pix -- date -u
# Comparar com: date -u (sua maquina local)
```

**Solucao:**

```bash
# Se certificado expirado — renovar com ICP-Brasil
# Atualizar secret Kubernetes
kubectl create secret tls bacen-certs -n pix \
  --cert=/opt/monetarie/certs/cpic.pem \
  --key=/opt/monetarie/certs/cpic.key \
  --dry-run=client -o yaml | kubectl apply -f -

# Se cadeia incompleta — baixar CA intermediaria
# Concatenar: cert + intermediate + root
cat cpic.pem intermediate.pem root.pem > ca-chain.pem

# Se clock desincronizado
# Verificar NTP no host
timedatectl status
# Forcar sincronizacao
sudo timedatectl set-ntp true
```

---

## 8. Migration Falha no Fresh DB

**Sintoma:** Ao executar `mix ecto.migrate` em um banco novo, as migrations falham com erros de tabela ou tipo inexistente.

**Possiveis causas:**
- Tabela particionada referenciada antes de ser criada
- Extensao PostgreSQL nao instalada (pg_trgm, uuid-ossp)
- Ordem de migrations com dependencias quebradas
- Migration anterior falhou parcialmente (estado inconsistente)

**Diagnostico:**

```bash
# Verificar status das migrations
kubectl exec deployment/pix-backend -n pix -- \
  bin/monetarie_pix eval "Shared.Release.migrate()"
# Ou localmente:
mix ecto.migrate

# Verificar extensoes instaladas
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT extname, extversion FROM pg_extension;
"
# Deve incluir: uuid-ossp, pg_trgm, pgcrypto

# Verificar se tabelas particionadas existem
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT relname, relkind
  FROM pg_class
  WHERE relname IN ('activity_log', 'login_history', 'messages')
  AND relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'monetarie_auth');
"
# relkind: 'p' = partitioned, 'r' = regular
```

**Solucao:**

```bash
# Instalar extensoes necessarias
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";
  CREATE EXTENSION IF NOT EXISTS pg_trgm;
  CREATE EXTENSION IF NOT EXISTS pgcrypto;
"

# Se migration falhou parcialmente — dropar e recriar
# CUIDADO: perda de dados!
psql -h 10.140.241.2 -U postgres -c "DROP DATABASE monetarie;"
psql -h 10.140.241.2 -U postgres -c "CREATE DATABASE monetarie;"

# Re-executar setup completo
mix ecto.setup
# Ou via K8s:
kubectl exec deployment/pix-backend -n pix -- \
  bin/monetarie_pix eval "Shared.Release.migrate()"
```

---

## 9. Seed Data Falha

**Sintoma:** O comando `mix run apps/shared/priv/repo/seeds.exs` falha com erro de coluna ou constraint.

**Possiveis causas:**
- Nome de coluna mudou em migration recente (ex: `participation_type`)
- Foreign key para `institution_id` sem institution correspondente
- Seed tentando inserir em tabela com dados existentes (unique constraint)
- Tipo de dado incompativel (integer vs UUID)

**Diagnostico:**

```bash
# Executar seeds com output verbose
mix run apps/shared/priv/repo/seeds.exs 2>&1 | tail -30
# Procurar por:
# ** (Postgrex.Error) ERROR 42703 (undefined_column): column "participation_type" does not exist
# ** (Postgrex.Error) ERROR 23503 (foreign_key_violation): insert or update violates FK

# Verificar schema da tabela
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  \d monetarie_spi.messages
"

# Verificar se institutions existem
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT id, name FROM monetarie_auth.institutions LIMIT 5;
"
```

**Solucao:**

```bash
# Se coluna nao existe — verificar migration mais recente
mix ecto.migrate

# Se FK violation — inserir institutions primeiro
# Seeds sao executados em ordem, verificar se o arquivo seeds.exs
# insere institutions antes de usuarios/transacoes

# Se unique constraint — limpar dados antigos antes de seed
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  DELETE FROM monetarie_spi.payments;
  DELETE FROM monetarie_spi.messages WHERE json_input->>'origin' = 'integration_test';
"

# Re-executar seeds
mix run apps/shared/priv/repo/seeds.exs
```

---

## 10. ANS Excedido (>1.6s)

**Sintoma:** Transacoes estao sendo liquidadas com delta superior a 1.600ms (limite do ANS do BCB).

**Possiveis causas:**
- Indexes do banco de dados faltando ou fragmentados
- Connection pool esgotado (fila de espera)
- Latencia de rede entre pods e banco de dados
- NATS consumer lag alto (mensagens acumuladas)
- Worker com max_concurrency baixo

**Diagnostico:**

```bash
# Verificar deltas das transacoes recentes
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT
    end_to_end_id,
    status_id,
    EXTRACT(EPOCH FROM (settlement_time - operation_time)) * 1000 AS delta_ms
  FROM monetarie_spi.messages
  WHERE settlement_time IS NOT NULL
    AND created_at > NOW() - INTERVAL '1 hour'
  ORDER BY delta_ms DESC
  LIMIT 10;
"
# delta_ms > 1600 indica violacao ANS

# Verificar tempo de checkout do pool
kubectl logs deployment/pix-backend -n pix | grep "queue_time"
# Se queue_time > 100ms, pool pode estar esgotado

# Verificar indexes
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  SELECT indexname, idx_scan, idx_tup_read
  FROM pg_stat_user_indexes
  WHERE schemaname = 'monetarie_spi'
  ORDER BY idx_scan DESC;
"

# Verificar latencia de rede
kubectl exec deployment/pix-backend -n pix -- \
  ping -c 5 10.140.241.2
# RTT > 5ms pode impactar transacoes
```

**Solucao:**

```bash
# Recriar indexes (se fragmentados)
psql -h 10.140.241.2 -U postgres -d monetarie -c "
  REINDEX INDEX CONCURRENTLY monetarie_spi.idx_messages_status_created;
  REINDEX INDEX CONCURRENTLY monetarie_spi.idx_messages_e2e_id_trgm;
"

# Aumentar pool de conexoes
kubectl set env deployment/pix-backend -n pix POOL_SIZE=300

# Escalar workers
# Editar max_concurrency e batch_size dos workers SPI

# Escalar pods
kubectl scale deployment/pix-backend -n pix --replicas=4
```

---

## 11. Circuit Breaker Aberto

**Sintoma:** Requisicoes para servicos internos retornam imediatamente com erro `circuit_open`. Logs mostram `[CircuitBreaker] OPEN for <service>`.

**Possiveis causas:**
- Servico downstream (DICT, SPI) com 5+ falhas consecutivas
- Servico downstream fora do ar ou timeout
- Problema de rede entre servicos internos
- Cooldown de 30 segundos ainda nao expirou

**Diagnostico:**

```bash
# Verificar logs do circuit breaker
kubectl logs deployment/pix-backend -n pix | grep "CircuitBreaker"
# Saida esperada:
# [CircuitBreaker] OPEN for dict-service after 5 failures
# [CircuitBreaker] HALF_OPEN for dict-service — probe request

# Verificar health dos servicos internos
curl -s https://pixapi-dev.fluxiq.com.br/api/v1/monitoring/health | jq .services
# Saida esperada:
# [
#   {"name": "dict-service", "status": "unhealthy", "responseTimeMs": 5001},
#   {"name": "spi-service", "status": "healthy", "responseTimeMs": 15}
# ]

# Verificar metricas do circuit breaker
curl -s https://pixapi-dev.fluxiq.com.br/metrics | grep circuit_breaker
```

**Solucao:**

```bash
# O circuit breaker se recupera automaticamente:
# 1. Apos 30s cooldown → transicao para half_open
# 2. Uma requisicao de teste (probe) e permitida
# 3. Se sucesso → closed (normal)
# 4. Se falha → open novamente (mais 30s)

# Verificar servico downstream
kubectl logs deployment/pix-backend -n pix | grep "dict-service\|spi-service"

# Se servico downstream esta realmente fora do ar
kubectl rollout restart deployment/pix-backend -n pix

# Reset manual via eval (ultimo recurso)
kubectl exec deployment/pix-backend -n pix -- \
  bin/monetarie_pix eval "
    :ets.delete(:circuit_breaker_state, {\"dict-service\", :state})
    :ets.delete(:circuit_breaker_state, {\"dict-service\", :failures})
  "
```

::: warning Reset manual do circuit breaker
O reset manual via ETS deve ser usado apenas em situacoes de emergencia. O circuit breaker existe para proteger o sistema de cascata de falhas. Reabrir manualmente o circuito quando o servico downstream ainda esta com problemas pode piorar a situacao.
:::

---

## 12. Idempotency Key Conflito

**Sintoma:** Requisicao POST retorna HTTP 409 Conflict com corpo contendo resposta anterior, ou HTTP 422 "Idempotency key already used".

**Possiveis causas:**
- Mesma chave de idempotencia reutilizada para requisicao diferente
- Retry automatico do cliente com mesma chave (comportamento esperado)
- TTL de 24h ainda nao expirou

**Diagnostico:**

```bash
# Verificar chave no Redis
redis-cli -h 10.140.240.4 GET "idempotency:<user_id>:<key>"
# Saida: JSON da resposta anterior

# Verificar TTL
redis-cli -h 10.140.240.4 TTL "idempotency:<user_id>:<key>"
# Saida: 82345 (segundos restantes, max 86400 = 24h)
```

**Solucao:**

```bash
# Opcao 1: Usar chave de idempotencia unica (UUID v4)
curl -X POST https://pixapi-dev.fluxiq.com.br/api/v1/payments \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, ...}'

# Opcao 2: Aguardar expiracao do TTL (24h)

# Opcao 3: Limpar chave especifica no Redis (emergencia)
redis-cli -h 10.140.240.4 DEL "idempotency:<user_id>:<key>"
```

::: tip Comportamento esperado
Se a requisicao retorna HTTP 200 com a resposta anterior, isso e o comportamento correto do mecanismo de idempotencia — a operacao original foi processada com sucesso e o sistema esta retornando o resultado cacheado. Apenas se o corpo da requisicao mudou (fingerprint SHA-256 diferente) e que o HTTP 422 sera retornado.
:::

---

## Ferramentas de Diagnostico Rapido

Script consolidado para diagnostico rapido do sistema:

```bash
#!/bin/bash
# /opt/monetarie/scripts/health-check.sh

echo "=== Monetarie PIX — Diagnostico Rapido ==="
echo "Horario: $(date)"
echo ""

echo "--- Pods ---"
kubectl get pods -n pix -o wide
echo ""

echo "--- Health API ---"
curl -s https://pixapi-dev.fluxiq.com.br/health | jq .overall 2>/dev/null || echo "FALHA"
echo ""

echo "--- PostgreSQL ---"
psql -h 10.140.241.2 -U postgres -d monetarie -c "SELECT 1;" > /dev/null 2>&1 && echo "OK" || echo "FALHA"
echo ""

echo "--- Redis ---"
redis-cli -h 10.140.240.4 PING 2>/dev/null || echo "FALHA"
echo ""

echo "--- NATS ---"
nats server ping --server=nats://10.10.40.5:4222 2>/dev/null && echo "OK" || echo "FALHA"
echo ""

echo "--- Consumer Lag ---"
for CONSUMER in inbound-processor outbound-sender status-updater return-processor; do
  PENDING=$(nats consumer info MONETARIE_SPI ${CONSUMER} --server=nats://10.10.40.5:4222 2>/dev/null | grep "Pending" | awk '{print $NF}')
  echo "${CONSUMER}: ${PENDING:-ERRO} mensagens pendentes"
done
echo ""

echo "--- Workers (ultimo heartbeat) ---"
kubectl logs deployment/pix-backend -n pix --tail=100 2>/dev/null | grep "Heartbeat" | tail -5
echo ""

echo "=== Diagnostico concluido ==="
```

## Resultado Esperado

Ao utilizar este guia, voce sera capaz de:

- Identificar e resolver os 12 problemas mais comuns da plataforma Monetarie PIX
- Usar comandos de diagnostico especificos para cada sintoma
- Distinguir entre problemas de configuracao, infraestrutura e aplicacao
- Aplicar solucoes sem downtime quando possivel
- Executar o script de diagnostico rapido para triagem inicial