Requisição 131 — Deploy Local de Projeto Não Repassa a Identidade do Projeto ao Atualizador de Banco

• Status do intake: ready-for-intake

• Data: 2026-08-25

• Origem: relato do operador durante a homologação do projeto [REDACTED]-local — alterações de HTML/CSS de páginas de projeto paravam no Data.json e nunca chegavam ao banco, sem nenhuma mensagem de erro. O contorno usado (--force-all) foi recusado pelo operador por não ser seguro para páginas editadas pelo usuário em produção.

• Classificação: bugfix, deploy, sincronizacao, projetos, protecao-de-dados

• Batch candidato: BATCH-133

1. Problema

O deploy local de um projeto (updates-manager-database.sh --project <ID>, usado pelas tarefas ?️ Projects - Synchronize => Database -> ID e ?️ Projects - Update => Core) não atualiza recursos cujo registro no banco já tenha a coluna project preenchida.

O sintoma é silencioso: a alteração é compilada para o Data.json, o relatório conta a linha como "sem alteração" e a rotina termina com sucesso. Nada indica que o recurso ficou para trás.

1.1. Causa-raiz

sincronizarTabela() (em gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php) separa dois fluxos a partir de CLI_OPTS['project']:

$project = $GLOBALS['CLI_OPTS']['project'] ?? null;
...
if ($temPreserve && !$forced) {
    if (!$project && !empty($exist['project'])) {         // atualização normal sobre recurso de projeto
        if (empty($exist['user_modified']) || (int)$exist['user_modified'] !== 1) {
            $same++; continue;                            // pula: proteção de projeto
        }
    }
}

É a regra descrita em ai-workspace/en/docs/CONN2FLOW-PROJECT-DATABASE-PROTECTION.md:

• Deploy com --project: sobrescreve o recurso e o marca com o id do projeto;

• Atualização normal: respeita a marcação e não toca em recurso de projeto.

A regra está correta. O defeito está em quem a alimenta: o ai-workspace/en/scripts/dev-environment/updates-manager-database.sh recebe --project (e o usa para resolver o dockerPath), mas monta os argumentos do PHP apenas com:

PHP_ARGS="--debug --log-diff"

Sem --project, CLI_OPTS['project'] fica nulo e o deploy do projeto é tratado como atualização normal — bloqueado pela marcação que ele mesmo gravou.

1.2. Assimetria entre os dois deploys do mesmo projeto

O caminho remoto nunca teve o defeito: gestor/controladores/api/api.php monta $GLOBALS['CLI_OPTS']['project'] = $project_id a partir do cabeçalho X-Project-ID enviado pelo deploy-project-v2.sh. Publicar em produção sempre funcionou; sincronizar o mesmo projeto no ambiente local, não.

1.3. Por que --force-all não é a solução

--force-all apenas ignora o cache de checksums por tabela (manager_updates.db_checksum) e faz todas as tabelas entrarem no ciclo de comparação. Ele não desliga a proteção de projeto — então não resolve o problema — e, ao alargar o alcance da execução, não é o instrumento adequado para uma rotina rotineira de deploy.

O contorno declarativo (forcar_atualizacao no project_tables_config.json) resolve item a item, mas atravessa a proteção de user_modified e a reseta para 0: usá-lo como prática corrente colocaria em risco justamente as páginas que o cliente editou pela interface.

2. Requisitos

2.1. Repasse da identidade do projeto

updates-manager-database.sh deve repassar --project=<ID> ao atualizador quando, e somente quando, tiver recebido --project. Sem o parâmetro, a execução continua sendo uma atualização normal do núcleo e não pode marcar recurso algum como pertencente a projeto.

O valor deve ser validado antes de compor a linha de comando executada por docker exec, no mesmo critério já aplicado a --tables.

2.2. Garantias que não podem ser afetadas

1. Recurso editado pelo usuário (user_modified = 1) continua preservado, inclusive no deploy de projeto. Os campos listados em preserve_on_user_modified não são sobrescritos, e system_updated passa a 1 para sinalizar que existe versão nova do sistema.

2. A atualização normal do núcleo continua respeitando a marcação de projeto.

3. Só forcar_atualizacao, declarado item a item, atravessa as proteções.

3. Impacto nas tarefas do VS Code

4. Plano de Validação

1. Testes automatizados (PHPUnit): a regra nos dois modos (com e sem identidade de projeto), a preservação de user_modified sob deploy de projeto e o repasse no script.

2. Validação ponta a ponta no ambiente local: alterar o CSS de uma página de projeto marcada, rodar o deploy sem --force-all e confirmar que a alteração chega ao banco com project preservado e user_modified intacto.

3. Suíte completa do núcleo sem regressão.