# REGRAS DO SYSCMS (Índice)

Este arquivo serve como índice para as regras detalhadas do projeto. A IA deve consultar os arquivos específicos abaixo para obter diretrizes detalhadas.

## 📂 Documentação de Regras

1. **[Comportamento da IA](rules/01_COMPORTAMENTO_IA.md)**
   - Como executar comandos (Proibição de `RunCommand` direto).
   - Criação de scripts PHP para tarefas.
   - Idioma e postura.

2. **[Arquitetura do Sistema](rules/02_ARQUITETURA.md)**
   - Estrutura de diretórios.
   - Componentes do Kernel (`Application`, `ModuleLoader`).
   - Padrões de Design (MVC, Repository, etc).

3. **[Sistema de Módulos](rules/03_MODULOS.md)**
   - Estrutura de pastas de um módulo.
   - Configuração do `module.json`.
   - Views, Rotas e Traduções.

4. **[Tecnologias e Stack](rules/04_TECNOLOGIAS.md)**
   - Bibliotecas Backend (PHP 8.1, Eloquent, Twig).
   - Frontend (Bootstrap 5.3, Alpine.js).
   - **Regra de Ícones**: Apenas Bootstrap Icons.

5. **[Padrões de Código](rules/05_PADROES_CODIGO.md)**
   - Nomenclatura (Classes, Métodos, Banco de Dados).
   - Regras de Banco de Dados (Prefixos, Multiempresa).
30.   - Segurança e Uploads.
31.   - **Armazenamento**: Use sempre `storage/uploads` fisicamente e `/storage` na URL.
32.
33. ## 📚 Documentação Complementar (Em `rules/`)

6. **[Guia do Desenvolvedor](rules/06_DEVELOPER_GUIDE.md)**
7. **[Uso do Ambiente](rules/07_ENVIRONMENT_USAGE.md)**
8. **[Guia de Execução de Comandos](rules/08_IA_COMMAND_EXECUTION_GUIDE.md)**
9. **[Configuração de Idioma](rules/09_LANGUAGE_CONFIG_README.md)**
10. **[Ciclo de Vida](rules/11_LIFECYCLE.md)**
12. **[Manual: Criar Módulos para Instalar](rules/12_MANUAL_COMO_CRIAR_MODULOS_PARA_INSTALAR.md)**
13. **[Guia de Usuário](rules/13_USER_GUIDE.md)**
14. **[Como Usar Hooks](rules/14_COMO_USAR_HOOK.md)**
15. **[Quill: Implementação Completa](rules/15_QUILL_IMPLEMENTATION_COMPLETE.md)**
16. **[Regras IA para Quill](rules/16_REGRAS_QUILL_IA.md)**
17. **[Template de Módulo](rules/17_MODULE_TEMPLATE.md)**
18. **[Sistema de Temas e Customizer](rules/18_THEMES_CUSTOMIZER.md)**
   - Arquitetura de temas, herança e child themes.
   - Configuração do `customizer.json`.
   - Uso de `theme_settings` no Twig.

19. **[Integração GlobalLists](rules/19_INTEGRACAO_GLOBALLISTS.md)**
   - Padrão obrigatório para campos de endereço (País, Estado, Cidade).
   - Migrations, Models e Vanilla JS para selects dinâmicos.

20. **[Gestão de Uploads](rules/22_UPLOADS_STORAGE.md)**
   - Proibição de escrita em `public/`.
   - Uso obrigatório de `storage/uploads`.
   - Link simbólico e geração de URLs.

---

## 🚀 Resumo Rápido para a IA

