Execução e gerenciamento de scripts operacionais

Contexto e Declaração do Problema

Ao longo da operação da Amplimed, surgem demandas recorrentes para:

Geração de relatórios pontuais (ex.: CSV)
Execução de comandos de correção em produção
Scripts de uso único (one-off)
Execuções emergenciais motivadas por incidentes em produção

Historicamente, não existia um local padronizado para esse tipo de necessidade. Como consequência:

Scripts e relatórios eram criados em APIs que não tinham relação direta com o propósito da execução
Muitas vezes eram escolhidas APIs com menor uso, apenas para evitar impacto
Não havia previsibilidade nem padronização de onde procurar ou registrar essas execuções

Além disso, a execução desses scripts ficava centralizada em poucas pessoas, normalmente exigindo acesso direto ao ambiente e execução manual via terminal.

Esse cenário gerava um segundo problema relevante:

Execuções manuais em produção, frequentemente realizadas fora do horário comercial (entre 20h e 00h)
Dependência direta do Tech Lead ou de quem detém os acessos
Risco operacional e desgaste humano desnecessário

Pergunta central:

Como centralizar, padronizar e operacionalizar a execução de scripts e relatórios de forma segura, auditável e menos dependente de execuções manuais em produção?

Mapeamento dos Problemas Relacionados a esta ADR

Os principais cenários afetados por esse problema eram:

Relatórios pontuais solicitados por analistas
Correções emergenciais em produção
Scripts de migração ou ajuste de dados de uso único
Necessidade de envio manual de arquivos (ex.: CSV) após execução local
Execuções críticas dependentes de uma única pessoa com acesso ao ambiente

Direcionadores da Decisão

Padronização: definir um local único e conhecido para scripts e relatórios operacionais
Segurança operacional: reduzir execuções manuais diretas em produção
Descentralização controlada: evitar dependência exclusiva do Tech Lead
Auditabilidade: registrar quem solicitou, quando e o que foi executado
Automação: permitir agendamento e execução imediata quando necessário
Escalabilidade organizacional: solução reutilizável para demandas futuras

Opções Consideradas

Opção 1: Criar uma API dedicada para scripts operacionais e relatórios

Decisão

Opção escolhida: Opção 1 – Criar uma API dedicada para scripts operacionais e relatórios (amplimed_scripts).

Foi decidido criar a amplimed_scripts, uma API responsável exclusivamente por:

Execução de comandos sob demanda
Agendamento de execuções
Geração de relatórios (ex.: CSV)
Envio automático de resultados via e-mail
Registro e controle das execuções realizadas

Essa solução resolve de forma estrutural os dois principais problemas identificados:

Onde colocar scripts e relatórios
Como executá-los sem depender de acesso manual ao ambiente

A API já foi desenvolvida e encontra-se em produção, atendendo às necessidades operacionais atuais.

Consequências

Positivas

Centralização e padronização de scripts operacionais
Redução significativa de execuções manuais em produção
Menor dependência do Tech Lead para tarefas operacionais
Possibilidade de agendamento e execução imediata
Envio automático de relatórios sem necessidade de execução local

Negativas

Criação e manutenção de uma nova API
Necessidade de governança para evitar uso indevido
Curva inicial de adoção pelos times

Neutras

Não altera regras de negócio das APIs existentes
Não substitui pipelines ou processos de deploy
Atua exclusivamente como ferramenta operacional

Confirmação e Validação

A aderência a este ADR é validada por meio de:

Uso recorrente da amplimed_scripts para demandas operacionais
Revisões de pull requests garantindo que scripts pontuais sejam criados nela
Monitoramento de execuções e falhas
Auditoria das execuções realizadas (quem, quando e o quê)

Prós e Contras das Opções

Opção 1 – amplimed_scripts (opção escolhida)

Positivo: solução estrutural, segura e reutilizável
Neutro: exige governança
Negativo: custo inicial de desenvolvimento e manutenção