Barras de areia e ambientes de teste

TL; DR

Caixa de areia confiável = isolamento total, dados sintéticos/impessoais, simuladores de sistemas externos realistas, assentos previsíveis e time-travel, idempotidade integrada e webhooks, limites transparentes e métricas. O Prod não está disponível, as chaves estão a rolar, só as folhas de cheque.

1) Mapa dos ambientes e seus papéis

Regra: sandbox ≠ prod. Qualquer ligação é através de simuladores unilaterais sem acesso a meios reais/jogos/dados pessoais.

2) Dados: sintético, anonimato, assentamento

Sintético padrão. Geradores de dados de passaporte/cartão, validadas mas não financeiras PAN (BIN de teste), pattern «vivo» de apostas e balanços.
Anonimato para estágio: Tocinização de identificadores, privacidade diferencial para unidades, remoção de combinações raras.
Cidos e determinismo, uma equipa, uma condição.

bash make db-reset && make db-seed ENV=sandbox SEED=2025_11_03

Time-travel: «hora» global do ambiente para testes de deadline/exportação.

3) Simuladores e braços (stubs)

Pagamentos/bancos/PSP

Auth/Capture/Refund/Payout со сценариями: `approved`, `declined_insufficient`, `3ds_required`, `timeout`, `duplicate`.
Webhooks PSP: assinados HMAC, retais, atrasos e «internet suja».

KYC/AML/Sanctions

Ответы: `clear`, `pep_match`, `sanction_hit`, `doc_mismatch`, `manual_review`.
Suporte à idempotação e rate limits como em prod.

Provedores de jogos/diretório

Lobby, fici, RTP/rounds - geração pseudosocial gerada por «pagamentos/falhas» para malas UX.

Opção: botão «rigor» do simulador (happy-path vs chaos).

4) Webhooks no banco de areia

Assinaturas HMAC (v1), cabeçalhos 'X-Event-Id', 'X-Timestamp', janela ≤ 5 minutos.
Retrai com backoff exponencial, DLQ e replay.
O console «redesenhar» e os logs de tentativa.

pseudo
POST /psp/webhooks
Headers: X-Signature, X-Timestamp, X-Event-Id
Body: { event_id, type, data, attempt }

5) Idempotidade e determinismo

Todas as mutações tomam 'Idempotency-Key'.
Os simuladores armazenam o resultado por chave (TTL 24-72 h).
Seed Determinismo: Na mesma entrada, o mesmo resultado (para testes repetitivos).

6) Segurança e acesso

Isolamento de redes/VPC, segredos e domínios individuais ('sandbox. example. com`).
RBAC/ABAC: Os papéis «parceiro», «qa», «dave», os escopos de tokens são mínimos.
Rate-limits e quotas: participação justa per-tenant/chave compreendida por '429 '/' Retry-After'.
Segredos apenas em KMS/Vault; Rotatividade regular.
Impede pagamentos reais em nível de código/config (função-flag hard block).

7) API Gateway e observabilidade em sandbox

As mesmas políticas são OAuth2/OIDC/JWT, CORS, WAF, perfil DDoS.
Métricas: p50/p95/p99, 4xx/5xx, hit-rate limites, latency webhooks, hits idempotentes.
Logi/trailer: sem PII; corelação 'trace _ id'.
Dashboard Saúde de Areia, farmácia, filas de webhooks, erros de simulação.

8) Bandeiras fichas, versões e compatibilidade

Incluir o fichch no sandbox → estágio → prod.
SemVer para API; banner Deprecation/sunset em Swagger/Redoc cantigas de areia.
Persisted queries para vitrines GraphQL (se houver).

9) CI/CD и promotion

1. Build/Unit →

2. Contract/Mock tests (OpenAPI/Protobuf/GraphQL SDL) →

3. Integração contra simuladores de →

4. Estage regress (anon. shots) →

5. Canary в prod.

Folha de cheque de gate: abaixo no parágrafo 12.

