Especificação de Requisitos: Reestruturação e Otimização de Dados, Sincronização e Visibilidade de Logs (req-029)

Esta especificação define o lote de trabalho req-029 (BATCH-029) para o Engenheiro Executor. O escopo abrange a reestruturação da sincronização de banco de dados do Conn2Flow, a migração de nomenclatura de colunas de idioma, a remoção de execução de subprocessos externos (exec/shell_exec) por motivos de segurança/hospedagem, e a injeção e centralização de logs do banco de dados na API, atualizações do sistema e plugins.

1. Migração de Colunas de Idioma (language)

Para fins de padronização internacional, todas as tabelas que utilizam o campo de idioma linguagem_codigo devem ser migradas para language:

• Ajuste de Migrações Existentes: Atualizar as migrações originais Phinx que criam as tabelas menus, galleries, publisher_highlights, publisher_index, prompts_ia, alvos_ia e modos_ia para renomear linguagem_codigo para language (ou instanciar diretamente como language).

• Nova Migração Corretiva [NEW]: Criar uma migração Phinx para renomear a coluna de linguagem_codigo para language nas tabelas existentes (utilizando $this->table()->renameColumn()), garantindo compatibilidade reversa se o banco já possuir as colunas antigas.

• Referências de Código: Atualizar em toda a aplicação (CRUDs administrativos, arquivos JavaScript, stubs de testes, widgets públicos) as referências a linguagem_codigo para language.

2. Metadados e Nova Estrutura de Tabelas (tables_config.json)

Para eliminar mapeamentos hardcoded em controladores, a configuração de sincronização será migrada para arquivos JSON:

• Configuração Local por Módulo: Nos JSONs dos módulos (ex: admin-paginas.json), adicionar um bloco "tabela" contendo regras de sincronização da tabela do módulo:

  • strategy: Estratégia de busca (pk ou natural_key).

  • natural_key_columns: Array contendo colunas da chave natural (ex: ['language', 'modulo', 'id']).

  • preserve_on_user_modified: Array de campos a preservar quando user_modified = 1 (ex: ['html', 'css']).

  • insert_only: Boolean indicando se o registro apenas aceita inserção e não atualizações (ex: usuarios).

• Configuração Global [NEW] tables_config.json: Criar este arquivo para centralizar os metadados de sincronização de tabelas globais (que não pertencem a módulos específicos), migrando as regras que antes estavam hardcoded (como tabelas de permissões, perfis, IA, etc.).

• Deleção Imperativa: Adicionar suporte a um bloco "deletar" nos JSONs locais de módulos e no arquivo global. Este bloco conterá registros antigos (identificados por PK ou chave natural) que devem ser apagados do banco durante o deploy.

3. Refatoração do Gerador (atualizacao-dados-recursos.php)

O script gerador de metadados será simplificado e unificado:

• Registry Pattern: Substituir os loops específicos por recurso por um motor de varredura genérico que lê as definições dos JSONs de módulos e o tables_config.json global.

• Geração de Contrato: Consolidar todas as regras de sincronização, registros de deleção e arquivos de dados em um único artefato consolidado: schema-metadata.json.

• Hooks de Dados (data-hooks.php): Implementar carregamento e execução dinâmica e sequencial de múltiplos scripts locais e globais nomeados data-hooks.php para tratamento de dados customizados pós-geração.

• Logs: Substituir silenciamentos cego @ por validações e padronizar escrita de logs via log_disco() da biblioteca oficial log.php.

4. Refatoração do Atualizador (atualizacoes-banco-de-dados.php)

O atualizador de banco de dados consumirá dinamicamente as definições geradas no contrato:

• Leitura Dinâmica: Carregar as regras de sincronização e loteamento de schema-metadata.json. Remover totalmente as variáveis globais hardcoded ($preserveMap, $tabelasChaveNatural, $tabelasInsertOnly).

• Loteador Dinâmico (Threshold-Based Batching): Obter o max_allowed_packet do MySQL dinamicamente e dividir os pacotes de inserts/updates em chunks menores quando ultrapassarem 70% do tamanho máximo do pacote MySQL. Adicionar um valor de fallback fixo de 16MB caso a query de leitura falhe ou retorne valor inválido.

• Deleção Física: Executar a exclusão lógica/física de registros especificados no bloco "deletar" do contrato.

• Transações e Logs: Envolver toda a sincronização em transações PDO (beginTransaction, commit, rollBack). Padronizar todas as chamadas de log para usar a biblioteca comum log.php.

5. Unificação e Visibilidade de Logs (Remoção de CLI Exec)

Para expor os logs nos três pontos consumidores (API, atualizações do sistema e plugins) e remover gargalos de segurança do servidor:

• Remoção de CLI Exec: Eliminar completamente todas as chamadas a subprocessos externos (ex: exec(), passthru(), shell_exec()) nos arquivos controladores atualizacoes-sistema.php, api.php e plugins-installer.php ao rodar atualizações de banco de dados. Todas as chamadas de banco (incluindo migrações Phinx) devem rodar estritamente inline (via require/include).

• Função log_unificado: Em atualizacoes-banco-de-dados.php e atualizacao-plugin-banco-de-dados.php, criar/refatorar a função:

  function log_unificado(string $msg, ?string $logFilename = null): void {
      global $LOG_FILE_DB, $GLOBALS;
      // Se há logger externo por referência, injetar
      if (isset($GLOBALS['EXTERNAL_LOGGER']) && is_array($GLOBALS['EXTERNAL_LOGGER'])) {
          $GLOBALS['EXTERNAL_LOGGER'][] = $msg;
      }
      $filename = $logFilename ?? $LOG_FILE_DB;
      log_disco($msg, $filename);
      // Se executado diretamente via terminal pelo desenvolvedor, imprimir no stdout
      if (PHP_SAPI === 'cli') {
          echo $msg . "\n";
      }
  }

  Substituir todas as ocorrências de log_disco e log_unificado antigas para usarem essa nova estrutura em ambos os scripts de atualização.

• Endpoint de Deploy da API (api.php):

  • No método api_executar_atualizacao_banco(), declarar localmente um array de logs e associar sua referência a $GLOBALS['EXTERNAL_LOGGER'].

  • O endpoint de upload do ZIP aceitará o parâmetro opcional full_log.

  • Retornar o log capturado na resposta JSON de sucesso (campo db_logs). Se full_log estiver ativo, retorna o log completo de debug. Caso contrário, envia apenas uma versão resumida (final report + warnings/errors).

• Atualização do Sistema (atualizacoes-sistema.php):

  • No método executarAtualizacaoBanco() (caminho inline), passar a referência do logger global.

  • Ler o array capturado e gravá-lo no log do sistema (logAtualizacao()), prefixando as mensagens com [BANCO].

• Atualização de Plugins (atualizacao-plugin-banco-de-dados.php):

  • Mesmo comportamento de centralização e encaminhamento ao $GLOBALS['EXTERNAL_LOGGER'] (que já é integrado no plugins-installer.php).

6. Critérios de Aceitação e Testes

• php -l em todos os arquivos modificados sem apresentar erros de compilação.

• Executar o gerador e certificar a criação correta de schema-metadata.json com os mapeamentos das tabelas migrados do hardcode antigo.

• Realizar um deploy de projeto via API e testar o parâmetro full_log, certificando que os logs detalhados do banco de dados aparecem corretamente estruturados na resposta JSON de retorno da requisição.

• Testar a execução inline da atualização de banco de dados e plugins, assegurando que não ocorram erros de transação ou chamadas de exec().