Human Request: Transição de Layout Hardcoded para Dinâmico via Widgets Envelopados e Highlights (req-003)

Contexto Geral

• O site parceiro encontra-se em fase de transição de um layout estático para dinâmico.

• A infraestrutura de deploy do Conn2Flow copia todo o conteúdo da pasta gestor/ para o container Docker local (testes) ou para a hospedagem de produção.

• Queremos dinamizar a homepage e os layouts HTML utilizando a arquitetura de Widgets Envelopados (Wrappers) no Core.

Objetivos da Rodada (Fatiamento no Core)

1. Nova Arquitetura de Widgets Envelopados (Wrappers):

   • Modificar o núcleo do sistema (conn2flow) para permitir que blocos de visualização/mockup estático em páginas físicas (delimitados por comentários específicos) sejam interceptados e substituídos em tempo de execução pelo retorno dinâmico do widget correspondente.

2. Módulo de Destaques (publisher-highlights):

   • Criar a migração do banco de dados (tabela publisher_highlights incluindo colunas de template HTML e CSS editáveis), o painel CRUD administrativo de curadoria integrado ao editor HTML (html-editor.php), e a lógica do widget backend para processamento e renderização dinâmica.

Especificação Técnica da Nova Arquitetura de Widgets

1. Sintaxe do Widget Envelopado (Layout/Páginas HTML)

Qualquer bloco HTML estático na página física poderá ser envelopado por marcadores de início e fim no formato de comentários HTML contendo a assinatura do widget. Como o layout dinâmico real e suas variáveis serão editados e controlados exclusivamente dentro do módulo administrativo, o HTML contido na página física pode ser um mockup 100% estático e limpo (sem tags de loop ou variáveis do sistema), servindo apenas para visualização de layout/preview para designers e editores visuais.

<!-- widgets#publisher-highlights->render({"grupo_slug": "noticias-home"}) < -->
<div class="container-secao">
    <h2>Destaques Recentes</h2>
    <div class="grid-items">
        <div class="card-estatico-exemplo">
            <img src="/images/noticia-exemplo-1.jpg" alt="Título da Notícia Estática 1">
            <h3>Título da Notícia Estática 1</h3>
            <p>Resumo visual de exemplo. Este trecho é apenas para preview estático no editor de páginas.</p>
            <a href="/noticias/exemplo-1">Leia mais</a>
        </div>
    </div>
</div>
<!-- widgets#publisher-highlights->render({"grupo_slug": "noticias-home"}) > -->

2. Modificações no Núcleo do Sistema (conn2flow)

A. Alterações em conn2flow/gestor/gestor.php (na função gestor_pagina_widgets)

O motor do gestor será modificado para buscar os blocos envelopados usando expressões regulares que capturem o ID completo do widget e o HTML interno como template:

• Regex de Captura: /<!--\s*widgets#(.+?)\s*<\s*-->([\s\S]*?)<!--\s*widgets#\s*\\1\s*>\s*-->/i

• Algoritmo de Processamento:

  1. Localizar todas as ocorrências de blocos envelopados na string de renderização da página ($_GESTOR['pagina']).

  2. Para cada correspondência:

     • Extrair a assinatura/ID do widget (Grupo 1).

     • Extrair o HTML estático interno (Grupo 2), que servirá de template.

     • Chamar widgets_get() passando um array contendo 'id' (a assinatura) e 'html' (o HTML capturado).

     • Substituir o bloco inteiro (incluindo os marcadores de início e fim) pelo HTML dinâmico retornado.