10) Guiões UAT para parceiros (no banco de areia)

Pagamentos: auth/capture/refund/payout com webhooks e erros PSP.
KYC/AML: Todos os estados + escalação manual.
Idempotidade: Repito 'Idempotency-Key' → o mesmo resultado.
Rate-limit: processamento correto de '429'.
Janelas de tempo: exportação de tokens, 'Retry-After', 'time-travel'.
Webhooks: assinaturas/retrai/DLQ, replay manual e dedup.

11) Política de dados e privacidade

Nunca armazenar o real PAN/KYC-doc em sandbox/estágio.
Anónima: camuflagem, remoção de identificadores diretos, correlação sintética.
TTL armazenamento de logs e corpos de webhooks ≤ regulado.

12) Folhas de cheque

12. 1 Lançamento de uma nova caixa de areia

• Rede/base/banco/armazenamento de objetos isolados
• Segredos criados no KMS/Vault, acesso por papéis
• Os simuladores PSP/KYC/jogos estão bloqueados e versionados
• Swagger/Redoc + Postman coleção (sandbox endpoants)
• Webhooks: HMAC, retry, DLQ, console replay
• Perfis Rate/Quota, banners Deprecation/Sunset (se houver)
• Dashboards e alertas (latency, 5xx, 429, DLQ)

12. 2 Promotion release (stage→prod)

• Comprovação de desenho contratual (sem breaking)
• P95/p99 de carga normal por estágio
• Webhooks passaram por UAT, idempotação
• As bandeiras fichas estão preparadas, o plano de reversão está disponível
• Changelog, guia migratório e envio aos parceiros

13) Antipattern

Uma caixa de areia que «secretamente» toca serviços pró/base.
Dados reais de cartão/passaporte em estágio/sandbox.
Simuladores sem wabhooks/retrações - «trilha feliz» só.
Falta de idempotidade → duplicação de pagamentos/apostas.
Um segredo HMAC comum para todos os parceiros.
Não há limites ou transparência 429/Retry-After.

14) Mini-snippets

.env. sandbox (exemplo)

dotenv
API_BASE=https://sandbox.api.example.com
OAUTH_ISS=https://sandbox.idp.example.com
PSP_SIM_URL=https://sandbox.psp-sim.example.com
KYC_SIM_URL=https://sandbox.kyc-sim.example.com
WEBHOOK_SECRET_ROTATION_DAYS=90
FEATURE_FORCE_SANDBOX_PAYMENTS=1

OpenAPI fatia (sandbox servidor)

yaml servers:
- url: https://sandbox.api.example.com/v1 description: Public Sandbox

Pseudocode de idempotação

pseudo if store.exists(idem_key): return store.get(idem_key)
res = do_business()
store.set(idem_key, res, ttl=72h)
return res

Desencadeadores de simulador PSP

json
{ "scenario": "payout", "case": "declined_insufficient", "payout_id": "p_123" }

15) Observabilidade e barras de areia SLO

Uptime sandbox API ≥ 99. 5% (a vitrine das integrações não deve cair).
Webhooks p95 ≤ 3 com até 2xx com carga normal.
Error budget 5xx gateway ≤ 0. 1%.
O portal está disponível e sincronizado com o contrato.

16) Governance

O proprietário do ambiente (SRE/Plataforma) e da API steward (contratos).
Processo RFC para alterações de breaking, calendário Deprecation/Sunset.
Limites/quotas individuais e «fair-use» para uma caixa de areia pública.

Currículos

A caixa de areia é um produto para desenvolvedores, não uma cópia da base de dados. Dê-lhe: isolamento rigoroso, dados sintéticos, simuladores completos com webhooks e retrações, determinismo através de assentos e time-travel, bandeiras fichas e limites transparentes. Assine todos os contratos, observabilidade e governance - e suas integrações serão rápidas, seguras e previsíveis, e seus lançamentos serão indolores.