req-074: Dinamização Completa de Planos e Saneamento de Hardcodes no Módulo Subscriptions ([REDACTED])

Descrição do Problema / Contexto

O módulo subscriptions (e seu respectivo arquivo de hooks) no projeto [REDACTED] ainda possui lógicas e tabelas estáticas/chumbadas em PHP herdadas de antes da criação das tabelas subscriptions_plans e subscriptions_plans_payments.

Queremos realizar um saneamento completo, substituindo esses mapeamentos estáticos por consultas dinâmicas no banco de dados para permitir que novos planos e integrações sejam criados pelo painel sem exigir alterações no código-fonte.

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

1. Eliminação dos Dicionários Estáticos de Nomes de Planos ($paypalPlanNames)

• Atualmente, as traduções dos slugs dos planos para nomes amigáveis estão duplicadas em arrays estáticos em diversos arquivos:

  • subscriptions.hooks.php (linhas 1012-1015 e 1283-1286)

  • subscriptions.php (linhas 529-530, 2003-2004 e 2110-2111)

• Mudança: Criar um helper (ex: subscriptions_obter_nome_plano($planSlug, $lang)) no módulo (ou diretamente nos hooks/controller) que consulta a tabela subscriptions_plans pelo id (slug) e language ativos, retornando o valor do campo name. Se o plano não for encontrado no banco, aplicar um fallback amigável (ex: ucfirst($planSlug)).

2. Dinamização de Filtros por Prefixo de Formulário (form_id LIKE 'form-pro-%')

• Em rotinas de webhook/IPN e de processamento de retorno de pagamento, o sistema filtra as submissões usando a regra chumbada form_id LIKE 'form-pro-%' (linhas 1667 e 1689 de subscriptions.hooks.php e linha 2058 de subscriptions.php).

• Mudança: Criar um helper para carregar todos os IDs de formulários associados a planos ativos:

  function subscriptions_obter_form_ids_planos() {
    $planRows = banco_select([
        'tabela' => 'subscriptions_plans',
        'campos' => ['form_id'],
        'extra' => "WHERE status='A' AND form_id IS NOT NULL AND form_id!=''"
    ]);
    if ($planRows) {
        return array_unique(array_map(function($r){ return $r['form_id']; }, $planRows));
    }
    return [];
  }

  E nos filtros SQL de busca de submissões, usar form_id IN ('id1', 'id2', ...) caso existam planos ativos configurados, caindo no fallback LIKE 'form-pro-%' apenas quando o banco estiver vazio.

3. Dinamização do Template de Checkout (subscription-checkout.html)

• Atualmente, o arquivo subscription-checkout.html (tanto em pt-br quanto em en) possui cerca de 1.000 linhas com 6 blocos de planos hardcoded duplicados (starter, acceleration, mentorship, cloud_nano, cloud_pro, custom). Cada bloco duplica a estrutura do formulário, as etapas de pagamento (PayPal) e de sucesso.

• Mudança:

  • Unificar os templates em uma única estrutura genérica dentro da tag <!-- valid_plan < -->.

  • Utilizar placeholders de substituição dinâmica:

  • #plan_name#: Nome do plano (ex: Cloud Starter).

  • #plan_description#: Subtítulo/descrição (ex: For Creators and Developers).

  • #plan_icon_svg#: O elemento SVG e gradiente de fundo correspondentes ao plano.

  • #plan_price_card#: O bloco contendo o preço, moeda e período (ex: $12.00 /mo) ou a mensagem de plano gratuito/personalizado.

  • #form_fields#: Seleção dinâmica de campos de input baseados no tipo do plano:

    • <!-- plan_fields_signup < --> ... > para planos com cadastro de usuário (Nome, Email, Telefone, Domínio desejado, Senha e Confirmar senha).

    • <!-- plan_fields_custom < --> ... > para planos sob medida (Nome, Email, Telefone, Empresa e Descrição da necessidade).

  • Em subscriptions.php (subscriptions_checkout()), o PHP carregará o plano selecionado do banco de dados, obterá suas parcelas e preços da tabela subscriptions_plans_payments, selecionará o bloco de inputs correto e realizará a troca das variáveis no template HTML unificado. Isso reduzirá o arquivo HTML de 1.000 linhas para menos de 200, garantindo compatibilidade automática com qualquer plano criado no futuro.