• Compatibilidade: O processamento tradicional de variáveis em linha @[[widgets#...]]@ deve continuar ativo como fallback.

B. Alterações em conn2flow/gestor/bibliotecas/widgets.php (na função widgets_get)

• Recebimento de Parâmetros: A função widgets_get deverá processar a chave 'html' do array $params.

• Injeção de Template: Ao converter e decodificar os parâmetros do widget (o $json extraído dos parênteses do ID), o sistema injetará o HTML estático recebido no array de parâmetros do callback:

  if (isset($html)) {
      $paramsArray['html'] = $html;
  }

• Despacho: O controlador específico do módulo (ex: publisher-highlights.widget.php) será acionado com o $paramsArray unificado, permitindo que o callback utilize o HTML original como base para renderização.

Módulos a Desenhar/Implementar (Core Conn2Flow)

1. Módulo Destaques (publisher-highlights)

• Vínculo: Está intimamente ligado ao módulo de publicações modulos/publisher (regras e dados) e modulos/publisher-pages (páginas dinâmicas instanciadas).

• Assinatura: <!-- widgets#publisher-highlights->render({"grupo_slug": "noticias-home"}) < -->

• Especificação do Banco de Dados (Migration Phinx): A tabela para este módulo terá a seguinte estrutura:

  • Nome da Tabela: publisher_highlights

  • Chave Primária: id_publisher_highlights (Auto-incremento)

  • Colunas:

    • id_usuarios (int, default 1, nulo aceitável) -> Usuário proprietário/criador.

    • name (varchar 255, não nulo) -> Nome visual amigável do bloco de destaques.

    • id (varchar 100, não nulo) -> Identificador único gerado por slug (grupo_slug).

    • publisher_id (varchar 100, não nulo) -> Vinculação com o identificador alfanumérico (slug/id) do publicador (publisher).

    • fields_schema (json, nulo aceitável) -> Configurações dinâmicas de regras de negócio e curadoria em formato JSON, utilizando identificadores alfanuméricos para referenciar registros.

    • html (mediumtext, nulo aceitável) -> O template HTML editável do widget.

    • css (text, nulo aceitável) -> Código CSS customizado para estilização do widget.

    • plugin (varchar 255, nulo aceitável).

    • language (varchar 10, default 'pt-br', não nulo).

    • status (char 1, default 'A') -> Estado do bloco ('A' = Ativo, 'I' = Inativo, 'D' = Deletado).

    • versao (int, default 1).

    • data_criacao (datetime, default CURRENT_TIMESTAMP).

    • data_modificacao (datetime, default CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP).

    • user_modified (tinyint, default 0).

    • system_updated (tinyint, default 0).

  • Índices:

    • ['id', 'language'] (Único) -> Garante a exclusividade do slug por idioma.

    • language (Normal).

• Estrutura do Painel Administrativo (CRUD): O módulo administrativo completo será construído duplicando a estrutura do módulo publisher original para gestor/modulos/publisher-highlights. Realizar a renomeação sistemática de arquivos/pastas de publisher para publisher-highlights e adaptar os controladores e templates do CRUD (mantendo os recursos de listagem automática e controle de status pela biblioteca interface.php).

  • Páginas e Funções:

    • publisher_highlights_adicionar():

    • Valida campos obrigatórios (name, publisher_id).

    • Gera o slug único no campo id usando banco_identificador() sobre o valor de name.

    • Salva as configurações iniciais no banco de dados e redireciona para edição.

    • publisher_highlights_editar():

    • Permite editar o name, o publicador vinculado (publisher_id) e as regras em fields_schema.

    • Carrega dados do histórico e backups de versão automáticos.

    • Habilitação do Editor HTML: Inicializa o editor visual do sistema (html-editor.php com alvo publisher-highlights) para a edição direta do código-fonte do template HTML (coluna html) e CSS (coluna css).

    • Vinculação de Variáveis: O painel exibe uma interface interativa (carregada em publisher-highlights-editar.html) que detecta os placeholders de repetição no formato @[[item#nome_da_variavel]]@ inseridos no template HTML e permite vinculá-los aos campos reais do publicador selecionado.

    • publisher_highlights_clonar():

    • Copia o registro de destaque selecionado para um novo identificador.

• Regras do Negócio Dinâmicas no fields_schema (JSON): O campo fields_schema guardará as opções de alimentação das publicações. O esquema JSON suportará:

  • rule (string): "manual" ou "latest".

  • count (int): Limite máximo de publicações a renderizar (default 4).

  • selected_items (array de strings): Lista ordenada de identificadores textuais/alfanuméricos das publicações (slugs).

  • variable_mapping (json): Mapeamento de variáveis do item template (ex: titulo correspondente ao campo de texto do publicador, imagem correspondente ao campo de upload, etc.).

• Configuração do Módulo (publisher-highlights.json): Criar o arquivo conn2flow/gestor/modulos/publisher-highlights/publisher-highlights.json para definir dependências, resources e rotas administrativas do CRUD.

• Modo IA (ai_modes/publisher-highlights/publisher-highlights.md): Criar regras de geração para assistentes de IA para formatar placeholders @[[item#nome_da_variavel]]@ e delimitar repetições entre <!-- item < --> e <!-- item > -->.

• Modelos Prontos de Destaque (Templates): Disponibilizar pelo menos 6 modelos visuais de destaques prontos (lista simples, grid cards, artigos editorial, lives vídeo destaque, notas mosaico, destaque principal carrossel).

• Integração com a Biblioteca Editor HTML (html-editor.php): Alterar html-editor.php para contemplar o novo tipo 'publisher-highlights'.

• Funcionamento Técnico (Renderização):

  • O widget recebe a slug correspondente do grupo de destaques (ex: "noticias-home").

  • Busca o registro correspondente na tabela publisher_highlights usando a slug.

  • Recupera o template HTML cadastrado na coluna html do registro.

  • No template carregado, isola a marcação contida entre las tags de loop <!-- item < --> e <!-- item > --> para ser usada como base para a repetição.

  • Busca as publicações (tabela de dados de publicações do publisher_id) aplicando a regra do fields_schema.

  • Para cada publicação ativa encontrada, substitui os placeholders no template do item.

  • Substitui o bloco inteiro de itens repetidos no template do widget.

  • Injeta o CSS customizado e retorna o HTML final.