req-059: Refinamentos, Overrides de Projeto e Sincronização Inteligente de Contents (Pull System)

Este lote de trabalho (BATCH-059) visa implementar refinamentos críticos ao Pull System (introduzido no BATCH-058), incluindo a renomeação clara do script servidor para evitar colisões, o suporte à configuração de escopos em nível de projeto (permitindo sincronizar recursos de módulos sem modificar os manifestos originais no Core) e a sincronização inteligente de arquivos da pasta contents/ com comparação de hashes MD5, timestamps e relatórios de conflito.

1. Modificações no Servidor (API e Renomeação)

1.1 Renomeação de Controlador

• Ação: Renomear gestor/controladores/recuperacoes/recuperacao-dados-recursos.php para gestor/controladores/recuperacoes/recuperacao-banco-de-dados.php.

• Justificativa: Clareza semântica (reverso de atualizacoes-banco-de-dados.php) e desambiguação em relação ao descompilador de recursos do cliente.

1.2 Endpoint de Recuperação (_api/project/recover) em gestor/controladores/api/api.php

• Requisito: Ler o parâmetro recover_contents a partir do corpo JSON ou parâmetro POST (boolean).

• Ação: Se recover_contents for verdadeiro, ler recursivamente o diretório de uploads do gestor (gestor/contents/) e adicionar todos os seus arquivos ao ZIP de resposta sob o caminho contents/... (mantendo a estrutura interna de subpastas do diretório original e preservando os timestamps dos arquivos).

2. Modificações no Compilador e Descompilador Cliente

2.1 Suporte a Overrides no tables_config.json

Modificar o compilador (gestor/controladores/agents/arquitetura/atualizacao-dados-recursos.php -> normalizarConfigTabela() / coletarConfigsTabelas()) e o descompilador (gestor/controladores/agents/arquitetura/recuperacao-dados-recursos.php -> rdr_normalizar_config()):

• Interpretar os campos "scope" e "modulo" declarados dentro do bloco "config" das tabelas no tables_config.json.

• Se "scope": "module" e "modulo": "nome_modulo" estiverem presentes:

  • Definir o escopo como module e o modulo correspondente.

  • Ajustar dinamicamente o diretório base (base_dir) para gestor/modulos/nome_modulo/resources em vez de usar o diretório de recursos globais do gestor.

  • Isso permite que projetos configurem regras de sincronização para tabelas do Core (como menus ou publisher_highlights) sem alterar seus manifestos JSON.

2.2 Sincronização Inteligente e Detecção de Conflitos em contents/

Modificar o descompilador (gestor/controladores/agents/arquitetura/recuperacao-dados-recursos.php):

• Se a pasta contents/ for encontrada na pasta de extração temporária:

  • Varre-se cada arquivo remotamente extraído e compara-se com o correspondente local em gestor/contents/.

  • Lógica de Cópia:

    1. Se o arquivo local existe, calcular e comparar o MD5 de ambos (md5_file). Se forem idênticos, pular a cópia (evita ruído/redescrever o arquivo).

    2. Se os MD5 forem diferentes:

       • Comparar os timestamps: copiar/sobrescrever local apenas se o remoto for estritamente mais novo (remote_mtime > local_mtime).

       • Se o local for mais novo ou tiver o mesmo timestamp, pular a cópia.

       • Log de Conflitos: Sempre que a cópia for pulada devido ao MD5 ser diferente mas o local ser mais novo ou igual (indicando choque de alterações), registrar um aviso no padrão RDR_CONFLITO arquivo=<caminho> (local mais recente, remoto diferente; pulado) e acumular o arquivo em uma lista interna de conflitos.

    3. Se o arquivo foi copiado com sucesso, aplicar touch($caminhoLocal, $remoteMtime) para sincronizar e preservar a data do servidor localmente.

  • Relatório de Conflitos: No final da descompilação, exibir um sumário resumido dos conflitos detectados: RDR_CONFLITOS total=<count>, listando os caminhos que demandam atenção/mesclagem manual.

3. Scripts de Controle e VS Code Tasks

3.1 Script de Pull (recover-project.sh)

• Modificar ai-workspace/en/scripts/projects/recover-project.sh:

  • Aceitar a opção --contents ou -c.

  • Passar "recover_contents": true no corpo JSON enviado no POST da API.

3.2 VS Code Tasks (tasks.json)

• Modificar .vscode/tasks.json adicionando uma nova tarefa:

  • ?️ Projects - Recover Current Project with Contents: executa ./ai-workspace/en/scripts/projects/recover-project.sh --contents.

4. Validação e Testes

1. Testes Estáticos:

   • Validar sintaxe de todos os arquivos modificados usando php -l.

2. Suíte de Testes Unitários:

   • Atualizar a suíte de testes unitários RecuperacaoDadosRecursosTest.php cobrindo a lógica de overrides de scope e modulo vindos do tables_config.json e cobrindo os cenários de sincronização inteligente de contents/ (mesmo MD5, MD5 diferente com remote mais novo, MD5 diferente com local mais novo/choque com relatório de conflito, e preservação de data).

3. Validação Manual:

   • Configurar o override de menus em tables_config.json.

   • Modificar dados locais e no servidor, executar o pull com --contents e confirmar que o relatório de conflitos aponta o choque de arquivos corretamente sem sobrescrever as alterações locais mais recentes.