Requisição 173 — Preservação de Query Strings em Redirecionamentos 301 e Contenção de Blocos-Fragmento no Widget de Formulários

Origem: Achados BL-016 (análise de rotas aposentadas na REQ-054 do conn2flow-site) e BL-017 (análise de renderização de templates no BATCH-047 do conn2flow-site). Lote Vinculado: BATCH-178. Status: ready-for-intake.

1. Diagnóstico e Causa-Raiz

1.1 Redirecionamento de paginas_301 Descarta Query String (BL-016)

Na tabela paginas_301, o roteador do Core (gestor_roteador_301_ou_404() em gestor/gestor.php) consulta se um caminho requisitado não encontrado possui mapeamento permanente (301) para uma página ativa no idioma atual:

if($paginas){
    gestor_roteador_erro(Array(
        'codigo' => 301,
        'redirect' => $paginas[0]['caminho'],
    ));
}

A função gestor_roteador_erro() suporta o parâmetro booleano 'querystring', que repassa gestor_querystring() para gestor_redirecionar(). Como 'querystring' => true não é passado na chamada de paginas_301, o redirecionamento descarta sumariamente toda a query string da URL original ($_SERVER['QUERY_STRING']).

Impacto: Ao acessar uma URL aposentada que receba parâmetros analíticos ou de contexto (por exemplo: /pro-checkout/?plan=starter&utm_source=adwords), o visitante é redirecionado para /checkout/ sem o plano e sem as UTMs, quebrando a conversão e perdendo o rastreamento de campanhas.

1.2 Widget de Formulários Vaza Blocos-Fragmento no HTML Renderizado (BL-017)

Os templates de formulários (target='forms' em gestor/modulos/forms/resources/*/templates/, como forms-contato-basico e forms-registro-usuario) declaram no final do arquivo blocos-fragmento usados como modelo para gerar opções e controles:

• <!-- option-choice < -->...<!-- option-choice > -->

• <!-- option-select < -->...<!-- option-select > -->

• <!-- password-toggle < -->...<!-- password-toggle > -->

Em gestor/modulos/forms/forms.widget.php, a função forms_widget_options_html() e forms_widget_wrap_password() leem esses blocos da string do template via modelo_tag_val(). No entanto, a função de renderização forms_widget_render_inline() apenas substitui o bloco central <!-- item < -->...<!-- item > --> e variáveis escalares do formulário, sem nunca remover esses blocos-fragmento do final do HTML devolvido.

Impacto: Como o que está entre os marcadores é markup HTML normal (<label>, <input>, <option>, <button>), o navegador desenha esses elementos crus no final da página pública, exibindo marcadores não processados como @[[option#type]]@, @[[option#value]]@ e @[[password#input]]@.

2. Escopo Normativo

2.1 Preservação de Query Strings em paginas_301

1. Em gestor/gestor.php (gestor_roteador_301_ou_404()):

   • Passar 'querystring' => true ao invocar gestor_roteador_erro() no desfecho de página 301 encontrada.

2. Em gestor/bibliotecas/gestor.php (gestor_redirecionar()):

   • Garantir que a concatenação da query string trate com segurança o caso de $local já conter ? (concatenando com & em vez de ??).

   • Preservar o status HTTP 301 e o comportamento idempotente para todos os demais tipos de redirecionamento do sistema.

2.2 Contenção e Expurgamento de Blocos-Fragmento no Widget forms

1. Em gestor/modulos/forms/forms.widget.php (forms_widget_render_inline() ou helper equivalente):

   • Após a extração e substituição dos itens, remover explicitamente do $html retornado os blocos-fragmento conhecidos:

     • <!-- option-choice < -->...<!-- option-choice > -->

     • <!-- option-select < -->...<!-- option-select > -->

     • <!-- password-toggle < -->...<!-- password-toggle > -->

   • Aplicar limpeza profilática para remover quaisquer marcadores residuais de bloco <!-- * < --> e tags de template remanescentes do widget que não devam vazar para o cliente.

   • Como rede de segurança (safety net), sanitizar marcadores @[[option#*]]@ e @[[password#*]]@ remanescentes, impedindo exibição de tokens crus para o usuário final.

2. Compatibilidade:

   • Preservar integralmente o funcionamento de campos select, radio, checkbox e do botão de visibilidade de senha (password-toggle).

   • Suportar tanto templates nativos quanto templates que envolvam os blocos em <template> (solução de contorno adotada no site).

3. Critérios de Aceite e Validação

1. Query String Preservada em 301:

   • Requisição a um caminho cadastrado em paginas_301 com parâmetros (/antigo/?plan=pro&ref=abc) responde HTTP 301 com header Location preservando os parâmetros exatos (/novo/?plan=pro&ref=abc).

   • Requisição sem parâmetros (/antigo/) responde HTTP 301 apontando para /novo/ sem ? espúrio.

2. Nenhum Marcador Cru na Renderização de Formulários:

   • Qualquer formulário renderizado pelo widget forms com campos select, radio, checkbox ou password deve retornar HTML livre de <!-- option-choice, <!-- option-select, <!-- password-toggle e de marcadores @[[...]]@.

   • As opções dos campos (tags <option>, <label> com radio/checkbox) e o botão de toggle de senha devem permanecer perfeitamente operacionais no DOM renderizado.

3. Testes Automatizados:

   • Teste unitário no PHPUnit cobrindo os cenários de redirecionamento 301 com e sem query string.

   • Teste unitário no PHPUnit cobrindo a renderização do widget forms garantindo a eliminação dos blocos-fragmento e marcadores crus.

4. Regressão Zero:

   • composer test (PHPUnit) e npx vitest run (Vitest) 100% verdes.

   • assets:minify --verificar e git diff --check sem erros.