req-058: Sistema de Recuperação e Engenharia Reversa de Recursos (Pull System)

Este lote de trabalho (BATCH-058) visa implementar a via inversa de sincronização de recursos (Pull System) no Conn2Flow. Permite que um desenvolvedor extraia os dados mais recentes do banco de dados de um projeto (ambiente de teste, homologação ou produção) e os converta automaticamente em arquivos locais do repositório (HTML, CSS, MD e metadados JSON), garantindo que as alterações feitas no banco via painel administrativo possam ser reintegradas ao Git de forma automatizada.

O fluxo é dividido em duas partes:

1. Servidor (API & Dump): Um endpoint na API que extrai os dados estruturados do banco de dados em arquivos JSON brutos e os disponibiliza como um pacote ZIP.

2. Cliente (Decompilador): Um script que roda localmente no repositório, lê os JSONs extraídos, e decompõe os campos de arquivos físicos (como HTML e CSS) e metadados de volta para a estrutura de pastas e manifestos JSON do projeto.

1. Modificações no Servidor (API)

1.1 Endpoint de Recuperação (_api/project/recover)

No arquivo gestor/controladores/api/api.php:

• Adicionar o sub-endpoint recover ao switch-case de projetos em api_handle_project() (ficando acessível via /_api/project/recover).

• Criar a função api_project_recover() com os seguintes requisitos:

  • Validar a chamada via api_authenticate(true) (requer OAuth válido).

  • Obter o ID do projeto do header X-Project-ID se fornecido (para contexto futuro).

  • Verificar se o método da requisição é POST.

  • Ler as tabelas a serem exportadas a partir do corpo JSON ({"tables": [...]}) ou parâmetro POST tables (lista separada por vírgulas). Se omitido ou vazio, ler todas as tabelas ativas registradas em gestor/db/data/schema-metadata.json.

  • Criar um diretório temporário único em logs/temp_recover_[time]_[uniqid]/.

  • Definir a constante SDD_NO_AUTORUN como true e incluir o script de atualizações de banco (gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php).

  • Estabelecer uma conexão PDO com o banco de dados do gestor (utilizando as credenciais de $GLOBALS['_BANCO']).

  • Invocar a função reverseExport($pdo, $tabelas, $temp_dir) para extrair o dump das tabelas selecionadas em arquivos *Data.json brutos no diretório temporário.

  • Compactar todos os arquivos JSON gerados dentro do diretório temporário em um arquivo ZIP temporário usando ZipArchive.

  • Retornar o ZIP como stream de download para o cliente definindo os cabeçalhos apropriados:

  • Content-Type: application/zip

  • Content-Disposition: attachment; filename="project-recover.zip"

  • Content-Length: [tamanho_do_zip]

  • Enviar o arquivo e limpar imediatamente as pastas e arquivos temporários criados em disco.

1.2 Novo Controlador de Recuperação

No arquivo gestor/controladores/recuperacoes/recuperacao-dados-recursos.php:

• Criar este arquivo no servidor para servir como ponto de entrada CLI alternativo de exportação de dados locais no servidor (caso necessário executar diretamente em ambiente do servidor).

• Ele deve inicializar o escopo do banco e executar a exportação de dados brutos de forma similar ao endpoint da API.

2. Modificações no Cliente (Descompilador de Recursos)

2.1 Descompilador Genérico (recuperacao-dados-recursos.php)

Criar o arquivo gestor/controladores/agents/arquitetura/recuperacao-dados-recursos.php para atuar localmente no repositório. O script deve realizar os seguintes passos:

1. Parâmetros CLI:

   • Aceitar o argumento --source-dir especificando a pasta local onde o ZIP do dump da API foi extraído (contendo os arquivos <PascalCase>Data.json).

2. Resolução de Configurações:

   • Carregar e varrer a configuração global gestor/resources/tables_config.json e todos os arquivos de configuração de módulos gestor/modulos/[modulo]/[modulo].json.

   • Mapear a estrutura de tabelas que possuem configuração registrada, localizando as seguintes diretivas: sync_resources, resources_dir (padrão igual ao nome da tabela), metadata_file, field_types, e a chave de identificação natural.

