Estratégia de sincronização de dados de clínicas entre bancos

Contexto e Declaração do Problema

A arquitetura atual da Amplimed utiliza um modelo multi-tenant por banco, no qual:

  • Existe um banco geral, que contém dados globais do sistema (usuários, clínicas e outros dados compartilhados)
  • Cada clínica possui seu próprio banco
  • Em ambos os bancos existe a tabela clinicas, com campos equivalentes (nome, endereço, telefone, status da base, entre outros)

Nesse modelo:

  • O banco da clínica sempre possui um único registro na tabela clinicas
  • O banco geral possui um registro correspondente para cada clínica existente

Quando dados da clínica são alterados no banco da própria clínica, essas alterações precisam ser refletidas no banco geral para garantir o funcionamento correto do sistema, especialmente em fluxos críticos como autenticação e acesso à plataforma.

Historicamente, essa sincronização é realizada por meio de um script de rotina (sincroniza_clinicas), executado diariamente via EasyCron.
Esse script sempre fez parte dos processos operacionais da plataforma e, de forma geral, atendeu às necessidades do sistema ao longo do tempo.

Entretanto, com a evolução do produto e da arquitetura, surgiram novos desafios:

  • Crescimento do número de processos que alteram dados da clínica
  • Escritas distribuídas entre diferentes stacks (PHP procedural, Laravel e possivelmente Node.js)
  • Dificuldade de mapear todos os pontos de persistência
  • Maior impacto de inconsistências em dados críticos, como statusBase

Recentemente, uma falha na execução do script resultou em divergência de dados entre os bancos, ocasionando problemas como clínicas com status incorreto no banco geral e usuários impedidos de realizar login.

Como parte de uma iniciativa de melhoria contínua e preparação para evolução futura, o script de sincronização foi refatorado para Laravel, com foco em:

  • Melhor manutenibilidade
  • Padronização de execução
  • Facilidade de evolução e observabilidade

Apesar dessa melhoria técnica, o modelo atual continua baseado em sincronização periódica, o que expõe riscos estruturais de divergência de dados.

Pergunta central:

Como garantir a sincronização consistente e confiável dos dados da clínica entre o banco da clínica e o banco geral, reduzindo riscos de divergência e dependência exclusiva de rotinas periódicas?

Mapeamento dos Problemas Relacionados a esta ADR

Os principais impactos observados ou potenciais são:

  • Divergência de dados entre banco da clínica e banco geral
  • statusBase incorreto no banco geral, impedindo login de usuários
  • Dependência de execução periódica para garantir consistência
  • Falhas silenciosas difíceis de detectar imediatamente
  • Dificuldade de rastrear a origem de alterações nos dados da clínica
  • Risco operacional elevado em caso de falha do processo de sincronização

Direcionadores da Decisão

  • Consistência de dados: evitar divergência entre representações da mesma entidade
  • Confiabilidade: reduzir riscos associados a falhas de sincronização
  • Evolução arquitetural: preparar o sistema para soluções mais robustas
  • Baixo acoplamento tecnológico: solução compatível com múltiplas stacks
  • Observabilidade: facilitar rastreamento e auditoria das sincronizações
  • Impacto operacional: proteger fluxos críticos como login e acesso à plataforma

Opções Consideradas

  • Opção 1: Manter exclusivamente o script de sincronização periódica (modelo atual)
  • Opção 2: Aumentar a frequência do script de sincronização
  • Opção 3: Centralizar todas as atualizações de dados da clínica em uma única API

Decisão

Opção escolhida: Ainda não definida.

Este ADR tem como objetivo registrar formalmente um problema estrutural conhecido, reconhecendo que a solução atual (o script de sincronização executado via EasyCron) faz parte das rotinas da plataforma há anos e cumpriu seu papel historicamente.

A refatoração recente do script para Laravel não foi uma solução paliativa, mas sim um passo evolutivo, visando melhorar a base técnica e preparar o terreno para uma possível evolução arquitetural.

A decisão futura deverá buscar uma estratégia mais robusta, que reduza riscos de divergência e diminua a dependência exclusiva de sincronização periódica, sem desconsiderar a realidade atual do sistema e suas múltiplas stacks.

Consequências

Positivas

  • Registro claro e formal de um problema estrutural
  • Base sólida para discussão e evolução arquitetural
  • Reconhecimento da solução atual como parte legítima da arquitetura

Negativas

  • O risco de divergência permanece enquanto a solução definitiva não é implementada
  • Continuidade da dependência do processo periódico atual

Neutras

  • Nenhuma mudança imediata no comportamento do sistema
  • Não impacta fluxos existentes enquanto o ADR estiver em discussão

Confirmação e Validação

A solução futura deverá ser validada por meio de:

  • Redução ou eliminação de divergências entre bancos
  • Diminuição da dependência de sincronização periódica
  • Monitoramento de inconsistências em dados críticos
  • Garantia de que falhas de sincronização não impactem login e operação
  • Auditoria e rastreabilidade das alterações nos dados da clínica

Prós e Contras das Opções

Opção 1 – Script de sincronização periódica (modelo atual)

  • Positivo: solução consolidada, em uso há anos e integrada aos processos da plataforma
  • Neutro: depende de execução periódica para garantir consistência
  • Negativo: suscetível a falhas silenciosas e janelas de inconsistência

Opção 2 – Aumentar frequência do script

  • Positivo: reduz janela de inconsistência
  • Neutro: mantém abordagem atual
  • Negativo: não elimina causa raiz e aumenta carga operacional

Opção 3 – Centralização via API única

  • Positivo: controle explícito dos pontos de escrita
  • Neutro: exige refatoração gradual
  • Negativo: difícil garantir cobertura total no curto prazo