req-056: Sincronização Declarativa de Recursos, Deleção e Atualização Forçada (Módulos e Globais)

Este lote de trabalho (BATCH-056) visa generalizar e automatizar a esteira de sincronização de recursos do Conn2Flow. Permite que qualquer tabela (de módulo ou global) possa declarar regras de sincronização, conversões especiais de dados (JSON e leitura de arquivos físicos), exclusões (deletar) e redefinição/sobrescrita de personalizações (forcar_atualizacao) de forma puramente declarativa no manifesto JSON correspondente, sem necessidade de desenvolver scripts PHP de hook repetitivos.

Adicionalmente, este lote inclui a sincronização da documentação técnica correspondente em português e inglês.

1. Modificações no Compilador de Recursos (atualizacao-dados-recursos.php)

No arquivo gestor/controladores/agents/arquitetura/atualizacao-dados-recursos.php:

1.1 Processamento Unificado de Configurações (gerarSchemaMetadata e normalizarConfigTabela)

• Atualizar a função normalizarConfigTabela() e o fluxo de processamento do contrato em gerarSchemaMetadata() para suportar que a chave "config" sob "tabela" (em manifestos de módulos [modulo].json) ou sob as chaves de "tabelas" (no arquivo global gestor/resources/tables_config.json) seja tanto um objeto associativo único quanto um array de objetos.

• Se for um objeto único, convertê-lo internamente em um array de 1 elemento para manter a consistência do fluxo.

• Consolidar as chaves "deletar" e "forcar_atualizacao" configuradas para cada tabela, registrando-as de forma agregada por tabela no contrato consolidado schema-metadata.json.

1.2 Varredura e Coleta Dinâmica de Tabelas (coletarRecursos)

Implementar na coleta de recursos a busca de tabelas genéricas configuradas em módulos ou no global que possuem "sync_resources": true:

1. Varredura de Configurações:

   • Iterar pelas tabelas e configurações registradas em tables_config.json e nos manifestos de módulos [modulo].json.

   • Se a propriedade "sync_resources" estiver ativa (true) para uma dada configuração:

     • Resolver o nome da tabela (tabela_nome ou o padrão do escopo).

     • Resolver a subpasta de recursos (resources_dir ou o padrão igual ao nome da tabela).

     • Para cada idioma configurado (pt-br, en, etc.):

     • Se for global:

       • Se metadata_file estiver definido: ler a lista de registros do arquivo JSON externo localizado em gestor/resources/[lang]/[metadata_file] (ou gestor/resources/[lang]/[resources_dir]/[metadata_file] se resources_dir estiver explicitamente definido).

       • Se metadata_file for nulo/omitido: ler os registros inline em gestor/resources/tables_config.json sob a chave "resources" -> "[lang]" -> "[tabela_nome]".

     • Se for módulo:

       • Se metadata_file estiver definido: ler a lista de registros do arquivo JSON externo localizado em gestor/modulos/[modulo]/resources/[lang]/[resources_dir]/[metadata_file].

       • Se metadata_file for nulo/omitido: ler os registros inline em [modulo].json sob a chave "resources" -> "[lang]" -> "[tabela_nome]".

2. Processamento e Conversão de Campos: Para cada registro localizado na varredura:

   • Processar os campos configurados em "field_types":

     • Se o tipo for "json" e o valor for um array/objeto, aplicar json_encode com formatação adequada.

     • Se o tipo for "file:ext" (ex: "file:html", "file:css"), buscar o arquivo físico [id].[ext] na pasta de recursos correspondente (global ou módulo) e injetar seu conteúdo como string purificada (sem BOM UTF-8) no campo especificado.

   • Resolver e preencher as colunas padronizadas (status = 'A', versao, user_modified).

3. Cálculo de Checksum e Incremento de Versão:

   • Calcular o checksum MD5 do registro baseado no payload do registro (ou nos campos mapeados como "file:*").

   • Se o checksum do novo registro coincidir com o do registro existente nos dados estáticos anteriores, manter a versão anterior (versao). Caso mude, incrementar a versão.

4. Acúmulo de Dados:

   • Adicionar os registros processados ao agrupamento dinâmico de tabelas (ex: $recursos['dynamicTablesData'][$tabela][]).

1.3 Persistência de Dados Dinâmicos (atualizarDados)

• Na função atualizarDados(), iterar sobre a lista acumulada de tabelas dinâmicas em dynamicTablesData.

• Gerar dinamicamente o arquivo serializado [TabelaNomePascalCase]Data.json na pasta de destino (gestor/db/data/), utilizando o utilitário dataFileNameFromTable($tabela) para obter a nomenclatura correta (ex: UsuariosPerfisModulosData.json para a tabela usuarios_perfis_modulos).

2. Modificações nas Configurações Globais (tables_config.json)

No arquivo gestor/resources/tables_config.json:

• Permitir que a chave "config" sob cada tabela do dicionário "tabelas" possa receber um array de objetos para suportar múltiplas tabelas.

