Requisição 198 — Atualização segura, fase 2: manifesto por camada, choques, backup seletivo e rollback

Origem: Humano, 2026-09-30: promoção do BL-028, propostas A, B.1 e D, conforme o parecer do Arquiteto. Lotes Vinculados: BATCH-202 (manifesto, precedência e choques), BATCH-203 (backup seletivo, health check e rollback) e BATCH-204 (o mesmo no deploy por API e c2f update:rollback). Status: implementada (BATCH-202, BATCH-203 e BATCH-204 complete, 2026-09-30); homologação humana pendente. Repositório: [REDACTED].

Contexto

Os dois riscos altos do BL-028 são estes:

• Sobreposição apagada em silêncio. O projeto sobrepõe um arquivo do core, e a atualização do sistema o sobrescreve sem aviso.

• Atualização sem volta. Não há backup do que muda nem rollback.

O princípio do Humano vale aqui: o core é canibalizável. Os choques são normais; o sistema precisa prevê-los, registrá-los e tratá-los.

Itens — BATCH-202

1. Manifesto por camada (BL-028 A):

   • cada entrega (core, cada plugin, projeto) grava caminho → hash do que entregou, em installation/manifests/<camada>.json, fora de db/;

   • generaliza o manifesto de migrações da req-194;

   • classifica cada arquivo como intacto, sobreposto, editado localmente ou retirado.

2. Precedência projeto > plugin > core no disco (BL-028 B.1):

   • a atualização do core não sobrescreve arquivo sobreposto;

   • guarda a versão nova em backups/overrides/<versão>/<caminho> e registra o choque, com o diff.

3. Registro de choques:

   • tabela atualizacoes_choques: camada, caminho, tipo (arquivo, tabela, migração, hook), versões, hashes, resolução e execução;

   • aba em admin-atualizacoes;

   • o deploy por API e o pipeline devolvem os choques na resposta.

4. Arquivos retirados:

   • o que a mesma camada entregou antes e não entrega mais sai do servidor;

   • só sai se estiver intacto; se foi editado localmente ou sobreposto, vira choque.

Itens — BATCH-203

1. Backup seletivo antes de aplicar (BL-028 D):

   • snapshot só dos arquivos que vão ser sobrescritos ou removidos (lista vinda do manifesto);

   • dump das tabelas que as migrações e o sync vão tocar;

   • tudo ligado ao id da execução.

2. Health check depois: rotas-chave com HTTP 200, sem fatal novo no log, migrações sem pendência.

3. Rollback:

   • automático dos arquivos quando o health check falha;

   • o banco volta pelo dump: automático quando só houve migrações da própria execução, com confirmação do operador quando houve escrita de usuários no meio;

   • comando c2f update:rollback <execução>;

   • retenção de N execuções.

Itens — BATCH-204

Acréscimo do Humano em 2026-09-30: "inclui aí também na API que você está fazendo um update, o deploy e todas as outras coisas".

1. Deploy por API com o mesmo pacote da atualização do sistema: snapshot seletivo dos arquivos antes de aplicar, dump do banco antes da etapa de banco, verificação depois (fatal novo no log e HTTP) e volta automática dos arquivos quando ela falha; a resposta traz o id do snapshot e o resultado.

2. Rollback pela API: endpoint que volta uma execução pelo snapshot, com o banco opcional.

3. c2f update:rollback <projeto> <execução> [--com-banco]: chama o rollback pela API (ou pelo [REDACTED] Lab), como previsto no item 2 do BATCH-203.

Critérios de aceite

1. Um projeto sobrepõe um arquivo do core, e o core é atualizado: a sobreposição continua valendo, e o choque aparece no painel com o diff da versão nova.

2. Um arquivo retirado de uma camada sai do servidor; se estava editado, vira choque.

3. Uma atualização que quebra o site volta sozinha ao estado anterior, com relatório.

4. Testes PHPUnit; homologação no Lab.