Kit & Módulos

Sistema de segmentos, módulos e configuração do perfil do site — do setup inicial à ativação individual de funcionalidades.

Visão Geral

O sistema de Kit & Módulos controla quais funcionalidades cada site (tenant) possui. Ele opera em dois eixos:

Módulos

Módulos são unidades de funcionalidade da plataforma. Cada módulo controla um conjunto de funcionalidades: telas do painel, rotas, menus, views do front e CSS.

Catálogo Completo

Tipos de Módulo

O Que Acontece ao Ativar/Desativar

Quando um módulo é ativado ou desativado para um tenant, os seguintes elementos são afetados automaticamente:

Starter Kits (Segmentos)

Starter Kits (ou Segmentos) são pacotes pré-configurados que definem o perfil completo de um site. Cada kit reúne:

• Módulos obrigatórios — ativados automaticamente, o tenant não pode desativar
• Módulos opcionais — sugeridos, o tenant escolhe quais ativar
• Template padrão — aplicado automaticamente na seleção
• Páginas modelo — conteúdo pré-pronto importado para o novo site

Kits Padrão da Plataforma

Seleção pelo Tenant

A tela de Kit & Módulos (/panel/segment) é onde o administrador do tenant configura o perfil do site.

Interface

A tela é dividida em duas colunas:

Fluxo de Seleção

1. O tenant clica em um card de kit → a interface carrega os detalhes via AJAX
2. Os módulos obrigatórios aparecem com checkbox marcado e desabilitado (não podem ser desmarcados)
3. Os módulos opcionais aparecem com checkbox livre
   • Se o tenant está reconfigurando o kit atual → módulos que já estavam ativos vêm pré-marcados
   • Se está trocando para um novo kit → todos os opcionais vêm desmarcados
4. O tenant pode ativar o switch de importação de páginas modelo (se houver páginas disponíveis)
5. Ao confirmar, o sistema executa tudo de uma vez:
   • Atualiza o segmento do tenant
   • Sincroniza módulos (core + obrigatórios + opcionais selecionados)
   • Importa páginas modelo (se solicitado)

Indicadores Visuais

• Borda verde — Kit atualmente ativo do tenant
• Borda azul — Kit selecionado para visualização/configuração
• Badge "Obrig." — Módulo obrigatório (verde, checkbox desabilitado)
• Badge do módulo — Cada módulo tem ícone + nome em formato compacto

Conflitos de Páginas

Ao importar páginas modelo, pode haver conflitos se o tenant já possui páginas com os mesmos slugs (ex: já tem /sobre ou /home).

Como o Sistema Trata

• Antes de confirmar, a interface mostra cada página modelo com seu status:

• Se todas as páginas já existem, o switch de importação é desabilitado automaticamente
• Um aviso amarelo mostra a contagem de páginas que serão ignoradas
• A importação nunca sobrescreve páginas existentes — a regra é: a página do tenant tem prioridade

Páginas Modelo

Páginas modelo (Starter Pages) são páginas pré-configuradas que podem ser importadas automaticamente quando o tenant seleciona um kit.

Tipos de Conteúdo

• WYSIWYG — Conteúdo HTML simples (editor visual)
• Page Builder — Conteúdo em blocos configuráveis (hero, features, CTA, galeria, etc.). Identificadas com badge PB

Campos

Vinculação a Kits

Cada página pode estar vinculada a um ou mais kits (relação muitos-para-muitos). A vinculação pode ser feita:

• No formulário da página modelo — selecionando quais kits a incluem
• No formulário do Starter Kit — selecionando quais páginas incluir

Páginas do Sistema

A plataforma já vem com 3 páginas pré-configuradas (criadas automaticamente na instalação):

O Que é Importado

Ao importar uma página modelo para o tenant:

• Cria um registro Page no tenant com título, conteúdo, layout e SEO
• Gera o url_rewrite (URL amigável) automaticamente
• Se usa Page Builder, copia todos os blocos com suas configurações:
  • Blocos inline (ex: slider) são convertidos em registros reais do tenant
  • Imagens são copiadas para o storage do tenant
• Configurações como featured_on_home e sort_order são preservadas

Gestão Master

O administrador da plataforma gerencia kits e módulos em /panel/master/segments.

Listagem

DataTable com colunas:

• ID, Ícone com cor, Nome, Descrição
• Template padrão (com link) + contagem de templates vinculados
• Contagem de módulos
• Contagem de tenants usando o kit
• Status (Ativo/Inativo)
• Ações: Editar, Duplicar, Excluir

