ADR: Otimização e Melhorias no Processo de Migrations

Status

Em Discussão

Contexto

No fluxo atual da Amplimed, as migrations geram problemas recorrentes durante o processo de atualização e na operação do sistema. Este documento analisa o processo existente e propõe melhorias para aumentar a confiabilidade e rastreabilidade das migrações de banco de dados.

Fluxo Atual de Execução

O sistema utiliza uma arquitetura event-driven para gerenciar migrations:

Trigger Inicial: Durante o login do usuário, o sistema verifica um cache com TTL de 12 horas
Publicação de Evento: Se o cache expirou, um evento de migration é publicado via Apache Kafka
Consumo Assíncrono: O serviço dedicado de migrations consome o evento
Verificação de Estado:
- Consulta a tabela migrations no banco da clínica
- Identifica migrations já executadas através dos registros na tabela
Execução Ordenada:
- Compara registros existentes com arquivos disponíveis na API
- Localiza arquivos de migration pendentes
- Executa o método up() contendo os comandos SQL
Registro: Insere novo registro na tabela migrations após execução bem-sucedida

Problema

Pergunta Central: Como podemos evitar problemas recorrentes de migrations não executadas ou com falhas durante o processo de atualização?

Problemas Identificados

Janela de Execução Limitada: O intervalo de 12 horas pode causar atrasos na aplicação de migrations críticas
Ausência de Validação Pós-Execução: Não há verificação se a migration teve o efeito esperado no banco
Rastreabilidade Limitada: Dificulta identificar quais clínicas executaram quais migrations
Dependência do Ciclo de Login: Clínicas com baixa atividade podem ficar desatualizadas por períodos prolongados

Decisão

Melhorias Propostas

Opção 1: Implementação de WebSocket para Clínicas Ativas Durante Release

Descrição: Estabelecer conexão WebSocket com clínicas logadas durante janelas de release para executar migrations em tempo real.

Aspecto	Avaliação
Prós	• Elimina necessidade de release antecipado (D-1) • Feedback imediato sobre execução • Reduz janela de inconsistência entre clínicas
Contras	• Aumenta complexidade da infraestrutura • Requer gerenciamento de conexões persistentes • Possíveis problemas de escalabilidade
Neutro	• Pode complementar o fluxo atual via Kafka • Implementação incremental possível

Opção 2: Validação Pós-Execução com Método `verify()`

Descrição: Adicionar método obrigatório verify() em cada migration para validar se as alterações foram aplicadas corretamente.

Aspecto	Avaliação
Prós	• Validação concreta do estado do banco • Detecção precoce de falhas silenciosas • Maior confiabilidade no processo
Contras	• Aumenta tempo de desenvolvimento • Risco de esquecimento se não automatizado • Requer educação e enforcement junto aos desenvolvedores
Neutro	• Possível impacto no tempo de execução das migrations • Pode ser implementado gradualmente

Opção 3: Dashboard de Migrations por Clínica

Descrição: Interface administrativa para visualizar status de migrations por clínica em tempo real.

Aspecto	Avaliação
Prós	• Visibilidade do estado de cada clínica • Facilita a resolução de problema • Permite ações proativas
Contras	• Não garante execução efetiva • Visão superficial sem o método verify() • Requer manutenção adicional
Neutro	• Complementa outras melhorias • Útil para monitoramento operacional

Features Sugeridas:

Filtros por status: Pendente, Em Execução, Sucesso, Falha
Histórico de execução com timestamps
Alertas para migrations com alta taxa de falha
Capacidade de re-executar migrations falhadas

Consequências

Positivas

Maior confiabilidade no processo de deployment
Redução de incidentes relacionados a migrations
Melhor visibilidade operacional
Menor tempo de resolução de problemas

Negativas

Aumento temporário na complexidade de desenvolvimento
Necessidade de treinamento da equipe
Investimento inicial em infraestrutura

Riscos

Resistência à adoção de novos processos
Possível aumento no tempo de desenvolvimento inicial
Necessidade de manter compatibilidade com fluxo legado durante transição