dockerfluxodecaixapro/rules/05_PADROES_CODIGO.md

Padrões de Código e Diretrizes

Nomenclatura (PSR-1/PSR-12)

• Classes: PascalCase (UserController)
• Métodos: camelCase (getUserById)
• Variáveis: camelCase (userData)
• Constantes: UPPER_SNAKE_CASE (MAX_ATTEMPTS)
• Tabelas DB: snake_case, com prefixo do nome da tabela nos campos (ex: tabela bus -> campos bus_id, bus_name).

Uso de Instruções Deprecated (Obsoletas)

1. Proibição: É estritamente PROIBIDO o uso de funções, métodos ou bibliotecas marcadas como deprecated nas versões atuais do PHP (8.1+) ou de dependências do sistema.
2. Atualização Pró-ativa: Ao encontrar avisos de obsolescência (ex: curl_close() em PHP 8.0+ para objetos CurlHandle), a IA deve substituir a instrução pela alternativa recomendada imediatamente.
3. Compatibilidade: Sempre garanta que a substituição mantenha a funcionalidade e a segurança, tratando retornos de tipos conforme as novas especificações da linguagem (ex: type casting em retornos ambíguos).

Compatibilidade Cross-Platform

1. Agnosticismo de S.O.: O código DEVE rodar em Windows e Linux sem modificações.
2. Caminhos de Arquivo: Use sempre a constante DIRECTORY_SEPARATOR ou a barra normal / (que o PHP entende em ambos os sistemas). Nunca use \ hardcoded.
3. Comandos de Sistema: Evite exec(), system(), passthru() com comandos específicos de shell (ex: rm, ls, grep). Use funções nativas do PHP (unlink, scandir, etc.).
4. Symlinks: Não dependa de symlinks. O sistema utiliza rotas de aplicação para servir arquivos.

Banco de Dados e Multiempresa

1. Prefixo de Campos: OBRIGATÓRIO. Todo campo deve ter o prefixo da tabela.
   • Ex: Tabela users -> users_id, users_name, users_email.
2. Isolamento Multiempresa e Multiusuário:
   • O SysCMS é um sistema multi-empresas e multi-usuários.
   • Todo registro deve obrigatoriamente ser vinculado aos seus proprietários via campos de controle:
     • idbus: Identificador da empresa/business (ex: subjects_idbus, notes_idbus).
     • iduser: Identificador do usuário proprietário (ex: subjects_iduser, notes_iduser).
   • Os dados das empresas (companies) não se misturam de forma alguma.
   • Todas as consultas devem filtrar pela empresa (idbus) e, quando aplicável, pelo usuário (iduser) logado.
   • 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. Esta regra deve ser respeitada em todos os módulos.
3. Novos Módulos: A criação de novos módulos deve SEMPRE seguir este critério de isolamento.
4. Não usar SQL puro: Use o Eloquent/Query Builder, exceto em casos de performance extrema devidamente documentados.
5. Imutabilidade de Tabelas Existentes (Novos Módulos): Ao criar um novo módulo, a IA é estritamente PROIBIDA de alterar a ESTRUTURA (DDL) de tabelas que já existem no sistema (ex: adicionar colunas em users). O novo módulo deve ser autossuficiente. A inserção, atualização ou remoção de REGISTROS (DML) em tabelas existentes (ex: inserir na tabela modules ou permissions) é PERMITIDA e esperada.
6. Módulo de Listas Globais (Exceção ao Isolamento):
   • O módulo lists é uma exceção à regra de isolamento idbus/iduser.
   • Ele fornece dados globais (Países, Estados, Cidades e Atividades) que são compartilhados por todos os inquilinos (tenants).
   • Tabelas do Módulo Lists: lists_countries, lists_states, lists_cities, lists_activities.
   • Estas tabelas NÃO possuem campos idbus ou iduser e são acessíveis globalmente.
   • Uso Obrigatório: Novos módulos que necessitem de dados de localização ou ramos de atividade DEVEM utilizar as tabelas globais do módulo lists via seus respectivos Modelos (Modules\Lists\Models), evitando a criação de tabelas duplicadas ou isoladas para estes fins.
   • Proibição Alpine.js: É estritamente PROIBIDO o uso de Alpine.js nos selects que interagem com o módulo globallists (ex: select de Estado que carrega select de Cidade). Nestes casos, deve-se utilizar JavaScript puro (Vanilla JS) para realizar as chamadas de API e manipulação do DOM. Isso evita conflitos de reatividade e garante performance.
   • Manipulação de JSON (API): Ao retornar dados destas listas via API, é MANDATÓRIO o uso de json_encode($data, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR). O flag JSON_UNESCAPED_UNICODE é essencial para que caracteres acentuados (ex: "São Paulo") sejam legíveis e processados corretamente pelo JavaScript no frontend.
   • Estrutura de Retorno: Utilize ->values()->all() após um map() em coleções do Eloquent para garantir que o JSON resultante seja um array indexado (ex: [...]) e não um objeto associativo (ex: {"0": ..., "1": ...}).
   • Multi-idioma: Campos de nome nestas tabelas (ex: countries_name, activities_name) são do tipo JSON e suportam 5 idiomas padrão (pt_BR, en_US, es_ES, de_DE, fr_FR). O acesso deve ser feito via o accessor getNameAttribute() ou propriedade name no Eloquent, que gerencia a tradução automática baseada no locale atual.

