req-073: Parametrização Dinâmica de E-mails e Integração de Estágios de Serviço em Planos de Assinatura ([REDACTED] / conn2flow)

Descrição do Problema / Contexto

Queremos remover lógicas chumbadas (hardcoded) no processamento de formulários do módulo subscriptions e dar mais flexibilidade à administração de Planos de Assinatura no painel administrativo:

1. Parâmetros de E-mail Dinâmicos: Em vez de carregar templates (order-confirmation-email ou custom-order-confirmation-email) e assuntos de e-mail com base em condicionais fixas de formulário (ex: $formId === 'form-pro-custom'), o sistema deve ler essas configurações diretamente da definição do formulário (fields_schema->email) que já possui as chaves message_component e subject.

2. Autocomplete de Componentes de E-mail: No construtor de formulários (forms), o campo Componente de mensagem deve se tornar um campo Autocomplete AJAX buscando dinamicamente os registros da tabela componentes do sistema (já que os e-mails são componentes).

3. Reorganização Visual do CRUD de Planos: O formulário do CRUD de planos de assinatura deve ser reorganizado em segmentos lógicos claros (Geral, Integração, Pagamentos / Gateways, Mapeamento de Cadastro), removendo placeholders soltos.

4. Estágio Inicial de Serviço e Flag Gratuito: Planos devem suportar a definição de se são gratuitos (is_free) e qual o seu estágio inicial de serviço (initial_stage). O estágio inicial deve ser populado dinamicamente com base no "Tipo de serviço" (service_stage_type) selecionado pelo usuário, buscando da tabela subscriptions_service_stages.

Mudanças Necessárias (Repositório [REDACTED])

1. Banco de Dados e Migração ([REDACTED])

• Criar migração Phinx no [REDACTED] (gestor/db/migrations/):

  • Adicionar a coluna is_free (tipo boolean, default false, comment "Indica se o plano é gratuito") na tabela subscriptions_plans.

  • Adicionar a coluna initial_stage (tipo string, limit 100, null true, comment "FK lógica para subscriptions_service_stages.id") na tabela subscriptions_plans.

2. Backend de Processamento do Checkout (subscriptions em [REDACTED])

• No arquivo gestor/modulos/subscriptions/subscriptions.ajax.public.php (função subscriptions_ajax_forms_process):

  • Buscar a coluna is_free na consulta do plano ($planRow).

  • Componente de E-mail Dinâmico: Substituir a condicional $isCustomPlan para ler $emailComponentId diretamente do campo message_component de $schema['email'] (obtido da definição de forms). Manter order-confirmation-email como fallback caso o campo esteja vazio.

  • Assunto de E-mail Dinâmico: Substituir a condicional $emailSubjectId para obter e usar diretamente a string do assunto do campo subject de $schema['email']. Substituir nessa string as variáveis de template (#name#, #code#, #formName#). Manter o comportamento original de buscar a variável caso o campo esteja ausente.

  • Status Inicial Dinâmico: Substituir a condicional de status $isCloudNano pela flag $planRow['is_free']:

  • Se o plano for gratuito (is_free = 1): status "Ativo - Plano Gratuito" (pt-br) / "Active - Free Plan" (en) com cor #16a34a (green-600).

  • Caso contrário: status "Novo - Aguardando Pagamento" (pt-br) / "New - Pending Payment" (en) com cor #2563eb (blue-600).

3. Autocomplete de Componentes no Módulo de Formulários (forms em conn2flow)

3.1. Rota AJAX no Backend (gestor/modulos/forms/forms.php)

• Adicionar o caso 'buscar-componentes' no switch de forms_start(), chamando a função forms_ajax_buscar_componentes().

• Implementar forms_ajax_buscar_componentes() buscando registros na tabela componentes onde a linguagem é a atual, status != 'D' e name ou id casem com o termo q. Retornar os primeiros 15 resultados em formato JSON compatível.

3.2. Templates HTML do Admin (conn2flow)

• Nos 6 templates HTML de adicionar, editar e clonar em pt-br e en:

  • Envolver o campo #email_message_component na estrutura de autocomplete .sig-autocomplete (com data-target="componentes" e botões de limpar .sig-clear e resultados .sig-results), idêntico à estrutura usada nos planos.

3.3. JavaScript do Admin (gestor/modulos/forms/forms.js em conn2flow)

• Copiar e integrar a lógica de escuta e requisição AJAX do autocomplete .sig-autocomplete para o arquivo forms.js.

• Ao selecionar um componente da listagem ou limpar, preencher o input correspondente e disparar o evento 'change' / 'input' para que o schema do formulário seja devidamente re-salvo na memória de alteração.

4. Layout e Estágios no CRUD de Planos (subscriptions-plans em [REDACTED])

4.1. Reorganização dos Templates HTML

• Nos 4 templates de CRUD de planos em [REDACTED]:

  • Reorganizar a estrutura em 4 segmentos lógicos (<div class="ui segment">):

  • Geral: Nome, ID/Slug, Descrição, Idioma, checkbox "Plano Gratuito" (is_free).

  • Integração: Formulário associado, Caminho de Retorno.

  • Serviço: Tipo de serviço (service_stage_type), Estágio Inicial de Serviço (initial_stage).

  • Pagamentos / Gateways: Gateway de pagamento, Total de cobranças, Redirecionar ao cadastro.

  • Mapeamento de Cadastro: Checkbox "Plano de Cadastro" e mapeamento de campos (apenas visível se ativo).

4.2. Lógica de Estágios de Serviço no CRUD (subscriptions-plans.php em [REDACTED])

• No arquivo subscriptions-plans.php:

  • Mapear os campos is_free e initial_stage nas operações de banco de dados (inserir/atualizar) e sanitizações de input.

  • Adicionar o select dropdown de #select-initial_stage# em subscriptions_plans_campos_interface().

  • Criar o endpoint AJAX 'buscar-estagios' que recebe stage_type (ex: hosting, project, mentorship), consulta a tabela subscriptions_service_stages e retorna a lista de estágios ativos daquele tipo no idioma atual.

4.3. JavaScript de Vinculação Dinâmica (subscriptions-plans.js em [REDACTED])

• No JS subscriptions-plans.js:

  • Monitorar alterações no select do "Tipo de serviço" (#service_stage_type).

  • Ao alterar, realizar chamada AJAX ao endpoint 'buscar-estagios' e repopular o select do estágio inicial (#initial_stage).

  • No estado inicial (edição), carregar os estágios condizentes com o tipo salvo e pré-selecionar o valor gravado.

Validação e Testes

1. Verificação Estática:

   • Rodar php -l nos arquivos PHP modificados/criados nos dois repositórios.

   • Rodar node --check nos JS modificados.

2. Execução de Migrações:

   • Rodar composer db:migrate no [REDACTED] para certificar que a migração de adicionar colunas rodou com sucesso.

3. Validação do Autocomplete do Forms:

   • Abrir o construtor de formulários no admin, digitar no campo Componente de mensagem e validar se a lista de componentes cadastrados no sistema é sugerida e selecionável.

4. Validação do CRUD de Planos:

   • Adicionar e Editar um plano, verificar se o formulário está agrupado visualmente de forma limpa.

   • Selecionar um "Tipo de serviço" (ex: Hospedagem) e confirmar que o dropdown "Estágio Inicial" é populado dinamicamente com os estágios condizentes da tabela subscriptions_service_stages.