Pular para conteúdo

Deploy e Migrações

Este runbook estabelece os procedimentos operacionais para implantação de código, orquestração de migrações relacionais e rotinas de contingência/rollback da plataforma EcomSmart Agents no servidor de produção (VPS).


Sequência de Inicialização e Dependências

Para evitar falhas de inicialização por dependências ausentes, os containers devem ser iniciados respeitando a seguinte ordem cronológica de prontidão:

flowchart TD
    step1[1. Rede Compartilhada: ecomsmart-net] --> step2[2. Bancos de Dados: merchants-db, redis, minio, weaviate]
    step2 --> step3[3. Tarefas de Boot: db-migrate e minio-init]
    step3 --> step4[4. Core Backend: frontend-entrypoint, genai-wrapper, whatsapp-entrypoint, woocommerce-wrapper]
    step4 --> step5[5. Agentes de Negócio: b2c, b2b e marketing]
    step5 --> step6[6. Camada Web & Borda: landing, panel, flow-gateway, cloudflare-tunnel]

    style step1 fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style step2 fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style step3 fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
    style step4 fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style step5 fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style step6 fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1

Governança de Migrações (Alembic)

As alterações estruturais no PostgreSQL (schemas platform e genai) são gerenciadas pelo Alembic através do container efêmero db-migrate (infra/db/Dockerfile). O container executa um preflight antes de alembic upgrade heads: ele cria o baseline quando necessário e repara apenas estados históricos conhecidos de alembic_version.

Comandos de Operação de Banco

# Aplicar preflight e todas as migrations pendentes.
# Este é o único comando normal de publicação de schema.
docker compose -f infra/docker-compose.yaml run --rm --no-deps db-migrate

# Consultar as revisões aplicadas diretamente no banco.
docker compose -f infra/docker-compose.yaml exec merchants-db \
  psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
  -c 'TABLE platform.alembic_version;'

Compatibilidade e rollback

Use operações idempotentes quando uma migration puder ser reexecutada com segurança, mas não mascare uma divergência de schema. Migrations destrutivas ou downgrade exigem backup validado e revisão das dependências. Evite DDL longo ou bloqueios exclusivos em horário de pico para não afetar o Agente B2C.


Seed de Dados de Demonstração e Testes

Após a conclusão das migrações do banco, é possível carregar o conjunto de dados demonstrativo (infra/db/seeds/admin_dashboard.sql), que popula 10 lojistas fictícios, planos de créditos, administradores e métricas de campanhas:

docker compose -f infra/docker-compose.yaml exec -T merchants-db \
  sh -c 'psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
  < infra/db/seeds/admin_dashboard.sql

Os usuários de teste são provisionados com a senha padrão EcomDemo@2026:

Usuário E-mail Perfil
Super Administrador marina@seed.ecomsmart.dev super_admin
Administrador Operacional rafael@seed.ecomsmart.dev admin
Administrador Convidado bianca@seed.ecomsmart.dev admin

Procedimento de Deploy em Produção

Execute este roteiro na VPS para atualizar a plataforma com segurança:

# 1. Navegue para o checkout da VPS e baixe a referência que será publicada
cd <diretorio-do-repositorio>
git fetch origin
git switch <branch-ou-tag-estavel>
git pull --ff-only origin <branch-ou-tag-estavel>

# 2. Compile as novas imagens Docker antes de reiniciar os serviços
docker compose -f infra/docker-compose.yaml build

# 3. Execute o preflight e as migrações de banco pendentes
docker compose -f infra/docker-compose.yaml run --rm --no-deps db-migrate

# 4. Reinicie os containers atualizados
docker compose -f infra/docker-compose.yaml up -d --remove-orphans

# 5. Valide a integridade dos serviços
docker compose -f infra/docker-compose.yaml ps
curl --fail http://127.0.0.1:${FLOW_GATEWAY_PORT:-3080}/health

# 6. Limpe imagens Docker órfãs antigas para economizar espaço
docker image prune -f

Procedimento de Rollback de Emergência

Caso uma nova versão apresente falhas críticas em produção:

  1. Reverter Código para uma referência previamente validada:
    git switch --detach <HASH_COMMIT_ESTAVEL_ANTERIOR>
    
  2. Avaliar o schema antes de revertê-lo: não execute downgrade como etapa automática. Aplique apenas uma migration de reversão revisada, ou restaure um backup compatível, se o código anterior não aceitar o schema atual.
  3. Recompilar e subir os containers:
    docker compose -f infra/docker-compose.yaml up -d --build
    
  4. Verificar Restauração: Monitore os logs dos agentes B2C e B2B para confirmar que os eventos de WhatsApp foram retomados:
    docker compose -f infra/docker-compose.yaml logs -f b2c b2b