id: "REQ-287" title: "Deploy de projeto com etapas visíveis: progresso do envio e do processamento no servidor" status: "ready-for-intake" date: "2026-10-20" author: "executor" target_repo: "conn2flow" batch: null topology: "dupla" autonomy: "supervisionado" origin: "Pedido do Engenheiro Chefe durante a REQ-285, ao fazer o deploy do conn2flow-site em produção"

req-287: Deploy de projeto com etapas visíveis

1. O relato

No ./c2f project:deploy <id>, depois de File size: 62M o terminal fica parado por minutos sem dizer nada. Não dá para saber se está enviando o arquivo, processando no servidor ou travado. O Engenheiro Chefe pediu sub-status: envio, execução no servidor, handshake, criando o que for preciso na API.

2. Como é hoje (conferido na REQ-285)

• ai-workspace/en/scripts/projects/deploy-project-v2.sh envia o pacote com um único curl -s (modo silencioso, sem progresso) para POST /_api/project/update.

• O servidor (api_project_update() em gestor/controladores/api/api.php) faz tudo dentro dessa requisição: extrai o zip, planeja e aplica os arquivos (com snapshot), faz o dump do banco inteiro no snapshot, roda migrações e sincronização de dados e a verificação de saúde. Só então responde.

• A resposta só traz o resultado final. Se a conexão cair no meio, o cliente não sabe em que etapa o servidor estava.

3. Escopo proposto

1. Envio com progresso: barra do curl (--progress-bar) ou percentual próprio, com tamanho e velocidade.

2. Execução no servidor como tarefa com estado: o POST recebe o pacote, grava a tarefa (temp/deploy-jobs/<id>.json, mesmo padrão das sessões do admin-atualizacoes) e responde 202 com o id. As etapas rodam e atualizam o estado: recebido → extraindo → arquivos (n de m) → snapshot/dump do banco → migrações → sincronizando <tabela> → verificação → concluído/erro. Ignorar abort do cliente e ter memória e tempo como nas etapas web do atualizador.

3. Rota de status: GET /_api/project/update/status?job=<id> (mesma autenticação), devolvendo etapa, percentual, últimas linhas do log e resultado final.

4. CLI acompanha: o script consulta a rota a cada poucos segundos e mostra a etapa atual com tempo decorrido; no fim, o mesmo resumo de hoje. Se a conexão cair, retoma pelo id.

5. Compatibilidade: servidor antigo (sem a rota) segue no modo síncrono atual; o CLI detecta pela resposta.

6. Trava e manutenção do deploy continuam valendo durante a tarefa (deploy.lock, maintenance.json).

4. Critérios de aceite

1. Durante o envio, o terminal mostra o progresso do upload.

2. Durante o processamento, o terminal mostra a etapa atual do servidor e o tempo decorrido, atualizados enquanto ela roda.

3. Queda da conexão no meio não perde o resultado: o CLI retoma pelo id da tarefa.

4. Servidor sem a rota nova continua funcionando como hoje.

5. Testes da API e do script verdes; deploy medido no Lab.