- **Padrão Frontend**: A IA coder deve dar preferência absoluta ao uso de **JavaScript puro (Vanilla JS)** em vez de Alpine.js para interações no frontend. O uso de Alpine.js deve ser restrito apenas a casos onde a reatividade complexa seja estritamente necessária e o Vanilla JS se torne impraticável.
- **Uploads**: **PROIBIDO** gravar em `public/`. Use sempre `storage/uploads` fisicamente e `/storage` na URL.
- **Paginação**: É **PROIBIDO** o uso de `Illuminate\Pagination` ou `$query->paginate()`. A paginação deve ser sempre implementada **manualmente** utilizando `$query->skip()->take()->get()` e calculando os offsets.
- **Execução de Comandos**: A IA tem permissão total para executar comandos `php` e `docker` diretamente no container para agilizar o desenvolvimento. É **OBRIGATÓRIO** que a IA execute o comando `.\sys.ps1 check` de forma autônoma após qualquer alteração significativa para validar o Lint e os Testes, sem necessidade de solicitação do usuário.
- **Autonomia de Validação**: A IA deve agir como um programador sênior, corrigindo proativamente erros de formatação (`.\sys.ps1 fix`) e falhas em testes antes de entregar a tarefa.
- **Responda em Português**.
- **Use Bootstrap Icons** (classes `bi-*`). É estritamente PROIBIDO o uso de outros ícones como `fas`, `fa`, `far` (FontAwesome) ou Material Icons.
- **DataTables**: Use sempre a **Versão COMPLETA** do DataTables.js (baseada em jQuery). O uso de `simple-datatables` é **PROIBIDO**. A inicialização deve ser feita via jQuery no `{% block scripts %}`.
- **Módulos**: Siga estritamente a estrutura `module.json`.
- **Instalação de Módulos**: É OBRIGATÓRIA a criação do arquivo `.zip` contendo o módulo para permitir sua instalação via upload ou distribuição.
- **Banco de Dados**: Use prefixos nos campos (ex: `users_id`).
- **Multiempresa e Multiusuário**: OBRIGATÓRIO o uso de `idbus` e `iduser` em todas as tabelas para garantir que os dados das empresas não se misturem. Novos módulos devem seguir este critério rigorosamente. **Regra de Acesso Global**: Quando `***_idbus` e `***_iduser` (onde `***` é o prefixo da tabela) em alguma tabela do banco de dados forem `0` e `0`, **OU quando estas colunas NÃO existirem na tabela**, significa que este registro é global e está disponível para qualquer módulo, qualquer empresa (company) e qualquer usuário.
- **Exceção (Listas Globais)**: O módulo `lists` (Países, Estados, Cidades, Atividades) é a única exceção à regra de `idbus`/`iduser`. Novos módulos DEVEM usar estas tabelas globais para dados de localização e ramos de atividade em vez de criar tabelas locais duplicadas.
  - **Proibição Alpine.js**: É PROIBIDO o uso de Alpine.js nos selects que utilizam o módulo `globallists` (ex: Estado/Cidade). Use **JavaScript puro (Vanilla JS)** para estas interações. Siga obrigatoriamente o padrão definido em `rules/19_INTEGRACAO_GLOBALLISTS.md`.
- **Padrão de API**: Respostas de API para estas listas DEVEM usar `json_encode($data, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR)` para garantir a integridade de caracteres acentuados.
- **Padrão de Requisição**: Ao realizar chamadas `fetch` para as APIs do GlobalLists, utilize o padrão de Vanilla JS documentado para garantir o pre-carregamento correto em formulários de edição.
- **Sistema de Temas**: Sempre que houver uma alteração visual solicitada pelo usuário, verifique se o tema ativo possui um override para a view em questão antes de editar o módulo base. Use `THEMES_MANUAL.md` como referência técnica.
- **Customizer**: Novos temas DEVEM incluir um arquivo `customizer.json` para permitir a personalização de cores e layouts via painel administrativo.
- **Proibição DB (Novos Módulos)**: Ao criar novos módulos, a IA é PROIBIDA de alterar a ESTRUTURA (schema) de tabelas existentes. Inserção de registros (INSERT) é permitida.
- **Sistema de Comentários**: Todo módulo que implemente comentários deve seguir o padrão do módulo **Blog**:
  - Validação de permissão (`allow_comments`).
  - Captcha para usuários não logados (usando Alpine.js).
  - Redirecionamento com parâmetros de query para erros (ex: `?error=comments_disabled`).
  - Suporte a multi-idioma (5 idiomas padrão).


Cabeçalho nos scripts:

/**
 * SysCMS - Content Management System
 *
 * Copyright (c) 2025 Marco Costa
 * All rights reserved.
 *
 * Author: Marco Costa
 * Email: contato@syspanel.com.br
 * Project: SysCMS
 *
 * This software is licensed, not sold.
 * Permission is granted to use this software
 * subject to the terms of the SysCMS Commercial License.
 *
 * Redistribution, sublicensing, resale, or
 * disclosure of this software, in whole or in part,
 * is strictly prohibited without prior written permission.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
 */