Requisição 174 — Sincronização Automática da Tabela `hooks` no Pipeline de Deploy de Projeto (`project:update-all`)

Origem: Achado BL-015 (relatado durante o BATCH-046 do conn2flow-site, onde o hook de confirmação de pagamento de assinaturas não foi registrado após deploy bem-sucedido no Lab). Lote Vinculado: BATCH-179. Status: ready-for-intake.

1. Diagnóstico e Causa-Raiz

Ao adicionar ou atualizar um hook em um módulo pertencente a um projeto (ex: modulos/host-manager/host-manager.json ou project/hooks/hooks.json) e executar o pipeline de atualização:

./c2f project:update-all <projeto-id>

ou

./c2f project:sync-db <projeto-id>

O pipeline executa as 8 etapas com status SUCCESS. Contudo, a tabela hooks no banco de dados do ambiente de destino não recebe o hook novo ou alterado.

Causa-Raiz

A função responsável por escanear os módulos/projeto e gravar na tabela hooks (atualizacoes_hooks_sincronizar() em gestor/controladores/atualizacoes/atualizacoes-hooks.php) é invocada exclusivamente em:

1. atualizacoes-sistema.php (hookAfterAll()), chamado apenas no deploy de núcleo do sistema (./c2f manager:update-all).

2. controladores/api/api.php (linha 353), no upload de arquivos de módulos via API REST.

O pipeline de projeto (project:update-all e project:sync-db) aciona updates-manager-database.sh, que executa unicamente gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php. Esse controlador sincroniza migrações Phinx e dados das tabelas cadastradas em gestor/db/data/, mas nunca executa a rotina de sincronização da tabela hooks.

O problema ocorre de forma idêntica em todos os modos de deploy do projeto: ssh, host e docker. No ambiente remoto SSH o efeito é ainda mais crítico porque o servidor não recebe deploys de núcleo locais (manager:update-all), tornando indispensável a intervenção manual para que hooks de projetos funcionem.

2. Escopo Normativo

2.1 Integração de Hooks em atualizacoes-banco-de-dados.php

1. Em gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php:

   • Carregar o controlador gestor/controladores/atualizacoes/atualizacoes-hooks.php e a biblioteca gestor/bibliotecas/hooks.php.

   • Após o processamento das migrações Phinx e das tabelas de dados (ou na etapa de encerramento do processo de banco), executar atualizacoes_hooks_sincronizar().

   • Garantir que a execução ocorra tanto no fluxo do sistema quanto no fluxo com parâmetro --project (deploy de projeto).

   • Incluir no resumo emitido em tela e no log (relatorioFinal) a quantidade de hooks sincronizados/processados, dando visibilidade imediata ao operador sobre o estado dos hooks.

2.2 CLI de Projeto (project:sync-hooks)

1. No CLI do framework:

   • Adicionar o comando c2f project:sync-hooks <projeto-id> (ou torná-lo subcomando de project) para permitir a sincronização direcionada e pontual da tabela hooks em projetos locais e remotos SSH, sem exigir a execução completa de todas as tabelas de banco.

2.3 Resiliência e Idempotência

1. A rotina deve ser estritamente idempotente (re-execuções sucessivas não devem duplicar registros na tabela hooks ou gerar efeitos colaterais).

2. Devem ser respeitados os modos ssh, host e docker do transporte de projetos, utilizando os mesmos padrões de elevação de privilégios (sudo -u <tenant> sh -c) consolidados nos lotes BATCH-172 e BATCH-173.

3. Critérios de Aceite e Validação

1. Deploy de Projeto Atualiza Hooks Automaticamente:

   • Um hook adicionado ao JSON de um módulo de projeto passa a constar na tabela hooks após uma única execução de ./c2f project:update-all <projeto-id> ou ./c2f project:sync-db <projeto-id>.

2. Remoção de Hooks Refletida:

   • Um hook removido do JSON de um módulo é devidamente desativado ou expurgado da tabela hooks.

3. Visibilidade no Relatório do Pipeline:

   • A saída do terminal do estágio de banco de dados exibe o status da sincronização de hooks.

4. Comando Dedicado de Hooks:

   • O comando ./c2f project:sync-hooks <projeto-id> executa a sincronização de hooks com sucesso e relatório claro.

5. Testes Automatizados:

   • Teste unitário no PHPUnit cobrindo a execução da sincronização de hooks integrada ao fluxo de banco de dados do projeto.

   • Suíte de testes (PHPUnit e Vitest) 100% verde com exit 0.