req-088: Criação dos Módulos/Widgets "forms-search" (Formulários de Busca) e "pages-index" (Páginas Índice)

Descrição do Problema / Contexto

Queremos expandir a plataforma adicionando a capacidade de busca textual de páginas do site. Para isso, precisamos criar dois novos módulos e seus respectivos widgets, baseados em estruturas de módulos existentes e consolidadas:

1. forms-search: Um módulo de formulários focado especificamente na captura de buscas textuais de páginas, baseado no módulo core forms.

2. pages-index: Um módulo de listagem/grade de páginas que exibe os resultados de busca e/ou as páginas ativas do sistema, baseado no módulo publisher-index.

A estratégia de desenvolvimento consiste em copiar os módulos originais inteiramente para os novos destinos e realizar as adaptações, substituições de slugs/tabelas e os refinamentos descritos abaixo.

Mudanças e Arquitetura Necessárias

1. Novo Módulo forms-search

• Origem: gestor/modulos/forms/

• Destino: gestor/modulos/forms-search/

• Adaptações de Nomenclatura:

  • Alterar o ID do módulo de forms para forms-search.

  • Alterar as referências de tabela de forms para forms_search e de forms_submissions para forms_search_submissions.

  • Alterar o ID numérico da tabela de id_forms para id_forms_search.

  • Mapear e atualizar arquivos e funções JavaScript/PHP internas (ex: de forms.js para forms-search.js, forms_render para forms_search_render, etc.).

• Comportamento Específico:

  • O formulário renderizado pelo widget (forms-search.widget.php) deve usar o método GET (em vez de POST).

  • O campo de entrada de busca no formulário final deve conter o atributo name="search" para enviar a variável search=... na URL.

  • A ação (action) do formulário deve apontar para o caminho da página configurada como alvo (uma página contendo a instância do widget de pages-index).

  • No construtor de formulários (admin), o campo de configuração do formulário deve permitir ao usuário definir a página/URL alvo do action.

  • Estatísticas de Busca (Analytics): Persistir os termos pesquisados registrando-os na tabela forms_search_submissions a cada busca para possibilitar futuras estatísticas/relatórios de pesquisa no CRUD administrativo do módulo.

2. Novo Módulo pages-index

• Origem: gestor/modulos/publisher-index/

• Destino: gestor/modulos/pages-index/

• Adaptações de Nomenclatura:

  • Alterar o ID do módulo de publisher-index para pages-index.

  • Alterar a referência da tabela local de publisher_index para pages_index.

  • Alterar o ID numérico da tabela de id_publisher_index para id_pages_index.

  • Adaptar os scripts e funções (ex: publisher-index.widget.js para pages-index.widget.js, publisher_index_render para pages_index_render, etc.).

• Comportamento Específico:

  • Consulta ao Banco: Substituir o INNER JOIN contra a tabela publisher_pages por uma consulta direta à tabela paginas filtrando apenas páginas públicas e ativas:

  • Filtro obrigatório: status='A' AND language='$language' AND tipo='pagina' AND sem_permissao=1.

  • Filtros e Busca:

  • Deve interceptar a variável GET search (ex: ?search=termo) na URL. Se presente, essa variável preenche inicialmente a busca textual do widget.

  • A busca textual deve filtrar a tabela paginas comparando contra os campos nome (título) e html (conteúdo da página), exemplo: nome LIKE '%termo%' OR html LIKE '%termo%'.

  • Suportar a ordenação do AJAX pelas 4 chaves existentes no módulo base: title_asc, title_desc, date_asc (data de modificação ascendente), date_desc (data de modificação descente).

  • Variáveis de Item Mapeadas:

  • No loop de renderização de itens (pages_index_widget_render_itens), disponibilizar três variáveis fixas obrigatórias:

    • [[item#title]]: Título da página (campo nome).

    • [[item#summary]]: Resumo textual da página, obtido a partir de strip_tags() do campo html da página e truncado para ~200 caracteres (mimetizando uma descrição).

    • [[item#url]]: URL/caminho relativo da página (campo caminho).

  • Página Padrão de Busca:

  • Registrar uma página padrão pública com caminho pages-index/ através do arquivo de sementes pages-index.json. Essa página virá pré-configurada com uma instância do widget pages-index para atuar como destino padrão de buscas globais disparadas em qualquer página do site.

3. Migração do Banco de Dados

• Destino: gestor/db/migrations/

• Nova Migração: 20260715120000_create_forms_search_and_pages_index_tables.php (ou timestamp correspondente) criando as tabelas:

  • forms_search (espelhando forms com as colunas de template embutidas: id_forms_search, id_users, name, id, description, template_id, fields_schema, module, plugin, language, status, version, html, css, css_compiled, html_extra_head, user_modified, system_updated, created_at, updated_at).

  • forms_search_submissions (espelhando forms_submissions).

  • pages_index (espelhando publisher_index com id_pages_index e sem publisher_id).

Validação e Testes

1. Verificação de Sintaxe:

   • Executar php -l em todos os novos arquivos PHP gerados nos novos diretórios dos módulos.

   • Executar node --check ou similar nos novos arquivos JavaScript (forms-search.js, forms-search.widget.js, pages-index.js, pages-index.widget.js).

2. Testes Unitários:

   • Rodar composer test no projeto conn2flow para garantir que os testes existentes não sofrem nenhuma regressão.

3. Validação Operacional:

   • Certificar que os dois novos widgets aparecem corretamente listados na tabela de widgets após a execução da atualização de dados e recursos (atualizacao-dados-recursos.php).

   • Verificar se a página padrão pages-index/ é gerada com o widget associado.

   • Validar que o formulário de busca envia requisições GET corretas com a query search=... para a página alvo, e que esta exibe as páginas correspondentes.