Requisição 197 — Atualização segura, fase 1: trava de deploy, backup, checagem de migrações e CLI/web alinhados

Origem: Humano, 2026-09-30: promoção do BL-028, fase 1, conforme o parecer do Arquiteto ("começa pela trava de deploy, que é o mais urgente"). Lote Vinculado: BATCH-201. Status: implementada (BATCH-201 complete); homologação humana pendente. Repositório: [REDACTED] (worktree conn2flow-bl028, branch feat/req-197).

Contexto

Diagnóstico do BL-028, achados 4 a 7:

• não há trava entre deploys no mesmo ambiente (em 2026-09-30, pipelines de agentes diferentes cruzaram duas vezes no Lab);

• a atualização com --backup chama backupTotal(), que não existe (erro fatal);

• migrações com a mesma versão criadas em paralelo só aparecem no servidor, como erro do Phinx;

• o CLI apaga db/ depois do banco e o web não.

Itens

1. Trava de deploy por ambiente:

   • arquivo de trava com dono, execução, início e validade (TTL), criado de forma atômica;

   • trava vencida é assumida com aviso; trava viva recusa com a identificação de quem está rodando.

   • Vale nos três caminhos:

     • atualização do sistema: CLI e web por etapas, com liberação no fim, no erro e no cancelamento;

     • deploy de projeto por API (api_project_update);

     • pipeline project:update-all: trava local por destino (host e caminho do SSH, ou a pasta local) em GIT/.c2f-deploy-locks/, comum a todos os clones e worktrees, que espera a trava liberar (com aviso periódico e limite) em vez de recusar de cara; --no-wait falha na hora.

2. Backup total que funciona: implementar backupTotal() (cópia da instalação, respeitando as pastas protegidas e sem copiar backups/); o caminho do backup entra no relatório e em atualizacoes_execucoes.

3. c2f db:check-migrations:

   • acusa versão duplicada e classe duplicada nas migrações do core, do projeto (e dos plugins, se houver);

   • roda como primeira verificação do project:update-all, antes de qualquer envio;

   • também avulso, para pre-commit.

4. CLI e web alinhados em db/: nenhum dos dois apaga db/ depois do banco.

   • db/migrations tem dois donos (core e projeto), e o manifesto da req-194 (db/.c2f-migrations-<dono>.json) mora em db/: apagar a pasta apagava as migrações do projeto e fazia toda atualização contar como "primeira vez".

   • As migrações obsoletas já saem pela limpeza por dono da req-194.

5. Tentativa automática no Tailwind: a substituição atômica do *.precompiled.css tenta de novo, por pouco tempo, quando o arquivo está preso (trava do OneDrive), em vez de derrubar o pipeline inteiro.

Fora do escopo (req-198 e req-199)

Manifesto por camada, registro de choques, backup seletivo, rollback, exclusão declarativa de dados e diff/merge dos choques.

Critérios de aceite

1. Dois project:update-all do mesmo projeto: o segundo espera o primeiro e só então roda; com --no-wait, falha dizendo quem está com a trava.

2. Atualização do sistema e deploy por API com trava viva: recusam com mensagem clara; trava vencida é assumida e registrada.

3. --backup gera o backup e a atualização segue.

4. Duas migrações com a mesma versão: db:check-migrations falha e o pipeline não começa.

5. Depois da atualização do sistema, pelo CLI ou pelo web, db/ e o manifesto continuam lá.

6. Testes PHPUnit dos itens; homologação no Lab ([REDACTED]).