req-069: Integração do Módulo de Formulários com o Controlador de Submissão de Biblioteca de Formulários

Descrição do Problema / Contexto

O widget público do módulo de Formulários (forms) utiliza hoje um controlador JavaScript simplificado e redundante (forms.widget.js). Esse script não possui tratamento para honeypots, Google reCAPTCHA v2/v3, rate limiting por IP, validações complexas nem tratamento centralizado de mensagens de erro providos pelo backend.

Queremos substituir a inicialização e envio do widget pelo controlador padrão da biblioteca de formulários (formulario.php e formulario.js). Como a página pública pode renderizar múltiplos formulários em locais diferentes (ex: contato no corpo da página e newsletter no rodapé), a biblioteca de formulários deve ser aprimorada para dar suporte a múltiplos formulários concorrentes sem que as configurações ou campos de um colidam com o outro no localStorage ou no escopo de variáveis JavaScript do gestor.form.

Mudanças Necessárias

1. Suporte a Múltiplos Formulários na Biblioteca PHP (formulario.php)

Modificar a função formulario_controlador($params = false) em gestor/bibliotecas/formulario.php:

• Permitir que $formId seja uma string única ou um array de IDs de formulário.

• Unificar o fluxo convertendo $formId para um array interno (ex: $formIds = is_array($formId) ? $formId : [$formId]).

• Executar a consulta no banco de dados (forms table), verificação de reCAPTCHA, controle de acesso (formulario_acesso_verificar) e preparação de parâmetros em um laço de repetição (foreach ($formIds as $fid)).

• Armazenar as configurações individuais de cada formulário indexadas por seu respectivo ID em um array associativo (ex: $forms_js_vars[$fid] = $fid_vars).

• Retrocompatibilidade: Se a chamada original for para um ID único (string), continuar injetando as variáveis em formato plano no namespace global do JS.

• Injetar o array associativo contendo as configurações por ID no namespace JavaScript (gestor_js_variavel_incluir('form', $forms_js_vars)).

2. Tratamento de Seletores e Contextos Múltiplos no JS (formulario.js)

Modificar gestor/assets/interface/formulario.js:

• Expandir a busca de seletores para atuar tanto no marcador clássico (._forms-submissions-controller) quanto no marcador padrão de widgets de formulário (.conn2flow-form).

• Ao iterar sobre cada formulário encontrado na página:

  • Recuperar o atributo de ID HTML do formulário (var formId = form.attr('id')).

  • Buscar a definição correspondente a este formulário dentro de gestor.form. Se o formId existir como chave em gestor.form, carregar as configurações específicas dele (data = gestor.form[formId]). Caso contrário, fazer fallback para o próprio objeto plano gestor.form (mantendo retrocompatibilidade).

  • Inicializar o controlador do formulário (initFormController(form, data)) de forma isolada para cada instância de formulário.

3. Integração do Widget com a Biblioteca (forms.widget.php)

Modificar gestor/modulos/forms/forms.widget.php:

• Na função forms_render($params):

  • Remover a inclusão do script legado via:

    gestor_pagina_javascript_incluir([
    'tipo' => 'widget',
    'modulo_id' => 'forms',
    ...
    ]);

  • Incluir e invocar a biblioteca de formulários configurando o ID do formulário correspondente:

    gestor_incluir_biblioteca('formulario');
    formulario_controlador([
    'formId' => $registro['id'],
    ]);

4. Remoção do Script Redundante (forms.widget.js)

• [DELETE] Excluir o arquivo gestor/modulos/forms/forms.widget.js, já que o fluxo de eventos e submissão AJAX passa a ser inteiramente regido pela biblioteca padrão do core (formulario.js e interface.js).

3. Validação e Testes

1. Verificação Estática:

   • Rodar node --check nos arquivos JavaScript alterados.

   • Rodar php -l nos arquivos PHP modificados.

2. Testes de Integração:

   • Rodar composer test para validar o fluxo do core.

3. Validação Manual (Runtime):

   • Renderizar o widget de formulário na página pública.

   • Confirmar que as validações de campos obrigatórios/e-mail são feitas no lado do cliente.

   • Submeter o formulário via AJAX e verificar se a gravação ocorre com sucesso, se redireciona para a página de sucesso correta, se o honeypot está presente e se não há colisões ou exceções no console do navegador.