First Commit

rules/18_THEMES_CUSTOMIZER.md

@@ -0,0 +1,46 @@
+# Sistema de Temas e Customizer (Arquitetura)
+
+Este documento detalha o funcionamento técnico do sistema de temas do SysCMS, incluindo a herança de templates e o motor de personalização dinâmica.
+
+## 1. Arquitetura de Herança (Template Hierarchy)
+
+O SysCMS utiliza um motor de busca de arquivos em camadas para permitir a máxima flexibilidade sem duplicidade de código:
+
+1.  **Tema Ativo (`themes/{active}/`)**: Prioridade máxima.
+2.  **Tema Pai (`themes/{parent}/`)**: Se o tema ativo tiver a tag `Template` no seu `style.css`.
+3.  **Módulos (`modules/{module}/views/`)**: Fallback automático para as views padrão do sistema.
+4.  **Templates Globais (`templates/`)**: Fallback para layouts e componentes comuns.
+
+## 2. Overrides de Módulos
+
+Para sobrescrever a visualização de um módulo (ex: `index`), o tema deve replicar a estrutura interna do módulo:
+`themes/{tema}/modules/{nome_do_modulo}/views/{template}.twig`
+
+Isso permite que um tema mude apenas partes específicas de um módulo sem afetar sua lógica de controle.
+
+## 3. O Personalizador (Customizer)
+
+O Customizer é alimentado por um arquivo JSON e armazena os valores no banco de dados.
+
+### Fluxo de Dados:
+1.  **Definição:** O tema declara campos no arquivo `customizer.json`.
+2.  **Gestão:** O administrador altera os valores em `Sistema > Temas > Personalizar`.
+3.  **Persistência:** Os valores são salvos na tabela `system_config` com a chave `theme_settings_{slug_do_tema}`.
+4.  **Injeção:** O `Kernel\View.php` lê esses valores e os injeta na variável global `theme_settings` em todas as views Twig.
+
+### Tipos de Campos Suportados:
+- `color`: Seletor de cores hexadecimal.
+- `text`: Campo de texto simples.
+- `switch`: Interruptor booleano (on/off).
+- `select`: Menu suspenso com opções pré-definidas.
+
+## 4. Assets e URLs Dinâmicas
+
+- Use `theme_url()` para carregar arquivos CSS/JS/Imagens do tema. Ele resolverá automaticamente o caminho correto considerando a herança (Child > Parent).
+- Use `asset_url()` para arquivos globais na pasta `/public/assets`.
+
+## 5. Diretrizes para Desenvolvedores (IA)
+
+- **Sempre verifique o tema ativo:** Antes de modificar qualquer arquivo em `/modules/`, verifique se o usuário deseja que a mudança seja global ou apenas para o tema atual.
+- **Não altere o Kernel para novos temas:** O sistema de temas já é genérico. Novas funcionalidades de temas devem ser implementadas via `customizer.json` e lógica de template.
+- **Child Themes:** Ao criar temas derivados, utilize a tag `Template:` no `style.css` para manter o código limpo e herdar funcionalidades do tema base.