dockerfluxodecaixapro/rules/RULES.md

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

   • Como executar comandos (Proibição de RunCommand direto).
   • Criação de scripts PHP para tarefas.
   • Idioma e postura.

2. Arquitetura do Sistema

   • Estrutura de diretórios.
   • Componentes do Kernel (Application, ModuleLoader).
   • Padrões de Design (MVC, Repository, etc).

3. Sistema de Módulos

   • Estrutura de pastas de um módulo.
   • Configuração do module.json.
   • Views, Rotas e Traduções.

4. Tecnologias e Stack

   • 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

   • Nomenclatura (Classes, Métodos, Banco de Dados).
   • Regras de Banco de Dados (Prefixos, Multiempresa).
6. • Segurança e Uploads.
7. • Armazenamento: Use sempre storage/uploads fisicamente e /storage na URL.

9. 📚 Documentação Complementar (Em rules/)

10. Guia do Desenvolvedor

11. Uso do Ambiente

12. Guia de Execução de Comandos

13. Configuração de Idioma

14. Ciclo de Vida

15. Manual: Criar Módulos para Instalar

16. Guia de Usuário

17. Como Usar Hooks

18. Quill: Implementação Completa

19. Regras IA para Quill

20. Template de Módulo

21. Sistema de Temas e Customizer

• Arquitetura de temas, herança e child themes.
• Configuração do customizer.json.
• Uso de theme_settings no Twig.

19. Integração GlobalLists

• 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

• 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. */