Criar código de replicação de dados (ETL) que não altere valores em silêncio nem vaze dados

## Não fazer push nem mexer em migrações sem pedido Mantenha cada alteração concentrada no problema que está sendo resolvido. Prefira a menor diferença coerente, a menos que uma refatoração mais ampla seja necessária para preservar a correção. Antes de introduzir um padrão, uma dependência, um auxiliar ou uma estrutura de teste, examine o código próximo e siga as convenções estabelecidas no espaço de trabalho. Considere a configuração do formatador, os diagnósticos do compilador e as definições de análise estática do espaço de trabalho como a fonte oficial do estilo que pode ser imposto. Não grave no repositório, publique ramificações, abra solicitações de alteração nem reescreva o histórico, a menos que o usuário solicite explicitamente essa ação. Não altere migrações de banco de dados, a menos que o trabalho solicitado exija especificamente uma alteração de migração. Isso inclui comentários e texto não executável dentro dos arquivos de migração. Execute verificações dispendiosas em todo o espaço de trabalho somente quando o escopo delas for justificado. Para alterações de baixo risco em documentação ou configuração, use a menor validação relevante e informe exatamente o que foi executado. ## Agrupar módulos por conceito de dados e manter as APIs privadas por padrão Organize por conceitos do domínio, e não por categorias genéricas. Mantenha juntos o comportamento de replicação e os tipos específicos da replicação; coloque componentes básicos reutilizáveis do banco de dados, auxiliares de origem, auxiliares de slots de replicação e acesso a metadados em um limite de integração. Use limites de pacote somente quando outro pacote tiver uma dependência real da API. Dentro de um domínio, prefira módulos com nomes como `schema`, `data`, `event`, `store`, `source` ou `slots`. Mantenha os binários de nível superior concentrados na orquestração. Transfira os detalhes da implementação para auxiliares e módulos bem delimitados. Use visibilidade privada por padrão e amplie-a somente para um chamador real. Prefira visibilidade privada, depois restrita ao pacote e, por último, pública. Trate cada reexportação como um contrato de API: - evite reexportações com curinga de módulos internos; - exponha somente a menor interface de configuração que seja útil; - mantenha privados a orquestração de processos de trabalho, os codificadores e decodificadores, a infraestrutura de execução e os detalhes da implementação; - evite fachadas de compatibilidade, a menos que sejam intencionalmente uma API estável. Prefira código claro e convencional a abstrações engenhosas. Agrupe tipos, construtores, métodos públicos e auxiliares privados em uma ordem legível. ## Detectar arredondamentos e outras mudanças silenciosas de valores Valide os valores localmente quando o destino aceitaria, de outra forma, uma alteração semântica silenciosa, como arredondamento, truncamento, limitação, coerção, estouro ou perda de precisão. Se o destino já rejeitar um valor não compatível com um erro explícito, não duplique uma validação dispendiosa no caminho de gravação sem uma necessidade demonstrada. Use conversões numéricas verificadas ou baseadas em traits quando elas forem sem perdas e estiverem disponíveis. Use conversões de tipo intencionalmente sujeitas a perdas somente quando a perda for compreendida, o intervalo for verificado quando apropriado e a representação de destino as exigir. Use uma conversão implícita somente quando o mapeamento for infalível, semanticamente sem perdas, preservar o valor e for óbvio. Modele atualizações parciais com três estados distintos: - campos omitidos preservam o valor armazenado; - um nulo explícito limpa um valor opcional ou redefine um valor predefinido; - valores não nulos substituem o valor armazenado. Ao converter uma configuração completa para a semântica de uma atualização parcial, use um auxiliar de conversão explícito. Não oculte uma mudança de preservar para limpar por trás de uma trait de conversão genérica. ## Retornar erros claros em vez de travar com entradas ruins Use erros tipados e valores de resultado para falhas recuperáveis. Acrescente contexto próprio, como operações, identificadores, contagens, tipos ou instruções, preservando o erro original como a cadeia de causas. Não reduza um erro subjacente a uma cadeia de caracteres, a menos que uma mensagem deliberadamente higienizada seja mais segura para o chamador. As respostas de APIs públicas não devem expor erros do controlador do banco de dados, consultas internas, dados de clientes nem detalhes da infraestrutura. Reserve pânicos para invariantes de programação violadas. Entradas externas, sintaxe malformada, valores não compatíveis e falhas do estado do sistema devem retornar erros explícitos. Os pontos de entrada do analisador sintático devem tratar entrada vazia, fim inesperado da entrada, escapes malformados, sequências de bytes inválidas, intervalos inválidos, estouro, subfluxo e sintaxe não compatível sem entrar em pânico. Prefira acesso verificado, iteradores e análise de fatias de bytes quando a entrada controlar os deslocamentos. A indexação direta é aceitável somente quando um limite local ou uma invariante de bloco de tamanho exato tornar isso evidente. Acrescente testes de regressão para cada limite de entrada malformada que anteriormente pudesse causar pânico ou uma interpretação incorreta silenciosa. ## Escolher como as tarefas em segundo plano param conforme o estado que guardam Evite código unsafe, a menos que seja necessário. Todo bloco unsafe deve ter uma explicação de segurança adjacente que declare a invariante que torna a operação válida. Prefira propriedade e empréstimo a clonagem desnecessária ou mutabilidade interna. Coloque trabalhos assíncronos de longa duração atrás de tarefas ou auxiliares nomeados e escolha o comportamento de encerramento de acordo com o estado possuído: - descartar um identificador de tarefa desanexa a tarefa; aborte explicitamente o trabalho em segundo plano que pode ser descartado quando ele precisar parar imediatamente; - descartar um conjunto de tarefas aborta todas as tarefas que ele possui; - não aborte de forma redundante um conjunto de tarefas imediatamente antes de sair do escopo que o descartará; - use operações de aborto explícitas quando o conjunto de tarefas permanecer ativo, mas suas tarefas precisarem parar; - use sinalização normal de encerramento e aguarde a conclusão quando as tarefas possuírem transações, gravações em buffer no destino ou estado de replicação sensível a novas tentativas. Não acrescente uma coordenação elaborada de encerramento para tarefas de consulta periódica ou telemetria cujo estado possa ser descartado com segurança. ## Manter segredos e dados de clientes fora do código e dos logs Trate arquivos rastreados, ramificações, commits, revisões, logs, capturas de tela, fixtures, artefatos gerados e saída do terminal como potencialmente públicos. Nunca coloque credenciais, tokens, pontos de acesso privados, dados de clientes, cargas úteis de produção, dados pessoais ou configurações proprietárias em código, testes, documentação, exemplos, comentários, mensagens, telemetria, detalhes de pânico ou arquivos gerados. Use marcadores fictícios nos exemplos. Armazene segredos reais somente em variáveis de ambiente aprovadas, arquivos locais ignorados, gerenciadores de segredos ou armazenamento de segredos da integração contínua. Se um valor suspeito parecer real ou tiver vindo de um ambiente privado, não o reproduza. Interrompa o caminho de publicação, informe o local sem citar o valor e recomende a rotação ou revogação quando a exposição puder ter ocorrido. Para a observabilidade: - prefira rótulos de baixa cardinalidade; - registre metadados estruturais, como nomes de tabelas, nomes de colunas, tipos, contagens, comprimentos, posições e nomes de operações; - nunca registre valores de linhas, conteúdo de células, corpos confidenciais de solicitações ou respostas, credenciais nem tokens; - use formatação de exibição segura para erros e campos estruturados; - higienize a captura de conteúdo em rotas confidenciais e escopos de monitoramento. ## Testar eventos reais de replicação e confirmar que os testes rodaram Execute primeiro os testes relevantes mais restritos e depois amplie quando o comportamento compartilhado, as regressões ou a solicitação justificarem. Verifique se os testes esperados realmente foram executados; um comando bem-sucedido sem testes correspondentes não constitui uma verificação aprovada. Liste os testes antes de aplicar filtros incertos. Execute os testes de documentação separadamente quando o executor principal de testes não os admitir. Reutilize fixtures próximas, auxiliares de banco de dados, primitivas de espera e asserções antes de criar uma infraestrutura de teste personalizada. Para testes de integração orientados a eventos: 1. Registre notificações ou identificadores de espera antes que o produtor possa emitir o evento. 2. Faça gravações no lado da origem. 3. Aguarde as notificações esperadas. 4. Encerre e aguarde a conclusão do fluxo de processamento antes de verificar o estado do destino, a menos que o teste aborde explicitamente o comportamento durante o processamento. 5. Faça as asserções com base no histórico cumulativo de eventos, a menos que uma reinicialização ou fase isolada exija limpá-lo. Faça os eventos esperados de captura de alterações de dados corresponderem ao comportamento real da identidade da réplica no banco de dados de origem. Não espere linhas de atualização parciais em modos que não possam emiti-las. ## Documentar o código e relatar as verificações executadas Documente itens públicos e privados com texto conciso e preciso. Vincule tipos e métodos usando as referências compatíveis com o sistema de documentação. Pontue os comentários e coloque-os acima do código que explicam. Defina nomes de métricas e chaves de rótulos como constantes, centralize os rótulos compartilhados e registre as descrições uma só vez. Mantenha uma tarefa específica de métricas por origem, além de uma pequena interface de orquestração. Antes de concluir, confirme o escopo afetado: - o alvo alterado compila; - a formatação passa na verificação; - a análise estática passa com a configuração de análise do espaço de trabalho; - os testes unitários e de integração relevantes passam e realmente foram executados; - os testes de documentação passam quando aplicáveis; - os comentários e a documentação correspondem ao comportamento final; - as métricas, os registros e os rótulos seguem as regras de nomenclatura e segurança de dados. Informe as verificações realizadas, o escopo delas e quaisquer verificações omitidas intencionalmente. Não alegue conclusão apenas com base no estado de saída de um comando quando a saída mostrar que nenhum alvo significativo foi submetido à verificação.