id: "REQ-285" title: "Falha na etapa de finalização (finalize) do atualizador do sistema pelo painel" status: "implemented-pending-homologation" date: "2026-10-20" author: "architect" target_repo: "conn2flow" batch: "BATCH-294" topology: "dupla" autonomy: "autonomo_monitorado" origin: "Relato do Engenheiro Chefe Humano após tentativa de atualização do Lab para gestor-v3.0.9"

req-285: Falha na etapa de finalização (finalize) do atualizador pelo painel

1. O Relato

Ao atualizar uma instância do site via painel administrativo (admin-atualizacoes) para a tag gestor-v3.0.9:

• Sessão criada e deploy de arquivos concluído com sucesso.

• Banco de dados e migrações executados com sucesso.

• Na etapa finalize, a interface emite imediatamente Falha finalize.

12:27:17 - Iniciando sessão (full).
12:27:23 - Sessão criada: 881b1016fe1c9b0c exec_id=4 tag=gestor-v3.0.9 modo=full
12:27:23 - Deploy: executando arquivos + merge .env
12:27:32 - Deploy concluído.
12:27:32 - Banco: iniciando
12:27:56 - Banco concluído.
12:27:56 - Finalizando sessão
12:27:56 - Falha finalize

2. Diagnóstico Preliminar do Arquiteto

1. Falha de Transporte/HTTP na Chamada AJAX: A mensagem Falha finalize ocorre especificamente no bloco .fail() da requisição AJAX acao: 'finalize'. Isso indica que a requisição não completou com HTTP 200 (podendo ser erro fatal HTTP 500, estouro de tempo/timeout, expiração de sessão ou erro no health check pós-atualização).

2. Execução de saudeVerificar() no Finalize: A etapa webFinalize roda saudeVerificar(), que faz chamadas curl e checa php-error.log. Dependendo de timeout de rede, certificado SSL local ou recursos, a chamada pode travar ou estourar o limite de tempo do PHP (a etapa finalize não invoca atualizacoes_web_recursos() para elevar memória/tempo como as etapas start, deploy e db).

3. Invalidador de Sessão (gestor_sessao_del_all): No encerramento da atualização, o script tenta limpar/reinicializar sessões, o que pode derrubar a autenticação ou o token CSRF da própria requisição que está em andamento.

3. Escopo da Requisição para o Agente Executor

1. Investigar Logs Reais: Inspecionar os logs de erro do Apache/PHP e logs/atualizacoes.log da sessão 881b1016fe1c9b0c no ambiente de teste/Lab para identificar o código HTTP e o erro exato.

2. Blindagem de Recursos no finalize: Garantir que atualizacoes_web_recursos() e tratamento de erros fatais protejam também a ação finalize em atualizacoes-sistema.php.

3. Resiliência do Health Check e Sessões: Evitar que falhas transitórias de rede local no health check ou na renovação de CSRF/sessão derrubem o status de sucesso da atualização já aplicada nos arquivos e banco.

4. Testes Unitários / Regressão: Cobrir o fluxo do webFinalize e validar cenários onde o health check ou reinicialização de sessão falham sem derrubar o payload JSON.

4. Critérios de Aceite

1. A chamada acao: 'finalize' responde status JSON estruturado (ok ou erro), nunca estourando com HTTP 500 não tratado.

2. Atualização completa pelo painel conclui sem travar na barra de progresso.

3. Testes do módulo admin-atualizacoes e suíte do Core 100% verdes.