Auditoria de Propagação de Contrato Cross-Platform

Visão Geral

Auditar uma mudança de contrato desde sua origem, através de todas as transformações e consumidores, antes do lançamento. Tratar um campo que existe em um esquema como incompleto até que seu significado, padrões, comportamento na rede, controles de rollout, tratamento no cliente, análises e testes sejam comprovados em todos os caminhos relevantes.

Este é um fluxo de trabalho de evidências somente leitura. Ele reporta lacunas de propagação; não as implementa.

Quando Usar Esta Habilidade

• Use ao adicionar ou alterar um campo, valor de enum, status, capacidade ou feature flag compartilhado por múltiplos componentes.
• Use quando banco de dados, backend, API, Web, Android, iOS, jobs, eventos ou análises podem interpretar o mesmo valor de forma diferente.
• Use quando uma mudança deve preservar registros existentes, clientes mais antigos ou um rollout com padrão desativado.
• Use quando uma mudança parece completa em um endpoint, mas pode estar faltando em pontos de entrada alternativos ou modelos gerados.

Como Funciona

Passo 1: Escrever o contrato semântico

Antes de rastrear arquivos, declare o invariante de negócio e defina cada estado observável. Distinga valores que linguagens e serializadores frequentemente colapsam:

Registre os requisitos de compatibilidade, propriedade, condição de rollout e o comportamento exato visível pelo usuário ou pelo sistema para cada estado. Não aceite optional, nullable e default false como equivalentes sem evidências.

Passo 2: Enumerar o grafo de propagação

Liste cada nó relevante antes de julgar a completude:

source of truth
  -> persistence and migration
  -> domain model and mapper
  -> service or policy computation
  -> every API, event, cache, and job projection
  -> generated or handwritten client model
  -> client state and presentation logic
  -> analytics and operational observability
  -> tests, rollout, and rollback checks

Inclua endpoints alternativos de leitura/escrita, projeções de lista/detalhe, consumidores em segundo plano, caches offline, interfaces de administração, versões mais antigas de aplicativos e pontos de avaliação de feature flag quando estiverem no escopo. Marque um nó not applicable apenas com um motivo.

Passo 3: Rastrear evidências, aresta por aresta

Para cada aresta, cite o produtor, a transformação, o consumidor e o teste usando caminhos de arquivo, símbolos, nomes de esquema ou outras evidências inspecionáveis. Atribua um status:

Não promova likely, convenção, compatibilidade de tipo ou um padrão de framework para proven. Uma declaração prova a forma, não o mapeamento ou comportamento em tempo de execução.

Passo 4: Verificar as fronteiras de alto risco

Inspecione explicitamente estas fronteiras:

• Migração e dados existentes: padrão, preenchimento, nulidade, rollback, leituras e escritas de versões mistas.
• Mapeamento de domínio: coerção para ausente/nulo, fallbacks de enum, validação, valores derivados, simetria de serialização.
• Superfícies de fan-out: DTOs de lista e detalhe, eventos, caches, jobs, índices de busca, SDKs e versões alternativas de API.
• Compatibilidade do cliente: decodificação de ausente e nulo explícito, enums desconhecidos, desvio de modelo gerado, payloads em cache, builds de lançamento ou minificados.
• Controle de rollout: padrão da flag, local de avaliação, consistência de coorte, kill switch e comportamento quando os dados armazenados discordam da flag.
• Análises: eventos oferecidos, renderizados, tentados, bem-sucedidos e falhados carregam contexto de contrato e versão suficientes para serem unidos de forma confiável.

Passo 5: Construir uma matriz de teste estado-por-caminho

Cruze os estados semânticos do Passo 1 com cada caminho material do Passo 2. No mínimo, inclua padrões de dados existentes, valores ativados e desativados, flag ligada e desligada, endpoints alternativos, clientes atuais e clientes mais antigos representativos.

…