4. Simplificação e Saneamento do Template da Landing Page (subscription.html)

• Atualmente, o arquivo subscription.html (em pt-br e en) possui cerca de 700 linhas contendo um layout complexo de marketing (seções Hero, Filosofia, VPS Blindado, Setup Gerenciado, IA Integrada, etc.) herdado do antigo pro-manager. Esse texto é estático e faz referências a produtos específicos da plataforma de SaaS anterior que não se aplicam ao módulo genérico de assinaturas.

• Mudança:

  • Limpar as seções de marketing estático redundante.

  • Transformar o template em uma página de preços limpa, moderna e genérica, focada unicamente na apresentação do grid de planos.

  • Manter um cabeçalho simples (Título e Subtítulo), o grid dinâmico (<!-- plans_grid < --> e o bloco repetidor <!-- plan_card < --> que já é tratado pelo PHP), e opcionalmente uma seção de rodapé minimalista com links de suporte/F.A.Q. genérico.

  • Isso reduzirá o arquivo para cerca de 100 linhas em ambas as línguas.

5. Saneamento do Template de Callback (subscription-start.html)

• O arquivo subscription-start.html (em pt-br e en) gerencia as telas de sucesso e cancelamento pós-checkout (como status_account_created, status_success_complete, status_success_pending e status_cancel). Algumas descrições textuais ainda contêm jargões específicos do produto anterior.

• Mudança:

  • Revisar e sanear os textos nas 4 seções de status para garantir que sejam totalmente neutros e genéricos (ex: referindo-se a "sua assinatura" e "seu dashboard" de forma abstrata).

  • Garantir que as variáveis de substituição dinâmicas (#plan_display_name#, #plan_name#, #customer_name#) sejam usadas para alimentar os detalhes da transação dinamicamente a partir do banco de dados.

6. Proteção de Segurança para Campos Password em Submissões (formulario.php no conn2flow)

• Atualmente, ao processar e salvar a submissão de um formulário na tabela forms_submissions (coluna fields_values em formato JSON), os valores dos campos de tipo password são salvos em texto plano por padrão. Isso expõe senhas de usuários e credenciais sensíveis desnecessariamente na auditoria de submissões do banco de dados.

• Mudança:

  • Em gestor/bibliotecas/formulario.php, no loop que constrói o array $fieldsValues para gravação no banco, verificar se o tipo do campo é password ($field['type'] === 'password').

  • Se for, gravar o valor como string vazia '' (ou máscara redacted), impedindo o vazamento de credenciais no banco de dados, mas mantendo a chave declarada no payload da submissão para integridade estrutural.

  • O valor em texto plano do $_POST continua disponível temporariamente durante a execução da requisição para que o hook/controller crie ou vincule o usuário adequadamente.

7. Remoção do Mapeamento Estático de Slugs ($plans e $planCelMap)

• No arquivo subscriptions.php (linhas 938-962), a lista de planos ativos $plans e o mapeamento de aliases $planCelMap (ex: aceleracao $\rightarrow$ acceleration) são estáticos.

• Mudança:

  • A lista de planos válidos para checkout será consultada em tempo real na tabela subscriptions_plans.

  • A resolução do parâmetro ?plan= verificará a existência direta do ID (slug) no banco de dados. Caso não encontre, aplicará um dicionário mínimo de fallbacks legados (para URLs antigas como aceleracao, mentoria ou personalizado) antes de classificar o plano como inválido (<!-- invalid_plan < -->).

Validação e Testes

1. Verificação Estática:

   • Rodar php -l em todos os arquivos PHP do módulo modificados (subscriptions.php e subscriptions.hooks.php).

   • Validar a integridade das tags de comentários HTML e placeholders no novo template de checkout.

2. Validação Operacional (Staging/Admin):

   • Validar que a tela de checkout público renderiza os planos corretos e as informações localizadas sem quebras ou avisos de PHP.

   • Testar o fluxo completo de checkout (formulário $\rightarrow$ pagamento/sucesso) para planos pagos, planos gratuitos (is_free) e planos sob medida (custom).

   • Testar o processamento simulado de um retorno/IPN de webhook e certificar que o sistema localiza a submissão correta no banco usando o mapeamento dinâmico.