No topo: botão para acessar "Páginas Modelo" e botão "Novo Starter Kit".

Formulário do Kit

O formulário de criação/edição é dividido em 4 seções:

1. Informações Básicas

• Nome — Identificação do kit (slug gerado automaticamente)
• Ícone — FontAwesome com preview em tempo real
• Cor — Hex color para o ícone (com color picker)
• Descrição — Texto exibido na seleção pelo tenant
• Status — Ativo/Inativo (inativos não aparecem na seleção)
• Ordem — Posição na listagem de seleção

2. Template Padrão

• Select com todos os templates globais ativos
• Ao selecionar, abre o painel de validação cruzada:
  • Detecta componentes presentes no HTML do template
  • Mostra avisos se módulos ou páginas necessários não estão selecionados
• Templates já vinculados ao kit aparecem como badges com link direto para o editor

3. Módulos

Todos os módulos não-core, organizados por categoria:

• Checkbox — Inclui/exclui o módulo do kit
• Switch "Obrig." — Marca como obrigatório (habilitado só quando checkbox marcado)
• Container com borda azul quando selecionado
• A validação cruzada atualiza em tempo real conforme módulos são marcados/desmarcados

4. Páginas Modelo

Todas as páginas modelo disponíveis:

• Checkbox — Inclui/exclui a página do kit
• Switch "Obrig." — Marca como obrigatória
• Badge PB para páginas com Page Builder
• Container com borda verde quando selecionado

Duplicar Kit

Cria cópia completa com novo slug (sufixo -copia-XXXX), incluindo todas as relações (módulos e páginas).

Excluir Kit

Só é possível excluir se nenhum tenant está usando o kit. Se houver tenants vinculados, a exclusão é bloqueada e um alerta mostra a contagem de sites afetados.

Validação Cruzada

O formulário de Starter Kit possui um sistema de validação cruzada em tempo real que garante consistência entre template, módulos e páginas.

Como Funciona

1. Ao selecionar ou trocar o template padrão, o sistema detecta os componentes presentes no HTML do template
2. Cada componente detectado é listado com ícone e nome
3. O sistema cruza com os módulos e páginas selecionados no formulário
4. Se houver inconsistências, exibe avisos amarelos

Tipos de Avisos

No final do painel, um resumo lista as pendências:

• "Módulos no template sem ativar:" — lista dos módulos faltantes
• "Páginas no template sem incluir:" — lista das páginas faltantes

Atualização em Tempo Real

A validação recalcula automaticamente quando:

• O template padrão é trocado
• Um módulo é marcado ou desmarcado
• Uma página modelo é marcada ou desmarcada

Ativação Individual de Módulos

Além da seleção por kit, o tenant pode ativar ou desativar módulos individualmente a qualquer momento.

Onde Ativar

Na mesma tela de Kit & Módulos (/panel/segment), o tenant pode:

• Reabrir a configuração do kit atual (clicando no card com borda verde)
• Marcar/desmarcar módulos opcionais
• Confirmar para salvar as alterações

Restrições

• Módulos core — Nunca podem ser desativados (checkbox não aparece)
• Módulos obrigatórios — Não podem ser desativados enquanto o kit atual exigir (mensagem de erro se tentar)
• Módulos opcionais — Livres para ativar/desativar

Impacto no Front-end

A ativação de módulos afeta diretamente o que aparece no site público do tenant.

Menu e Navegação

Menus dinâmicos no template (componentes <x-front.category-menu>) são renderizados apenas se o módulo correspondente está ativo. Com módulo inativo, o menu simplesmente não aparece no HTML.

CSS Condicional

O layout do front carrega CSS de módulos condicionalmente:

@if(has_module('blog'))
    <link href="/css/front/blog.css" rel="stylesheet">
@endif

@if(has_module('products'))
    <link href="/css/front/products.css" rel="stylesheet">
@endif

Módulos inativos não carregam seus CSS, reduzindo o peso da página.

Rotas e Páginas

Rotas de módulos inativos retornam 404 automaticamente. Se alguém tentar acessar /blog com módulo Blog desativado, verá a página de erro 404.

Configurações de Módulos

Na sidebar de Configurações (/panel/settings), os grupos de configurações de módulos aparecem apenas para módulos ativos. Com Blog inativo, a seção "Blog" nas configurações não aparece.

Fluxo Completo

Resumo do ciclo de vida completo de um tenant usando Kit & Módulos: