req-060: Pipeline de Metadados de Projeto e Desacoplamento de Configuração (project-schema-metadata.json)

Este lote de trabalho (BATCH-060) visa refinar a arquitetura do Pull System (BATCH-058/BATCH-059). Em ambiente de execução/produção (servidor), as pastas resources/, db/ e os subdiretórios resources dos módulos não existem (pois todos os recursos rodam diretamente do banco de dados). Sendo assim, o servidor não possui acesso ao arquivo tables_config.json local.

Para resolver este desacoplamento, implementaremos o arquivo transitório project-schema-metadata.json, que atua como a especificação de projeto compilada enviada ao servidor para guiar o dump de banco de dados.

1. Modificações no Ambiente de Projeto (Compilação e Deploy)

1.1 Geração de project-schema-metadata.json no Compilador

No script do compilador de recursos (gestor/controladores/agents/arquitetura/atualizacao-dados-recursos.php -> gerarSchemaMetadata()):

• Se o arquivo de configurações de tabelas do projeto gestor/resources/tables_config.json existir:

  • Ler e processar o arquivo.

  • Gerar um arquivo consolidado chamado project-schema-metadata.json e gravá-lo na raiz da pasta gestor/ (no mesmo nível da pasta db/, ou seja, dois níveis acima da pasta db/data/).

  • O formato do project-schema-metadata.json deve ser um JSON limpo contendo o mapa de tabelas normalizadas configuradas pelo projeto. Exemplo:

    {
    "tabelas": {
        "menus": { ... },
        "publisher_highlights": { ... }
    }
    }

1.2 Inclusão no Deploy (deploy-project-v2.sh)

No script de deploy (ai-workspace/en/scripts/projects/deploy-project-v2.sh):

• Garantir que o arquivo gestor/project-schema-metadata.json, caso exista no workspace local, seja empacotado no ZIP de deploy na raiz da pasta gestor/ (ao lado de db/ e controladores/).

• Ao descompactar o pacote ZIP no servidor, o arquivo project-schema-metadata.json será instalado fisicamente na raiz do gestor do servidor de execução.

2. Modificações no Ambiente de Execução (Servidor)

2.1 Leitura do Manifesto no Endpoint de Recuperação (api.php)

No endpoint da API api_project_recover() em gestor/controladores/api/api.php:

• Buscar pelo arquivo project-schema-metadata.json na raiz do gestor/ ($_GESTOR['ROOT_PATH'] . 'project-schema-metadata.json').

• Se o arquivo existir:

  • Ler o JSON e extrair a lista de tabelas declaradas sob a chave "tabelas".

  • Se a lista de tabelas solicitada pelo cliente for vazia/omitida, mesclar as tabelas do project-schema-metadata.json com as tabelas padrão extraídas do schema-metadata.json.

  • Isso garante que a API consiga exportar as tabelas customizadas do projeto mesmo sem as pastas de resources em disco no servidor.

2.2 Leitura do Manifesto no CLI do Servidor (recuperacao-banco-de-dados.php)

No script CLI de dump do servidor (gestor/controladores/recuperacoes/recuperacao-banco-de-dados.php):

• Implementar a mesma busca por gestor/project-schema-metadata.json.

• Se encontrado, ler as tabelas configuradas no arquivo de projeto para determinar quais tabelas exportar via reverseExport().

3. Descompilação Cliente e Documentação

3.1 Descompilação Local (recuperacao-dados-recursos.php)

• O descompilador executado localmente no repositório continuará usando o arquivo local gestor/resources/tables_config.json (que existe na base de código do projeto) para mapear o escopo, módulo, campos de arquivos e tipos de dados, escrevendo os arquivos e metadados nos destinos locais corretos.

3.2 Atualização da Documentação Técnica

Atualizar o arquivo de documentação em português:

• Arquivo: ai-workspace/pt-br/docs/CONN2FLOW-SISTEMA-RECURSOS.md

• Conteúdo:

  • Explicar o funcionamento e a necessidade do arquivo project-schema-metadata.json para carregar as configurações de tabelas de projeto ao ambiente de produção (servidor).

  • Incluir exemplos práticos de como configurar o tables_config.json para:

  • Recursos de Módulos (com "scope": "module" e "modulo" direcionando para a pasta de módulos).

  • Recursos Globais (sem módulo, salvando na pasta resources global).

  • Tabelas exclusivamente de banco de dados (como arquivos, definindo "sync_resources": false).

  • Documentar a mesma explicação e exemplos no arquivo correspondente em inglês, caso exista.