• Suportar a inclusão declarativa dos novos parâmetros de sincronização (sync_resources, resources_dir, metadata_file, field_types, deletar e forcar_atualizacao) no bloco de configuração de tabelas globais.

3. Modificações no Atualizador de Banco (atualizacoes-banco-de-dados.php)

No arquivo gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php:

3.1 Sobrescrita por Atualização Forçada (forcar_atualizacao)

No fluxo de processamento de registros de tabelas no método sincronizarTabela():

1. Carregar Alvos de Atualização Forçada:

   • Carregar a lista de registros configurados sob "forcar_atualizacao" a partir do contrato consolidado schema-metadata.json para a respectiva tabela.

2. Ignorar Proteções de Projeto e Modificação do Usuário:

   • Ao iterar e comparar os registros do banco de dados, verificar se o registro atual coincide com alguma das regras da lista "forcar_atualizacao" (comparando via PK ou por colunas da chave natural conforme estratégia).

   • Se coincidir:

     • Bypass de Projeto: Ignorar a verificação de projeto (!$project && !empty($exist['project'])). O registro do deploy do núcleo/sistema deve ser atualizado normalmente.

     • Bypass de user_modified: Ignorar a verificação user_modified (não preservar os campos originais do banco). O registro deve ser atualizado com todo o payload do arquivo JSON de dados.

     • Reset de user_modified: Se o registro no banco possuir user_modified = 1, forçar a alteração de user_modified de volta para 0 no banco ($diff['user_modified'] = 0), sinalizando o alinhamento com a base de código do deploy.

     • Preservar o campo project conforme configurado (sem alterá-lo ou limpá-lo).

4. Modificações na Documentação

Atualizar os arquivos de documentação técnica do sistema para incluir as novas capacidades de sincronização por tabelas de módulos e globais, metadados inline/externos, exclusões e atualização forçada:

4.1 Documentação de Recursos

Arquivos:

• CONN2FLOW-SISTEMA-RECURSOS.md

• CONN2FLOW-RESOURCES-SYSTEM.md

• Detalhar as novas capacidades de sincronização declarativa para qualquer tabela (módulos e globais).

• Explicar o mapeamento da subpasta resources/ e as diretivas de conversão (field_types para json e file:ext).

4.2 Documentação de Atualizações do Sistema

Arquivos:

• CONN2FLOW-ATUALIZACOES-SISTEMA.md

• CONN2FLOW-SYSTEM-UPDATES.md

• Atualizar a seção que explica a sincronização de banco de dados para documentar o comportamento de deletar e forcar_atualizacao usando as chaves de identificação natural/PK.

• Explicar como as proteções de user_modified e project são ignoradas e redefinidas na atualização forçada.

4.3 Documentação Detalhada de Módulos

Arquivos:

• CONN2FLOW-MODULOS-DETALHADO.md

• CONN2FLOW-MODULES-DETAILED.md

• Adicionar no detalhamento da estrutura do manifesto [modulo].json as propriedades "config" de tabela como objeto/array e suas respectivas sub-propriedades de sincronização de recursos.

4.4 Visão Geral de Módulos

Arquivos:

• CONN2FLOW-MODULOS-OVERVIEW.md

• CONN2FLOW-MODULES-OVERVIEW.md

• Atualizar a visão geral da estrutura física e lógica de módulos para incluir a capacidade de acoplar tabelas customizadas na esteira de dados.

4.5 Documentação de Multilinguagem Híbrida

Arquivos:

• CONN2FLOW-SISTEMA-MULTILÍNGUE-HIBRIDO.md

• CONN2FLOW-MULTILINGUAL-HYBRID-SYSTEM.md

• Explicar como a resolução de idiomas do metadados externos (pasta resources/[lang]/) e metadados inline (chave resources -> [lang]) é feita de forma unificada no gerador para tabelas genéricas de módulos e globais.

4.6 Documentação de Proteção do Banco

Arquivos:

• CONN2FLOW-PROTECAO-BANCO-PROJETOS.md

• CONN2FLOW-PROJECT-DATABASE-PROTECTION.md

• Atualizar as regras de proteção para documentar a exceção/bypass inserido via mecanismo de atualização forçada (forcar_atualizacao), detalhando como o flag user_modified é redefinido para 0 no banco e como registros marcados por projeto são sincronizados novamente.

5. Validação e Testes

1. Testes Estáticos / Sintaxe:

   • Rodar verificações estáticas de PHP para validar a integridade dos arquivos modificados:

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

     • php -l gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php

2. Suíte de Testes Automatizados:

   • Executar os testes unitários e de integração do core para garantir que não existem regressões no fluxo original de sincronização de tabelas e resoluções de chave natural:

     • composer test

3. Validação Manual:

   • Configurar uma tabela global e uma tabela de módulo de teste contendo registros no forcar_atualizacao.

   • Modificar manualmente um registro no banco de dados e marcar user_modified = 1.

   • Executar a compilação de recursos e a sincronização do banco de dados, confirmando que os dados físicos foram reintegrados e o flag user_modified retornou a 0 no banco.