Padronização de Componentes ERP

1. Unidade de Medida (UOM):
   • É OBRIGATÓRIO o uso de um campo select para a "Unidade de Medida" em todos os formulários do ERP (Produtos, Matérias-Primas, Pedidos, etc.).
   • O uso de campo de texto livre (input type="text") para este fim é PROIBIDO.
   • Opções Padrão: UN, KG, G, MG, L, ML, M, CM, MM, M2, M3, PC, CX, PAC, RO, FR.
   • O valor padrão inicial deve ser sempre UN (Unidade).

Frontend e JavaScript

1. Preferência por Vanilla JS: A IA coder deve dar preferência absoluta ao uso de JavaScript puro (Vanilla JS) em vez de Alpine.js para todas as interações no frontend.
2. Restrição ao Alpine.js: O uso de Alpine.js deve ser limitado apenas a componentes que exijam alta reatividade ou gerenciamento de estado complexo onde o Vanilla JS resultaria em código excessivamente verboso ou difícil de manter.
3. Módulo de Listas Globais: É expressamente proibido o uso de Alpine.js em seletores que interagem com o módulo globallists (ex: País/Estado/Cidade). Nestes casos, o uso de Vanilla JS é mandatório para garantir performance e evitar conflitos.
4. DataTables.js:
   • Use sempre a Versão COMPLETA (baseada em jQuery) integrada ao sistema.
   • O uso de simple-datatables é PROIBIDO.
   • A inicialização deve ser feita no {% block scripts %} do template Twig.
   • Configure sempre a tradução (language) utilizando a URL do CDN oficial ou arquivo local, priorizando o idioma do sistema.
   • Garanta a responsividade habilitando a opção responsive: true.

Segurança

1. Validação: Obrigatória em todos os inputs.
2. CSRF: Obrigatório em formulários POST.
3. Captcha: Obrigatório em formulários públicos.
4. Permissões: Verificar permissões antes de qualquer ação (can(), middlewares).

Uploads e Arquivos

1. Localização Física: Sempre em storage/uploads/{modulo}/.
2. Proibição: É terminantemente PROIBIDO gravar arquivos diretamente em public/.
3. Acesso Web: Use sempre o helper url() com o caminho completo (ex: url('storage/uploads/modulo/arquivo.jpg')). 61→4. Processamento: Imagens devem ser processadas pelo Intervention Image (formatar e comprimir conforme .env). 62→5. Permissões: Não criar pastas fora de storage.

Logs

• Todos os logs devem ser gravados em /logs.
• Usar Monolog para estruturar logs.

Editor de Texto Rico (Quill)

Usar Quill apenas para:

• Conteúdo extenso (artigos, posts).
• Necessidade de formatação (HTML).
• Não usar para campos simples (títulos, nomes).
• Container deve ter ID #quill-editor ou classe .quill-editor.

Comentários e Documentação Técnica

1. Formato: OBRIGATÓRIO o uso de PHPDoc (/** ... */) para classes, métodos, propriedades e cabeçalhos de arquivo.
2. Idioma: OBRIGATÓRIO escrever todos os comentários técnicos em Inglês.
   • Exceção: Strings literais exibidas ao usuário final (mensagens de erro, labels, etc.) devem permanecer no idioma original (Português/Multi-idioma).
3. Escopo:
   • Cabeçalhos de arquivo devem conter informações de copyright e licença em inglês.
   • Métodos devem descrever parâmetros (@param), retornos (@return) e exceções (@throws).
4. Lógica: A tradução de comentários NÃO deve alterar nomes de variáveis, funções ou lógica do sistema.