3. Descompilação: Para cada arquivo [NomeTabelaPascalCase]Data.json encontrado na pasta de origem:

   • Carregar os registros estruturados do arquivo JSON.

   • Para cada registro:

     • Resolver o ID único (PK ou chave natural) e o idioma (language ou linguagem_codigo).

     • Extração de Arquivos Físicos (file:ext): Para cada campo configurado em "field_types" com a diretiva "file:ext" (ex: "html": "file:html", "css": "file:css"):

     • Extrair o conteúdo textual do campo.

     • Escrever o arquivo físico correspondente no caminho de destino (Global: gestor/resources/[lang]/[resources_dir]/[id]/[id].[ext] / Módulo: gestor/modulos/[modulo]/resources/[lang]/[resources_dir]/[id]/[id].[ext]).

     • Remover a respectiva chave e valor do registro de metadados.

     • Tratamento de JSON: Se um campo estiver mapeado como "json" e seu valor no banco for uma string de dados JSON, decodificá-lo de volta em array/objeto PHP para gravação limpa.

     • Saneamento de Colunas: Remover colunas exclusivas de banco de dados (versao, checksum, user_modified, project, auto-increment PKs) para manter os arquivos de metadados do repositório livres de dados gerados dinamicamente no build.

     • Acumular o registro tratado na lista de metadados correspondente à tabela e idioma.

4. Escrita de Metadados:

   • Para cada tabela e idioma processado:

     • Caso metadata_file esteja configurado (ex: "highlights.json"):

     • Gravar a lista JSON de metadados em gestor/resources/[lang]/[metadata_file] ou gestor/modulos/[modulo]/resources/[lang]/[resources_dir]/[metadata_file].

     • Caso metadata_file seja nulo/omitido (inline):

     • Carregar o arquivo JSON raiz correspondente (tables_config.json ou [modulo].json).

     • Atualizar a chave "resources" -> "[lang]" -> "[tabela_nome]" com o array de metadados.

     • Gravar o arquivo de configuração de volta ao disco com formatação legível.

3. Modificações nos Scripts e VS Code Tasks

3.1 Script de Pull (recover-project.sh)

Criar o script ai-workspace/en/scripts/projects/recover-project.sh no repositório:

• Ler o arquivo dev-environment/data/environment.json para carregar a URL da API e o token OAuth do projeto especificado via parâmetro (ou do projectTarget padrão).

• Executar um POST curl autenticado ao endpoint _api/project/recover.

• Fazer o download do ZIP de resposta e extraí-lo em uma pasta temporária temp/recover_extract/.

• Chamar o script de descompilação local:

  php gestor/controladores/agents/arquitetura/recuperacao-dados-recursos.php --source-dir=temp/recover_extract/

• Em seguida, rodar localmente o compilador de recursos para regenerar as versões locais de *Data.json e garantir a consistência total dos arquivos:

  php gestor/controladores/agents/arquitetura/atualizacao-dados-recursos.php

• Excluir o diretório temporário de extração.

3.2 VS Code Tasks (tasks.json)

No arquivo .vscode/tasks.json, adicionar as seguintes tarefas:

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

• ?️ Projects - Recover Project -> ID: executa o script ./ai-workspace/en/scripts/projects/recover-project.sh --project ${input:projectID}.

4. Validação e Testes

1. Testes Estáticos:

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

2. Suíte de Testes Unitários:

   • Desenvolver testes unitários para a rotina de descompilação (em tests/Unit/PHP/) cobrindo cenários de extração de arquivos físicos, parsing de campos JSON e escrita inline/externa de metadados.

3. Validação Manual:

   • Fazer modificações no banco de dados local.

   • Rodar a tarefa de recuperação no VS Code.

   • Verificar no Git se as alterações foram corretamente trazidas para os arquivos de recursos globais e de módulos.