id: "REQ-273" title: "Novo Tipo de Campo 'Domínio' (domain) no Módulo Forms e Biblioteca de Formulários" status: "ready-for-intake" date: "2026-10-15" author: "arquiteto" target_repo: "conn2flow" batch: "BATCH-282"

REQ-273: Novo Tipo de Campo "Domínio" (domain) no Módulo Forms e Biblioteca de Formulários

• Identificador: REQ-273

• Lote Alvo: BATCH-282 (conn2flow)

• Status: ready-for-intake

• Topologia de Agentes: dupla (Arquiteto Master ➔ Engenheiro Executor)

• Modo de Autonomia: autonomo_monitorado

• Repositório Base: [REDACTED]

• Cooperação de Sessão: Independente e isolado do conn2flow-site (zero colisão de arquivos).

1. Contexto e Motivação

Durante a contratação de planos de hospedagem e assinatura no site (form-pro-acceleration e formulários correlatos), o cliente final informa o domínio desejado para sua nova instalação (ex: [REDACTED], [REDACTED]).

Atualmente, o módulo forms oferece apenas os tipos text e url:

1. Problema do tipo url: Navegadores modernos (validação HTML5 de <input type="url">), a biblioteca client-side (formulario.js) e a função PHP filter_var(..., FILTER_VALIDATE_URL) exigem estritamente o protocolo http:// ou https://. Se o cliente digitar apenas o domínio [REDACTED], o envio é rejeitado como URL inválida.

2. Problema do tipo text: Como caixa de texto simples, não há qualquer validação de formato FQDN (Fully Qualified Domain Name). O cliente pode digitar espaços, acentos, barras, arrobas ou caracteres proibidos, o que quebra o provisionamento de contas e DNS no [REDACTED] / HestiaCP (v-add-web-domain).

Portanto, faz-se necessária a criação do tipo nativo domain (Domínio) no módulo de formulários e na biblioteca do Core, com validação inteligente client e server-side.

2. Escopo Técnico e Atividades

Atividade 1: Inclusão do Tipo no Editor do Módulo Forms

• Arquivos-alvo:

  • gestor/modulos/forms/resources/pt-br/pages/forms-editar/forms-editar.html

  • gestor/modulos/forms/resources/pt-br/pages/forms-adicionar/forms-adicionar.html

  • gestor/modulos/forms/resources/pt-br/pages/forms-clonar/forms-clonar.html

  • (e versões em resources/en/ correspondentes)

  • gestor/modulos/forms/forms.json

  • gestor/modulos/forms/forms.js (e forms.min.js)

• Ações:

  1. No <template id="field-row-template">, dentro do <select class="forms-field-type">, adicionar a opção:

     <option value="domain">@[[field-type-domain]]@</option>

  2. Em forms.json, adicionar a variável field-type-domain:

     • pt-br: "Domínio"

     • en: "Domain"

  3. Em forms.js, suportar o tipo domain nas funções auxiliares de opções e placeholders (sugerindo exemplo [REDACTED]).

Atividade 2: Renderização de Input Especializado (Sem Trava HTML5 de URL)

• Arquivo-alvo:

  • gestor/modulos/forms/forms.widget.php

• Ações:

  1. Em forms_widget_render_field, assegurar que para type === 'domain', o $inputType gerado seja 'text' (evitando que o navegador force a regra estrita de URL).

  2. Injetar atributos de higiene e acessibilidade móvel:

     • autocapitalize="none"

     • spellcheck="false"

     • autocomplete="off"

Atividade 3: Sanitização e Validação Client-Side

• Arquivo-alvo:

  • gestor/assets/interface/formulario.js

• Ações:

  1. Na função validateField, adicionar o tratamento para field.type === 'domain':

     • Sanitização em tempo real: Se o usuário colar com http://, https:// ou barra no final, o script limpa automaticamente e converte para minúsculas:

       var cleanVal = value.replace(/^https?:\/\//i, '').replace(/\/+$/, '').trim().toLowerCase();
       if (cleanVal !== value) {
       input.val(cleanVal);
       value = cleanVal;
       }

     • Validação de FQDN via Regex:

       var domainRegex = /^(?!:\/\/)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
       if (!domainRegex.test(value)) {
       isValid = false;
       errorMsg = fillPrompt(pickPrompt(prompts, 'domain', 'O campo #label# precisa de um domínio válido (ex: [REDACTED]).'), field, null);
       }

Atividade 4: Validação Server-Side e Prompts Multilíngues

• Arquivos-alvo:

  • gestor/resources/pt-br/components/form-ui/form-ui.html

  • gestor/resources/en/components/form-ui/form-ui.html

  • gestor/bibliotecas/formulario.php

• Ações:

  1. Nos templates form-ui.html:

     • Em <!-- prompts < -->:

     • pt-br: <!-- prompt-domain < -->O campo #label# precisa de um domínio válido.<!-- prompt-domain > -->

     • en: <!-- prompt-domain < -->The field #label# requires a valid domain.<!-- prompt-domain > -->

     • Em <!-- ajax-messages < -->:

     • pt-br: <!-- ajax-message-invalid-domain < -->Domínio inválido no campo #fieldLabel#.<!-- ajax-message-invalid-domain > -->

     • en: <!-- ajax-message-invalid-domain < -->Invalid domain in field #fieldLabel#.<!-- ajax-message-invalid-domain > -->

  2. Em gestor/bibliotecas/formulario.php:

     • Extrair prompt-domain e ajax-message-invalid-domain no array $form_ui_prompts e $form_ui_ajax_messages.

     • Na rotina de processamento (formulario_processamento):

     • Se field.type === 'domain' e o valor não estiver vazio:

       1. Remover prefixo http://, https:// e barra final /.

       2. Salvar o valor em $_POST[$field['name']] normalizado em minúsculas (strtolower).

       3. Validar contra regex RFC 1035 / RFC 1123: '/^(?!:\/\/)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i'

       4. Se inválido, retornar erro AJAX com $form_ui_ajax_messages['invalidDomain'].

Atividade 5: Compilação de Recursos e Testes

• Incrementar versão de recurso (asset_version) no metadado do módulo forms.json e formulario.php.

• Sincronizar recursos via ./c2f manager:update-all.

• Executar a suíte de testes com php cli/c2f.php test:run garantindo zero regressões.

3. Critérios de Aceite (DoD)

1. [ ] Editor de Formulários: O tipo "Domínio" (domain) está selecionável em adicionar/editar/clonar formulários e persiste corretamente no fields_schema.

2. [ ] Renderização do Input: O campo de domínio renderiza sem disparar validação nativa de URL do browser, com autocapitalize/spellcheck desativados.

3. [ ] Sanitização Client: Digitar ou colar [REDACTED] limpa automaticamente para [REDACTED].

4. [ ] Validação Client: Domínios sem ponto, com caracteres inválidos ou espaços disparam erro inline visual claro.

5. [ ] Validação Server: O backend PHP higieniza e rejeita envios forçados com strings malformatadas ou com protocolos espúrios.

6. [ ] Internacionalização: Mensagens traduzidas em pt-br e en.

7. [ ] Testes e Build: ./c2f manager:update-all e testes do framework executados com sucesso.